"G. Branden Robinson" <g.branden.robin...@gmail.com> 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