Re: [TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[G. Branden Robinson]

Hi Larry,

At 2023-09-19T16:39:25-0700, Larry McVoy wrote:
> One of the projects I thought I'd do in my retirement, but haven't
> done, was to provide man page / paper as in "a paper", not tree paper,
> versions of all the GNU info stuff.  I could not be less thrilled with
> info, yeah there are ways to deal, but it just isn't as good (to me)
> as how Unix did docs.  It's like they want to force emacs on us to
> read docs.
> 
> I'd start with groff.
> 
> So I'm a little off topic but if people wanted to work on that, I'd be
> up for that project.  It's not as big as what you are saying but it's
> pretty big, I think we just start with something, see if we can get
> debian/ubuntu to pick it up, lather, rinse repeat.

You have raised this issue before (multiple times) so I will remind you
that I'm working on this.

$ COLUMNS=72 git diff --stat 1.22.4 1.23.0 man/{roff,groff{,_font,_out}}.*.man
 man/groff.7.man      | 9853 ++++++++++++++++++++++++++++--------------
 man/groff_font.5.man | 1269 ++++--
 man/groff_out.5.man  | 1035 +++--
 man/roff.7.man       | 2973 +++++++++----
 4 files changed, 9991 insertions(+), 5139 deletions(-)

Check out the compiled groff man pages PDF.  I'm open to your critiques
but I'd prefer you made then when I could be confident that had recently
familiarized yourself with the problem.

https://www.gnu.org/software/groff/manual/groff-man-pages.pdf

> The one drawback I see is people might want to provide info and man
> docs.  My personal preference is that the info stuff goes away but I
> have learned I don't get what I want.  So there may be a period of
> time where both need to be maintained.

I have no particular love for Texinfo, but it really is trying to do a
somewhat different thing than a man page does.  As Trent Fisher and
Werner Lemberg left it, groff's Texinfo manual felt (to me) influenced
by the O'Reilly Nutshell book approach.  And that's not a bad thing.  It
converses with and guides the reader in a way that classically laconic
Unix man pages don't.

Since Bertrand released groff 1.23.0 in July, I've further whacked on
the early chapters of the groff Texinfo manual (among other things).
You can find a bleeding edge version here.

https://www.dropbox.com/sh/17ftu3z31couf07/AAC_9kq0ZA-Ra2ZhmZFWlLuva?dl=0

But if someone simply refuses to read the Texinfo manual, I've tried to
make roff(7) an introduction to the formatting language and further
developed groff(1) as a general introduction from the command-line
perspective.

I think we're deep into the "maintain both" period:

$ grep -n '@c.*parallel' doc/groff.texi
584:@c BEGIN Keep parallel with groff(1), section "Description" (after the
602:@c END Keep parallel with groff(1), section "Description" (after the
605:@c BEGIN Keep parallel with groff(1), section "Usage" (introduction).
616:@c END Keep parallel with groff(1), section "Usage" (introduction).
1591:@c BEGIN Keep parallel with groff(1), subsection "Paper format".
1626:@c END Keep parallel with groff(1), subsection "Paper format".
1631:@c BEGIN Keep parallel with groff(1), section "Examples".
1696:@c END Keep parallel with groff(1), section "Examples".
5036:@c BEGIN Keep roughly parallel with roff(7) section "Concepts".
5342:@c END Keep roughly parallel with roff(7) section "Concepts".
5561:@c TODO: Consider parallelizing with groff_tmac(5) "Description".
5934:@c BEGIN Keep (roughly) parallel with section "Measurements" of
6052:@c END Keep (roughly) parallel with section "Measurements" of groff(7).
...
16963:@c BEGIN Keep parallel with section "Warnings" of troff(1).
17138:@c END Keep parallel with section "Warnings" of troff(1).
17568:@c BEGIN TODO: Make parallel with groff_out(5).
18448:@c END TODO: Make parallel with groff_out(5).
18453:@c BEGIN Keep parallel with groff_font(5).
18940:@c END Keep parallel with groff_font(5).

Yes, these are screeching examples of DRY violation.  But such
violations are warranted if doing so means that users have a fighting
chance to obtain competence with the system being documented.

Regards,
Branden

signature.asc
Description: PGP signature