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 Sun, 17 Jun 2018 18:13:40 -0400, G. Branden Robinson wrote:
> 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.

The general rule is that each patch in a series should be as
self-sufficient as possible to avoid the need to read the whole series
before starting the review, make it possible to accept certain changes
and reject others, and also to make it possible to backport a subset of
the series if needed. In the case of code, it also avoids breaking
future bisections.

However I am going to be tolerant here, due to the nature of the
changes (documentation only), the size of the series, and the amount of
splitting work you already did.

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

Thanks for doing that. I'll trust you on that, no time to check.

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

This is precisely the relative nature of the file paths (added to the
random name of most of the involved files) which led me to the
conclusion that this example did not fit in FILES.

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

I agree it also does not fit perfectly in EXAMPLE either. But it was in
neither originally, it is you who insist to only use standard
sections ;-)

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

I guess I would not include an example of working tree in the first
place if I had to write the manual page from scratch. On the other hand
I can't disagree that it is a useful reference for new users, so
dropping it wouldn't be smart.

Considering the working tree "picture" as a mere illustration, I see
that the main focus of that section was to explain the purpose of the
patches/ and .pc/ directories within the working tree. These are
relative (as discussed above) but at least they have well-defined names.

So, OK, let that part of the manual page live in FILES.

-- 
Jean Delvare
SUSE L3 Support