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.

[Jean Delvare]

On Tue, 12 Jul 2022 09:05:12 -0500, G. Branden Robinson wrote:
> 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

My notes say:

[JD: Preserve the EXAMPLE section]

So basically I was OK with the change, except for the removal of the
EXAMPLE section.

> 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.

This (and many other things I complained about during my initial
review) were in fact address by other patches later in the series. I am
generally strict on the requirement that patches should be as
independent from each other as possible, however I decided to make an
exception this time, firstly because we're dealing with documentation,
not code, so being able to bisect the series is less valuable. Secondly
because the work on this already lasted way too long and moving
individual changes from one patch to another potentially means editing
several patches in between just to make them apply again.

Well I think I wrote exactly that already in my reply that you linked
above.

Anyway, the bottom line is that all such comments from me can be
ignored, as long as the issue they point out no longer exists once all
26 patches are applied.

> > > (...)
> > > -.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.

That must have changed recently, as my copy of that man page has it in
singular form.

> 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.

That's pretty much how it looks like in my current version, I think.

-- 
Jean Delvare
SUSE L3 Support