Re: [Quilt-dev] [PATCH] clean up the quilt man page

[Jean Delvare]

Hi Branden and Andreas,

On Fri, 1 Jun 2018 07:35:33 -0400, G. Branden Robinson wrote:
> At 2018-06-01T13:11:40+0200, Andreas Grünbacher wrote:
> > I'm not going to jump ahead of Jean who has been maintaining quilt the
> > last couple of years, but thanks, your changes look like an
> > improvement. The patch is somewhat difficult to review because it
> > mixes formatting and content changes, so that may take a while.  

To be honest, I started looking into it last Friday, but the patch was
so large and raised so many questions (because I don't know much about
*roff really, just enough to survive) that I had to switch to something
more urgent before going to the end, and then I forgot about it.
Smaller patches are clearly easier to process.

> I like focused changesets as much as anyone (it's one of the things
> quilt facilitates marvelously), but this turned out to be a monolith
> because I had no idea when I started how much I was going to be
> changing.
> 
> I'm happy to break this into chunks if that would ease review, but I'd
> like some feedback on how finely to chop it.
> 
> The changes I can think of that do the most to obscure others are:
> 
> > > * Eliminate empty lines; they are bad *roff style.  
> 
> > > * Break lines after sentences.  In many cases, only a single space was
> > >   used between sentences, which leads to incorrect inter-sentence
> > >   spacing in all *roff output formats.  Two spaces are better (because
> > >   groff recognizes them as separating sentences, but line breaks are the
> > >   best style.  

About that... Personally I find it harder to read, because a line break
between 2 sentences looks like a change of paragraph to me. Is there
actually any benefit of using a line break instead of two spaces, other
than personal preference?

> > > * Reorganize sections to use only section names endorsed by
> > >   man-pages(7), and put them in the recommended order.  
> 
> It would be straightforward for me to prepare 1-3 patches that perform
> the above; I think all the other changes could be more easily reviewed
> even as remaining "monolith".
> 
> Suggestions?

Sounds like a great plan. If you are able to split the changes into 3
or 4 patches, that should make the last one small enough to be
reviewable, even if it contains a mix of "all the rest".

Specifically, sections reorganization must be a separate patch because
it is intrusive. The first two points above, however, can be 2 patches
or 1 patch, I'm fine either way, because they are somewhat related and
should not collide with each other - so whatever is easier for you.

Believe me, I'm not going to make your life harder than strictly
needed for my reviewing needs, I'm very happy to have a *roff
specialist at my fingertips to clean up our man page, so I am going to
trust you on everything.

Thank you very much,
-- 
Jean Delvare
SUSE L3 Support