From 29925e098c774d57995b387978dcfad39030c051 Mon Sep 17 00:00:00 2001 From: Werner LEMBERG Date: Thu, 24 Feb 2000 18:01:48 +0000 Subject: [PATCH] * doc/groff.texinfo: Further checking/updating. Adding more index entries. --- ChangeLog | 3 +- doc/groff.texinfo | 243 ++++++++++++++++++++++++++++++++++-------------------- 2 files changed, 154 insertions(+), 92 deletions(-) diff --git a/ChangeLog b/ChangeLog index 31dd291b..cd8d3e67 100644 --- a/ChangeLog +++ b/ChangeLog @@ -3,7 +3,8 @@ * src/preproc/grn/main.cc: Introduce BASE_THICKNESS, defining line thicknesses to be integer multiples of this value. - * doc/groff.texinfo: Further checking/updating. + * doc/groff.texinfo: Further checking/updating. Adding more index + entries. 2000-02-23 Werner LEMBERG diff --git a/doc/groff.texinfo b/doc/groff.texinfo index 9d1cf1bf..fe6a1aac 100644 --- a/doc/groff.texinfo +++ b/doc/groff.texinfo @@ -10,7 +10,7 @@ @c We use the following indices: @c @c cindex: concepts -@c findex: requests +@c findex: requests, escapes, and functions @c vindex: registers @c pindex: programs @c tindex: environment variables @@ -619,10 +619,12 @@ impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in @section History @cindex history +@cindex @code{runoff} @code{troff} can trace its origins back to a formatting program called @code{runoff} which ran on MIT's CTSS system. This name came from the common phrase of the time ``I'll run off a document.'' +@cindex @code{roff} The first version of @sc{Unix} was developed on a PDP-7 which was sitting around Bell Labs. In 1971 the developers wanted to get a PDP-11 for further work on the operating system. In order to justify the cost @@ -632,6 +634,7 @@ program was a reimplementation of @code{runoff}. In accordance with @sc{Unix}'s penchant for abreviations, it was named @code{roff} (an abreviation of @code{runoff}). +@cindex @code{nroff} When they needed a more flexible language, a new version of @code{roff} called @code{nroff} (Newer @code{roff}) was written. It had a much more complicated syntax, but provided the basis for all future versions. @@ -668,6 +671,7 @@ other devices became a priority. However, before this could be done, he was killed in an auto accident. @pindex ditroff +@cindex @code{ditroff} So, Brian Kernighan took on the task of rewriting @code{troff}. The newly rewritten version produced a device independent code which was very easy for postprocessors to read and translate to the appropriate @@ -1203,10 +1207,10 @@ understand to use a macro package.@footnote{This section is derived from @cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman.} References are made throughout to more detailed information, if desired. -@code{groff} reads an input file prepared by the user and outputs a +@code{gtroff} reads an input file prepared by the user and outputs a formatted paper suitable for publication or framing. The input consists of text, or words to be printed, and embedded commands (@dfn{requests} -and @dfn{escapes}), which tell @code{groff} how to format the printed +and @dfn{escapes}), which tell @code{gtroff} how to format the printed copy. For more detail on this @pxref{Embedded Commands}. The word @dfn{argument} is used in this manual to mean a word or number @@ -1230,7 +1234,7 @@ request which says to space four lines instead of one. Arguments are separated from the request and from each other by spaces. More details on this can be found in @ref{Request Arguments}. -The primary function of @code{groff} is to collect words from input +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 example, the input: @@ -1269,13 +1273,13 @@ The text 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 a few hints for preparing text for input to @code{groff}. First, +Here a few hints for preparing text for input to @code{gtroff}. First, keep the input lines short. Short input lines are easier to edit, and -@code{groff} will pack words onto longer lines for you anyhow. In +@code{gtroff} will pack words onto longer lines for you anyhow. In keeping with this, it is helpful to begin a new line after every period, comma, or phrase, since common corrections are to add or delete sentences or phrases. Secondly, do not hyphenate words at the end of -lines---@code{groff} is smart enough to hyphenate words for you as +lines---@code{gtroff} is smart enough to hyphenate words for you 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 you will get a space where not wanted, such as @@ -1284,7 +1288,7 @@ over a line, since then you will get a space where not wanted, such as @findex ls @cindex double spacing @cindex spacing -@code{groff} will double space output text automatically if you use the +@code{gtroff} will double space output text automatically if you use the request @w{@samp{.ls 2}}. You can revert to single spaced mode by typing @w{@samp{.ls 1}}. @@ -1348,7 +1352,7 @@ action, use @samp{.br}. @cindex common features @cindex features, common -@code{groff} provides very low level operations for formatting a +@code{gtroff} provides very low level operations for formatting a document. There are many common routine operations which are done in all documents. These common operations are written into @dfn{macros} and collected into a @dfn{macro package}. @@ -1578,7 +1582,7 @@ This chapter documents the main macro packages that come with @cindex programming tutorial @cindex tutorial for programming -This chapter covers @strong{all} of the facilities of @code{groff}. If +This chapter covers @strong{all} of the facilities of @code{gtroff}. If you are intending to use a macro package, you probably do not want to read this chapter. @@ -1621,10 +1625,11 @@ read this chapter. @section Text @cindex text -@code{groff} input files contain text with control commands interspersed -throughout. But, even without control codes, @code{groff} will still do -several things with your text: filling and adjusting, adding additional -space after sentences, hyphenating and inserting implicit line breaks. +@code{gtroff} input files contain text with control commands +interspersed throughout. But, even without control codes, @code{gtroff} +will still do several things with your text: filling and adjusting, +adding additional space after sentences, hyphenating and inserting +implicit line breaks. @menu * Filling and Adjusting:: @@ -1764,7 +1769,7 @@ be discussed later. Since @code{gtroff} does filling automatically, it is traditional in @code{groff} not to try and type things in as nicely formatted paragraphs. These are some conventions commonly used when typing -@code{groff} text: +@code{gtroff} text: @itemize @bullet{} @item @@ -1904,58 +1909,109 @@ attach a scaling indicator. @code{gtroff} has most of operators common to other languages: +@c XXX more details; examples + @itemize @bullet @item -Arithmetic: +, -, /, *, % +@cindex arithmetic operators +@cindex operators, arithmetic +@findex + +@findex - +@findex / +@findex * +@findex % +Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/} +(division), @samp{*} (multiplication), @samp{%} (modulo). @item -Comparison: <, >, >=, <=, =, == (the last two are the same) +@cindex comparison operators +@cindex operators, comparison +@findex < +@findex > +@findex >= +@findex <= +@findex = +@findex == +Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=} +(less than or equal), @samp{>=} (greater than or equal), @samp{=} +(equal), @samp{==} (the same as @samp{=}). @item -Logical: &, : +@cindex logical operators +@cindex operators, logical +@findex & +@findex : +Logical: @samp{&} (logical and), @samp{:} (logical or). @item -Unary operators: -, +, ! (if/while only??) +@cindex unary operators +@cindex operators, unary +@findex - +@findex + +@findex ! +Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+} +(just for completeness; does nothing in expressions), @samp{!} (logical +not). See below for the use of unary operators in motion requests. +@c XXX (if/while only??) @item -Maximum and minimum: >?, ? +@findex ?} (maximum), @samp{?3} yields@w{ }@samp{5}. +@c XXX add example @item -Scaling: (@var{c};@var{e}) -Evaluate @var{e} using @var{c} as the default scaling indicator. -If @var{c} is missing, ignore scaling indicators in the -evaluation of @var{e}. +@cindex scaling operator +@cindex operator, scaling +Scaling: @code{(@var{c};@var{e})}. Evaluate @var{e} using @var{c} as +the default scaling indicator. If @var{c} is missing, ignore scaling +indicators in the evaluation of @var{e}. @end itemize -Parenthesis may be used as in any other language. -However, in groff they are necessary to ensure order of evaluation. -Groff has no operator precedence, -expressions are evaluated left to right. -This means that @samp{3+5*4} is evaluated as if it were parenthesized -like @samp{(3+5)*4}, not as @samp{3+(5*4)}, like you may expect. - -For many requests which cause a motion on the page, the unary -operators work differently. -The @samp{+} and @samp{-} operators indicate a motion relative to the -current position (down or up, respectively). The @samp{|} operator -indicates an absolute position on the page or input line. (????) -@code{+} and @code{-} are also treated differently by @code{nr} (?) +@cindex parentheses +@findex ( +@findex ) +Parentheses may be used as in any other language. However, in +@code{gtroff} they are necessary to ensure order of evaluation. +@code{gtroff} has no operator precedence; expressions are evaluated left +to right. This means that @samp{3+5*4} is evaluated as if it were +parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, like you may +expect. + +@findex + +@findex - +@findex | +@cindex motion operators +@cindex operators, motion +For many requests which cause a motion on the page, the unary operators +work differently. The @samp{+} and @samp{-} operators indicate a motion +relative to the current position (down or up, respectively). The +@samp{|} operator indicates an absolute position on the page or input +line. +@c XXX (????) +@samp{+} and @samp{-} are also treated differently by the @code{nr} +request. +@c XXX (?), add xref +@cindex space characters in expressions +@cindex expressions and space characters Due to the way arguments are parsed, spaces are not allowed in -expressions, unless the entire expression is surrounded by parenthesis. +expressions, unless the entire expression is surrounded by parentheses. -@c distribute these through the text -@xref{Request Arguments} -@c distribute these through the text -@xref{Conditionals and Loops} +@xref{Request Arguments}, and @ref{Conditionals and Loops}. @node Identifiers, Embedded Commands, Expressions, Programming Tutorial @section Identifiers @cindex identifiers -Like any other language troff, has rules for properly formed -identifiers. -In troff an identifier can be made up of most any printable -character. -The only exception is characters which are interpreted by troff -(backslash, square bracket and ?). So, for example, any of the following -are valid. +@findex \ +@findex [ +@findex ] +@findex ? +Like any other language, @code{gtroff} has rules for properly formed +@dfn{identifiers}. In @code{gtroff} an identifier can be made up of +almost any printable character. The only exception are characters which +are interpreted by @code{gtroff} (backslash, square brackets, and +@samp{?}). So, for example, any of the following is valid. @example br @@ -1965,38 +2021,40 @@ end-list @@_ @end example -You can test whether an identifier is valid in groff with the -@code{\A} escape. It expands to 1 or 0 according whether its argument -(given in quotes) is or is not acceptable as the name of a string, -macro, diversion, number register, environment or font. It will return -0 if no argument is given. This is useful if you want to lookup user -input in some sort of associative table. - -Identifiers in groff can be any length, but, in some contexts, -groff needs to told -where identifiers end and text begins (and in different ways -depending on their length) - +@findex \A +You can test whether an identifier is valid in @code{gtroff} with the +@code{\A} escape. It expands to@w{ }1 or@w{ }0 according to whether its +argument (given in quotes) is or is not acceptable as the name of a +string, macro, diversion, number register, environment, or font. It +will return@w{ }0 if no argument is given. This is useful if you want +to look up user input in some sort of associative table. + +@c XXX add xrefs above + +Identifiers in @code{gtroff} can be any length, but, in some contexts, +@code{gtroff} needs to be told where identifiers end and text begins +(and in different ways depending on their length). + +@findex ( +@findex [ +@findex ] @itemize @bullet{} @item -Single character +Single character. @item -Two characters -Must be prefixed with @samp{(} in some situations. +Two characters. Must be prefixed with @samp{(} in some situations. @item -Arbitrary length (groff only) -Must be bracketed with @samp{[}, @samp{]} in some situations. -Any length identifier can be put in brackets. +Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[} +and@w{ }@samp{]} in some situations. Any length identifier can be put +in brackets. @end itemize Unlike many other programming languages, undefined identifiers are silently ignored or expanded to nothing. +@c XXX add info about -ww command line option. -@c distribute these through the text -@xref{Interpolating Registers} -@c distribute these through the text -@xref{Strings} +@xref{Interpolating Registers}, and @ref{Strings}. @node Embedded Commands, Registers, Identifiers, Programming Tutorial @@ -2004,18 +2062,19 @@ silently ignored or expanded to nothing. @cindex embedded commands @cindex commands, embedded -With most documents you need more funtionality beyond filling, -adjusting and implicit line breaking. -In order to gain further functionality, groff allows commands to be -embeded into your text, in two ways. +With most documents you need more funtionality beyond filling, adjusting +and implicit line breaking. In order to gain further functionality, +@code{gtroff} allows commands to be embedded into your text, in two +ways. The first is a @dfn{request} which takes up an entire line, and does -some large scale operation (e.g. break lines, start new pages). +some large scale operation (e.g.@: break lines, start new pages). -The other is an @dfn{escape} which can be embedded anywhere -in your text, or even as an argument to a request. (Not always?) -Escapes generally do more minor operations like sub- and super- -scripts, print a symbol, &c. +The other is an @dfn{escape} which can be embedded anywhere in your +text, or even as an argument to a request. +@c XXX (Not always?) +Escapes generally do more minor operations like sub- and superscripts, +print a symbol, etc. @menu * Requests:: @@ -2029,21 +2088,23 @@ scripts, print a symbol, &c. @cindex control character @cindex character, control -A request line begins with a control character, -which is either a single quote (@samp{'}) or a period (@samp{.}). -These can be changed @pxref{Character Translations}, for details. -After this there may be optional tabs or spaces followed by an -identifier which is the name of the request. -This may be followed by any number of space separated arguments. +@findex ' +@findex . +A request line begins with a control character, which is either a single +quote (@samp{'}) or a period (@samp{.}). These can be changed; +@xref{Character Translations}, for details. After this there may be +optional tabs or spaces followed by an identifier which is the name of +the request. This may be followed by any number of space separated +arguments. @findex \& If you want to begin a line with a control character without it being -interpreted, precede it with a @code{\&}. This represents a zero -width space, which means it will not affect you output. +interpreted, precede it with @samp{\&}. This represents a zero width +space, which means it will not affect your output. -In most cases you will use the period as a control character. -Several requests will cause a break, using the single quote control -character will prevent this. +In most cases you will use the period as a control character. Several +requests will cause a break; using the single quote control character +will prevent this. @menu * Request Arguments:: -- 2.11.4.GIT