Bug#900033: dpkg-deb.1: Some fixes in the manual

[Bjarni Ingi Gislason]

On Mon, May 28, 2018 at 02:59:24AM +0200, Guillem Jover wrote:
> On Mon, 2018-05-28 at 02:47:40 +0200, Guillem Jover wrote:
> > On Thu, 2018-05-24 at 22:34:36 +, Bjarni Ingi Gislason wrote:
> > >   Begin each sentence on a new line (or use two spaces between them,
> > > which is not recommended as the text contains formatting commands).
> > > See man-pages(7) [package "manpages"] and "info groff".
> > 
> > This is a somewhat controversial style dispute in general, and I find
> > two spaces uglier. :) In addition vim seems to agree, and prints red
> > on ".  " with syntax highlighting.
> 
> Let me clarify. I do not agree with the explicit two space after dot,
> I've always found that to be rather ugly. OTOH I find the rationale
> for splitting sentences on newline sound, because it reduces diff
> changes as it requires less text reflowing. The fact that groff
> considers that an implicit ".  " is then minor, although still
> slightly annoying. :) Split lines still looks ugly and unnatural when
> reading the source though, so I'm still not 100% sold on that one.
> 
> But I've only split lines for text I've added or changed, I don't
> think touching existing text just for this is worth the diff noise.
> 
  "groff" has an extended ".ss" request.  To get only one space
character between sentences in the formatted man page,".ss 12 0" is
used in a file that is always read, for example "troffrc", "man.local",
"mdoc.local" or some personal file that is named in "GROFF_TMAC_PATH".

-- 
Bjarni I. Gislason

Bug#900033: dpkg-deb.1: Some fixes in the manual

[Bjarni Ingi Gislason]

On Mon, May 28, 2018 at 02:47:40AM +0200, Guillem Jover wrote:
> Hi!
> 
> [ I've seen you have filed a different bug report for each man page
>   you have checked/reviewed, but that might mean tons of bugs for lots
>   of pages. Probably better to reuse one of this for further fixes, or
>   this might get a bit out of control. :) ]
> 
  I usually only test for warnings from "groff".  If there are some, I run
the whole testing script on the man pages, if there are not too many.
Otherwise just patches to eliminate the warnings.

> On Thu, 2018-05-24 at 22:34:36 +, Bjarni Ingi Gislason wrote:
>[...] 
> >   Protect an ellipsis on both sides, '\&...\&'.
> 
> Why do we need this?
> 

  This is to make the same "form" for an ellipsis everywhere (only one
version of an ellipsis)
The best, simplest way is to define a string, for example the following
is usually used:

.de EL \&.\|.\|.\&

  The first '\&' is for the case the ellipsis starts on the beginning of
a line.
  The second to neutralize the "end-of-sentence" meaning of the period.

> >   Protect a full stop, exclamation mark, that is not an end of sentence.
> 
> Idem?
> 

  I do not understand this.

> >   Know the difference between "abc..." and "abc ...".
> 
> This one seems wrong. In the cases I've seen changed, it applies to
> command-line argument description, where "foo..." has a distinctive meaning
> of repetition, so splitting it seems wrong.
> 

  People write "foo..." because

1) The first ones did not know better

2) Other saw this and copied it.

  Read about ellipsis in relation to the text before it.

  foo... means missing letters, foo ... means missing words (or more
types of text "foo" are possible))

> >   Print a reverse solidus (\) with '\e', not '\\'.
> 
> Ok I guess. Although I think in POD we'd just use \\.
> 
> >   Use a macro 'I', 'IX', or 'XI' instead of escape requests, where the
> > italic correction is too often missing in the text.
> 
> If this was being writen from scratch, then I guess, but given the
> current text I think it makes little sense, and it makes the conversion
> uglier. So I'd rather avoid it. Also if we wanted better markup I'd
> rather consider switching from man to mdoc macros.
> 

My patches changes this only if there are a few cases.
Some prefer the escapes, but I find it harder to read and understand
than the macros.  And the italic corrections are too often missing.

> >   Begin each sentence on a new line (or use two spaces between them,
> > which is not recommended as the text contains formatting commands).
> > See man-pages(7) [package "manpages"] and "info groff".
> 
> This is a somewhat controversial style dispute in general, and I find
> two spaces uglier. :) In addition vim seems to agree, and prints red
> on ".  " with syntax highlighting.
> 

  Man pages use two spaces, that is the legacy form.
To avoid controversies of style a new line is the best choice; also
better for patches.

  I only split a line if there is only one space character between
sentences and there are not many cases.  Sometimes I only add the
second character.

  I find it better to fix this when discovered, than waste somebody's
time later.

> > #
> > 
> > Test nr. 40:
> > 
> > Add a comma after "e.g." and "i.e." (man-pages(7) [package "manpages"]).
> > 
> > 251:members (i.e. \fBcontrol.tar\fP and \fBdata.tar\fP; since dpkg 1.17.6).
> 
> This probably needs to be done globally over the entire git repo's
> contents.
> 

  The best way is to drop these Latin abbreviations and use the English
words; there is no need to shorten text nowadays.

  So I will change common abbreviations to words in the future.

-- 
Bjarni I. Gislason

Bug#900033: dpkg-deb.1: Some fixes in the manual

[Guillem Jover]

On Mon, 2018-05-28 at 02:47:40 +0200, Guillem Jover wrote:
> On Thu, 2018-05-24 at 22:34:36 +, Bjarni Ingi Gislason wrote:
> >   Begin each sentence on a new line (or use two spaces between them,
> > which is not recommended as the text contains formatting commands).
> > See man-pages(7) [package "manpages"] and "info groff".
> 
> This is a somewhat controversial style dispute in general, and I find
> two spaces uglier. :) In addition vim seems to agree, and prints red
> on ".  " with syntax highlighting.

Let me clarify. I do not agree with the explicit two space after dot,
I've always found that to be rather ugly. OTOH I find the rationale
for splitting sentences on newline sound, because it reduces diff
changes as it requires less text reflowing. The fact that groff
considers that an implicit ".  " is then minor, although still
slightly annoying. :) Split lines still looks ugly and unnatural when
reading the source though, so I'm still not 100% sold on that one.

But I've only split lines for text I've added or changed, I don't
think touching existing text just for this is worth the diff noise.

Thanks,
Guillem

Bug#900033: dpkg-deb.1: Some fixes in the manual

[Guillem Jover]

Hi!

[ I've seen you have filed a different bug report for each man page
  you have checked/reviewed, but that might mean tons of bugs for lots
  of pages. Probably better to reuse one of this for further fixes, or
  this might get a bit out of control. :) ]

On Thu, 2018-05-24 at 22:34:36 +, Bjarni Ingi Gislason wrote:
> Package: dpkg
> Version: 1.19.0.5+b1
> Severity: minor
> Tags: patch

>   Warnings from "groff":
> 
> :133 (macro IR): only 1 argument, but more are expected
> :210 (macro BR): only 1 argument, but more are expected
> :279 (macro BR): only 1 argument, but more are expected
> 
> Output is from: test-groff -b -e -mandoc -T utf8 -rF0 -t -w w -z 
> 
>   ["test-groff" is a developmental version of "groff"]

Ah, nice stuff. Thanks for trying to cleanup the markup, it's
always appreciated. :)

> ###
> 
>   Summary:

Some of these I do not agree with, and in addition might even make a
possible conversion to POD
()
I've been pondering about, more difficult. Some others might actually
make it easier, and some might be irrelevant, as pod2man does
unfortunately not care (such as the - and \- distinction).

>   Remove extra quotation mark (").

Good.

>   Use '\(en', not '\-' to denote a range of numbers.

Ok I guess, with POD we could encode it with E<>, or ignore it.

>   Protect an ellipsis on both sides, '\&...\&'.

Why do we need this?

>   Protect a full stop, exclamation mark, that is not an end of sentence.

Idem?

>   Know the difference between "abc..." and "abc ...".

This one seems wrong. In the cases I've seen changed, it applies to
command-line argument description, where "foo..." has a distinctive meaning
of repetition, so splitting it seems wrong.

>   Print a reverse solidus (\) with '\e', not '\\'.

Ok I guess. Although I think in POD we'd just use \\.

>   Use a macro 'I', 'IX', or 'XI' instead of escape requests, where the
> italic correction is too often missing in the text.

If this was being writen from scratch, then I guess, but given the
current text I think it makes little sense, and it makes the conversion
uglier. So I'd rather avoid it. Also if we wanted better markup I'd
rather consider switching from man to mdoc macros.

>   Begin each sentence on a new line (or use two spaces between them,
> which is not recommended as the text contains formatting commands).
> See man-pages(7) [package "manpages"] and "info groff".

This is a somewhat controversial style dispute in general, and I find
two spaces uglier. :) In addition vim seems to agree, and prints red
on ".  " with syntax highlighting.

> #
> 
> Test nr. 40:
> 
> Add a comma after "e.g." and "i.e." (man-pages(7) [package "manpages"]).
> 
> 251:members (i.e. \fBcontrol.tar\fP and \fBdata.tar\fP; since dpkg 1.17.6).

This probably needs to be done globally over the entire git repo's
contents.

Thanks,
Guillem

Bug#900033: dpkg-deb.1: Some fixes in the manual

[Bjarni Ingi Gislason]

Package: dpkg
Version: 1.19.0.5+b1
Severity: minor
Tags: patch

Dear Maintainer,

   * What led up to the situation?

  Warnings from "groff":

:133 (macro IR): only 1 argument, but more are expected
:210 (macro BR): only 1 argument, but more are expected
:279 (macro BR): only 1 argument, but more are expected

Output is from: test-groff -b -e -mandoc -T utf8 -rF0 -t -w w -z 

  ["test-groff" is a developmental version of "groff"]

###

  Summary:

  Remove extra quotation mark (").

  Use '\(en', not '\-' to denote a range of numbers.

  Protect an ellipsis on both sides, '\&...\&'.

  Protect a full stop, exclamation mark, that is not an end of sentence.

  Know the difference between "abc..." and "abc ...".

  Print a reverse solidus (\) with '\e', not '\\'.

  Use a macro 'I', 'IX', or 'XI' instead of escape requests, where the
italic correction is too often missing in the text.

  Begin each sentence on a new line (or use two spaces between them,
which is not recommended as the text contains formatting commands).
See man-pages(7) [package "manpages"] and "info groff".


###

  Details:

Input file is dpkg-deb.1

mandoc: dpkg-deb.1:68:32: STYLE: unterminated quoted argument



Test nr. 5:

Change '-' (\-) to '\(en' (en-dash) for a numeric range.

dpkg-deb.1:234:The accepted values are 0-9 with: 0 being mapped to compressor 
none for gzip.

#

Test nr. 8:

Protect a full stop (.) with "\&", if it has a blank (white-space) in
front of or (ignoring characters transparent to it) after it, and it
does not mean an end of a sentence.

28:.RI [ option "...] " command
43:.BR dpkg\-deb ". " dpkg
57:.IR binary-directory ". " binary-directory
251:members (i.e. \fBcontrol.tar\fP and \fBdata.tar\fP; since dpkg 1.17.6).

#

Test nr. 10:

Separate an ellipsis from the preceding string with a space
character, if it does not mean a continuation of it.

See a manual of style about the difference between "abc..." and
"abc ...".

28:.RI [ option "...] " command
99:.BR \-I ", " \-\-info " \fIarchive\fP [\fIcontrol-file-name\fP...]"
122:.BR \-f ", " \-\-field " \fIarchive\fP [\fIcontrol-field-name\fP...]"

#

Test nr. 16:

Use the correct macro for the font change of one argument.
Split a  punctuation mark from the only argument if one is there

133:.IR control-field-name
210:.BR \-\-version
279:.BR \-\-nocheck

#

Test nr. 20:

Use "\e" to print the escape character instead of "\\" (which gets
interpreted in copy mode).

229:The default for this field is \(lq${Package}\\t${Version}\\n\(rq.

#

Test nr. 21:

Use a macro to change to the italic font, instead of \fI [1], if
possible.
The macros have the italic corrections, but "\c" removes them
  or
add the italic corrections.
[1] man-pages(7) [package "manpages"]

215:\fB\-\-showformat=\fP\fIformat\fR
221:\(lq${\fIfield-name\fR}\(rq form, a list of the valid fields can be easily
265:\fIrootless\-builds.txt\fP), but should \fBnot\fP be used when the

#

Test nr. 40:

Add a comma after "e.g." and "i.e." (man-pages(7) [package "manpages"]).

251:members (i.e. \fBcontrol.tar\fP and \fBdata.tar\fP; since dpkg 1.17.6).

#

Test nr. 41:

Wrong distance between sentences or protect the indicator.

1) Separate the sentences and subordinate clauses; each begins on a new
line.  See man-pages(7) [package "manpages"] and "info groff".

Or

2) Adjust space between sentences (two spaces),

3) or protect the indicator by adding "\&" after it.

The "indicator" is an "end-of-sentence character" (.!?).

61:as the control file itself. This directory will
71:and parse it. It will check the file for syntax errors and other problems,
119:argument. The default format displays the package's name and version
132:control file. If more than one
142:package archive. It is currently produced in the format generated by
152:result in a correct installation! Use
182:format (since dpkg 1.17.14). Together with
191:format. Together with
217:will produce. The format is a string that will be output for each package
224:on the same package. A complete explanation of the formatting options
240:building a package (since dpkg 1.16.2). Allowed values are \fBnone\fP (since
251:members (i.e. \fBcontrol.tar\fP and \fBdata.tar\fP; since dpkg 1.17.6).
253:\fBdata.tar\fP member will use those parameters. The only supported
282:usual checks on the proposed contents of an archive. You can build
291:Enables debugging output. This is not very interesting.
317:to install software! You must use
333:md5sum control file generated by debian/rules. Though this is not directly

#

  Patch:

--- dpkg-deb.1  2018-05-06 07:53:26.0 +
+++ dpkg-deb.1.new  2018-05-23 22:49:55.0 +
@@ -25,7 +25,7 @@ dpkg\-deb \- Debian package archive (.de
 .
 .SH SYNOPSIS
 .B dpkg\-deb
-.RI [ option "...] " command
+.RI [ option " \&...\&] " command
 .
 .SH DESCRIPTION
 .B dpkg\-deb
@@ -40,7 +40,7 @@ You can also invoke
 by calling
 .B dpkg
 with whatever options you want to pass to
-.BR