diff options
Diffstat (limited to 'doc/groff.texinfo')
| -rw-r--r-- | doc/groff.texinfo | 282 |
1 files changed, 173 insertions, 109 deletions
diff --git a/doc/groff.texinfo b/doc/groff.texinfo index 902ce9a2..8be63d03 100644 --- a/doc/groff.texinfo +++ b/doc/groff.texinfo @@ -79,8 +79,7 @@ instead of in the original English. @page @vskip 0pt plus 1filll -Copyright @copyright{} 1994-2000 Free Software Foundation, Inc. - +Copyright @copyright@w{ }1994-2000 Free Software Foundation,@w{ }Inc. @sp 2 Version 1.16 of @code{groff}, @* Spring 2000 @@ -96,10 +95,10 @@ preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the -section entitled ``GNU General Public License'' is included -exactly as in the original, and provided that the entire resulting -derived work is distributed under the terms of a permission notice -identical to this one. +section entitled ``GNU General Public License'' is included exactly as +in the original, and provided that the entire resulting derived work is +distributed under the terms of a permission notice identical to this +one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, @@ -128,18 +127,10 @@ contributions are welcome. Send them to bug-groff@@gnu.org. * Introduction:: * Invoking groff:: * Tutorial for Macro Users:: -* -man:: -* -ms:: -* -me:: -* -mm:: +* Macro Packages:: * Programming Tutorial:: -* geqn:: -* gtbl:: -* gpic:: -* grap:: -* grefer:: -* gsoelim:: -* Devices:: +* Preprocessors:: +* Output Devices:: * File formats:: * Installation:: * Request Index:: @@ -158,8 +149,8 @@ contributions are welcome. Send them to bug-groff@@gnu.org. @center Version 2, June 1991 @display -Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. -59 Temple Place, Suite 330, Boston, MA 02111, USA +Copyright @copyright{}@w{ }1989, 1991 Free Software Foundation, Inc. +59@w{ }Temple Place, Suite@w{ }330, Boston, MA@w{ }02111, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. @@ -303,27 +294,29 @@ scope of this License. @item You may copy and distribute the Program (or a work based on it, under Section@w{ }2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: +Sections@w{ }1 and@w{ }2 above provided that you also do one of the +following: @enumerate a @item Accompany it with the complete corresponding machine-readable source -code, which must be distributed under the terms of Sections 1 and 2 -above on a medium customarily used for software interchange; or, +code, which must be distributed under the terms of Sections@w{ }1 and@w{ +}2 above on a medium customarily used for software interchange; or, @item Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the -corresponding source code, to be distributed under the terms of Sections -1 and 2 above on a medium customarily used for software interchange; or, +corresponding source code, to be distributed under the terms of +Sections@w{ }1 and@w{ }2 above on a medium customarily used for software +interchange; or, @item Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with -Subsection b above.) +Subsection@w{ }b above.) @end enumerate The source code for a work means the preferred form of the work for @@ -490,19 +483,19 @@ the exclusion of warranty; and each file should have at least the @var{one line to give the program's name and an idea of what it does.} Copyright (C) 19@var{yy} @var{name of author} -This program is free software; you can redistribute it and/or modify it -under the terms of the GNU General Public License as published by the -Free Software Foundation; either version 2 of the License, or (at your -option) any later version. +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or (at +your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU General Public License for more details. -You should have received a copy of the GNU General Public License along -with this program; if not, write to the Free Software Foundation, Inc., -59 Temple Place, Suite 330, Boston, MA 02111, USA. +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA. @end smallexample Also add information on how to contact you by electronic and paper mail. @@ -513,15 +506,15 @@ when it starts in an interactive mode: @smallexample Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type -`show w'. This is free software, and you are welcome to redistribute it -under certain conditions; type `show c' for details. +`show w'. This is free software, and you are welcome to redistribute +it under certain conditions; type `show c' for details. @end smallexample -The hypothetical commands @samp{show w} and @samp{show c} should show -the appropriate parts of the General Public License. Of course, the -commands you use may be called something other than @samp{show w} and -@samp{show c}; they could even be mouse-clicks or menu items---whatever -suits your program. +The hypothetical commands @samp{show@w{ }w} and @samp{show@w{ }c} should +show the appropriate parts of the General Public License. Of course, +the commands you use may be called something other than @samp{show@w{ +}w} and @samp{show@w{ }c}; they could even be mouse-clicks or menu +items---whatever suits your program. You should also get your employer (if you work as a programmer) or your school, if any, to sign a ``copyright disclaimer'' for the program, if @@ -529,13 +522,11 @@ necessary. Here is a sample; alter the names: @smallexample @group -Yoyodyne, Inc., hereby disclaims all copyright -interest in the program `Gnomovision' -(which makes passes at compilers) written -by James Hacker. +Yoyodyne, Inc., hereby disclaims all copyright interest in the program +`Gnomovision' (which makes passes at compilers) written by James +Hacker. -@var{signature of Ty Coon}, 1 April 1989 -Ty Coon, President of Vice +@var{signature of Ty Coon}, 1 April 1989 Ty Coon, President of Vice @end group @end smallexample @@ -562,9 +553,9 @@ entrenched in the @sc{Unix} community. * What Is groff?:: * History:: * groff Capabilities:: -* Macro Packages:: -* Preprocessors:: -* Postprocessors:: +* Macro Package Intro:: +* Preprocessor Intro:: +* Output device intro:: * Credits:: @end menu @@ -576,7 +567,7 @@ entrenched in the @sc{Unix} community. @code{groff} is of an older generation of document preparation systems, which operate more like compilers than the more recent interactive -WYSIWYG @footnote{What You See Is What You Get} systems. @code{groff} +WYSIWYG@footnote{What You See Is What You Get} systems. @code{groff} and its contemporary counterpart, @TeX{}, both work using a @dfn{batch} paradigm: The input (or @dfn{source}) files are normal text files with embedded formatting commands. These files can then be processed by @@ -711,9 +702,14 @@ a document (@code{grog}). It was declared a stable (i.e.@: non beta) package with the release of version@w{ }1.04 around November@w{ }1991. +Beginning in@w{ }1999, @code{groff} has new maintainers (the package was +an orphan for a few years). As a result, new features and programs like +@code{grn}, a preprocessor for gremlin images, and @code{grohtml}, an +output device to produce HTML output, have been added. + -@node groff Capabilities, Macro Packages, History, Introduction +@node groff Capabilities, Macro Package Intro, History, Introduction @section @code{groff} Capabilities @cindex @code{groff} capabilities @cindex capabilities of @code{groff} @@ -765,7 +761,7 @@ Output and error messages @end itemize -@node Macro Packages, Preprocessors, groff Capabilities, Introduction +@node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction @section Macro Packages @cindex macro packages @@ -776,10 +772,10 @@ operations (e.g.@w{ }starting paragraphs, printing headers and footers, etc.)@: should be done. These macros can be collected together into a @dfn{macro package}. There are a number of macro packages available; the most common (and the ones described in this manual) are @code{-man}, -@code{-me}, @code{-ms}, and @code{-mm}. +@code{-mdoc}, @code{-me}, @code{-ms}, and @code{-mm}. -@node Preprocessors, Postprocessors, Macro Packages, Introduction +@node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction @section Preprocessors @cindex preprocessors @@ -799,27 +795,31 @@ preprocessors to use. @code{groff} currently has preprocessors for producing tables (@code{tbl}), typesetting equations (@code{eqn}), drawing pictures -(@code{pic}), and for processing bibliographies (@code{refer}). An -associated program which is useful when dealing with preprocessors is -@code{soelim}. +(@code{pic} and @code{grn}), and for processing bibliographies +(@code{refer}). An associated program which is useful when dealing with +preprocessors is @code{soelim}. There are other preprocessors in existence, but there are, unfortunately, no free implementations available. They are for drawing -pictures (@code{ideal} and @code{gremlin}), for drawing graphs +pictures (@code{ideal}), for drawing graphs (@code{grap}), and chemical structures (@code{chem}). +A free implementation of @code{grap}, a preprocessor for drawing graphs, +can be obtained as an extra package. -@node Postprocessors, Credits, Preprocessors, Introduction -@section Postprocessors +@node Output device intro, Credits, Preprocessor Intro, Introduction +@section Output Devices @cindex postprocessors +@cindex output devices +@cindex devices for output @code{groff} actually produces device independent code which may be fed into a postprocessor which will produce output for a particular device. Currently, @code{groff} has postprocessors for PostScript, ascii -terminals, X@w{ }windows (for previewing), @TeX{} DVI format, and HTML. +terminals, X@w{ }Windows (for previewing), @TeX{} DVI format, and HTML. -@node Credits, , Postprocessors, Introduction +@node Credits, , Output device intro, Introduction @section Credits @cindex credits @@ -866,6 +866,7 @@ don't contain proprietary software, this prefix is omitted since GNU @pindex gtroff @pindex gpic @pindex geqn +@pindex ggrn @pindex gtbl @pindex grefer @pindex gsoelim @@ -873,20 +874,20 @@ don't contain proprietary software, this prefix is omitted since GNU Normally it runs the @code{gtroff} program and a postprocessor appropriate for the selected device. The default device is @samp{ps}. It can optionally preprocess with any of @code{gpic}, @code{geqn}, -@code{gtbl}, @code{grefer}, or @code{gsoelim}. +@code{gtbl}, @code{ggrn}, @code{grefer}, or @code{gsoelim}. -This section only documents options to the @code{groff} front end. Many -of the arguments to @code{groff} are passed on to @code{gtroff}, +This section only documents options to the @code{groff} front end. +Many of the arguments to @code{groff} are passed on to @code{gtroff}, therefore those are also included. Arguments to pre- or postprocessors can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking -gtbl}, @ref{Invoking grefer}, @ref{Invoking gsoelim}, @ref{Invoking -grotty}, @ref{Invoking grops}, @ref{Invoking grohtml}, @ref{Invoking -grodvi}, and @ref{Invoking gxditview} +gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking +gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking +grohtml}, @ref{Invoking grodvi}, and @ref{Invoking gxditview} The command line format for @code{groff} is: @example -groff [ -abehilpstvzCENRSVXZ ] [ -F@var{dir} ] [ -m@var{name} ] +groff [ -abeghilpstvzCENRSVXZ ] [ -F@var{dir} ] [ -m@var{name} ] [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ] [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ] [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] @@ -918,6 +919,8 @@ Print a help message. Preprocess with @code{geqn}. @item -t Preprocess with @code{gtbl}. +@item -g +Preprocess with @code{ggrn}. @item -p Preprocess with @code{gpic}. @item -s @@ -1113,7 +1116,7 @@ will guess the approriate command to print @file{paper.ms} and then run it after adding the @samp{-Tdvi} option. -@node Tutorial for Macro Users, -man, Invoking groff, Top +@node Tutorial for Macro Users, Macro Packages, Invoking groff, Top @chapter Tutorial for Macro Users @cindex tutorial for macro users @cindex macro tutorial for users @@ -1452,31 +1455,54 @@ how the package behaves. This ranges from setting the default type size to changing the appearance of section headers. -@node -man, -ms, Tutorial for Macro Users, Top -@chapter -man +@node Macro Packages, Programming Tutorial, Tutorial for Macro Users, Top +@chapter Macro Packages +@cindex macro packages +@cindex packages, macros + +This chapter documents the main macro packages that come with +@code{groff}. + + +@menu +* -man:: +* -mdoc:: +* -ms:: +* -me:: +* -mm:: +@end menu + +@node -man, -mdoc, Macro Packages, Macro Packages +@section -man @cindex @code{-man} -@node -ms, -me, -man, Top -@chapter -ms +@node -mdoc, -ms, -man, Macro Packages +@section -mdoc +@cindex @code{-mdoc} + + + +@node -ms, -me, -mdoc, Macro Packages +@section -ms @cindex @code{-ms} -@node -me, -mm, -ms, Top -@chapter -me +@node -me, -mm, -ms, Macro Packages +@section -me @cindex @code{-me} -@node -mm, Programming Tutorial, -me, Top -@chapter -mm +@node -mm, , -me, Macro Packages +@section -mm @cindex @code{-mm} -@node Programming Tutorial, geqn, -mm, Top +@node Programming Tutorial, Preprocessors, Macro Packages, Top @chapter Programming Tutorial @cindex programming tutorial @cindex tutorial for programming @@ -3969,7 +3995,7 @@ request can make a macro have more than one name. This would be called as @example -.vl $Id: groff.texinfo,v 1.3 2000/02/11 22:17:10 wlemb Exp $ +.vl $Id: groff.texinfo,v 1.4 2000/02/21 15:07:32 wlemb Exp $ @end example @@ -4802,12 +4828,12 @@ permitted for @var{xxx} to have been defined as a macro and thus contain newlines (it is not permitted for the argument to @code{\X} to contain newlines). The inclusion of -newlines requires an extetension to the @sc{Unix} troff output format, and will +newlines requires an extension to the @sc{Unix} troff output format, and will confuse drivers that do not know about this extension. @c distribute these through the text -@xref{Devices} +@xref{Output Devices} @node Miscellany, Debugging, Postprocessor Access, Programming Tutorial @section Miscellany @@ -5155,8 +5181,26 @@ the new @code{\?} escape sequence. @xref{Diversions}, for more information. @cindex summary -@node geqn, gtbl, Programming Tutorial, Top -@chapter @code{geqn} +@node Preprocessors, Output Devices, Programming Tutorial, Top +@chapter Preprocessors +@cindex preprocessors + +This chapter covers describes all preprocessors that come with +@code{groff} or which are freely available. + +@menu +* geqn:: +* gtbl:: +* gpic:: +* ggrn:: +* grap:: +* grefer:: +* gsoelim:: +@end menu + + +@node geqn, gtbl, Preprocessors, Preprocessors +@section @code{geqn} @cindex @code{eqn} @cindex @code{geqn} @@ -5166,14 +5210,14 @@ the new @code{\?} escape sequence. @xref{Diversions}, for more information. @end menu @node Invoking geqn, , geqn, geqn -@section Invoking @code{geqn} +@subsection Invoking @code{geqn} @cindex invoking @code{geqn} @cindex @code{geqn}, invoking -@node gtbl, gpic, geqn, Top -@chapter @code{gtbl} +@node gtbl, gpic, geqn, Preprocessors +@section @code{gtbl} @cindex @code{tbl} @cindex @code{gtbl} @@ -5183,13 +5227,13 @@ the new @code{\?} escape sequence. @xref{Diversions}, for more information. @end menu @node Invoking gtbl, , gtbl, gtbl -@section Invoking @code{gtbl} +@subsection Invoking @code{gtbl} @cindex invoking @code{gtbl} @cindex @code{gtbl}, invoking -@node gpic, grap, gtbl, Top -@chapter @code{gpic} +@node gpic, ggrn, gtbl, Preprocessors +@section @code{gpic} @cindex @code{pic} @cindex @code{gpic} @@ -5199,20 +5243,39 @@ the new @code{\?} escape sequence. @xref{Diversions}, for more information. @end menu @node Invoking gpic, , gpic, gpic -@section Invoking @code{gpic} +@subsection Invoking @code{gpic} @cindex invoking @code{gpic} @cindex @code{gpic}, invoking -@node grap, grefer, gpic, Top -@chapter @code{grap} +@node ggrn, grap, gpic, Preprocessors +@section @code{ggrn} +@cindex @code{grn} +@cindex @code{ggrn} + + +@menu +* Invoking ggrn:: +@end menu + +@node Invoking ggrn, , ggrn, ggrn +@subsection Invoking @code{ggrn} +@cindex invoking @code{ggrn} +@cindex @code{ggrn}, invoking + + + +@node grap, grefer, ggrn, Preprocessors +@section @code{grap} @cindex @code{grap} +@code{grap} is available as an extra package, written by Ted Faber. + -@node grefer, gsoelim, grap, Top -@chapter @code{grefer} +@node grefer, gsoelim, grap, Preprocessors +@section @code{grefer} @cindex @code{refer} @cindex @code{grefer} @@ -5222,14 +5285,14 @@ the new @code{\?} escape sequence. @xref{Diversions}, for more information. @end menu @node Invoking grefer, , grefer, grefer -@section Invoking @code{grefer} +@subsection Invoking @code{grefer} @cindex invoking @code{grefer} @cindex @code{grefer}, invoking -@node gsoelim, Devices, grefer, Top -@chapter @code{gsoelim} +@node gsoelim, , grefer, Preprocessors +@section @code{gsoelim} @cindex @code{soelim} @cindex @code{gsoelim} @@ -5239,15 +5302,16 @@ the new @code{\?} escape sequence. @xref{Diversions}, for more information. @end menu @node Invoking gsoelim, , gsoelim, gsoelim -@section Invoking @code{gsoelim} +@subsection Invoking @code{gsoelim} @cindex invoking @code{gsoelim} @cindex @code{gsoelim}, invoking -@node Devices, File formats, gsoelim, Top -@chapter Devices -@cindex devices +@node Output Devices, File formats, Preprocessors, Top +@chapter Output Devices +@cindex output devices +@cindex devices for output @@ -5261,7 +5325,7 @@ the new @code{\?} escape sequence. @xref{Diversions}, for more information. * gxditview:: @end menu -@node Special Characters, grotty, Devices, Devices +@node Special Characters, grotty, Output Devices, Output Devices @section Special Characters @cindex special characters @cindex characters, special @@ -5270,7 +5334,7 @@ the new @code{\?} escape sequence. @xref{Diversions}, for more information. @c distribute these through the text @xref{Font Files} -@node grotty, grops, Special Characters, Devices +@node grotty, grops, Special Characters, Output Devices @section @code{grotty} @cindex @code{grotty} @@ -5287,7 +5351,7 @@ the new @code{\?} escape sequence. @xref{Diversions}, for more information. -@node grops, grodvi, grotty, Devices +@node grops, grodvi, grotty, Output Devices @section @code{grops} @cindex @code{grops} @@ -5312,7 +5376,7 @@ the new @code{\?} escape sequence. @xref{Diversions}, for more information. -@node grodvi, grolj4, grops, Devices +@node grodvi, grolj4, grops, Output Devices @section @code{grodvi} @cindex @code{grodvi} @@ -5329,7 +5393,7 @@ the new @code{\?} escape sequence. @xref{Diversions}, for more information. -@node grolj4, grohtml, grodvi, Devices +@node grolj4, grohtml, grodvi, Output Devices @section @code{grolj4} @cindex @code{grolj4} @@ -5346,7 +5410,7 @@ the new @code{\?} escape sequence. @xref{Diversions}, for more information. -@node grohtml, gxditview, grolj4, Devices +@node grohtml, gxditview, grolj4, Output Devices @section @code{grohtml} @cindex @code{grohtml} @@ -5363,7 +5427,7 @@ the new @code{\?} escape sequence. @xref{Diversions}, for more information. -@node gxditview, , grohtml, Devices +@node gxditview, , grohtml, Output Devices @section @code{gxditview} @cindex @code{gxditview} @@ -5380,7 +5444,7 @@ the new @code{\?} escape sequence. @xref{Diversions}, for more information. -@node File formats, Installation, Devices, Top +@node File formats, Installation, Output Devices, Top @chapter File formats @cindex file formats @cindex formats, file |