home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / gnu / texinfo-3.1-bin.lha / info / texi.info-9 (.txt) < prev   
GNU Info File  |  1994-07-11  |  47KB  |  925 lines
  1. This is Info file texi.info, produced by Makeinfo-1.55 from the input
  2. file texi.texi.
  3.    This file documents Texinfo, a documentation system that uses a
  4. single source file to produce both on-line information and a printed
  5. manual.
  6.    Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
  7.    This is the second edition of the Texinfo documentation,
  8. and is consistent with version 2 of `texinfo.tex'.
  9.    Permission is granted to make and distribute verbatim copies of this
  10. manual provided the copyright notice and this permission notice are
  11. preserved on all copies.
  12.    Permission is granted to copy and distribute modified versions of
  13. this manual under the conditions for verbatim copying, provided that
  14. the entire resulting derived work is distributed under the terms of a
  15. permission notice identical to this one.
  16.    Permission is granted to copy and distribute translations of this
  17. manual into another language, under the above conditions for modified
  18. versions, except that this permission notice may be stated in a
  19. translation approved by the Free Software Foundation.
  20. File: texi.info,  Node: Tips,  Next: Sample Texinfo File,  Prev: Command List,  Up: Top
  21. Tips and Hints
  22. **************
  23.    Here are some tips for writing Texinfo documentation:
  24.    * Write in the present tense, not in the past or the future.
  25.    * Write actively!  For example, write "We recommend that ..." rather
  26.      than "It is recommended that ...".
  27.    * Use 70 or 72 as your fill column.  Longer lines are hard to read.
  28.    * Include a copyright notice and copying permissions.
  29. Index, index, index!
  30. ....................
  31.    Write many index entries, in different ways.  Readers like indices;
  32. they are helpful and convenient.
  33.    Although it is easiest to write index entries as you write the body
  34. of the text, some people prefer to write entries afterwards.  In either
  35. case, write an entry before the paragraph to which it applies.  This
  36. way, an index entry points to the first page of a paragraph that is
  37. split across pages.
  38.    Here are more hints we have found valuable:
  39.    * Write each index entry differently, so each entry refers to a
  40.      different place in the document.  The index of an Info file lists
  41.      only one location for each entry.
  42.    * Write index entries only where a topic is discussed significantly.
  43.      For example, it is not useful to index "debugging information" in
  44.      a chapter on reporting bugs.  Someone who wants to know about
  45.      debugging information will certainly not find it in that chapter.
  46.    * Consistently capitalize the first word of every index entry, or
  47.      else use lower case.  According to convention, you should
  48.      capitalize the first word of an index entry.  However, this
  49.      practice may make an index look crowded.  Some writers prefer
  50.      lower case.  Regardless of which you prefer, choose one style and
  51.      stick to it.  Mixing the two styles looks bad.
  52.    * Always capitalize or use upper case for those words in an index for
  53.      which this is proper, such as names of countries or acronyms.
  54.    * Write the indexing commands that refer to a whole section
  55.      immediately after the section command, and write the indexing
  56.      commands that refer to the paragraph before the paragraph.
  57.      In the example that follows, a blank line comes after the index
  58.      entry for "Leaping":
  59.           @section The Dog and the Fox
  60.           @cindex Jumping, in general
  61.           @cindex Leaping
  62.           
  63.           @cindex Dog, lazy, jumped over
  64.           @cindex Lazy dog jumped over
  65.           @cindex Fox, jumps over dog
  66.           @cindex Quick fox jumps over dog
  67.           The quick brown fox jumps over the lazy dog.
  68.      (Note that the example shows entries for the same concept that are
  69.      written in different ways--`Lazy dog', and `Dog, lazy'--so readers
  70.      can look up the concept in different ways.)
  71. Blank lines
  72. ...........
  73.    * Insert a blank line between a sectioning command and the first
  74.      following sentence or paragraph, or between the indexing commands
  75.      associated with the sectioning command and the first following
  76.      sentence or paragraph, as shown in the tip on indexing.
  77.      Otherwise, a formatter may fold title and paragraph together.
  78.    * Always insert a blank line before an `@table' command and after an
  79.      `@end table' command; but never insert a blank line after an
  80.      `@table' command or before an `@end table' command.
  81.      For example,
  82.           Types of fox:
  83.           
  84.           @table @samp
  85.           @item Quick
  86.           Jump over lazy dogs.
  87.           
  88.           @item Brown
  89.           Also jump over lazy dogs.
  90.           @end table
  91.           @noindent
  92.           On the other hand, ...
  93.      Insert blank lines before and after `@itemize' ... `@end itemize'
  94.      and `@enumerate' ... `@end enumerate' in the same way.
  95. Complete phrases
  96. ................
  97.    Complete phrases are easier to read than ...
  98.    * Write entries in an itemized list as complete sentences; or at
  99.      least, as complete phrases.  Incomplete expressions ... awkward
  100.      ... like this.
  101.    * Write the prefatory sentence or phrase for a multi-item list or
  102.      table as a complete expression.  Do not write "You can set:";
  103.      instead, write "You can set these variables:".  The former
  104.      expression sounds cut off.
  105. Editions, dates and versions
  106. ............................
  107.    Write the edition and version numbers and date in three places in
  108. every manual:
  109.   1. In the first `@ifinfo' section, for people reading the Texinfo
  110.      file.
  111.   2. In the `@titlepage' section, for people reading the printed manual.
  112.   3. In the `Top' node, for people reading the Info file.
  113. Also, it helps to write a note before the first `@ifinfo' section to
  114. explain what you are doing.
  115. For example:
  116.      @c ===> NOTE! <==
  117.      @c Specify the edition and version numbers and date
  118.      @c in *three* places:
  119.      @c   1. First ifinfo section  2. title page  3. top node
  120.      @c To find the locations, search for !!set
  121.      
  122.      @ifinfo
  123.      @c !!set edition, date, version
  124.      This is Edition 4.03, January 1992,
  125.      of the @cite{GDB Manual} for GDB Version 4.3.
  126.      ...
  127. --or use `@set' and `@value' (*note `@value' Example: value Example.).
  128. Definition Commands
  129. ...................
  130.    Definition commands are `@deffn', `@defun', `@defmac', and the like,
  131. and enable you to write descriptions in a uniform format.
  132.    * Write just one definition command for each entity you define with a
  133.      definition command.  The automatic indexing feature creates an
  134.      index entry that leads the reader to the definition.
  135.    * Use `@table' ... `@end table' in an appendix that contains a
  136.      summary of functions, not `@deffn' or other definition commands.
  137. Capitalization
  138. ..............
  139.    * Capitalize `Texinfo'; it is a name.  Do not write the `x' or `i'
  140.      in upper case.
  141.    * Capitalize `Info'; it is a name.
  142.    * Write TeX using the `@TeX{}' command.  Note the uppercase `T' and
  143.      `X'.  This command causes the formatters to typeset the name
  144.      according to the wishes of Donald Knuth, who wrote TeX.
  145. Spaces
  146. ......
  147.    Do not use spaces to format a Texinfo file, except inside of
  148. `@example' ... `@end example' and similar commands.
  149.    For example, TeX fills the following:
  150.          @kbd{C-x v}
  151.          @kbd{M-x vc-next-action}
  152.             Perform the next logical operation
  153.             on the version-controlled file
  154.             corresponding to the current buffer.
  155. so it looks like this:
  156.      `C-x v' `M-x vc-next-action' Perform the next logical operation on
  157.      the version-controlled file corresponding to the current buffer.
  158. In this case, the text should be formatted with `@table', `@item', and
  159. `@itemx', to create a table.
  160. @code, @samp, @var, and `---'
  161. .............................
  162.    * Use `@code' around Lisp symbols, including command names.  For
  163.      example,
  164.           The main function is @code{vc-next-action}, ...
  165.    * Avoid putting letters such as `s' immediately after an `@code'.
  166.      Such letters look bad.
  167.    * Use `@var' around meta-variables.  Do not write angle brackets
  168.      around them.
  169.    * Use three hyphens in a row, `---', to indicate a long dash.  TeX
  170.      typesets these as a long dash and the Info formatters re