Re: groff.texinfo: missing invocation documentation

[Krzysztof Żelechowski]

Dnia sobota, 17 lipca 2010 o 09:03:25 Werner LEMBERG napisał(a):
> > 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.
> 
> Thanks.  Please resend the patch as an attachment since there are
> wrapped lines (due to bad email clients, I suspect).
> 

Resending without wrapping.


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} = @address@hidden
+ 
+ @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 ---------------------------------------------------------------------