Previous Next Table of Contents

2. Text elements.

2.1 File names and directories.

File names, including the names of executable programs, should always be formatted in monospaced type. Only the name should be formatted, and not the trailing punctuation. Names of executable programs need not include the fully qualified path if the directory where it is located is in the environment's $PATH variable. Capitalization in all instances should follow the capitalization of the file name, even at the beginning of a sentence.

To create a filesystem, use <tt>mkfs</tt> or
<tt>mke2fs</tt>, as appropriate for your system.
To create a filesystem, use mkfs or mke2fs, as appropriate for your system.

<tt>emacs</tt> is widely supported and included in most Linux 
distributions.
emacs is widely supported and included in most Linux distributions.

The <tt>passwd</tt> program should be used to change the
passwords of users already in the <tt>/etc/passwd</tt>
database.  <tt>adduser</tt> will add users to
<tt>/etc/passwd</tt>.
The passwd program should be used to change the passwords of users already in the /etc/passwd database. adduser will add users to /etc/passwd.

MS-DOS executable filenames include the filename's extension. Use capitals to distinguish the name from Linux executable names.

In order to format a hard drive under MS-DOS, you need a bootable
diskette with <tt>FORMAT.COM</tt> and <tt>FDISK.EXE</tt>.
In order to format a hard drive under MS-DOS, you need a bootable diskette with FORMAT.COM and FDISK.EXE.

2.2 Code fragments and screen shots.

Text of code fragments and screen shots should have a ragged right margin and be no wider than the body text, to avoid problems with text running off the printed page.

The code environment does not translate well in printed output. Reproduction of the rules above and below the text that the <code> tags generate is hardware dependent, and the rules might disappear

The <verb> and <tscreen> tags are not redundant in the LaTeX code they generate. The most obvious difference is that the tscreen environment indents the text; the verb environment doesn't. Documents look best if you use one or the other throughout the document. The environments can be nested.

At the time of this writing, the LinuxDoc DTD with LaTeX indents the first line after a verb or tscreen environment. If this is not acceptable, you can delete the intervening blank line(s) between the \end{verbatim} or \end{tscreen} command and the text below it in the LaTeX output.

2.3 Environment variables.

Use <tt> and </tt> tags for environment variables in the text. They should be in caps like the variable itself and be preceeded by a dollar sign:

  • $PATH
  • $DISPLAY
  • $PAGER
  • 2.4 URLs.

    The <url> tag does not translate well to LaTeX. If possible, set off URLs in <verb> or <tscreen> blocks.

    2.5 Software packages.

    Names of software packages should use the normal body text. The capitalization should follow the capitalization which the author or maintainer uses in the documentation.

  • Ghostscript has a unique licensing agreement.
  • APS-FILTER is a program which will simplify your life.
  • Metafont is not a difficult package to use.
  • 2.6 Concepts.

    Concepts and terms which are unfamiliar to the reader should be formatted in bold letters the first time they appear.

    The root directory is the topmost level of a Unix file system. At boot time, the filesystems of each device are mounted on subdirectories of the root directory.

    2.7 Brand names.

    In general you will not need to specify copyrights or trademarks. They will be covered by the general copyright of the book. Capitalization and punctuation should, of course, be the same as the manufacturer's. Try to follow the capitalization and punctuation of the copyright or patent notice and not the logo on the box.

  • PostScript
  • Hewlett Packard
  • Iomega Zip drive
  • Unix was developed at by AT&T in New Jersey and elsewhere.

  • Previous Next Table of Contents