-*- Outline -*-

* Typesetting notes (for the printed book)
** Interactive shell logs (where the results of commands are displayed
   interpspersed with lines typed at a CLI prompt by the user), should be
   in a Courier font, with the lines typed by the user (those starting with
   a ``$ '' prompt) emboldened.
** text between "@quotation" and "@end quotation", is out-of-band data which
   should be in a typeset in a box with a margin icon to show that the
   marked text is a ``tip''.
** for consistency, refer to ``compilation units'' throughout and not
   ``translation units''.
** use the following typographical conventions:

	@sc{aix}
	@acronym{AT&T}
	@acronym{BSD}
	@sc{gcc}
	@sc{hp-ux}
	@sc{posix}
	@sc{ansi} and @sc{iso}
	@sc{dll}
	@acronym{ELF}
	@acronym{FTP}
	@sc{api}
	@sc{pic} and non-@sc{pic}
	Unix
	Win32
	Windows
	Cygwin
	@sc{gnu}/Linux; we must keep RMS happy!
	built-in

   except in @chapter headings where @sc and @acronym look *really* bad!

** Refer to the projects as Autoconf, Automake and Libtool.
** Refer to the actual programs as @code{autoconf}, @code{automake}, etc.
** Refer to configure scripts as @file{configure} scripts.
** Use @uref for URLs, not @code, @url, or anything else.
** Beware of the construction ``COLLECTIVE tools''.
** Use that nasty American `ized' form. :-)


* Examples
** use @smallexample whenever the text of the example is more than 50
   characters (or so) wide.
** use @group/@end group to break examples in sensible places
** always use ``$ '' as the shell prompt, unless something else would
   make the example clearer.
** whereever possible, maintain the example sources separately, where
   they can be compiled and tested, and m4 include them into the text
   (after appropriate preprocessing).


* Writing style
** begin each chapter with a paragraph or two summarising what the reader
   can expect to learn by reading the remainder of that chapter.
** use third person when walking through an example:
   If you look at the contents of the @command{hello} program you built...
** use first person when describing prior art:
   I need to know that I have to @emph{bless} my library with @command{ranlib}
** if you start a sentence with a tool name (libtool), don't capitalise it!


* Use of texinfo directives
** use @code for shell (or C) code quotes inside normal text
** use @command for command line examples and switch names inside normal text
** use @file for references to the filesystem
** use @samp for any other courier font inside normal text
** use @command to refer to the autoconf, automake or libtool commands,
   but _not_ as part of a phrase like `libtool library' or `automake macro'
** use @command for other commands like `gcc', `make', etc.
** use @option for command line options


A BRIEF GUIDE TO TEXINFO MARKUP FOR A PRINTED BOOK

I can generate a fully typeset postscript document from the texinfo sources
for you too look at to demonstrate exactly what was intended by the tags.

* Basics
** Any character preceded by an ``@'', or any token delimitted by @xxx{yyy} is
  a markup tag.  For the latter, xxx is the tag and yyy is the text being
  operated on.
*** except @@, @{ and @} which are typeset as @, { and } respectively.

* Fonts
** @b and @i are bold and italic respectively.
** @strong and @emph are bold and italic respectively.
** @sc means ``small-caps'', where the tagged text is typeset in block
   capitals but 2 points smaller than the surrounding text since acronyms
   in fullsize roman capitals can jar the eye.
** @acronym is the same as @sc I think.
** @r is for a proportional font (think ``roman'') in a block of courier
   such as a code example.  We like comments in courier code blocks to be
   typeset with a proportional font.
** @dfn is italic.
** @uref and @code are in a monospaced font.
** @file, @option and @command are in a monospaced font set between single ` and '.
** @example ... @end example and @smallexample ... @smallexample should be
   typeset in a monospaced font (courier).

* Headers
** @chapter/@appendix/@unnumbered =>  a heading    1. Chapter Name
** @section                       =>  c heading    1.2 Section Name
** @subsection                    =>  d heading    1.2.3 Subsection Name
** @subsubsection                 =>  e heading    1.2.3.4 Subsubsection Name
** etc.

* Cross references
** The @node tag for chapter, section and subsection headings are unique
   throughout the entire book, and are used by the typesetting tools to
   find page and section numbers for the cross reference dynamically.
** @xref and @pxref are typeset as:
     See section N.N.N [name of section], page x
** @ref is typeset as:
     section N.N.N [name of section], page x

* Lists
** @itemize ... @end itemize contain a list of some sort, where each item in
   the list is preceded by an @item tag.  The tag after @itemize is usually
   either @bullet, if a bullet point should be typeset before each new list
   item, or @asis if the items are layed out (and indented) as a bullet list
   but the bullet mark itself omitted.
** @enumerate ... @end enumberate also contain a bullet list, however instead
   of bullet points, the items are preceded by sequential numbers starting at
   1.
** @table ... @end table delimit a two column table (no lines should be drawn
   however), with about an inch and a half for the left column, and the
   remainder of the width for the other column.  Each row in the list is
   started with an @item tagm, with the balance of the @item line forming
   the text for the left column, and the text between there and the next @item
   tag justified in the right column.  If the text for the left column spills
   into the right column, the text for the right column starts one line below
   the spilled line.  If the table starts with @table @bullet, there should
   be a bullet point before each left column entry.

   eg:      one    this is the text for the first
                   table entry.

            two    this is the text for the second
                   entry, though it would normally
                   share a right margin with the
                   normal text.

            this is the third item
                   see how this text simply begins
                   on the next line.

* Function Definitions
** @deftypefn Function int posix_path(char *@var{path})
   blah blah blha
   @end deftypefn

   is typeset as

   int posix_path (char *path)                         Function

       blah blah blah

   Function name in bold, @var tag in italic, `blah blah blah' indented
   one level, `Function' right justified, `int posix_path (char *path)'
   all in monospaced font.

* Misc
** @menu ... @end menu tags are for the hypertext document, not the
   printed book.
** @node tags are not relevant to the printed book.
** COLLECTIVE is a placeholder that will be replaced by whatever we
   eventually agree is a good collective name for `GNU autoconf, automake
   and libtool'.
** `@group ... @end group' denotes that the contained lines should not be 
   split across the page.
** `@example ... @end example' denotes that the contained lines should not
   be refilled, and should appear layed out exactly (excepting texinfo control
   sequences such as `@{' etc.) as shown in a fixed width font.
** `@smallexample ... @end smallexample' is exactly the same.
