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: Steffen Nurpmeso
Subject: Re: [Groff] Nesting font macros in man pages
Date: Thu, 27 Apr 2017 14:21:10 +0200
User-agent: s-nail v14.9.0-pre4-20-g5500e891

"G. Branden Robinson" <address@hidden> wrote:

Sorry for answering so late, my daily routine has shifted to night
again, almost sunset, and that really makes me frustrated.

 |At 2017-04-25T20:19:21+0200, Steffen Nurpmeso wrote:
 ...
 |>|> c.  Show people a mapping from groff's "extended" man macro package to
 |>|>     mdoc, so that the route for switching over is clearly signposted.
 ...
 |> 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.)

Sure it was.  I think there are multiple problems.
You have a notion of "callable" and "parsed", and you should be
aware of that or you introduce errors which are hard to find.  It
may be that you don't even see an error in the visual output
because no special font attribute applies or so.  Be aware that
"No" is a command that needs to be escaped.  Not rarely i see *BSD
commits fly by which fix errors in manual pages because of errors
in some nesting level, or missing escaping, and these programmers
use this language for many years or even decades.  Of course this
is part of normal iteration, too, but isn't it better if you have
a as-minimal-as-possible set of commands which clearly stand out.

Generally speaking both of man and mdoc spread the text and make
the source hard to grasp, which i don't consider to be something
viable, and which, together with the missing possibility to add
semantic information, here especially man, for richer output
formats, is surely part of the move away from roff.

  ...
 |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.

If i got that right it came up after the info system, and i will
always wonder why you do have semantic info for targets, but not
for sources, especially if you do invent a command set where many
commands take arguments, e.g., you do have ".Bd -literal", you do
have .Sx to refer to a heading, you do have .Va to refer to
a variable, why not ".Va -index" or the like, so that you can
specify where the .Va has been defined?  That is such a crucial
part of good documentation, especially in science, a good index!,
why was that missing.

 |> 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

Yes.

 |should emphasize that I'm here not to bury groff, but to praise it.
 |
 |Unlike, I think, [2].

I don't use doclifter.  And i prefer less and the tty over
anything else, really.  A few URLs to kick off, fine, but it is
absurd to go over the internet if the information is often
available locally already.  Anyway..

  ...
 |[2] https://lists.gnu.org/archive/html/groff/2014-02/msg00104.html

--steffen



reply via email to

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