[bug #51327] [man pages] break long input lines

[G. Branden Robinson]

Update of bug #51327 (project groff):

                  Status:                    None => Postponed              
                 Summary: [PATCH] [man pages] split lines more than 80
characters long => [man pages] break long input lines

    _______________________________________________________

Follow-up Comment #4:

I looked at this, and there is only handful a few pages with lines longer then
72 characters, let alone 80.

Rather than supplying patches for an issue like this in material that is
frequently revised, particularly when the problem is already fairly well
managed, it is better to supply a mechanism for detecting it and to consider
each case in context.  Removing "[PATCH]" annotation.


$ git grep -E '.{73}' *.man*
contrib/mm/groff_mm.7.man:.BI EC\  "\fR[\fPtitle \fR[\fPoverride \fR[\fPflag
\fR[\fPrefname\fR]]]]\fP"
contrib/mm/groff_mm.7.man:.BI EX\  "\fR[\fPtitle \fR[\fPoverride \fR[\fPflag
\fR[\fPrefname\fR]]]]\fP"
contrib/mm/groff_mm.7.man:.BI FG\  "\fR[\fPtitle \fR[\fPoverride \fR[\fPflag
\fR[\fPrefname\fR]]]]\fP"
contrib/mm/groff_mm.7.man:.BI LB\  "text-indent mark-indent pad type
\fR[\fPmark \fR[\fPLI-space \fR[\fPLB-space\fR]]]\fP"
contrib/mm/groff_mm.7.man:.BI PGFORM\  "\fR[\fPlinelength \fR[\fPpagelength
\fR[\fPpageoffset\ " \fR[\fP1\fR]]]]\fP
contrib/mm/groff_mm.7.man:.BI "PIC \fR[\fP\-B\fR] [\fP\-L\fR] [\fP\-C\fR]
[\fP\-R\fR] [\fP\-I\ " "n\fR]\fP filename \fR[\fPwidth \fR[\fPheight\fR]]\fP"
contrib/mm/groff_mm.7.man:.BI TB\  "\fR[\fPtitle \fR[\fPoverride \fR[\fPflag
\fR[\fPrefname\fR]]]]\fP"
contrib/mm/groff_mm.7.man:.BI TC\  "\fR[\fPslevel \fR[\fPspacing \fR[\fPtlevel
\fR[\fPtab \fR[\fPh1 \fR[\fPh2 \fR[\fPh3 \fR[\fPh4 \fR[\fPh5\fR]]]]]]]]]\fP"


groff_mm(7) is a page I haven't gotten around to doing a deep revision of yet
(one of the relatively few since groff 1.22.4).

I'll take care of these eventually but it's not a task I want to take on right
now.  Most of the above are macro synopses that are also tags to `TP`
paragraphs, so they're subject to input traps.

As of groff 1.22.4 they can be rewritten using output line continuation \c,
and for a few groff_mm(7) macro synopses I have already done so; see commit
9ce6e638fab4a0e8899ecc2027a78f5890349230.


man/groff_char.7.man:\[rs]      (escape character)      \f[B]\[rs]e\f[] or
\f[B]\[rs][rs]\f[] reverse solidus
man/groff_char.7.man:\[ha]      \[u02C6] modifier circumflex   
\f[B]\[rs](ha\f[] circumflex/caret/\[lq]hat\[rq]
man/groff_char.7.man:\[ga]U.K.\& outer quotes\[aq]@\f[B]\[rs][oq]\f[]U.K.\&
outer quotes\f[B]\[rs][cq]\f[]
man/groff_char.7.man:\[ga]U.K.\& \[ga]\[ga]inner\[aq]\[aq]
quotes\[aq]@\f[B]\[rs][oq]\f[]U.K.\& \f[B]\[rs][lq]\f[]inner\f[B]\[rs][rq]\f[]
quotes\f[B]\[rs][cq]\f[]
man/groff_char.7.man:\[ga]\[ga]U.S.\& outer
quotes\[aq]\[aq]@\f[B]\[rs][lq]\f[]U.S.\& outer quotes\f[B]\[rs][rq]\f[]
man/groff_char.7.man:\[ga]\[ga]U.S.\& \[ga]inner\[aq]
quotes\[aq]\[aq]@\f[B]\[rs][lq]\f[]U.S.\&
\f[B]\[rs][oq]\f[]inner\f[B]\[rs][cq]\f[] quotes\f[B]\[rs][rq]\f[]
man/groff_char.7.man:\[bracketrightex]  \e[bracketrightex]      u23A5   right
square bracket extension


These are entries in the special character glyph name lists.  While revising
the page I found it much more maintainable if I used very wide tab stops (in
the editor only) and turned off wrapping.  This case may have to remain
as-is.


src/devices/gropdf/gropdf.1.man:rectangle which covers whole current page size
(in which case the rest of the
src/devices/gropdf/gropdf.1.man:dimensions to place the box. Including "fill"
in the command will make the
src/devices/gropdf/gropdf.1.man:rectangle filled with the current background
colour "\eM[colour]" and including
src/devices/gropdf/gropdf.1.man:The "cmd" may also be "off", on its own, which
will terminate drawing the
src/devices/gropdf/gropdf.1.man:Finally the command may be "footnote" followed
by a new value for "bottom"
src/devices/gropdf/gropdf.1.man:which will be used for all current boxes, just
for the current page. This is
src/devices/gropdf/gropdf.1.man:box is the vertical position of groff when you
issue the command and the bottom of
src/devices/gropdf/gropdf.1.man:coordinates are only used if the box drawing
extends onto the next page, so,
src/devices/gropdf/gropdf.1.man:If "box" is included in the command then this
parameter provides the line width
src/devices/gropdf/gropdf.1.man:There is also a macro file which can be
included if you are using the ms macro


I have on multiple occasions started but not completed (and therefore not
pushed) revisions of gropdf(1) and grops(1).  The above will be handled when I
finally carry off that task.


src/preproc/tbl/tbl.1.man:.\"so we might confine such interpolations to one
column of the table and


This is commented-out material.  If un-commented, it will be within the limit.
 I will review it but make no pledge of near-term revision.


src/utils/grog/tests/foo.man:.\"
========================================================================
src/utils/grog/tests/foo.man:.\" Set up some character translations and
predefined strings.  \*(-- will
src/utils/grog/tests/foo.man:.\" give a nicer C++.  Capital omega is used to
do unbreakable dashes and
src/utils/grog/tests/foo.man:.\" therefore won't be available.  \*(C` and
\*(C' expand to `' in nroff,
src/utils/grog/tests/foo.man:.    if (\n(.H=4u)&(1m=24u) .ds --
\(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
src/utils/grog/tests/foo.man:.    if (\n(.H=4u)&(1m=20u) .ds --
\(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
src/utils/grog/tests/foo.man:.\" Escape single quotes in literal strings from
groff's Unicode transform.
src/utils/grog/tests/foo.man:.\" titles (.TH), headers (.SH), subsections
(.SS), items (.Ip), and index
src/utils/grog/tests/foo.man:.\" entries marked with X<> in POD.  Of course,
you'll have to process the
src/utils/grog/tests/foo.man:.ds :
\\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
src/utils/grog/tests/foo.man:.ds o
\\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
src/utils/grog/tests/foo.man:.\"
========================================================================
src/utils/grog/tests/foo.man:.TH FOO 1 "2021-06-30" "perl v5.28.1" "User
Contributed Perl Documentation"
src/utils/grog/tests/foo.man:.\" For nroff, turn off justification.  Always
turn off hyphenation; it makes


This is a test case using pod2man(1) output and I will not alter it for this
purpose.


tmac/groff_mdoc.7.man:In addition to the page structure domain, there are two
more domains, the
tmac/groff_mdoc.7.man:The manual domain is defined as macros that are a subset
of the day to day
tmac/groff_mdoc.7.man:Macros in the manual domain handle command names,
command-line arguments and
tmac/groff_mdoc.7.man:options, function names, function parameters, pathnames,
variables, cross
tmac/groff_mdoc.7.man:These domain items have value for both the author and
the future user of the
tmac/groff_mdoc.7.man:Hopefully, the consistency gained across the manual set
will provide easier
tmac/groff_mdoc.7.man:(dot character) at the beginning of an input line in
some context other than
tmac/groff_mdoc.7.man:This means an argument on the argument list which
matches a general text or
tmac/groff_mdoc.7.man:In this case the argument, although the name of a macro,
is not preceded by
tmac/groff_mdoc.7.man:Macros whose argument lists are parsed for callable
arguments are referred
tmac/groff_mdoc.7.man:Several content macros are used to demonstrate page
layout macros; reading
tmac/groff_mdoc.7.man:If there are alternative values for a mandatory
parameter, braces are used
tmac/groff_mdoc.7.man:Three header macros designate the document title or
manual page title, the
tmac/groff_mdoc.7.man:These macros are called once at the very beginning of
the document and are
tmac/groff_mdoc.7.man:If it is specified, and no volume name is given, a
default volume name is
tmac/groff_mdoc.7.man:.No i386 , ia64 , ibmnws , iyonix , landisk , loongson ,
luna68k , luna88k ,
tmac/groff_mdoc.7.man:.No mvme68k , mvme88k , mvmeppc , netwinder , news68k ,
newsmips , next68k ,
tmac/groff_mdoc.7.man:.No ofppc , palm , pc532 , playstation2 , pmax , pmppc ,
powerpc , prep ,
tmac/groff_mdoc.7.man:.Ql
\*[doc-volume-operating-system]/\*[doc-volume-as-i386] \*[doc-volume-ds-2]
tmac/groff_mdoc.7.man:1.3, 1.3a, 1.4, 1.4.1, 1.4.2, 1.4.3, 1.5, 1.5.1, 1.5.2,
1.5.3, 1.6, 1.6.1,
tmac/groff_mdoc.7.man:1.0, 1.1, 1.1.5, 1.1.5.1, 2.0, 2.0.5, 2.1, 2.1.5, 2.1.6,
2.1.7, 2.2, 2.2.1,
tmac/groff_mdoc.7.man:2.2.2, 2.2.5, 2.2.6, 2.2.7, 2.2.8, 2.2.9, 3.0, 3.1, 3.2,
3.3, 3.4, 3.5, 4.0,
tmac/groff_mdoc.7.man:4.1, 4.1.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.6.2, 4.7, 4.8,
4.9, 4.10, 4.11, 5.0,
tmac/groff_mdoc.7.man:5.1, 5.2, 5.2.1, 5.3, 5.4, 5.5, 6.0, 6.1, 6.2, 6.3, 6.4,
7.0, 7.1, 7.2, 7.3,
tmac/groff_mdoc.7.man:7.4, 8.0, 8.1, 8.2, 8.3, 8.4, 9.0, 9.1, 9.2, 9.3, 10.0,
10.1, 10.2, 10.3,
tmac/groff_mdoc.7.man:2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 3.0,
3.1, 3.2, 3.3, 3.4,
tmac/groff_mdoc.7.man:3.5, 3.6, 3.7, 3.8, 3.9, 4.0, 4.1, 4.2, 4.3, 4.4, 4.5,
4.6, 4.7, 4.8, 4.9,
tmac/groff_mdoc.7.man:5.0, 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8, 5.9, 6.0,
6.1, 6.2, 6.3, 6.4,
tmac/groff_mdoc.7.man:1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.8.1, 1.9,
1.10, 1.11, 1.12,
tmac/groff_mdoc.7.man:1.12.2, 1.13, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7,
2.8, 2.9, 2.9.1, 2.10,
tmac/groff_mdoc.7.man:2.10.1, 2.11, 2.12, 2.13, 3.0, 3.0.1, 3.0.2, 3.1, 3.2,
3.2.1, 3.2.2, 3.3,
tmac/groff_mdoc.7.man:3.4, 3.4.1, 3.4.2, 3.4.3, 3.5, 3.6, 3.6.1, 3.6.2, 3.7,
3.8, 3.8.1, 3.8.2,
tmac/groff_mdoc.7.man:4.2.3, 4.2.4, 4.3, 4.4, 4.4.1, 4.4.2, 4.4.3, 4.5, 4.6,
4.6.1, 4.6.2, 4.7,
tmac/groff_mdoc.7.man:4.8, 4.8.1, 4.9, 5.0, 5.0.1, 5.0.2, 5.1, 5.2, 5.2.1,
5.2.2, 5.3, 5.4, 5.4.1,
tmac/groff_mdoc.7.man:in this example, the user has to replace the meta
expressions given in angle
tmac/groff_mdoc.7.man:Traditionally flags are marked by the preceding dash,
however, some commands
tmac/groff_mdoc.7.man:.Bl -tag -width ".Li .Fd\ X#include\ <sys/types.h>X"
-compact -offset 15n
tmac/groff_mdoc.7.man:command causes a line break if a function has already
been presented and a
tmac/groff_mdoc.7.man:This leaves a nice vertical space in between the
previous function call and
tmac/groff_mdoc.7.man:It may be used anywhere else in the man page without
problems, but its main
tmac/groff_mdoc.7.man:leaving a nice vertical space between the current
function name and the one
tmac/groff_mdoc.7.man:macro is used to specify the library where a particular
function is compiled
tmac/groff_mdoc.7.man:literal macro may be used for special characters,
variable constants, etc.\&
tmac/groff_mdoc.7.man:It has the peculiarity of remembering the first argument
it was called with,
tmac/groff_mdoc.7.man:regurgitates this initial name for the sole purpose of
making less work for
tmac/groff_mdoc.7.man:Note: A section two or three document function name is
addressed with the
tmac/groff_mdoc.7.man:(which produce an opening and a closing option bracket
respectively) may be used
tmac/groff_mdoc.7.man:.Bl -tag -width ".Li .Op\ Fl\ c\ Ar\ objfil\ Op\ Ar\
corfil\ ," -compact -offset 15n
tmac/groff_mdoc.7.man:section, it causes a line break (useful for old style
variable declarations).
tmac/groff_mdoc.7.man:The object being to enclose one or more strings between
a pair of characters
tmac/groff_mdoc.7.man:For each enclosure macro there is also a pair of open
and close macros which
tmac/groff_mdoc.7.man:macro inserts an apostrophe and exits any special text
modes, continuing in
tmac/groff_mdoc.7.man:.Bl -tag -width ".Li .Bq\ Em\ Greek\ ,\ French\ ."
-compact -offset indent
tmac/groff_mdoc.7.man:It was created from the same underlying enclosure macros
as those presented
tmac/groff_mdoc.7.man:macro suppresses insertion of a space between the
current position and its
tmac/groff_mdoc.7.man:macro designates a reference to a section header within
the same document.
tmac/groff_mdoc.7.man:section and begins collection of reference information
until the reference
tmac/groff_mdoc.7.man:macro is handled properly as a parameter; other macros
will cause strange
tmac/groff_mdoc.7.man:Its intended use is to imitate a small caps fonts for
uppercase acronyms.
tmac/groff_mdoc.7.man:If not specified, headers, footers and page layout
defaults will not be set
tmac/groff_mdoc.7.man:The description should be the most terse and lucid
possible, as the space
tmac/groff_mdoc.7.man:is required for manual page sections\~2 and\~3; the
command and general name
tmac/groff_mdoc.7.man:Several other macros may be necessary to produce the
synopsis line as shown
tmac/groff_mdoc.7.man:section is a brief paragraph on the command, function or
file, followed by a
tmac/groff_mdoc.7.man:section should reveal any related environment variables
and clues to their
tmac/groff_mdoc.7.man:Files which are used or created by the man page subject
should be listed via
tmac/groff_mdoc.7.man:.Oo \-offset Ao string Ac Oc Oo \-file Ao file name Ac
Oc Oo \-compact Oc Xc
tmac/groff_mdoc.7.man:The block of text is formatted (i.e., the text is
justified on both the left
tmac/groff_mdoc.7.man:is specified with one of the following strings, the
string is interpreted to
tmac/groff_mdoc.7.man:The indentation value is normally set to\~6n or about
two thirds of an inch
tmac/groff_mdoc.7.man:macro name, and the default offset value associated with
this macro is used.
tmac/groff_mdoc.7.man:argument is parsed to make a row, each column within the
row is a separate
tmac/groff_mdoc.7.man:macro name, and the default width value associated with
this macro is used.
tmac/groff_mdoc.7.man:macro name, and the default offset value associated with
this macro is used.
tmac/groff_mdoc.7.man:Suppress insertion of vertical space before the list and
between list items.
tmac/groff_mdoc.7.man:.\" \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup
struct\e\ dictionarytable\e\ *tab[]
tmac/groff_mdoc.7.man:.\" .Fn struct\ dictionarytable\ *dictionarylookup char\
*h struct\ dictionarytable\ *tab[] ,
tmac/groff_mdoc.7.man:.\" .Fn struct\ dictionarytable\ *dictionarylookup char\
*h struct\ dictionarytable\ *tab[] ,
tmac/groff_mdoc.7.man:.\" .Fn struct\ dictionarytable\ *dictionarylookup char\
*h struct\ dictionarytable\ *tab[] .
tmac/groff_mdoc.7.man:.\" \&.Fn \*qstruct dictionarytable *dictionarylookup\*q
\*qchar *h\*q \*qstruct dictionarytable *tab[]\*q
tmac/groff_mdoc.7.man:.\" .Fn "struct dictionarytable *dictionarylookup" "char
*h" "struct dictionarytable *tab[]" ,
tmac/groff_mdoc.7.man:.\" .Fn "struct dictionarytable *dictionarylookup" "char
*h" "struct dictionarytable *tab[]" ,
tmac/groff_mdoc.7.man:.\" .Fn "struct dictionarytable *dictionarylookup" "char
*h" "struct dictionarytable *tab[]" .


This is groff_mdoc(7).  Until the last few lines it appears to govern itself
well within a 76 column limit rather than 72.  In that sense the original
report is not even applicable. At the very end, the lines that overrun are
commented out; see the tbl(1) case above.  And as with groff_mm(7), I have not
undertaken a comprehensive review and revision of this page.  Each one offers
a significant  project in that respect; with the latter it also promises to
tie Ingo Schwarze and me into a burlap sack together and watch us fight our
way out--dark entertainment for some members of the mailing list, perhaps, but
not something I want to gate a release on.

In any event I want to do a heavy revision on groff_out(5) before groff_mm(7)
or groff_mdoc(7), both because I think the first needs it more and because it
documents part of the groff "core".

Postponing.

    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?51327>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/