[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
signature.asc
Description: PGP signature
- [Groff] Nesting font macros in man pages, G. Branden Robinson, 2017/04/24
- Re: [Groff] Nesting font macros in man pages, Ralph Corderoy, 2017/04/24
- Re: [Groff] Nesting font macros in man pages, G. Branden Robinson, 2017/04/24
- Re: [Groff] Nesting font macros in man pages, Ingo Schwarze, 2017/04/24
- Re: [Groff] Nesting font macros in man pages, G. Branden Robinson, 2017/04/24
- Re: [Groff] Nesting font macros in man pages, Ingo Schwarze, 2017/04/25
- Re: [Groff] Nesting font macros in man pages, G. Branden Robinson, 2017/04/25
- Re: [Groff] Nesting font macros in man pages, Ingo Schwarze, 2017/04/25
- Re: [Groff] Nesting font macros in man pages, Steffen Nurpmeso, 2017/04/25
- Re: [Groff] Nesting font macros in man pages,
G. Branden Robinson <=
- Re: [Groff] Nesting font macros in man pages, Ralph Corderoy, 2017/04/26
- Re: [Groff] Nesting font macros in man pages, G. Branden Robinson, 2017/04/26
- Re: [Groff] Nesting font macros in man pages, Steffen Nurpmeso, 2017/04/27
- Re: [Groff] Nesting font macros in man pages, Ingo Schwarze, 2017/04/27
- Re: [Groff] Nesting font macros in man pages, James K. Lowden, 2017/04/28
- Re: [Groff] Nesting font macros in man pages, Damian McGuckin, 2017/04/28
- Re: [Groff] Nesting font macros in man pages, G. Branden Robinson, 2017/04/28
- Re: [Groff] Nesting font macros in man pages, John Gardner, 2017/04/28
- Re: [Groff] Nesting font macros in man pages, Ralph Corderoy, 2017/04/29
- Re: [Groff] Nesting font macros in man pages, James K. Lowden, 2017/04/30