Red Hat Linux Bible: Fedora and Enterprise Edition [Electronic resources] نسخه متنی

Creating Documents in Groff or LaTeX

You can create documents for either of Linux's Groff (troff/nroff) or LaTeX (TeX) styles of publishing using any text editor. Red Hat Linux comes with several text editors, or you can download others from the Internet. See the "Choosing a Text Editor" sidebar for information.

The process of creating documents in Groff or LaTeX consists of the following general steps:

1. 
   

   Create a document with any text editor. The document will contain text and markup.



2. 
   

   Format the document using a formatting command that matches the style of the document that you created (for example, with groff or latex). During this step, you may need to indicate that the document contains special content, such as equations (eqn command), tables (tbl command), or line drawings (pic command).



3. 
   

   Send the document to an output device. The device may be a printer or display program.

If you are used to a word processor with a GUI, you may find these publishing tools difficult. In general, Groff is useful to create man pages for Red Hat Linux. LaTeX is useful if you need to produce mathematical documents, perhaps for publication in a technical journal.

Text processing with Groff

The nroff and troff text formatting commands were the first interfaces available for producing typeset quality documents with the UNIX system. They aren't editors; rather, they are commands that you send your text through, with the result being formatted pages:

• 
  

  nroff ( Produces formatted plain text and includes the ability to do pagination, indents, and text justification, as well as other features.



• 
  

  troff ( Produces typeset text, including everything nroff can do, plus the ability to produce different fonts and spacing The troff command also supports kerning.

Hardcore UNIX/Linux users tend to edit files with either the vi or emacs text editor. These editors have been around a long time and are hard to learn, but efficient to use. (Your fingers never leave the keyboard.) The emacs editor has some GUI support, though it will run fine in a Terminal window. There are also GUI versions of vi and emacs that add menu and mouse features to the editors. These are GVim (gvim command in the vim-X11 package) and Xemacs (xemacs command) editors.

Some of the other, simpler text editors that can run on your graphical desktop are:

• 
  

  gedit (gedit command) — This text editor, which comes with Red Hat, is the lightweight text editor for GNOME. It has simple edit functions (cut, copy, paste, and select all) and settings let you set indentations and word wrap. Special functions, such as a spell checker and a diff feature are included. You can start gedit by typing gedit from a Terminal window. Go to http://gedit.sourceforge.net for more information.



• 
  

  Advanced Editor (kwrite command) — This text editor includes a menu bar to create, open, or save files. It also has simple edit functions (cut, copy, paste, undo, and help). Other edit features let you set indents, find/replace text, and select all text. This comes with the KDE desktop, so you can access it by selecting Accessories More Accessories Kwrite.



• 
  

  Text Editor (kedit command) — Another simple text editor. Features let you open files from your file system or from a URL. It also includes a convenient toolbar and a spell checker. It comes with the KDE desktop, so you can access it by selecting Accessories More Accessories Text Editor.

The groff command is the front-end for producing nroff/troff documentation. Because Linux man pages are formatted and output in Groff, most of the examples here help you create and print man pages with Groff.

People rarely use primitive nroff/troff markup. Instead, there are common macro packages that simplify creating nroff/troff formatted documents, which include:

• 
  

  man — The man macros are used to create Linux man pages. You can format a man page using the -man option to the groff command.



• 
  

  mm — The mm macros (memorandum macros) were created to produce memos, letters, and technical white papers. This macro package includes macros for creating a table of contents, lists of figures, references, and other features that are helpful for producing technical documents. You can format an mm document using the -mm groff option.



• 
  

  me — The me macros were popular for producing memos and technical papers on Berkeley UNIX systems. Format an me document using the -me groff option.

Groff macro packages are stored in /usr/share/groff/*/tmac. The man macros are called from the an.tmac file, mm macros are from m.tmac, and me macros are from e.tmac. The naming convention for each macro package is xxx.tmac, where the xxx is replaced by one or more letters representing the macro package. In each case, you can understand the name of the macro package by adding an m to the beginning of the file suffix.

When you run the groff formatting command, you can indicate on the command line which macro packages you are using. You can also indicate that the document should be run through any of the following commands that preprocess text for special formats:

• 
  

  eqn — This preprocessor formats macros that produce equations in groff.



• 
  

  pic — This preprocessor formats macros that create simple line drawings in groff.



• 
  

  tbl — This preprocessor formats macros that produce tables within groff.

The formatted Groff document is output for a particular device type. The device can be a printer, a window, or (for plain text) your shell. Here are output forms supported by Groff:

• 
  

  ps — Produces PostScript output for PostScript printer or a PostScript previewer.



• 
  

  lj4 — Produces output for an HP LaserJet4 printer or other PCL5-compatible printer.



• 
  

  ascii — Produces plain-text output that can be viewed from a Terminal window.



• 
  

  dvi — Produces output in TeX dvi, to output to a variety of devices described later.



• 
  

  X75 — Produces output for an X11 75 dots/inch previewer.



• 
  

  X100 — Produces output for an X11 100 dots/inch previewer.



• 
  

  latin1 — Produces typewriter-like output using the ISO Latin-1 character set.

Formatting and printing documents with Groff

You can try formatting and printing an existing Groff document using any man pages on your Red Hat Linux system (such as those in /usr/share/man/*). (Those man pages are compressed, so you can copy them to a temporary directory and unzip them to try out Groff.)

These commands copy the chown man page to the /tmp directory and unzips it. Then, groff formats the chown man page in plain text so you can page through it on your screen.

$ cp /usr/share/man/man1/chown.1.gz /tmp
$ gunzip /tmp/chown.1.gz
$ groff -Tascii -man /tmp/chown.1 | less

In the previous example, the chown man page (chown.1.gz) is copied to the /tmp directory, is unzipped (using gunzip), and is output in plain text (-Tascii) using the man macros (-man). The output is piped to less, to page through it on your screen. Instead of piping to less ( | less), you could direct the output to a file (> /tmp/chown.txt).

To format a man page for typesetting, you could specify PostScript or HP LaserJet output. You should either direct the output to a file or to a printer. Here are a couple of examples:

$ groff -Tps -man /tmp/chown.1 > /tmp/chown.ps
$ groff -Tlj4 -man -l /tmp/chown.1

The first example creates PostScript output (-Tps) and directs it to a file called /tmp/chown.ps. That file can be read by a PostScript previewer (such as ghostscript) or sent to a printer (lpr /tmp/chown.ps). The next example creates HP LaserJet output (-Tlj4) and directs it to the default printer (-l option).

Creating a man page with Groff

Before HOW-TOs and info files, man pages were the foundation for information about UNIX (and UNIX-like) systems. Each command, file format, device, or other component either had its own man page or was grouped on a man page with similar components. To create your own man page requires that you learn a few macros (in particular, man macros). Figure 6-3 shows the source for a fictitious man page for a command called waycool.

Figure 6-3: Simple markup is required to create man pages.

A few other kinds of macros are used in the man page. The .IP macros format indented paragraphs for things such as options. The man page also contains some lower-level font requests; for example, \fB says to change the current font to bold, \fI changes the font to italic, and \fR changes it back to regular font. (This markup is better than asking for a particular font type because it just changes to bold, italic, or regular for the current font.) Figure 6-4 shows what the waycool man page looks like after it is formatted with groff:

Figure 6-4: Man page formatting adds headers and lays out the page of text.

$ groff -man -Tps -l waycool.1

Table 6-1 lists the macros that you can use on your man pages. These macros are described on the man(7) manual page (type man 7 man to view that page).

Creating a letter, memo, or white paper with Groff

Memorandum macros (which are used with the -mm option of Groff) were once popular among UNIX users for producing technical documents, letters, and memos. Although more modern word processors with a variety of WYSIWYG templates have made mm outdated, in a pinch mm can still be a quick way to create a typeset-style document in a text environment.

To format and print (to a PostScript printer) a document with mm macros, use the following:

$ groff -mm -Tps -l letter.mm

The following is a simple example of how to use mm macros to produce a letter:

.WA "Christopher T. Craft"
999 Anyway Way
Anytown, UT 84111 USA
.WE
.IA
John W. Doe
111 Notown Blvd.
Notown, UT 84111
.IE
.LO RN "Our telephone conversation"
.LO SA "Dear Mr. Doe:"
.LT
In reference to our telephone conversation on the 4th, I am calling to
confirm our upcoming appointment on the 18th. I look forward to
discussing the merger. I believe we have a win-win situation here.
.FC "Yours Truly,"
.SG

The output of the letter, if you use the groff command line mentioned in the paragraph preceding the code example, is shown in Figure 6-5.

Figure 6-5: Create a simple letter using mm macros.

The mm macros were often used to produce technical memos. The following is an example of a sign-off sheet that might go at the front of a larger technical memo.

.TL
Merger Technical Specifications
.AF "ABC Corporation"
.AU "Christopher Craft"
.AT "President"
.AS
This memo details the specifications for the planned merger.
.AE
.MT "Merger Description and Marching Orders"
As a result of our talks with XYZ corporation, we plan to go
forward with the merger. This document contains the following:
.BL
.LI
Schedule and time tables.
.LI
Financial statements.
.LI
Asset allocations.
.LE
.SP
Please add any corrections you have, then sign the approval line
indicated at the bottom of this sheet.
.FC
.SG
.AV "John W. Doe, XYZ Corporation President"
.AV "Sylvia Q. Public, XYZ Corporation CFO"
.NS
Everyone in the corporation.
.NE

Figure 6-6 shows the output of this memo.

Figure 6-6: Add headings and approval lines automatically to memos.

Adding equations, tables, and pictures

To interpret special macros for equations, tables, and line drawings, you can run separate commands (eqn, tbl, and pic commands) on the file before you run the groff command. Alternatively, you can add options to the groff command line to have the file preprocessed automatically by any of the commands (-e for eqn, -t for tbl, and -p for pic).

Here are some examples of EQN, TBL, and PIC markup included in a Groff document. The first example shows an equation that can be processed by eqn for a Groff document:

.EQ
a ~ mark = ~ 30
.EN
.sp
.EQ
a sup 2 ~ + ~ b sup 2~lineup = ~ 1000
.EN
.sp
.EQ
x sup 3 ~ + ~ y sup 3 ~ + ~ z sup 3~lineup = ~ 1400
.EN

If this appeared in a memo called memoeqn.mm, the memo would be preprocessed by eqn and then sent to the printer using the following command:

$ groff -Tps -l -mm -e memoeqn.mm

All data between the .EQ and .EN macros are interpreted as equations. The resulting output from the equation would appear as shown in Figure 6-7.

Figure 6-7: Produce equations in documents with the use of the eqn command's .EQ and .EN macros.

To create a table in a Groff document, use the .TS and .TE macros of the tbl preprocessor. The following is an example of the markup used to produce a simple table.

.TS
center, box, tab(:);
c s s
c | c | c
l | l | l.
Mergers and Acquisitions Team
=
Employee:Title:Location
=_
Jones, James:Marketing Manager:New York Office
Smith, Charles:Sales Manager:Los Angeles Office
Taylor, Sarah:R&D Manager:New York Office
Walters, Mark:Information Systems Manager:Salt Lake City Office
Zur, Mike:Distribution Manager:Portland Office
.TE

After the .TS macro starts the table, the next line indicates that the table should be centered on the page (center) and surrounded by a line box and that a colon will be used to separate the data into cells (tab(:)). The next line shows that the heading should be centered in the box (c) and should span across the next two cells (s s). The line after that indicates that the heading of each cell should be centered (c | c | c) and that the data cells that follow should be left justified (l | l | l).

The rest of the information in the table is the data. Note that the tab separators are colon characters (:). When the table is done, you end it with a .TE macro. If the table were in a memo called memotbl.mm, tbl could preprocess the memo and then send it to the printer using the following command:

$ groff -Tps -l -mm -t memotbl.mm

Data between .TS and .TE macros are interpreted as tables. Figure 6-8 displays this example.

Figure 6-8: Set how text is justified and put in columns with the use of the tbl command's .TS and .TE macros.

The PIC macros (.PS and .PE) let you to create simple diagrams and flow charts to use in Groff. PIC is really only qualified to create simple boxes, circles, ellipses, lines, arcs, splines, and some text. The following is some PIC code that could be in a Groff document:

.PS
box invis "Start" "Here"; arrow
box "Step 1"; arrow
circle "Step 2"; arrow
ellipse "Step 3"; arrow
box "Step 4"; arrow
box invis "End"
.PE

After the .PS, the first line indicates an invisible box (invis) that contains the words Start Here, followed by an arrow. That arrow connects to the next box containing the words Step 1. The next elements (connected by arrows) are a circle (Step 2), an ellipse (Step 3), another box (Step 4), and another invisible box (End). The .PE indicates the end of the pic drawing.

If these lines appeared in a document called memopic.mm, you could preprocess the PIC code and print the file using the following command:

$ groff -Tps -l -mm -p memopic.mm

Figure 6-9 shows an example of this drawing.

Figure 6-9: Create simple flow diagrams with the pic command's .PS and .PE macros.

Text processing with TeX/LaTeX

TeX is a collection of commands used primarily to produce scientific and mathematical typeset documents. The most common way to use TeX is by calling a macro package. The most popular macro package for Tex is LaTeX, which takes a higher-level approach to formatting TeX documents. TeX and LaTeX tools are contained in the tetex-latex package.

TeX interprets the LaTeX macros from the latex format file (latex.fmt). By default, the latex.fmt and plain.fmt format files are the only ones that are automatically built when the TeX package is installed. Other macro files that you can use with TeX include:

• 
  

  amstex — Mathematical publications, including The American Mathematical Society uses this as their official typesetting system.



• 
  

  eplain — Includes macros for indexing and table of contents.



• 
  

  texinfo — Macros used by the Free Software Foundation to produce software manuals. Text output from these macros can be used with the Red Hat Linux info command.

You can create a TeX/LaTeX file using any text editor. After the text and macros are created, you can run the tex command (or one of several other related utilities) to format the file. The input file is in the form filename.tex. The output is generally three different files:

• 
  

  filename.dvi — This is the device-independent output file that can be translated for use by several different types of output devices (such as PostScript).



• 
  

  filename.log — This is a log file that contains diagnostic messages.



• 
  

  filename.aux — This is an auxiliary file used by LaTeX.

The .dvi file produced can be formatted for a particular device. For example, you could use the dvips command to output the resulting .dvi file to your PostScript printer (dvips filename.dvi). Or you could use the xdvi command to preview the dvi file in X.

Creating and formatting a LaTeX document

Because LaTeX is the most common way of using TeX, this section describes how to create and format a LaTeX document. A LaTeX macro (often referred to as a command) appears in a document in one of the two following forms:

• 
  

  \string{option}[required] — First there is a backslash (\), which is followed by a string of characters. (Replace string with the name of the command.) Optional arguments are contained in braces ({}), and required arguments are in brackets ([]).



• 
  

  \?{option}[required] — First there is a backslash (\), which is followed by a single character that is not a letter. (Replace ? with the command character.) Optional arguments are contained in braces ({}), and required arguments are in brackets ([]).

Each command defines some action to be taken. The action can control page layout, the font used, spacing, paragraph layout, or a variety of other actions on the document. The minimum amount of formatting that a LaTeX document can contain is the following:

\documentclass{name}
\begin{document}
TEXT GOES HERE!
\end{document}

You should replace {name} with the name of the class of document you are creating. Valid document classes include article, book, letter, report, and slides. The text for the file, along with your formatting commands, goes between the begin and end document commands.

The best way to get started with LaTeX is to use the LyX editor. LyX provides a GUI for creating LaTeX documents. It also contains a variety of templates you can use instead of just creating a document from scratch. Figure 6-10 shows an example of the LyX editor.

Figure 6-10: Create LaTeX documents graphically with the LyX editor.