Re: [Quilt-dev] [patch 04/26] Reorganize sections to use only section names endorsed by man-pages(7), and put them in the recommended order.

[G. Branden Robinson]

Hi Jean,

At 2018-06-17T23:04:08+0200, Jean Delvare wrote:
> On Sat, 16 Jun 2018 12:22:36 -0400, g.branden.robinson@gmail.com wrote:
> > Use subsection macro (SS) where helpful.

I have to admit I'm not clear on the state of this one's acceptance.

Reviewing your last mail to me on item 4 in this series, I don't feel I
was left with a clear request for explanation or revision, but I'm also
not certain that you were completely satisfied.

https://www.mail-archive.com/quilt-dev@nongnu.org/msg02463.html

However, maybe it's a little easier to return to your initial reply,
below.

> > Index: quilt/doc/quilt.1.in
> > ===================================================================
> > --- quilt.orig/doc/quilt.1.in
> > +++ quilt/doc/quilt.1.in
> > @@ -112,9 +112,9 @@ and refreshing patches
> >  .RB ( "quilt refresh" ).
> >  Files in the .pc directory are automatically removed when they are
> >  no longer needed, so there is no need to clean up manually.
> > -.SH QUILT COMMANDS REFERENCE
> > +.SS Quilt commands reference
> >  @REFERENCE@
> > -.SH COMMON OPTIONS TO ALL COMMANDS
> > +.SH OPTIONS
> 
> I understand the rationale for renaming the section, however the
> information "common to all commands" is lost in the process, while I
> believe it was valuable (in contrast with all options listed under
> "Quilt commands reference", which are command-specific.) I think it
> should be reintegrated as an introduction message before the first
> option.

Yes, I think that's a good idea.  Alternatively, `SS` could be deployed
yet again to clarify this issue.  Or both.  Like this.

.SH OPTIONS
.SS "Common options"
The following options are recognized by all
.I quilt
commands.

(By the way, I no longer spell section titles in full capitals because
that is an information-losing transformation that should be done
optionally at formatting time (if at all) rather than in the source.
groff 1.23's man(7) implementation will support performing that
transformation and Ingo Schwarze, the mandoc(1) developer, either
already supports this revised convention or is planning to (he also
contributes to groff).

https://git.savannah.gnu.org/cgit/groff.git/tree/NEWS#n222
)

> > -.SH EXAMPLE OF WORKING TREE
> > +.SH ENVIRONMENT
> > +In addition to that, quilt recognizes the following variables:
> 
> After the move, it is no longer clear what "to that" refers to. The 2
> environment variables are in fact a complement to all the variables
> which can be set in quiltrc files. They are listed separately because
> they are not quilt-specific.
> 
> Given that these are actually independent from the rest, my
> recommendation would be to simply drop the "In addition to that,".

I'm amenable to that, and moreover, what remains is implied by the fact
of having a section of that name in a man page of that name, so the
whole sentence could go away.

As a personal style point, I avoid using trailing colons before lists as
an escape hatch from the responsibility of writing a complete sentence.
(I acknowledge that is it is super-popular among man page writers.)  So
dropping the sentence would be an even bigger win from my view.  ;-)

> > +.SH FILES
> > +.SS "Example of working tree"
> 
> I don't believe that the example working tree belongs to the FILES
> section. EXAMPLE is listed as an allowed section name in man-pages(7),
> so why not just use that?

I concur.

> Also note that somewhere else in the man page is a pointer to this
> part, under the form "see EXAMPLE OF WORKING TREE below." Notice the
> use of capitals. As these capitals will be gone after your rework, the
> pointer should be adjusted accordingly.

Agreed.  By the way, another nice feature coming in groff 1.23 is that
when you render to PDF, man page title headings, and section and
subsection headings all get bookmarked, meaning that a PDF viewer with a
navigation pane exposes them as clickable links.

> > -.SH EXAMPLE
> > -Please refer to the pdf documentation for a full example of use.
> 
> You are dropping this line completely. I know that the pdf
> documentation is mentioned later in the "SEE ALSO" section, but there
> the "example" keyword is missing. We really want to point users
> looking for concrete examples to that pdf documentation. So either the
> statement above must stay, or the description under "SEE ALSO" must be
> extended to state that the pdf documentation includes a full example
> of use.

If the file tree diagram is relocated to "EXAMPLES" (the Linux man-pages
project prefers the plural[1]), then this section heading indeed needs
to come back.

I also don't think it would be altogether bad to reference the PDF
documentation with explicit mention of an example in "SEE ALSO"; that
section ain't just for man page cross references.

Regards,
Branden

[1] https://man7.org/linux/man-pages/man7/man-pages.7.html

signature.asc
Description: PGP signature