5.6.1 Formatting

• Use two spaces after every period/full-stop ending a sentence.

• Don't use capital letters for emphasis--use `@strong{}' instead.

• Put a comma or colon after "e.g.".

• When "i.e." or "etc." is followed by a space, use `@:' after it, to indicate that that the final period does not end the sentence. E.g.: `i.e.@:'.

• Don't put a newline between a function's return type and its name, e.g.:

  int somefunc (void);

  is incorrect;

  int somefunc (void);

  is correct.

• When introducing a new term, it is usually a good idea to use `@dfn{}' to mark it as a definition. It may also be a good idea to add it to the concept index using `@cindex{}'. E.g.:

  @cindex definition This is a @dfn{definition}.

• Command-line options should use the `@samp{}' or `@option{}' mark-up. `@option{}' is new in Texinfo 4.0.

• Names of programs should use `@command{}' (unless program's name has become a proper name, like GCC or GDB).

• Constants like EINVAL should be enclosed in `@code{}'.

• Environment variables like LOGNAME should be enclosed in `@env{}'.

• Avoid the urge to use `@ref{}' or variant in the middle of sentence, because it will look ugly in info documentation and terrible in printed documentation. Instead use a textual reference followed by a comma followed by the reference command, e.g.:

  @code{yabbadabbadoo()}, @ref{yabbadabbadoo()}.

• Be aware of how you use the `-' character. Use the following mark-up correctly:
  • `@minus{}' to insert a minus sign;

  • `---' to insert an em-dash--do not put spaces on either side of `---';

  • `-' to hyphenate;

  • `@-' to insert a discretionary hyphenation point.

• Use @uref to refer to a URL. texinfo also has @url for inserting URLs, but @uref is more useful when texinfo is formatted into HTML. The Texinfo manual discourages the use of @url.

• Under the subheading `Portability', `@portability' should be used to indicate whether a feature is specified in the ANSI C and POSIX standards. For example:

  @subheading Portability @portability !ansi, posix

  Please note that `@portability' is not used to indicate whether the DJGPP implementation complies with the standards listed. Instead, `@port-note' may be used to describe implementation-specific details:

  @port-note ansi The buffer size limit is imposed by DJGPP.

  `@portability' and `@port-note' are DJGPP-specific extensions of texinfo (@xref{Top, , texinfo, texinfo}) that are expanded into normal texinfo by mkdoc. mkdoc is part of the DJGPP sources. It is used to build the C library documentation (@xref{Top, , libc, libc}). Therefore, `@portability' and `@port-note' should only be used in DJGPP's C library documentation.

• When writing prototypes in header files remember to prefix any formal arguments that you use with the underscore character (`_') to avoid polluting the name space.

• Finally, for some relevant texinfo technique, look at the source of this page in the DJGPP sources---`src/docs/kb/contrib.txi'.