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

[Andreas Grünbacher]

Branden,

2018-05-30 17:32 GMT+02:00 G. Branden Robinson <address@hidden>:
> Hi folks,
>
> In the course of trying to figure out why "quilt graph --all" wasn't
> working the way I expected, I was wondering why the quilt man page
> didn't look like others I work with and a look at its sources revealed
> that it did a few things unconventionally.
>
> As a groff and man-pages project contributor, I use and like quilt a
> lot, so I decided to spend a few hours making the page more attractive
> and more in line with recommended best practices.
>
> I've attached a patch and reproduced the patch header inline.
>
> I'd be pleased to offer further explanation/justification of any changes
> I'm proposing.  I have ideas for further contributions I can make; they
> appear at the bottom below.
>
> And let me thank you all profusely for not using docbook-to-man, which
> generates man pages that make one long for the beauty of sendmail.cf.

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.

Thanks,
Andreas

> ---
> Refactor man page.
>
> This is a major refactor with respect to organization and markup, and a
> minor one with respect to the actual content.
>
> The general theme is to make the man page much more consistent with good
> *roff and man page style as documented in man-pages(7), groff_man(7),
> the GNU Troff manual, and elsewhere.
>
> I can't promise this is comprehensive, but:
>
> * Expand the synopsis to cover more invocation scenarios.
> * Mark up synopsis canonically (literals in bold, variable content in
>   italics, and roman for "synopsis language" (option brackets, etc.)).
> * Escape hyphens that are supposed to be ASCII hyphens.  This helps with
>   cut-and-paste of text from multiple output formats, not just the
>   terminal.
> * Use character escapes for directional quotes and spacing tilde.
> * Use man macros for font face changes; reduces the amount of syntax to
>   learn (or imitate), and gets you proper italic corrections when
>   abutting italic with non-italic text,
> * Reorganize sections to use only section names endorsed by
>   man-pages(7), and put them in the recommended order.
> * Expand OPTIONS section to document -h.
> * Add ENVIRONMENT section and migrate relevant content to it.
> * Use subsection (SS) and start/end example macros (EX/EE) more
>   liberally.
> * This patch presumes the availability of the groff extensions to the
>   man macro package, which are 20+ years old and permissively licensed.
>   The ones used can be copied into the header of this page if necessary.
> * One or two other groff extensions are used (like long names for
>   character escapes); others, like the .fam request, are removed.
> * 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.
> * Tidy and tighten the language in places.
> * Add BUGS section noting deficiencies in the QUILT_COLORS discussion.
> * Add reference to ECMA-48 (with URL) for canonical discussion of ANSI
>   escape sequences.
>
> Still to be done:
>
> Use correct markup in the @REFERENCE@ material, generate good-looking
> ASCII output from it (with groff), and interpolate THAT into the
> generated README file.
>
> More ambitiously, doc/reference could be moved into the man page
> directly (with appropriate markup), appropriate markers added (only
> visible when groff is specially invoked) and good-looking ASCII output
> interpolated into README.
>
> Feedback?  Thoughts?
>
> --
> Regards,
> Branden
>
> _______________________________________________
> Quilt-dev mailing list
> address@hidden
> https://lists.nongnu.org/mailman/listinfo/quilt-dev
>