[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Quilt-dev] [PATCH] clean up the quilt man page
From: |
Jean Delvare |
Subject: |
Re: [Quilt-dev] [PATCH] clean up the quilt man page |
Date: |
Tue, 5 Jun 2018 13:17:04 +0200 |
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