groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Groff] Nesting font macros in man pages


From: G. Branden Robinson
Subject: Re: [Groff] Nesting font macros in man pages
Date: Wed, 26 Apr 2017 09:46:43 -0400
User-agent: NeoMutt/20170113 (1.7.2)

At 2017-04-25T20:19:21+0200, Steffen Nurpmeso wrote:
> Btw., if you want really clean man(7) you should point people to
> the really good guys, e.g., the plan9port manuals are a phantastic
> example of minimalistic and pure pages.

I'd love to, as I'm the sort who's still excited by Plan 9 (and its
successor Inferno), however, http://code.swtch.com/plan9port/ is a 404
for me.

Do you have an up-to-date link?

>  |> My recommendation is to take the momentum an-ext has, however small, and
>  |> press it:
>  |> 
>  |> a.  Add more macros to fit semantic needs and the hiding of lower-level
>  |>     requests and escapes.
>  |> b.  Hand-hold users to the nth degree with examples and recommended best
>  |>     practices.
>  |> c.  Show people a mapping from groff's "extended" man macro package to
>  |>     mdoc, so that the route for switching over is clearly signposted.
>  |
>  |It seems to me that b) is fine, a) is very problematic because it
>  |severely harms portability, and c) may or may not help to convince
>  |people.  I'm not sure the intermediate step of reinventing man(7)
>  |as a semantic language will make the transition easier.  Why should
>  |people have to learn a new man(7) language in between, in addition
>  |to the old man(7) and in addition to mdoc(7)?
> 
> Even though still without voice, a) is in no way problematic if
> the original roff command set is used and no wild and funny
> programming sessions lead to mandoc incompatibilities.  b) is
> fantastic, c) i don't really believe in, mdoc has quite some
> similarities to brainfuck, things like
> 
>   .Op : Ns Fl c Ar cc-addr Ns \&:
> or
>   .Fl S Ar var Ns Op Ns = Ns Ar value Ns
> 
> are nice for teaching, but no one can really promote something
> like this, can he.

I have two gripes about mdoc:

1. The slavish devotion to two-letter names for things, which like the
   man macro package and the oldest parts of *roff itself, make it
   self-anti-documenting.  I may be tempting mockery by saying this from
   a vi session inside an xterm, but good Lord, we've gotten past the
   days of ASR 33 teletypes by now[1].  (That said, I'm sure this
   unfriendliness was imposed by the existing *roff implementations at
   the time mdoc was designed.)

2. Most of mdoc's own documentation is too technical, even in
   mdoc.samples.  I find the glib and frequent usage of the term
   "domains" off-putting and inaccessible, and I don't think I'm
   unusually stupid.  (Pauses for a beat.)

But, not to pound on Ingo's beloved too much, from what I understand of
mdoc's design, I find it much, much better considered than man(7).  It
clearly benefited from having a large corpus of existing man pages to
consider, so it knew better than man(7) did what sort of problems it was
going to have to solve.

> And sometimes things have to be adjusted a bit so that things can
> overall stay the same.  The roff system is a fantastic
> achievement, and if at all possible i will use it until the day
> i die.  I am looking forward for my thing.

Agreed.  Any proposals I make are with an eye toward making the roff
system better, not worse.  That could go without saying--but I guess I
should emphasize that I'm here not to bury groff, but to praise it.

Unlike, I think, [2].

Regards,
Branden

[1] Somebody confirm for me that these were run with _remote echo_ at
    110 baud, so that every keystroke was an adventure in
    anticipation...
[2] https://lists.gnu.org/archive/html/groff/2014-02/msg00104.html

Attachment: signature.asc
Description: PGP signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]