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