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

[G. Branden Robinson]

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.

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

man-page-cleanup.patch
Description: Text Data

signature.asc
Description: PGP signature