Re: [Groff] Nesting font macros in man pages

[G. Branden Robinson]

At 2017-04-25T16:52:20+0200, Ingo Schwarze wrote:
> 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).

I'm not suggesting recklessness.  Any proposals to extend the man macro
package should be mooted in a discussion involving experts and users,
not thrown over the wall, take-it-or-leave-it style.

Any extensions _I_ propose I expect to be evaluated in a context of
"rough consensus and working code".

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

No, because we have the long precedent of an-ext.tmac and its licensing.
Any man macros not declared in the Cretaceous can be defined inline in
man page sources.  Those who care about portability to legacy
environments can do this, and those who don't can leave them out.

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

Sadly for our consensus, I'm finding evidence against this position in
existing man pages.  I've started a new thread for that.

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

Thanks!  I'll have a look at these.

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

I haven't written it yet.  I don't feel I have a full understanding of
\c yet, just an intuitive "feel" which won't do for technical
documentation.

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

I don't advocate this course of action; I'm reminding you that you
aren't the dictator of What Shall Be.  ;-)

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

In groff(7) and CSTR #54, \c is given precise parity with every other
escape.

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

I like mdoc's introduction of macros to replace character escapes in man
pages sources.  It's something I'd like to see in further development of
an-ext.tmac.  Sorry to madden you.  ;-)

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

As noted in the thread I just started, people have been using \c to
achieve this trick in several high-visibility man pages for many years.

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

Progress demands a path.  People are not rewriting all of their man(7)
pages in mdoc(7).  How do you propose to incentivize them?  Even if
someone funded a third-party mass-rewriting effort, you have no
guarantee that upstream authors and maintainers would accept the
transition.

You cannot strike the world with lightning and remold it your wishes.
What do you propose to do instead?

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

Nothing I aim to propose should prevent anyone from migrating to mdoc if
it's attractive to them.  I think some of the worst habits of man page
writers can be addressed with parts "a" and "b" of my proposal below,
but I don't expect to be able to semanticize man(7) pages to the degree
that mdoc(7) can.  The former has too much legacy and technical debt.

You want to scoop up the people who are willing to do a wholesale
rewrite of their man pages from man(7) to mdoc(7).

My aim is to improve the man(7) usage of people who _aren't_.

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

You're making a testable assertion here.

1. Portability is not harmed if extended man macros are inlined in pages
   where portability to legacy systems is desired.
2. All *roff/man processors generate output.  These outputs can be
   prepared.

I am not interested in portability problems to platforms that do not
exist in the real world.

I am prepared to measure the impact of my proposals.

> and c) may or may not help to convince people.

Then I respectfully submit that mdoc(7) has a big problem appealing to
people.  That's going to seriously frustrate your initiative.

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

Why should they have to learn the old man(7)?  Write in the new one.

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

It's easy enough to kill off, especially for TH, since almost no man
pages in all of *nix-dom have non-ASCII characters in their names.

.SH is a little trickier since these strings are localizable.  However,
the domain of section titles in man pages is small, and in CJK languages
there aren't case distinctions anyway.

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

Well, bold and brave Linux hackers weren't just going to take GNU's word
for anything.  :-|

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

Yeah, I'd love to take it out back and shoot it but it's not near the
top of my list, either.

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

Thanks.  I see that this involves an Eric Raymond initiative.

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

See above.  I'm not yet prepared to write it.  But I will once I have
achieved sufficient understanding, if no one beats me to it.

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

Somewhere in the man-pages suite there are words to the effect that they
expected a superior macro package to come along some day.  If I stumble
across it again I'll be sure and raise it to the group's attention.

Unless you can point me to evidence that the man-pages folks are
cussedly recalcitrant I'm going to assume they're as cooperative as any
mature development group.

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

Yes, and I'm not sure the section ordering problem is insuperable.
With a little tweak to the SH macro, for example, sections could be
pushed into diversions and then popped in a site-configurable order, for
example.

Okay, I said that just to give you a heart attack.  ;-)

Regards,
Branden

signature.asc
Description: PGP signature