Re: [PATCH 00/31]: revise man pages

"G. Branden Robinson" <[email protected]> Fri, 24 Apr 2026 10:13:20 -0500
Newsgroups	gmane.editors.nano.devel
Message-ID	<20260424151320.kbujr6ffhdoc7by2@illithid>
Hi Benno,

At 2026-04-24T12:45:15+0200, Benno Schulenberg wrote:
> Op 24-04-2026 om 00:53 schreef G. Branden Robinson:
> > I have some revisions to propose to nano's man pages.
> 
> Ooofff!  That's almost two megabytes of email that are of
> no interest to the average subscriber of this mailing list.

I apologize; I didn't realize that form of patch submission, which
people (including myself) have used on, say, the GNU bash, bug-ncurses,
and linux-man lists, was outside the norm--not to say the routine--on
the nano-devel list.

I won't do that again.

> :/  A tarball on Savannah would have been a better choice.

You mean attached to a Savannah ticket?  Acknowledged.

> > My objectives were to make the man pages more idiomatic as I
> > understand historical and contemporary composition practices,
> 
> With "idiomatic" you mean "conforming to a certain style"?
> If so, what style is that?  The style of other man pages?

Yes.  Of man pages in Unix and Unix-like operating systems.  Yes.

> > to exercise groff man(7) features I believe to be of value to
> > composers and human readers of man pages,
> 
> Used features should be in a release of groff that is at least
> five years old.  I've already seen the use of .MR (in patch 30)
> which doesn't work on my machine -- groff-1.22.4.

I considered the possibility, which is why I arranged the patch to adopt
`MR` late in the series.  In each patch adopting an extension, I
included in the commit log message historical information about that
extension's provenance/longevity.

Long story short: `MR` is the only one less than five years old.  As a
feature of groff man(7), it will reach that age in July 2028.

> > and to improve consistency among the documents internally and with
> > nano's Texinfo manual.
> 
> Most textual differences between the man pages and the info manual
> are on purpose.  When the same wording is used in both, it is just
> out of laziness.  Wording things in a different way increases the
> chances that a reader (of both texts) gets the precise meaning.

Ah, I see.  I didn't think of that.

> > Attachments:
> > 
> > 1.  a PDF of nano's man pages for U.S. letter paper
> > 2.  a PDF of nano's man pages for A4 paper
> > 3.  a gzipped tar archive of the documents after each patch,
> 
> Ouch.  No one asked for those.  That's a whole megabyte of
> unsolicited email.  :/

I apologize again.  The ideas were to (1) make it easy to appreciate the
improved typography and appearance of the nano man pages; (2) establish
that I made no changes parochially, improving page layout on U.S. Letter
paper while degrading it on ISO A4 format; and (3) aid any patch
reviewer to measure the impact of each change.  I had used all of these
as resources for myself in developing the changes for myself, and
thereby caught many errors in my own work.  I had thought of inclusion
of acceptance-testing materials as a courtesy and useful tool, not as
unwanted clutter.  I stand corrected.

> I will work through the patches one by one, as I find the time.
> Please don't answer those replies until I've finished.

Understood.  I won't submit a patch (or series) to this list again.

Regards,
Branden
signature.asc (application/pgp-signature, 833 B)