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]

At 2018-06-17T23:04:08+0200, Jean Delvare wrote:
> On Sat, 16 Jun 2018 12:22:36 -0400, address@hidden wrote:
> > Use subsection macro (SS) where helpful.
> 
> That one is harder to review...

I think most of your concerns are addressed by subsequent patches.  In
this one I was trying not to alter any lines that I was moving, _except_
for section headings, which is the whole point of the patch.  Naturally
when deranging some slabs of running prose, some forward and backward
references are going to get scrambled.

Let me see if I can locate the fixes for the issues of concern, below.

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

This one is fixed in [14/26], "Document -h flag in the Options section."

> > +.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,".

This one is fixed in [24/26], "Wordsmith Environment section."

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

The man-pages project defines the FILES section as "A list of the files
the program or function uses, such as configuration files, startup
files, and files the program directly operates on." (man-pages(7)).

Quilt directly operates on many files, namely those in the .pc and
patches subdirectories.  man-pages(7) tells us, "Give the full pathname
of these files, and use the installation process to modify the directory
part to match user preferences"--however the very nature of quilt is
such that .pc and patches will all be relative to one or more arbitrary
locations, so we can't use absolute paths.

My perspective is that the Example of (a) Working Tree is neither
intended as nor useful primarily as an example of _use_ for the quilt
program ("One or more examples demonstrating how this function, file or
command is used," as man-pages(7) puts it).

Instead, the example working tree is offered to illuminate the reader
with respect to the locations of the files quilt opens and operates on.
Many man pages can just throw down an absolute path and be done with it,
but that won't do for quilt's working trees.

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

This one is fixed in [12/26], "Update internal and external
cross-references."

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

I'm happy to update patch [12/26] to include a mention of examples on
offer in that document, so I'll do that.

> It is getting late here, so I'll review the remainder of this patch
> series tomorrow.

Thanks!  I'm glad I anticipated some of your concerns; please let me
know about the ones which remain.

-- 
Regards,
Branden

signature.asc
Description: PGP signature