Re: [Groff] Nesting font macros in man pages

[Ingo Schwarze]

Hi,

G. Branden Robinson wrote on Tue, Apr 25, 2017 at 07:14:58AM -0400:

> No, what I really want is a TP-ish macro that lets you break the tag
> across multiple input lines, so the writer doesn't have to use font
> escapes.
> 
> If that means a new macro, I'm fine with that.

I think that plan is even worse.  Even in mdoc(7), i think extremely
carefully before proposing a new macro and avoid it if it is somehow
possible, even though in mdoc(7) it would be less of a problem
because legacy implementations virtually don't exist: everybody is
using mandoc, groff, or Heirloom, so extending the language would
be viable - but it is still better to avoid it.  I don't think i
invented a single new macro during during the about seven years
that i maintain mdoc(7).

For man(7), introducing new macros would be worse.  There, it would
utterly break portability because other implementations do exist,
for example on commercial Solaris and maybe on other commercial
systems, and man(7) still matters as the fallback language to use
when installing portable software and its documentation on legacy
systems, even if that documentation is written in mdoc(7).  So i
don't think we can afford inventing new man(7) macros.  Using them
would utterly destroy portability of the affected manuals.

> This is fine, but it says to me that your original complaint ("a
> horrible hack [to be] avoided ... even in the implementation of macro
> sets") is overstated.

In that sense, maybe, though i said "to be avoided if possible".

> Maybe \c it's like inline assembly in C.  Something best reserved to
> experts under special circumstances, perhaps, but not a horrible hack.

I guess we can agree on that, yes.


> At 2017-04-25T07:04:27+0200, Ingo Schwarze wrote:

>> Well, and the partial one in mandoc, but mandoc follows groff in
>> roff matters.

> I need to look more deeply into that; I don't know how you'd implement
> mandoc without implementing the bulk of *roff.

I explained that during an international conference in 2011:

  https://www.openbsd.org/papers/bsdcan11-mandoc-openbsd.html

Pages 7, 12, 13, 14, 20, 24 are particularly relevant to your question.

There are newer presentations, see http://mdocml.bsd.lv/press.html,
in particular the recent overview

  https://www.openbsd.org/papers/eurobsdcon2015-mandoc.pdf


>> G. Branden Robinson wrote on Mon, Apr 24, 2017 at 09:22:25PM -0400:

>>> If \c is documented badly and/or under-specified, let's determine its
>>> precise semantics and document them clearly.

>> I do suspect there is room for improvement, or at least clarification,
>> in the \c specification, so working on that likely makes sense.
>> But please, regard that as a work to help macro implementors,
>> **not** end users!

> Well, fine, let's proceed with that, then.  See end of this mail.

I don't see any patch there...
Did you forget to append it?

> The groff community needs to be singing from the same hymnal when it
> comes to recommended best practices.  If an-ext.tmac should be
> deprecated and avoided, that needs to be formally established and
> reflected in the software releases, maybe with a .tm warning in its
> source.

I agree that would be better.

>>> In my experience, one can write an attractive manpage almost without
>>> ever restoring to straight requests.

>> And yet you suggest that authors should use the \c escape sequence,
>> which quite definitely is a very low-level roff feature and not
>> an element of the man(7) language at all.

> Yes, but so are character escapes, which are unavoidable in good
> manpage writing.

Well, mandoc_char says:

  DESCRIPTION
     This page documents the roff(7) escape sequences accepted by
     mandoc(1) to represent special characters in mdoc(7) and man(7)
     documents.

     The rendering depends on the mandoc(1) output mode; in ASCII
     output, most characters are completely unintelligible.  For
     that reason, using any of the special characters documented
     here, except those discussed in the DESCRIPTION, is strongly
     discouraged; they are supported merely for backwards compatibility
     with existing documents.

     In particular, in English manual pages, do not use special-character
     escape sequences to represent national language characters in
     author names; instead, provide ASCII transcriptions of the
     names.

And then it lists the following characters under DESCRIPTION

  \& \(mi \(en \(em "\ " \(dq \(ga \(aq \(ti \e

in the sense that none of the many others should be used, and even
most of these few are rarely needed.  Only \& and \e are common.

So you may be slightly overstating the case for character escapes.

>> In the example you bring up, there is indeed no viable alternative to
>> using \f font escapes.  You propose to trade the \f for \c.  I say \c
>> is much worse than \f.  The syntax and semantics of \f is relatively
>> easy to understand, and people writing man(7) are used to it, while \c
>> is quite arcane.

> Okay.  What alternatives can you propose for getting rid of \f in man
> pages, short of migrating the universe to mdoc?

I am not away of any way to do that without utterly breaking
compatibility.  Unfortunately.  If you find one, great, but i
doubt that any is possible.

>>> (People are often ignorant of the an-ext macros, which are so
>>> liberally licensed they can be used anywhere.)

>> I admit that the en-ext macros minimally improve semantic capabilities
>> of the man(7) language, but by so little that man(7) remains an
>> almost exclusively presentational language even with man-ext.
>> For that reason, i deem that using man-ext does more damage than
>> good:  It doesn't substantially improve the language, but it
>> does cause compat grief on old systems, which is exactly where
>> the legacy man(7) language is still needed.  Bad tradeoff...

> What I'm hearing is that you feel that man(7) is a lost cause:
> 
> A.  It desparately needs improvement because of its presentational,
>     rather than semantic, focus.
> B.  Improvement will break portability.
> 
> This basically amounts to doing nothing and letting man(7) die of its
> own accord.

Exactly.

I'm a strong believer in incremental software development.  But
there are exceptional cases where incremental improvements are not
viable, in particular when the basic paradigm employed is busted
and the language is a dense tangle of historically cemented layering
violations.  The man(7) language is one of these cases.  Fortunately,
it has been obsolete for 25 years now, and mdoc(7) is mature and
readily available.  That GNU is the last major free operating system
that did not adopt it yet does not preclude future progress.

> But it hasn't.  Look at the past 20 years.  It's still alive,
> and what vibrancy it has lost, it has lost to stuff like Markdown
> which is even _less_ semantic.

Agreed:  Markdown (and probably ASCIIdoc, too) are worse than man(7):

  http://undeadly.org/cgi?action=article&sid=20170304230520

> Not to mdoc.

Look at the last seven years. 

mdoc(7) and mandoc(1) are firmly established in all *BSD projects
and in Minix 3.  Illumos (formerly OpenSolaris) switched to mdoc(7)
in 2014.  Even in the GNU/Linux camp, there is some movement.  Debian
has an official mandoc port since 2016, Arch Linux since 2010.
Alpine Linux and Void Linux use mandoc by default (rather than the
man-db + groff combo) since 2014.

Changes take time.  I haven't given up on GNU just yet.

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

> I have my pet peeves as well; I don't like the shouty caps in arguments
> to TH and SH.  That's information-losing and presentationy.

Admitted, i don't like that either, but that (ugly) convention is
uncontroversial: all existing documentation recommends it.

What i was talking about was not "pet peeves", but unnecessary
divergence from previously established standards.  The Linux man
pages project was started in 1993.  By that time, groff already
unambiguously documented most of the points i listed.  Yet man-pages(7)
gratuitiously diverged in these - admittedly minor - respects.

> Why not encourage people to have site-local files that redefine
> these macros to do a ".tr aAbBcC" etc. if they insist on seeing
> screaming caps?

That old AT&T UNIX era convention could probably simply be dropped
without replacement, but it doesn't seem high priority.


>>> At 2017-04-24T18:29:57+0200, Ingo Schwarze wrote:

>>>> Writing mdoc(7) is much easier for the novice because it's semantic
>>>> and because it does not require mixing in low-level roff features.

>>> And yet, why have so few people outside of the BSD community adopted it?

>> Frankly, i'm not sure.  Illumos has, for example; so of the free
>> operating systems, it's mostly GNU that doesn't use it.  One reason
>> could likely be that GNU used to use texinfo(1), but that is being
>> abandoned now.

> Is that official?  The last time I checked their list archives (a few
> months ago), they were openly wondering "whither texinfo?" but hadn't
> yet decided to abandon the project.

https://lists.gnu.org/archive/html/groff/2014-02/msg00104.html


> 1.  Let's document, for the newbs and ourselves, what the heck "\c"
>     really means.

Sure, but i don't see the patch you promised.

> 3.  Let's talk to the man-pages folks about harmonizing style
>     recommendations.

Sure, though that may be a slow process and some differences will
likely remain.  The Linux man pages project is only one project,
while the conventions documented in groff and mandoc documentation
are used across four major projects, and the Linux man pages project
is the one that deviated from established practices in the few minor
points noticed in the first place (side note: OpenSolaris diverged
even more).  Yet, i would understand the Linux man pages project
would hesitate to edit all their pages for harmonization.

Such slight differences between different projects are also not
fatal, even if they put a slight strain on casual readers in
heterogenous environments.

Yours,
  Ingo