[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 03/03: doc/groff.texi: Revise tutorial chapter.
|
From: |
G. Branden Robinson |
|
Subject: |
[groff] 03/03: doc/groff.texi: Revise tutorial chapter. |
|
Date: |
Wed, 21 Jun 2023 00:44:10 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit e58bf113e2d48c14a2b84ee254853dc79e09afbf
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Jun 20 21:52:32 2023 -0500
doc/groff.texi: Revise tutorial chapter.
* Use @slanted instead of @dfn Texinfo command since we don't provide
authoritative, formal definitions of terms in this chapter.
* Clarify concept index entries.
* Note that Allman's meintro.me document remains available in groff.
* Stop telling people in general terms why they would follow a cross
reference. It's _always_ "for more info".
* Spead in terms of "alignment" and "adjustment", not "justification",
for consistency with our other documentation. (The implication of the
`rj` request name notwithstanding.)
* Distinguish major/full-service packages from minor/auxliary ones.
Offer cross reference to groff_tmac(5).
* Rename sections to modernize terminology or employ the terminology we
use in the rest of our documentation.
- "Displays" -> "Displays and Keeps"
- "Footnotes and Annotations" -> "Footnotes and Endnotes"
- "Paper Formats" -> "Document Formats"
- "Multiple Columns" -> "Columnation"
- "Indices" -> "Indexing"
- "Predefined Strings" -> "Predefined Text"
* Use Texinfo command @result to mark output examples, even where we
don't show input, for consistency with the rest of this manual.
* Use our Texinfo private macro @Example for examples, not the Texinfo
command @quotation.
* Clarify that lines starting with tabs cause a break.
* Present and distinguish "text lines" and "control lines".
* Say "GNU troff" instead of "gtroff". These days it is much less often
installed as the latter.
* When offering input advice, add forward reference to "Input
Conventions" section/node.
* Discuss vertical spacing in favor of line spacing. Drop discussion of
`ls` and `pvs` requests. Add forward reference to "Manipulating
Spacing" section/node.
* Where appropriate, discuss how packages for man page formatting differ
from most other full-service macro packages (generally by providing
fewer features).
* Add cautionary node about flipping willy-nilly between formatter
requests and package macros that place vertical space.
* Discuss `rj` request along with `ce`.
* Discuss presence and purpose of no-break control character.
* Drop discussion of "delayed text" (a me(7)-ism) in favor of
"endnotes".
* Drop discussion of "major quotes". This is another me(7)-ism that we
have renamed to "long quotations" in meref.me, but also it is not a
feature generally available by that name.
* Mention lists as an application of tagged paragraphs. Not all
full-service packages have list macros per se.
* Update discussion of tables of contents and indices. Suggest that
those rendering to PDF and wanting to relocate the TOC page might want
to read gropdf(1). See Savannah #64278.
* Explain why multi-pass formatting is necessary to solve certain
problems.
* Motivate preference for font selection macros over requests and escape
sequences.
* Tighten wording.
* Mark chapter as reviewed for correct grave accent and apostrophe
usage.
---
doc/groff.texi | 461 +++++++++++++++++++++++++++++++--------------------------
1 file changed, 252 insertions(+), 209 deletions(-)
diff --git a/doc/groff.texi b/doc/groff.texi
index 543aa2674..40cb4130c 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -1656,9 +1656,6 @@ groff -X -Z mydoc.t | gxditview -title 'trial run' -
are equivalent.
@c END Keep parallel with groff(1), section "Examples".
-@codequotebacktick off
-@codequoteundirected off
-
@c =====================================================================
@@ -1672,13 +1669,13 @@ are equivalent.
@cindex user's macro tutorial
Most users of the @code{roff} language employ a macro package to format
-their documents. Successful macro packages tend to ease the composition
+their documents. Successful macro packages ease the composition
process; their users need not have mastered the full formatting
-language, nor even some of its major features like diversions, traps,
-and environments. A familiarity with some basic concepts and mechanisms
-common to macro packages (like ``displays'') remains helpful; this
-chapter aims to bring you to this level. If you prefer a meticulous and
-comprehensive presentation, try @ref{GNU troff Reference} instead.
+language, nor understand features like diversions, traps, and
+environments. This chapter aims to familiarize you with basic concepts
+and mechanisms common to many macro packages (like ``displays''). If
+you prefer a meticulous and comprehensive presentation, try @ref{GNU
+troff Reference} instead.
@menu
* Basics::
@@ -1690,24 +1687,24 @@ comprehensive presentation, try @ref{GNU troff
Reference} instead.
@node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro
Users
@section Basics
-@cindex basics of macros
-@cindex macro basics
+@cindex basics of macro package usage
+@cindex macro package usage, basics of
-This section covers some of the basic concepts necessary to understand
-how to use a macro package.@footnote{This section is derived from
-@cite{Writing Papers with nroff using -me} by Eric@tie{}P.@: Allman.}
-References are made throughout to more detailed information, if desired.
+Let us first survey some basic concepts necessary to use a macro package
+fruitfully.@footnote{The remainder of this chapter is based on
+@cite{Writing Papers with nroff using -me} by Eric@tie{}P.@: Allman,
+which is distributed with @code{groff} as @file{meintro.me}.}
+References are made throughout to more detailed information.
GNU @code{troff} reads an input file prepared by the user and outputs a
formatted document suitable for publication or framing. The input
consists of text, or words to be printed, and embedded commands
-(@dfn{requests} and @dfn{escape sequences}), which tell GNU @code{troff}
-how to format the output. For more detail on this, see @ref{Formatter
-Instructions}.
+(@slanted{requests} and @slanted{escape sequences}), which tell GNU
+@code{troff} how to format the output. @xref{Formatter Instructions}.
-The word @dfn{argument} is used in this chapter to mean a word or number
-that appears on the same line as a request, and which modifies the
-meaning of that request. For example, the request
+The word @slanted{argument} is used in this chapter to mean a word or
+number that appears on the same line as a request, and which modifies
+the meaning of that request. For example, the request
@Example
.sp
@@ -1723,12 +1720,12 @@ spaces one line, but
@noindent
spaces four lines. The number@tie{}4 is an argument to the @code{sp}
request, which says to space four lines instead of one. Arguments are
-separated from the request and from each other by spaces (@emph{no}
+separated from the request and from each other by spaces (@emph{not}
tabs). @xref{Invoking Requests}.
-The primary function of @code{gtroff} is to collect words from input
-lines, fill output lines with those words, justify the right-hand margin
-by inserting extra spaces in the line, and output the result. For
+The primary function of GNU @code{troff} is to collect words from input
+lines, fill output lines with those words, adjust the line to the
+right-hand margin by widening spaces, and output the result. For
example, the input:
@Example
@@ -1743,34 +1740,33 @@ years ago, etc.
@noindent
is read, packed onto output lines, and justified to produce:
-@quotation
-Now is the time for all good men to come to the aid of their party.
-Four score and seven years ago, etc.
-@end quotation
+@Example
+ @result{} Now is the time for all good men to come to the aid of
+ @result{} their party. Four score and seven years ago, etc.
+@endExample
-@cindex break
-@cindex line break
Sometimes a new output line should be started even though the current
-line is not yet full; for example, at the end of a paragraph. To do
-this it is possible to cause a @dfn{break}, which starts a new output
-line. Some requests cause a break automatically, as normally do blank
-input lines and input lines beginning with a space.
-
-Not all input lines are text to be formatted. Some input lines are
-requests that describe how to format the text. Requests always have a
-period (@samp{.}) or an apostrophe (@samp{'}) as the first character of
-the input line.
-
-The text formatter also does more complex things, such as automatically
+line is not yet full---for example, at the end of a paragraph. To do
+this it is possible to force a @slanted{break}, starting a new output
+line. Some requests cause a break automatically, as do (normally) blank
+input lines and input lines beginning with a space or tab.
+
+Not all input lines are @slanted{text lines}---words to be formatted.
+Some are @slanted{control lines} that tell a macro package (or GNU
+@code{troff} directly) how to format the text. Control lines start with
+a dot (@samp{.}) or an apostrophe (@samp{'}) as the first character, and
+can be followed by a @slanted{macro call}.
+
+The formatter also does more complex things, such as automatically
numbering pages, skipping over page boundaries, putting footnotes in the
correct place, and so forth.
-Here are a few hints for preparing text for input to @code{gtroff}.
+Here are a few hints for preparing text for input to GNU @code{troff}.
@itemize @bullet
@item
First, keep the input lines short. Short input lines are easier to
-edit, and @code{gtroff} packs words onto longer lines anyhow.
+edit, and GNU @code{troff} packs words onto longer lines anyhow.
@item
In keeping with this, it is helpful to begin a new line after every
@@ -1779,35 +1775,38 @@ or phrases.
@item
End each sentence with two spaces---or better, start each sentence on a
-new line. @code{gtroff} recognizes characters that usually end a
+new line. GNU @code{troff} recognizes characters that usually end a
sentence, and inserts inter-sentence space accordingly.
@item
-Do not hyphenate words at the end of lines---@code{gtroff} is smart
+Do not hyphenate words at the end of lines---GNU @code{troff} is smart
enough to hyphenate words as needed, but is not smart enough to take
hyphens out and join a word back together. Also, words such as
``mother-in-law'' should not be broken over a line, since then a space
can occur where not wanted, such as ``@w{mother- in}-law''.
@end itemize
-@cindex double-spacing (@code{ls})
-@cindex spacing
-@code{gtroff} double-spaces output text automatically if you use the
-request @w{@samp{.ls 2}}. Reactivate single-spaced mode by typing
-@w{@samp{.ls 1}}.@footnote{If you need finer granularity of the vertical
-space, use the @code{pvs} request (@pxref{Changing the Type Size}).}
+We offer further advice in @ref{Input Conventions}.
-A number of requests allow you to change the way the output is arranged
-on the page, sometimes called the @dfn{layout} of the output page.
+@cindex vertical spacing (introduction)
+@cindex spacing, vertical (introduction)
+GNU @code{troff} permits alteration of the distance between lines of
+text. This is termed @slanted{vertical spacing} and is expressed in the
+same units as the type size---the point. The default is 10-point type
+on 12-point spacing. To get @slanted{double-spaced} text you would set
+the vertical spacing to 24 points. Some, but not all, macro packages
+expose a macro or register to configure the vertical spacing.
-@cindex new page (@code{bp})
-The @code{bp} request starts a new page, causing a line break.
+A number of requests allow you to change the way the output is arranged
+on the page, sometimes called the @slanted{layout} of the output page.
+Most macro packages don't supply macros for performing these (at least
+not without performing other actions besides), as they are such basic
+operations. The macro packages for writing man pages, @file{man} and
+@file{mdoc}, don't encourage explicit use of these requests at all.
-@cindex blank line (@code{sp})
-@cindex empty line (@code{sp})
-@cindex line, empty (@code{sp})
+@cindex spacing (introduction)
The request @w{@samp{.sp @var{N}}} leaves @var{N}@tie{}lines of blank
-space. @var{N}@tie{}can be omitted (meaning skip a single line) or can
+space. @var{N}@tie{}can be omitted (skipping a single line) or can
be of the form @var{N}i (for @var{N}@tie{}inches) or @var{N}c (for
@var{N}@tie{}centimeters). For example, the input:
@@ -1820,10 +1819,18 @@ My thoughts on the subject
@noindent
leaves one and a half inches of space, followed by the line ``My
thoughts on the subject'', followed by a single blank line (more
-measurement units are available, see @ref{Measurements}).
-
-@cindex centering lines (@code{ce})
-@cindex lines, centering (@code{ce})
+measurement units are available; see @ref{Measurements}).
+
+If you seek precision in spacing, be advised when using a macro package
+that it might not honor @code{sp} requests as you expect; it can use a
+formatter feature called @slanted{no-space mode} to prevent excess space
+from accumulating. Macro packages typically offer registers to control
+spacing between paragraphs, before section headings, and around displays
+(discussed below); use these facilities preferentially.
+@xref{Manipulating Spacing}.
+
+@cindex centering lines (introduction)
+@cindex lines, centering (introduction)
Text lines can be centered by using the @code{ce} request. The line
after @code{ce} is centered (horizontally) on the page. To center more
than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number
@@ -1837,14 +1844,29 @@ lines to center
@endExample
@noindent
-The @w{@samp{.ce 0}} request tells @code{groff} to center zero more
+The @w{@samp{.ce 0}} request tells GNU @code{troff} to center zero more
lines, in other words, stop centering.
-@cindex line break (@code{br})
-@cindex break (@code{br})
+@cindex right-aligning lines (introduction)
+@cindex lines, right-aligning (introduction)
+@cindex right-justifying lines (introduction)
+@cindex lines, right-justifying (introduction)
+GNU @code{troff} also offers the @code{rj} request for right-aligning
+text. It works analogously to @code{ce} and is convenient for setting
+epigraphs.
+
+@cindex page break (introduction)
+@cindex break, page (introduction)
+The @code{bp} request starts a new page; this necessarily implies an
+ordinary (line) break.
+
+@cindex break (introduction)
+@cindex line break (introduction)
All of these requests cause a break; that is, they always start a new
line. To start a new line without performing any other action, use
-@code{br}.
+@code{br}. If you invoke them with the apostrophe @samp{'}, the
+@slanted{no-break control character}, the (initial) break they normally
+perform is suppressed. @samp{'br} does nothing.
@c =====================================================================
@@ -1854,27 +1876,35 @@ line. To start a new line without performing any other
action, use
@cindex common features
@cindex features, common
-@code{gtroff} provides very low-level operations for formatting a
-document. There are many common routine operations that are done in
-all documents. These common operations are written into @dfn{macros}
-and collected into a @dfn{macro package}.
+GNU @code{troff} provides low-level operations for formatting a
+document. Many routine operations are undertaken in nearly all
+documents that require a series of such primitive operations to be
+performed. These common tasks are grouped into @slanted{macros}, which
+are then collected into a @slanted{macro package}.
+
+Macro packages come in two varieties:@: ``major'' or ``full-service''
+ones that manage page layout, and ``minor'' or ``auxiliary'' ones that
+do not, instead fulfilling narrow, specific tasks. Find a list in the
+@cite{groff_tmac@r{(5)}} man page. Type @samp{man groff_tmac} at the
+command line to view it.
-All macro packages provide certain common capabilities that fall into
-the following categories.
+We survey several capabilities of full-service macro package below.
+Each package employs its own macros to exercise them. For details,
+consult its man page or, for @file{ms}, see @ref{ms}.
@menu
* Paragraphs::
* Sections and Chapters::
* Headers and Footers::
* Page Layout Adjustment::
-* Displays::
-* Footnotes and Annotations::
+* Displays and Keeps::
+* Footnotes and Endnotes::
* Table of Contents::
-* Indices::
-* Paper Formats::
-* Multiple Columns::
+* Indexing::
+* Document Formats::
+* Columnation::
* Font and Size Changes::
-* Predefined Strings::
+* Predefined Text::
* Preprocessor Support::
* Configuration and Customization::
@end menu
@@ -1885,44 +1915,56 @@ the following categories.
@subsection Paragraphs
@cindex paragraphs
-One of the most common and most used capability is starting a paragraph.
-There are a number of different types of paragraphs, any of which can be
-initiated with macros supplied by the macro package. Normally,
-paragraphs start with a blank line and the first line indented, like the
-text in this manual. There are also block style paragraphs, which omit
-the indentation:
+Paragraphs can be separated and indented in various ways. Some start
+with a blank line and have a first-line indentation, like most of the
+ones in this manual. Block paragraphs omit the indentation.
@Example
-Some men look at constitutions with sanctimonious
-reverence, and deem them like the ark of the covenant, too
-sacred to be touched.
+ @result{} Some men look at constitutions with sanctimonious
+ @result{} reverence, and deem them like the ark of the
+ @result{} covenant, too sacred to be touched.
@endExample
+@cindex tags, paragraph
+@cindex tagged paragraphs
+@cindex lists
@noindent
-And there are also indented paragraphs, which begin with a tag or label
-at the margin and the remaining text indented.
+We also frequently encounter @slanted{tagged} paragraphs, which begin
+with a tag or label at the left margin and indent the remaining text.
@Example
-one This is the first paragraph. Notice how the first
- line of the resulting paragraph lines up with the
- other lines in the paragraph.
+ @result{} one This is the first paragraph. Notice how the
+ @result{} first line of the resulting paragraph lines
+ @result{} up with the other lines in the paragraph.
@endExample
+@noindent
+If the tag is too wide for the indentation, the line is broken.
+
+@Example
+ @result{} longlabel
+ @result{} The label does not align with the subsequent
+ @result{} lines, but they align with each other.
+@endExample
+
+@noindent
+A variation of the tagged paragraph is the itemized or enumerated
+paragraph, which might use punctuation or a digit for a tag,
+respectively. These are frequently used to construct lists.
+
@Example
-longlabel
- This paragraph had a long label. The first
- character of text on the first line does not line up
- with the text on second and subsequent lines,
- although they line up with each other.
+ @result{} o This list item starts with a bullet. When
+ @result{} producing output for a device using the ASCII
+ @result{} character set, an 'o' is formatted instead.
@endExample
-A variation of this is a bulleted list.
+@noindent
+Often, use of the same macro without a tag continues such a discussion.
@Example
-. Bulleted lists start with a bullet. It is possible
- to use other glyphs instead of the bullet. In nroff
- mode using the ASCII character set for output, a dot
- is used instead of a real bullet.
+ @result{} -xyz This option is recognized but ignored.
+ @result{}
+ @result{} It had a security hole that we don't discuss.
@endExample
@c ---------------------------------------------------------------------
@@ -1930,179 +1972,180 @@ A variation of this is a bulleted list.
@node Sections and Chapters, Headers and Footers, Paragraphs, Common Features
@subsection Sections and Chapters
-Most macro packages supply some form of section headers. The simplest
-kind is simply the heading on a line by itself in bold type. Others
-supply automatically numbered section heading or different heading
-styles at different levels. Some, more sophisticated, macro packages
-supply macros for starting chapters and appendices.
+The simplest kind of section heading is unnumbered, set in a bold or
+italic style, and occupies a line by itself. Others possess
+automatically numbered multi-level headings and/or different typeface
+styles or sizes at different levels. More sophisticated macro packages
+supply macros for designating chapters and appendices.
@c ---------------------------------------------------------------------
@node Headers and Footers, Page Layout Adjustment, Sections and Chapters,
Common Features
@subsection Headers and Footers
-Every macro package gives some way to manipulate the @dfn{headers} and
-@dfn{footers} (also called @dfn{titles}) on each page. This is text put
-at the top and bottom of each page, respectively, which contain data
-like the current page number, the current chapter title, and so on. Its
-appearance is not affected by the running text. Some packages allow for
-different ones on the even and odd pages (for material printed in a book
-form).
+@slanted{Headers} and @slanted{footers} occupy the top and bottom of
+each page, respectively, and contain data like the page number and the
+article or chapter title. Their appearance is not affected by the
+running text. Some packages allow for different titles on even- and
+odd-numbered pages (for printed, bound material).
-The titles are called @dfn{three-part titles}, that is, there is a
-left-justified part, a centered part, and a right-justified part. An
-automatically generated page number may be put in any of these fields
-with the @samp{%} character (@pxref{Page Layout}).
+Headers and footers are together called @slanted{titles}, and comprise
+three parts:@: left-aligned, centered, and right-aligned. A @samp{%}
+character appearing anywhere in a title is automatically replaced by the
+page number. @xref{Page Layout}.
@c ---------------------------------------------------------------------
-@node Page Layout Adjustment, Displays, Headers and Footers, Common Features
+@node Page Layout Adjustment, Displays and Keeps, Headers and Footers, Common
Features
@subsection Page Layout
-Most macro packages let the user specify top and bottom margins and
-other details about the appearance of the printed pages.
+Most macro packages let the user specify the size of the page margins.
+The top and bottom margins are typically handled differently than the
+left and right margins; the latter two are derived from the
+@slanted{page offset}, @slanted{indentation}, and @slanted{line length}.
+@xref{Line Layout}. Commonly, packages support registers to tune these
+values.
@c ---------------------------------------------------------------------
-@node Displays, Footnotes and Annotations, Page Layout Adjustment, Common
Features
-@subsection Displays
+@node Displays and Keeps, Footnotes and Endnotes, Page Layout Adjustment,
Common Features
+@subsection Displays and Keeps
@cindex displays
-@dfn{Displays} are sections of text to be set off from the body of the
-paper. Major quotes, tables, and figures are types of displays, as are
-all the examples used in this document.
-
-@cindex quotes, major
-@cindex major quotes
-@dfn{Major quotes} are quotes that are several lines long, and hence
-are set in from the rest of the text without quote marks around them.
-
-@cindex list
-A @dfn{list} is an indented, single-spaced, unfilled display. Lists
-should be used when the material to be printed should not be filled and
-justified like normal text, such as columns of figures or the examples
-used in this paper.
+@slanted{Displays} are sections of text set off from the surrounding
+material (typically paragraphs), often differing in indentation, and/or
+spacing. Tables, block quotations, and figures are displayed.
+Equations and code examples, when not much shorter than an output line,
+often are. Lists may or may not be. Packages for setting man pages
+support example displays but not keeps.
+@c XXX: man, mdoc keep support planned
-@cindex keep
-A @dfn{keep} is a display of lines that are kept on a single page if
-possible. An example for a keep might be a diagram. Keeps differ from
-lists in that lists may be broken over a page boundary whereas keeps are
-not.
+@cindex keeps (introduction)
+A @slanted{keep} is a group of output lines, often a display, that is
+formatted on a single page if possible; it causes a page break to happen
+early so as to not interrupt the kept material.
@cindex keep, floating
@cindex floating keep
-@dfn{Floating keeps} move relative to the text. Hence, they are good
-for things that are referred to by name, such as ``See figure@tie{}3''.
-A floating keep appears at the bottom of the current page if it fits;
-otherwise, it appears at the top of the next page. Meanwhile, the
-surrounding text `flows' around the keep, thus leaving no blank areas.
+@slanted{Floating keeps} can move, or ``float'', relative to the text
+around them in the input. They are useful for displays that are
+captioned and referred to by name, as with ``See figure@tie{}3''.
+Depending on the package, a floating keep appears at the bottom of the
+current page if it fits, and at the top of the next otherwise.
+Alternatively, floating keeps might be deferred to the end of a section.
+Using a floating keep can avoid the large vertical spaces that may
+precede a tall keep of the ordinary sort when it won't fit on the page.
@c ---------------------------------------------------------------------
-@node Footnotes and Annotations, Table of Contents, Displays, Common Features
-@subsection Footnotes and Annotations
+@node Footnotes and Endnotes, Table of Contents, Displays and Keeps, Common
Features
+@subsection Footnotes and Endnotes
@cindex footnotes
-@cindex annotations
+@cindex endnotes
-There are a number of requests to save text for later printing.
-
-@dfn{Footnotes} are printed at the bottom of the current page.
-
-@cindex delayed text
-@dfn{Delayed text} is very similar to a footnote except that it is
-printed when called for explicitly. This allows a list of references to
-appear (for example) at the end of each chapter, as is the convention in
-some disciplines.
-
-Most macro packages that supply this functionality also supply a means
-of automatically numbering either type of annotation.
+@slanted{Footnotes} and @slanted{endnotes} are forms of delayed
+formatting. They are recorded at their points of relevance in
+the input, but not formatted there. Instead, a @slanted{mark} cues the
+reader to check the ``foot'', or bottom, of the current page, or in the
+case of endnotes, an annotation list later in the document. Macro
+packages that support these features also supply a means of
+automatically numbering either type of annotation.
@c ---------------------------------------------------------------------
-@node Table of Contents, Indices, Footnotes and Annotations, Common Features
+@node Table of Contents, Indexing, Footnotes and Endnotes, Common Features
@subsection Table of Contents
@cindex table of contents
@cindex contents, table of
-@dfn{Tables of contents} are a type of delayed text having a tag
-(usually the page number) attached to each entry after a row of dots.
-The table accumulates throughout the paper until printed, usually after
-the paper has ended. Many macro packages provide the ability to have
-several tables of contents (e.g., a standard table of contents, a list
-of tables, etc).
+A package may handle a @slanted{table of contents} by directing section
+heading macros to save section heading text and the page number where it
+occurs for use in a later @slanted{entry} for a table of contents. It
+writes the collected entries at the end of the document, once all are
+known, upon request. A row of dots (a @slanted{leader}) bridges the
+text on the left with its location on the right. Other collections
+might work in this manner, providing lists of figures or tables.
+
+A table of contents is often found at the end of a GNU @code{troff}
+document because the formatter processes the document in a single pass.
+The @command{gropdf} output driver supports a PDF feature that relocates
+pages at the time the document is rendered; see the @cite{gropdf@r{(1)}}
+man page. Type @samp{man gropdf} at the command line to view it.
@c ---------------------------------------------------------------------
-@node Indices, Paper Formats, Table of Contents, Common Features
-@subsection Indices
+@node Indexing, Document Formats, Table of Contents, Common Features
+@subsection Indexing
@cindex index, in macro package
-While some macro packages use the term @dfn{index}, none actually
-provide that functionality. The facilities they call indices are
-actually more appropriate for tables of contents.
-
@pindex makeindex
-To produce a real index in a document, external tools like the
-@code{makeindex} program are necessary.
+An index is similar to a table of contents, in that entry labels and
+locations must be collected, but poses a greater challenge because it
+needs to be sorted before it is output. Here, processing the document
+in multiple passes is inescapable, and tools like the @code{makeindex}
+program are necessary.
@c ---------------------------------------------------------------------
-@node Paper Formats, Multiple Columns, Indices, Common Features
-@subsection Paper Formats
-@cindex paper formats
+@node Document Formats, Columnation, Indexing, Common Features
+@subsection Document Formats
+@cindex document formats
-Some macro packages provide stock formats for various kinds of
-documents. Many of them provide a common format for the title and
-opening pages of a technical paper. The @file{mm} macros in particular
-provide formats for letters and memoranda.
+Some macro packages supply stock configurations of certain documents,
+like business letters and memoranda. These often also have provision
+for a @slanted{cover sheet}, which may be rigid in its format. With
+these features, it is even more important to use the package's macros in
+preference to the formatter requests presented earlier, where possible.
@c ---------------------------------------------------------------------
-@node Multiple Columns, Font and Size Changes, Paper Formats, Common Features
-@subsection Multiple Columns
+@node Columnation, Font and Size Changes, Document Formats, Common Features
+@subsection Columnation
-Some macro packages (but not @file{man}) provide the ability to have two
-or more columns on a page.
+Macro packages apart from @file{man} and @file{mdoc} for man page
+formatting offer a facility for setting multiple columns on the page.
@c ---------------------------------------------------------------------
-@node Font and Size Changes, Predefined Strings, Multiple Columns, Common
Features
+@node Font and Size Changes, Predefined Text, Columnation, Common Features
@subsection Font and Size Changes
-The built-in font and size functions are not always intuitive, so all
-macro packages provide macros to make these operations simpler.
+The formatter's requests and escape sequences for setting the typeface
+and size are not always intuitive, so all macro packages provide macros
+to make these operations simpler. They also make it more convenient to
+change typefaces in the middle of a word and can handle italic
+corrections automatically. @xref{Italic Corrections}.
@c ---------------------------------------------------------------------
-@node Predefined Strings, Preprocessor Support, Font and Size Changes, Common
Features
-@subsection Predefined Strings
+@node Predefined Text, Preprocessor Support, Font and Size Changes, Common
Features
+@subsection Predefined Text
-Most macro packages provide various predefined strings for a variety of
-uses; examples are sub- and superscripts, printable dates, quotes and
-various special characters.
+Most macro packages supply predefined strings to set prepared text like
+the date, or to perform operations like super- and subscripting.
@c ---------------------------------------------------------------------
-@node Preprocessor Support, Configuration and Customization, Predefined
Strings, Common Features
+@node Preprocessor Support, Configuration and Customization, Predefined Text,
Common Features
@subsection Preprocessor Support
All macro packages provide support for various preprocessors and may
-extend their functionality.
-
-For example, all macro packages mark tables (which are processed with
-@code{gtbl}) by placing them between @code{TS} and @code{TE} macros.
-The @file{ms} macro package has an option, @samp{.TS@tie{}H}, that
-prints a caption at the top of a new page (when the table is too long to
-fit on a single page).
+extend their functionality by defining macros to set their contents in
+displays. Examples include @code{TS} and @code{TE} for @command{gtbl},
+@code{EQ} and @code{EN} for @command{geqn}, and @code{PS} and @code{PE}
+for @command{gpic}.
@c ---------------------------------------------------------------------
@node Configuration and Customization, , Preprocessor Support, Common Features
@subsection Configuration and Customization
-Some macro packages provide means of customizing many of the details of
-how the package behaves. This ranges from setting the default type size
-to changing the appearance of section headers.
+Packages provide means of customizing many of the details of how the
+package behaves. These range from setting the default type size to
+changing the appearance of section headers.
+
+@codequotebacktick off
+@codequoteundirected off
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 03/03: doc/groff.texi: Revise tutorial chapter.,
G. Branden Robinson <=