Re: Manuals in pdf format

[Werner LEMBERG]

>     BTW, a footer string as defined with @xxxfooting jumps up and
>     down within the output -- this is *really* ugly, and I consider
>     it as a severe typographical bug (I use texinfo 4.8).
> 
> I cannot reproduce this with the current texinfo.tex
> (ftp://tug.org/tex/texinfo.tex).

Attached is a reduced version of groff.texinfo, together with a PDF
version of it.  It has been produced with 

  pdfeTeXk, Version 3.141592-1.21a-2.2 (Web2C 7.5.4) (format=pdfetex
    2005.9.13)
  texinfo.tex version 2006-06-01.17
  texinfo 4.8

using the command

  texi2dvi -e -p test.texinfo

Please note that the footer on page 4 (this is physical page 8) is one
line lower than the footer on page 3 and 5.


    Werner

\input texinfo   @c -*-texinfo-*-

@c
@c Please convert this manual with `texi2dvi -e groff.texinfo' due to
@c problems in texinfo regarding expansion of user-defined macros.
@c
@c You need texinfo 4.8 or newer to format this document!
@c

@c %**start of header (This is for running Texinfo on a region.)
@setfilename test.info
@settitle The GNU Troff Manual
@setchapternewpage odd
@footnotestyle separate
@c %**end of header (This is for running Texinfo on a region.)

@documentlanguage en
@documentencoding ISO-8859-1


@smallbook

@finalout


@copying
This manual documents GNU @code{troff} version 1.19.2.

Copyright @copyright{} 1994-2000, 2001, 2002, 2003, 2004, 2005, 2006
Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being `A GNU Manual,''
and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled `GNU Free Documentation
License.''

(a) The FSF's Back-Cover Text is: `You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''
@end quotation
@end copying


@c We use the following indices:
@c
@c   cindex: concepts
@c   rqindex: requests
@c   esindex: escapes
@c   vindex: registers
@c   kindex: commands in font files
@c   pindex: programs and files
@c   tindex: environment variables
@c   maindex: macros
@c   stindex: strings
@c   opindex: operators
@c
@c tindex and cindex are merged.

@defcodeindex rq
@defcodeindex es
@defcodeindex ma
@defcodeindex st
@defcodeindex op
@syncodeindex tp cp


@c To avoid uppercasing in @deffn while converting to info, we define
@c our special @Var{}.

@macro Var{arg}
@address@hidden
@end macro


@c To assure correct HTML translation, some ugly hacks are necessary.
@c While processing a @def... request, the HTML translator looks at the
@c next line to decide whether to start indentation, and if the line starts
@c with @def... (e.g. @deffnx), indentation is started.  We must therefore
@c ensure that a @def... is seen, during macro expansion.
@c
@c The following macros have to be used:
@c
@c One item:
@c
@c   @Def...
@c
@c Two items:
@c
@c   @Def...List
@c   @Def...ListEnd
@c
@c More than two:
@c
@c   @Def...List
@c   @Def...Item
@c   @Def...Item
@c   ...
@c   @Def...ListEnd
@c
@c The definition block must end with
@c
@c   @endDef...
@c
@c The above is valid for texinfo 4.0f and above.


@c a dummy macro to assure the address@hidden'

@macro defdummy
@c
@end macro


@c definition of requests

@macro Defreq{name, arg}
@deffn Request @t{.\name\} \arg\
@rqindex \name\
@c
@end macro

@macro DefreqList{name, arg}
@deffn Request @t{.\name\} \arg\
@defdummy
@rqindex \name\
@c
@end macro

@macro DefreqItem{name, arg}
@deffnx Request @t{.\name\} \arg\
@defdummy
@rqindex \name\
@c
@end macro

@macro DefreqListEnd{name, arg}
@deffnx Request @t{.\name\} \arg\
@rqindex \name\
@c
@end macro

@macro endDefreq
@end deffn
@end macro


@c definition of escapes

@macro Defesc{name, delimI, arg, delimII}
@deffn Escape @address@hidden@t{\delimII\}
@esindex \name\
@c
@end macro

@macro DefescList{name, delimI, arg, delimII}
@deffn Escape @address@hidden@t{\delimII\}
@defdummy
@esindex \name\
@c
@end macro

@macro DefescItem{name, delimI, arg, delimII}
@deffnx Escape @address@hidden@t{\delimII\}
@defdummy
@esindex \name\
@c
@end macro

@macro DefescListEnd{name, delimI, arg, delimII}
@deffnx Escape @address@hidden@t{\delimII\}
@esindex \name\
@c
@end macro

@macro endDefesc
@end deffn
@end macro


@c definition of registers

@macro Defreg{name}
@deffn Register @t{\\n[\name\]}
@vindex \name\
@c
@end macro

@macro DefregList{name}
@deffn Register @t{\\n[\name\]}
@defdummy
@vindex \name\
@c
@end macro

@macro DefregItem{name}
@deffnx Register @t{\\n[\name\]}
@defdummy
@vindex \name\
@c
@end macro

@macro DefregListEnd{name}
@deffnx Register @t{\\n[\name\]}
@vindex \name\
@c
@end macro

@macro endDefreg
@end deffn
@end macro


@c definition of registers specific to macro packages, preprocessors, etc.

@macro Defmpreg{name, package}
@deffn Register @t{\\n[\name\]}
@vindex \name\ @address@hidden
@c
@end macro

@macro DefmpregList{name, package}
@deffn Register @t{\\n[\name\]}
@defdummy
@vindex \name\ @address@hidden
@c
@end macro

@macro DefmpregItem{name, package}
@deffnx Register @t{\\n[\name\]}
@defdummy
@vindex \name\ @address@hidden
@c
@end macro

@macro DefmpregListEnd{name, package}
@deffnx Register @t{\\n[\name\]}
@vindex \name\ @address@hidden
@c
@end macro

@macro endDefmpreg
@end deffn
@end macro


@c definition of macros

@macro Defmac{name, arg, package}
@defmac @t{.\name\} \arg\
@maindex \name\ @address@hidden
@c
@end macro

@macro DefmacList{name, arg, package}
@defmac @t{.\name\} \arg\
@defdummy
@maindex \name\ @address@hidden
@c
@end macro

@macro DefmacItem{name, arg, package}
@defmacx @t{.\name\} \arg\
@defdummy
@maindex \name\ @address@hidden
@c
@end macro

@macro DefmacListEnd{name, arg, package}
@defmacx @t{.\name\} \arg\
@maindex \name\ @address@hidden
@c
@end macro

@macro endDefmac
@end defmac
@end macro


@c definition of strings

@macro Defstr{name, package}
@deffn String @t{\\*[\name\]}
@stindex \name\ @address@hidden
@c
@end macro

@macro DefstrList{name, package}
@deffn String @t{\\*[\name\]}
@defdummy
@stindex \name\ @address@hidden
@c
@end macro

@macro DefstrItem{name, package}
@deffnx String @t{\\*[\name\]}
@defdummy
@stindex \name\ @address@hidden
@c
@end macro

@macro DefstrListEnd{name, package}
@deffnx String @t{\\*[\name\]}
@stindex \name\ @address@hidden
@c
@end macro

@macro endDefstr
@end deffn
@end macro


@c our example macro

@macro Example
@example
@group
@end macro

@macro endExample
@end group
@end example
@end macro


@c <text>

@tex
\gdef\Langlemacro{\angleleft}
\gdef\Ranglemacro{\angleright}
@end tex

@iftex
@set Langlemacro @Langlemacro
@set Ranglemacro @Ranglemacro
@end iftex

@ifnottex
@set Langlemacro <
@set Ranglemacro >
@end ifnottex

@macro angles{text}
@address@hidden@value{Ranglemacro}
@end macro


@c a <= sign
@c
@c A value defined with @set is embedded into three group levels if
@c called with @value, so we need seven \aftergroup to put \le outside
@c of the groups -- this is necessary to get proper mathematical spacing.

@tex
\gdef\LEmacro{\aftergroup\aftergroup\aftergroup\aftergroup
              \aftergroup\aftergroup\aftergroup\le}
@end tex

@iftex
@set LEmacro @LEmacro
@end iftex

@ifnottex
@set LEmacro <=
@end ifnottex

@macro LE
@value{LEmacro}
@end macro


@c Special care is required with parentheses, brackets, and braces:
@c
@c . Real parentheses in @deffn produce an error while compiling with
@c   TeX.
@c . Real brackets use the wrong font in @deffn, overriding @t{}.
@c
@c . @{ and @} fail with info if used in a macro.
@c
@c Since macros aren't expanded in @deffn during -E, the following
@c definitions are for non-TeX only.
@c
@c This is true for texinfo 4.0 and above.

@iftex
@set Lparenmacro @lparen
@set Rparenmacro @rparen
@set Lbrackmacro @lbrack
@set Rbrackmacro @rbrack
@set Lbracemacro @{
@set Rbracemacro @}
@end iftex

@ifnottex
@set Lparenmacro (
@set Rparenmacro )
@set Lbrackmacro [
@set Rbrackmacro ]
@set Lbracemacro @{
@set Rbracemacro @}
@end ifnottex

@macro Lparen{}
@value{Lparenmacro}
@end macro
@macro Rparen{}
@value{Rparenmacro}
@end macro
@macro Lbrack{}
@value{Lbrackmacro}
@end macro
@macro Rbrack{}
@value{Rbrackmacro}
@end macro
@macro Lbrace{}
@value{Lbracemacro}
@end macro
@macro Rbrace{}
@value{Rbracemacro}
@end macro


@c This suppresses the word `Appendix' in the appendix headers.

@tex
\gdef\gobblefirst#1#2{#2}
\gdef\putwordAppendix{\gobblefirst}
@end tex


@c We map some latin-1 characters to corresponding texinfo macros.

@tex
\global\catcode`^^e4\active % ä
\gdef^^e4{\"a}
\global\catcode`^^c4\active % Ä
\gdef^^c4{\"A}
\global\catcode`^^e9\active % é
\gdef^^e9{\'e}
\global\catcode`^^c9\active % É
\gdef^^c9{\'E}
\global\catcode`^^f6\active % ö
\gdef^^f6{\"o}
\global\catcode`^^d6\active % Ö
\gdef^^d6{\"O}
\global\catcode`^^fc\active % ü
\gdef^^fc{\"u}
\global\catcode`^^dc\active % Ü
\gdef^^dc{\"U}
\global\catcode`^^e6\active % æ
\gdef^^e6{\ae}
\global\catcode`^^c6\active % Æ
\gdef^^c6{\AE}
\global\catcode`^^df\active % ß
\gdef^^df{\ss}
@end tex


@c Note: We say `Roman numerals' but `roman font'.


@dircategory Typesetting
@direntry
* Groff: (groff).               The GNU troff document formatting system.
@end direntry


@titlepage
@title groff
@subtitle The GNU implementation of @code{troff}
@subtitle Edition 1.19.3
@subtitle Spring 2006
@author by Trent address@hidden
@author and Werner Lemberg (@email{bug-groff@@gnu.org})

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@headings off
@evenheading @| @| @thischapter
@oddheading @thissection @| @|
@evenfooting @thispage @| @| @thistitle
@oddfooting @thistitle @| @| @thispage

@contents

@ifinfo
@node Top, Introduction, (dir), (dir)
@top GNU troff

@insertcopying
@end ifinfo

@ifhtml
@menu
* Introduction::
* Invoking groff::
* Tutorial for Macro Users::
* Macro Packages::
* gtroff Reference::
* Preprocessors::
* Output Devices::
* File formats::
* Installation::
* Copying This Manual::
* Request Index::
* Escape Index::
* Operator Index::
* Register Index::
* Macro Index::
* String Index::
* Glyph Name Index::
* Font File Keyword Index::
* Program and File Index::
* Concept Index::
@end menu

@node Top, Introduction, (dir), (dir)
@top GNU troff

@insertcopying
@end ifhtml

@menu
* Introduction::
* Invoking groff::
* Tutorial for Macro Users::
* Macro Packages::
* gtroff Reference::
* Preprocessors::
* Output Devices::
* File formats::
* Installation::
* Copying This Manual::
* Request Index::
* Escape Index::
* Operator Index::
* Register Index::
* Macro Index::
* String Index::
* Glyph Name Index::
* Font File Keyword Index::
* Program and File Index::
* Concept Index::
@end menu



@c =====================================================================
@c =====================================================================

@node Introduction, Invoking groff, Top, Top
@chapter Introduction
@cindex introduction

GNU @code{troff} (or @code{groff}) is a system for typesetting documents. 
@code{troff} is very flexible and has been used extensively for some thirty
years.  It is well entrenched in the @acronym{UNIX} community.

@menu
* What Is groff?::
* History::
* groff Capabilities::
* Macro Package Intro::
* Preprocessor Intro::
* Output device intro::
* Credits::
@end menu


@c =====================================================================

@node What Is groff?, History, Introduction, Introduction
@section What Is @code{groff}?
@cindex what is @code{groff}?
@cindex @code{groff} -- what is it?

@code{groff} belongs to an older generation of document preparation
systems, which operate more like compilers than the more recent
interactive @address@hidden 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 @code{groff} to produce a typeset document on a
variety of devices.

@code{groff} should not be confused with a @dfn{word processor}, an
integrated system of editor and text formatter.  Also, many word
processors follow the @acronym{WYSIWYG} paradigm discussed earlier.

Although @acronym{WYSIWYG} systems may be easier to use, they have a
number of disadvantages compared to @code{troff}:

@itemize @bullet
@item
They must be used on a graphics display to work on a document.

@item
Most of the @acronym{WYSIWYG} systems are either non-free or are not
very portable.

@item
@code{troff} is firmly entrenched in all @acronym{UNIX} systems.

@item
It is difficult to have a wide range of capabilities within the confines of
a GUI/window system.

@item
It is more difficult to make global changes to a document.
@end itemize

@quotation
``GUIs normally make it simple to accomplish simple actions and
impossible to accomplish complex actions.''  --Doug Gwyn (22/Jun/91 in
@code{comp.unix.wizards})
@end quotation


@c =====================================================================

@node History, groff Capabilities, What Is groff?, Introduction
@section History
@cindex history

@cindex @code{runoff}, the program
@cindex @code{rf}, the program
@code{troff} can trace its origins back to a formatting program called
@code{runoff}, written by address@hidden@tie{}Saltzer, which ran on MIT's CTSS
operating system in the mid-sixties.  The name came from the use of the
phrase ``run off a document'', meaning to print it out.  Bob Morris ported it
to the 635 architecture and called the program @code{roff} (an abbreviation
of @code{runoff}).  It was rewritten as @code{rf} for the @w{PDP-7}
(before having @acronym{UNIX}), and at the same time (1969), Doug
McIllroy rewrote an extended and simplified version of @code{roff} in
the @acronym{BCPL} programming language.

@cindex @code{roff}, the program
The first version of @acronym{UNIX} was developed on a @w{PDP-7} which
was sitting around Bell Labs.  In 1971, the developers wanted to get a
@w{PDP-11} for further work on the operating system, and to justify the
cost, proposed the development of a document formatting system for the
@acronym{AT&T} patents division.  This first formatting program was a
reimplementation of McIllroy's @code{roff}, written by
address@hidden@tie{}Ossanna.

@cindex @code{nroff}, the program
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.
When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a
version of @code{nroff} that would drive it.  It was dubbed
@code{troff}, for ``typesetter @code{roff}'', although many people have
speculated that it actually means ``Times @code{roff}'' because of the
use of the Times font family in @code{troff} by default.  As such, the
name @code{troff} is pronounced address@hidden' rather than `trough'.

With @code{troff} came @code{nroff} (they were actually the same program
except for some @samp{#ifdef}s), which was for producing output for line
printers and character terminals.  It understood everything @code{troff}
did, and ignored the commands which were not applicable (e.g.@: font
changes).

Since there are several things which cannot be done easily in
@code{troff}, work on several preprocessors began.  These programs would
transform certain parts of a document into @code{troff}, which made a
very natural use of pipes in @acronym{UNIX}.

The @code{eqn} preprocessor allowed mathematical formulæ to be
specified in a much simpler and more intuitive manner.  @code{tbl} is a
preprocessor for formatting tables.  The @code{refer} preprocessor (and
the similar program, @code{bib}) processes citations in a document
according to a bibliographic database.

Unfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly
language and produced output specifically for the CAT phototypesetter.
He rewrote it in C, although it was now address@hidden of uncommented
code and still dependent on the CAT.  As the CAT became less common, and
was no longer supported by the manufacturer, the need to make it support
other devices became a priority.  However, before this could be done,
Ossanna died by a severe heart attack in a hospital while recovering
from a previous one.

@pindex ditroff
@cindex @code{ditroff}, the program
So, Brian Kernighan took on the task of rewriting @code{troff}.  The
newly rewritten version produced device independent code which was
very easy for postprocessors to read and translate to the appropriate
printer codes.  Also, this new version of @code{troff} (called
@code{ditroff} for ``device independent @code{troff}'') had several
extensions, which included drawing functions.

Due to the additional abilities of the new version of @code{troff},
several new preprocessors appeared.  The @code{pic} preprocessor
provides a wide range of drawing functions.  Likewise the @code{ideal}
preprocessor did the same, although via a much different paradigm.  The
@code{grap} preprocessor took specifications for graphs, but, unlike
other preprocessors, produced @code{pic} code.

James Clark began work on a GNU implementation of @code{ditroff} in
address@hidden  The first version, @address@hidden, was released
address@hidden  @code{groff} included:

@itemize @bullet
@item
A replacement for @code{ditroff} with many extensions.

@item
The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.

@item
Postprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and
address@hidden  GNU @code{troff} also eliminated the need for a
separate @code{nroff} program with a postprocessor which would produce
@acronym{ASCII} output.

@item
A version of the @file{me} macros and an implementation of the
@file{man} macros.
@end itemize

Also, a front-end was included which could construct the, sometimes
painfully long, pipelines required for all the post- and preprocessors.

Development of GNU @code{troff} progressed rapidly, and saw the
additions of a replacement for @code{refer}, an implementation of the
@file{ms} and @file{mm} macros, and a program to deduce how to format a
document (@code{grog}).

It was declared a stable (i.e.@: non-beta) package with the release of
address@hidden around address@hidden

Beginning address@hidden, @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 an output device to
produce @acronym{HTML} output have been added.


@c =====================================================================

@node groff Capabilities, Macro Package Intro, History, Introduction
@section @code{groff} Capabilities
@cindex @code{groff} capabilities
@cindex capabilities of @code{groff}

So what exactly is @code{groff} capable of doing?  @code{groff} provides
a wide range of low-level text formatting operations.  Using these, it
is possible to perform a wide range of formatting tasks, such as
footnotes, table of contents, multiple columns, etc.  Here's a list of
the most important operations supported by @code{groff}:

@itemize @bullet
@item
text filling, adjusting, and centering

@item
hyphenation

@item
page control

@item
font and glyph size control

@item
vertical spacing (e.g.@: double-spacing)

@item
line length and indenting

@item
macros, strings, diversions, and traps

@item
number registers

@item
tabs, leaders, and fields

@item
input and output conventions and character translation

@item
overstrike, bracket, line drawing, and zero-width functions

@item
local horizontal and vertical motions and the width function

@item
three-part titles

@item
output line numbering

@item
conditional acceptance of input

@item
environment switching

@item
insertions from the standard input

@item
input/output file switching

@item
output and error messages
@end itemize


@c =====================================================================

@node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction
@section Macro Packages
@cindex macro packages

Since @code{groff} provides such low-level facilities, it can be quite
difficult to use by itself.  However, @code{groff} provides a
@dfn{macro} facility to specify how certain routine operations
(address@hidden 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 @file{man},
@file{mdoc}, @file{me}, @file{ms}, and @file{mm}.


@c =====================================================================

@node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction
@section Preprocessors
@cindex preprocessors

Although @code{groff} provides most functions needed to format a
document, some operations would be unwieldy (e.g.@: to draw pictures).
Therefore, programs called @dfn{preprocessors} were written which
understand their own language and produce the necessary @code{groff}
operations.  These preprocessors are able to differentiate their own
input from the rest of the document via markers.

To use a preprocessor, @acronym{UNIX} pipes are used to feed the output
from the preprocessor into @code{groff}.  Any number of preprocessors
may be used on a given document; in this case, the preprocessors are
linked together into one pipeline.  However, with @code{groff}, the user
does not need to construct the pipe, but only tell @code{groff} what
preprocessors to use.

@code{groff} currently has preprocessors for producing tables
(@code{tbl}), typesetting equations (@code{eqn}), drawing pictures
(@code{pic} and @code{grn}), and for processing bibliographies
(@code{refer}).  An associated program which is useful when dealing with
preprocessors is @code{soelim}.

A free implementation of @code{grap}, a preprocessor for drawing graphs,
can be obtained as an extra package; @code{groff} can use @code{grap}
also.

There are other preprocessors in existence, but, unfortunately, no free
implementations are available.  Among them are preprocessors for drawing
mathematical pictures (@code{ideal}) and chemical structures
(@code{chem}).


@c =====================================================================

@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 to produce output for a particular device.
Currently, @code{groff} has postprocessors for @sc{PostScript}
devices, character terminals, address@hidden (for previewing), @TeX{}
DVI format, HP address@hidden and Canon LBP printers (which use
@acronym{CAPSL}), and @acronym{HTML}.


@c =====================================================================

@node Credits,  , Output device intro, Introduction
@section Credits
@cindex credits

Large portions of this manual were taken from existing documents, most
notably, the manual pages for the @code{groff} package by James Clark,
and Eric Allman's papers on the @file{me} macro package.

The section on the @file{man} macro package is partly based on
address@hidden@: Kleinmann's @file{groff_man} manual page written for the
Debian GNU/Linux system.

Larry Kollar contributed the section in the @file{ms} macro package.



@bye

test.pdf
Description: Adobe PDF document