groff.texinfo: missing invocation documentation

[Krzysztof Żelechowski]

GROFF VERSION: 1.20

MACHINE: noname

OS: openSuSE 11.2

COMPILER: g++ 4.4

INPUT FILES: groff/doc/groff.texinfo

COMMAND LINE: 
cd 'doc' && make 'groff.html' && xdg-open 'file:groff.html#grotty'

DESCRIPTION OF INCORRECT BEHAVIOUR:
The postprocessor sections are empty.

SUGGESTED FIX:
I suggest to keep the full documentation for postprocessors in separate 
documents because it is rather extensive; it would be best if they were info 
files so that they can be referenced from the groff info document.  For the 
time being, they are in separate manual pages.  However, the original author 
has left stub sections in the groff info document that have to be removed 
filled somehow.  I have decided it would be better to fill them with a summary 
of the documentation provided in the separate manual page.  I have rewritten 
the information from the manual page so as to make it more compact; I have 
also skipped the options that are documented as private.  Please review and 
merge, I hope you will find nothing incongruous but the writer can never be 
sure.

TO DO: "prepend" is not an English word, and rightfully so, because being "in 
front" is opposite to "pending"; replace with "put in front" or "prefix" 
everywhere as appropriate.

Index: doc/groff.texinfo
===================================================================
RCS file: /sources/groff/groff/doc/groff.texinfo,v
retrieving revision 1.291
diff -p -r1.291 groff.texinfo
*** doc/groff.texinfo   2 Jun 2010 14:26:25 -0000       1.291
--- doc/groff.texinfo   17 Jul 2010 06:32:25 -0000
*************** is available as an extra package from th
*** 14759,14764 ****
--- 14759,14767 ----
  @cindex @code{grotty}, the program
  
  @c XXX
+ The postprocessor @code{grotty} translates the output from GNU @code{troff} 
+ into a form suitable for typewriter-like devices.  
+ It is fully documented on its manual page, q.v.
  
  @menu
  * Invoking grotty::
*************** is available as an extra package from th
*** 14773,14778 ****
--- 14776,14829 ----
  
  @c XXX
  
+ The postprocessor @command{grotty} accepts the following command-line 
options:
+ 
+ @table @option
+ @item -b
+ Do not overstrike bold glyphs.
+ 
+ @item -B
+ Do not underline bold-italic glyphs.
+ 
+ @item -c
+ Use overprint and disable colours for printing on legacy Teletype printers 
+ (see below).  
+ Overrides other options related to rendering glyphs.
+ 
+ @item -d
+ Do not render lines.
+ 
+ @item -f
+ Use form feed control characters in the output.
+ 
+ @item address@hidden
+ Put the directory @address@hidden/address@hidden
+ in front of the search path for the font and device description files, 
+ given the target device @var{name}.
+ 
+ @item -h
+ Use horizontal tabs for sequences of 8 space characters.
+ 
+ @item -i
+ Request italic glyphs from the terminal.
+ 
+ @item -o
+ Do not overstrike.
+ 
+ @item -r
+ Highlight italic glyphs.
+ 
+ @item -u
+ Do not underline italic glyphs.
+ 
+ @item -U
+ Do not overstrike bold-italic glyphs.
+ 
+ @item -v
+ Print the version number.
+ 
+ @end table
+ 
  @c The following is no longer true; fix and extend it.
  
  @c @pindex less
*************** is available as an extra package from th
*** 14780,14795 ****
  @c @cindex ISO 6249 SGR
  @c @cindex terminal control sequences
  @c @cindex control sequences, for terminals
! @c For TTY output devices, underlining is done by emitting sequences of
! @c @samp{_} and @samp{\b} (the backspace character) before the actual
! @c character.  Literally, this is printing an underline character, then
! @c moving back one character position, and printing the actual character
! @c at the same position as the underline character (similar to a
! @c typewriter).  Usually, a modern terminal can't interpret this (and
! @c the original Teletype machines for which this sequence was
! @c appropriate are no longer in use).  You need a pager program like
! @c @code{less} which translates this into ISO 6429 SGR sequences to
! @c control terminals.
  
  
  @c =====================================================================
--- 14831,14847 ----
  @c @cindex ISO 6249 SGR
  @c @cindex terminal control sequences
  @c @cindex control sequences, for terminals
! The @option{-c} mode for TTY output devices means
! that underlining is done by emitting sequences of
! @samp{_} and @samp{^H} (the backspace character) before the actual
! character.  Literally, this is printing an underline character, then
! moving the caret back one character position, and printing the actual 
character
! at the same position as the underline character (similar to a
! typewriter).  Usually, a modern terminal can't interpret this (and
! the original Teletype machines for which this sequence was
! appropriate are no longer in use).  You need a pager program like
! @code{less} which translates this into address@hidden SGR sequences to
! control terminals.
  
  
  @c =====================================================================
*************** is available as an extra package from th
*** 14799,14804 ****
--- 14851,14860 ----
  @cindex @code{grops}, the program
  
  @c XXX
+ The postprocessor @command{grops} translates the output from GNU 
@command{troff} 
+ into a form suitable for address@hidden@registeredsymbol{} PostScript 
devices.  
+ It is fully documented on its manual page, q.v.
+ 
  
  @menu
  * Invoking grops::
*************** is available as an extra package from th
*** 14813,14818 ****
--- 14869,14924 ----
  @cindex @code{grops}, invoking
  
  @c XXX
+ The postprocessor @code{grops} accepts the following command-line options:
+ 
+ @table @option
+ @item address@hidden
+ Use backward compatibility settings given by @var{flags} 
+ as documented in @cite{grops(1)} manual page.  
+ Overrides the command @command{broken} in the @file{DESC} file.
+ 
+ @item address@hidden
+ Print @var{n} copies of each page.
+ 
+ @item address@hidden
+ Put the directory @address@hidden/address@hidden 
+ in front of the search path for the font, prologue and device description 
files, 
+ given the target device @var{name}, usually @strong{ps}.
+ 
+ @item -g
+ Tell the printer to guess the page length.  
+ Useful for printing vertically centered pages 
+ when the paper dimensions are determined at print time.
+ 
+ @item address@hidden @dots{}
+ Consider the directory @address@hidden 
+ for searching included files specified with relative paths.  
+ The current directory is searched as fallback.
+ 
+ @item -l
+ Use landscape orientation.
+ 
+ @item -m
+ Use manual feed.
+ 
+ @item address@hidden
+ Set the page dimensions.  
+ Overrides the commands 
+ @command{papersize}, @command{paperlength} and @command{paperwidth} 
+ in the @file{DESC} file.  See @cite{groff_font(5)} manual page for details.
+ 
+ @item address@hidden
+ Use the @var{prologue} in the font path as the prologue 
+ instead of the default @file{prologue}.  
+ Overrides the environment variable @env{GROPS_PROLOGUE}.
+ 
+ @item address@hidden
+ Set the line thickness to n/1000 em.  Overrides the default value @var{n} = 
40.
+ 
+ @item -v
+ Print the version number.
+ 
+ @end table
  
  @c ---------------------------------------------------------------------
  
*************** is available as an extra package from th
*** 14823,14828 ****
--- 14929,14951 ----
  
  @c XXX
  
+ The escape sequence
+ 
+ @code{\X'ps: 
+ import 
+ @var{file} @var{llx} @var{lly} @var{urx} @var{ury} @var{width} 
address@hidden'}
+ 
+ places a rectangle of the specified @var{width}
+ containing the PostScript drawing from @address@hidden 
+ bounded by the box from @var{llx} @var{lly} to @var{urx} @var{ury} 
+ (in PostScript coordinates) at the insertion point.  
+ If @var{height} is not specified, the embedded drawing is scaled 
proportionally.
+ 
+ @xref{Miscellaneous}, @code{psbb} request 
+ to automatically generate the bounding box.
+ 
+ This escape sequence is used internally by the macro @code{PSPIC} 
+ (see @cite{groff_tmac(5)} manual page).
  
  @c =====================================================================
  
*************** is available as an extra package from th
*** 14831,14836 ****
--- 14954,14963 ----
  @cindex @code{grodvi}, the program
  
  @c XXX
+ The postprocessor @command{grodvi} translates the output from GNU 
@command{troff} 
+ into the @strong{DVI} output format 
+ compatible with the @address@hidden document preparation system.  
+ It is fully documented on its manual page, q.v.
  
  @menu
  * Invoking grodvi::
*************** is available as an extra package from th
*** 14844,14850 ****
--- 14971,15003 ----
  @cindex @code{grodvi}, invoking
  
  @c XXX
+ The postprocessor @code{grodvi} accepts the following command-line options:
+ 
+ @table @option
+ @item -d
+ Do not use @strong{tpic} specials to implement drawing commands.
+ 
+ @item address@hidden
+ Put the directory @address@hidden/address@hidden 
+ in front of the search path for the font and device description files, 
+ given the target device @var{name}, usually @strong{dvi}.
+ 
+ @item -l
+ Use landscape orientation.
+ 
+ @item address@hidden
+ Set the page dimensions.  
+ Overrides the commands 
+ @command{papersize}, @command{paperlength} and @command{paperwidth} 
+ in the @file{DESC} file.  See @cite{groff_font(5)} manual page for details.
+ 
+ @item -v
+ Print the version number.
  
+ @item address@hidden
+ Set the line thickness to n/1000 em.  Overrides the default value @var{n} = 
40.
+ 
+ @end table
  
  @c =====================================================================
  
*************** is available as an extra package from th
*** 14853,14858 ****
--- 15006,15017 ----
  @cindex @code{grolj4}, the program
  
  @c XXX
+ The postprocessor @command{grolj4} translates the output from GNU 
@command{troff} 
+ into the @strong{PCL5} output format 
+ suitable for printing 
+ on a @address@hidden@registeredsymbol{} address@hidden printer.  
+ It is fully documented on its manual page, q.v.
+ 
  
  @menu
  * Invoking grolj4::
*************** is available as an extra package from th
*** 14866,14872 ****
--- 15025,15062 ----
  @cindex @code{grolj4}, invoking
  
  @c XXX
+ The postprocessor @code{grolj4} accepts the following command-line options:
+ 
+ @table @option
+ @item address@hidden
+ Print @var{n} copies of each page.
+ 
+ @item address@hidden
+ Put the directory @address@hidden/address@hidden 
+ in front of the search path for the font and device description files, 
+ given the target device @var{name}, usually @strong{lj4}.
+ 
+ @item -l
+ Use landscape orientation.
+ 
+ @item address@hidden
+ Set the page dimensions.  
+ Sets the paper size.  
+ Valid values for @var{size} are: 
+ @command{letter}, @command{legal}, @command{executive}, @command{a4}, 
+ @command{com10}, @command{monarch}, @command{c5}, @command{b5}, 
@command{d1}.
+ 
+ @item -v
+ Print the version number.
  
+ @item address@hidden
+ Set the line thickness to n/1000 em.  Overrides the default value @var{n} = 
40.
+ 
+ @end table
+ 
+ The special drawing command @command{\D'R @var{dh} @var{dv}'} 
+ draws a horizontal rectangle from the current position 
+ to the position at offset @var{dh} @var{dv}.
  
  @c =====================================================================
  
*************** is available as an extra package from th
*** 14875,14880 ****
--- 15065,15077 ----
  @cindex @code{grolbp}, the program
  
  @c XXX
+ The postprocessor @command{grolbp} 
+ translates the output from GNU @command{troff} 
+ into the @strong{LBP} output format 
+ suitable for printing 
+ on @address@hidden@registeredsymbol{} CAPSL} printers.  
+ It is fully documented on its manual page, q.v.
+ 
  
  @menu
  * Invoking grolbp::
*************** is available as an extra package from th
*** 14888,14893 ****
--- 15085,15122 ----
  @cindex @code{grolbp}, invoking
  
  @c XXX
+ The postprocessor @code{grolbp} accepts the following command-line options:
+ 
+ @table @option
+ @item address@hidden
+ Print @var{n} copies of each page.
+ 
+ @item address@hidden
+ Put the directory @address@hidden/address@hidden 
+ in front of the search path for the font, prologue and device description 
files, 
+ given the target device @var{name}, usually @strong{lbp}.
+ 
+ @item -l
+ Use landscape orientation.
+ 
+ @item address@hidden
+ Use the @var{orientation} specified: @command{portrait} or 
@command{landscape}.
+ 
+ @item address@hidden
+ Set the page dimensions.  
+ See @cite{groff_font(5)} manual page for details.
+ 
+ @item address@hidden
+ Set the line thickness to n/1000 em.  Overrides the default value @var{n} = 
40.
+ 
+ @item -v
+ Print the version number.
+ 
+ @item -h
+ Print command-line help.
+ 
+ @end table
+ 
  
  
  @c =====================================================================
*************** is available as an extra package from th
*** 14897,14902 ****
--- 15126,15136 ----
  @cindex @code{grohtml}, the program
  
  @c XXX
+ The postprocessor @command{grohtml} 
+ translates the output from GNU @command{troff} 
+ into the @strong{HTML} output format 
+ suitable for displaying in a Web browser.  
+ It is fully documented on its manual page, q.v.
  
  @menu
  * Invoking grohtml::
*************** is available as an extra package from th
*** 14911,14916 ****
--- 15145,15225 ----
  @cindex @code{grohtml}, invoking
  
  @c XXX
+ The postprocessor @code{grolbp} accepts the following command-line options:
+ 
+ @table @option
+ @item address@hidden
+ Use this number of @var{bits} (= 1, 2 or 4) for text antialiasing, 
+ default: @var{bits} = 4. 
+ 
+ @item -a0
+ Do not use text antialiasing.
+ 
+ @item -b
+ Use white background.
+ 
+ @item address@hidden
+ Store rendered images in the directory @address@hidden
+ 
+ @item address@hidden
+ Print @var{n} copies of each page.
+ 
+ @item address@hidden
+ Put the directory @address@hidden/address@hidden 
+ in front of the search path for the font, prologue and device description 
files, 
+ given the target device @var{name}, usually @strong{html}.
+ 
+ @item address@hidden
+ Use this number of @var{bits} (= 1, 2 or 4) for antialiasing of drawings; 
+ default: @var{bits} = 4. 
+ 
+ @item -a0
+ Do not use antialiasing for drawings.
+ 
+ @item -h
+ Use the @code{B} element for section headings.
+ 
+ @item address@hidden
+ Use the @var{resolution} for rendered images; default: @var{resolution} = 
100.
+ 
+ @item address@hidden
+ Set the image @var{stem name}; default: @var{stem} = @file{grohtml-
@var{$$}}.
+ 
+ @item address@hidden
+ Place each section in a separate file called @address@hidden@var{#}.html}.
+ 
+ @item -l
+ Do not generate the table of contents.
+ 
+ @item -n
+ Generate simple fragment identifiers.
+ 
+ @item address@hidden
+ Use vertical paddding @var{offset} for images.
+ 
+ @item -p
+ Display the page rendering progress to standard error.
+ 
+ @item -r
+ Do not use horizontal rules to separate headers and footers.
+ 
+ @item address@hidden
+ Set the base font size, 
+ to be modified using the elements @code{BIG} and @code{SMALL}.
+ 
+ @item address@hidden
+ Generate separate files for sections at @var{level}.
+ 
+ @item -v
+ Print the version number.
+ 
+ @item -V
+ Generate a validator button at the bottom.
+ 
+ @item -y
+ Generate a signature of groff after the validator button, if any.
+ 
+ @end table
  
  @c ---------------------------------------------------------------------