groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [groff] Release Candidate 1.22.4.rc3


From: Ingo Schwarze
Subject: Re: [groff] Release Candidate 1.22.4.rc3
Date: Thu, 29 Nov 2018 07:11:34 +0100
User-agent: Mutt/1.8.0 (2017-02-23)

Hi Larry,

Larry Kollar wrote on Wed, Nov 28, 2018 at 11:42:00PM -0500:
> Ingo Schwarze <address@hidden> wrote:
>> Branden wrote:

>>> * My semantic macro package extending groff_man(7), if I can get it
>>>  where I'm happy with it and folks on the list don't bleed from the
>>>  eyes about it.

>> That would be a HUGE step backwards, making the groff manual pages
>> even less portable (they are already among the 20-30 least portable
>> manual page sets in those about ten thousand free software projects
>> that i looked at, and the amount of portability problems in groff
>> manual pages is vastly larger than in most other of those 20-30
>> projects).  You surely want to make that worse, right?

> Being a fan of semantic markup myself, I'd normally agree.
> On the other hand, wouldn't the groff manpages always come
> with a groff formatter?

Don't FreeBSD manual pages always come with FreeBSD and Linux manual
pages always with Linux?  No, they dont't, i read more FreeBSD,
NetBSD, and Linux manual pages on OpenBSD than on any other system.
Also, somebody might want to peek at the groff manual pages in the
source tree before compiling groff.

But more importantly, how does it help to have groff installed,
even installed system-wide?  On almost all operating systems, you
can install groff, but on several, it won't be the default manual
page formatter.  Examples: FreeBSD, OpenBSD, NetBSD, illimos, Alpine
Linux, Void Linux, maybe some versions of Solaris or other commercial
Unix systems, ...

So, you installed the groff programs, but you cannot install the
manual pages because the system's manual page formatter would choke
on them.  What do you do?  Hack into the groff build system to
format the manual pages at build time, then install the preformatted
versions?  That's what we did in the OpenBSD port of groff until a
month ago.  Then, i implemented about a dozen new features in
mandoc(1) just for groff, just for being able to handle the groff
manual pages - and that was *after* years of work done to cope with
low-portability manual pages in other software packages.

> Groff is the *de facto* standard for *roff these days;

No doubt about that; i'd say since approximately 1994, so for well
over twenty years.

> I for one wouldn't mind semantic extensions to groff_man(7). It would
> allow for the kind of flexibility HTML offers now, except for an equivalent
> to tidy(1) to corral presentational markup. It might also go a long way
> toward eliminating a lot of the portability issues -- who's to say
> alternate *roff developers won't adapt the extended macros for their
> own packages?

Well, the largest ecosystem with non-roff as the manual page formatter
is FreeBSD (plus the smaller cousins OpenBSD, NetBSD, illumos,
Alpine Linux, ...) so i would be forced to implement them in mandoc.
Inconvenient because it basically means bowing to NIH syndrome and
because there is more important fish to fry, but likely to happen
anyway.  I already implemented man-ext and several other GNU
extensions in the past, even many of those that i consider bad
ideas.

The second largest ecosystem are commercial Unix distros.  I'd be
surprised if those would move at all, they typically don't do
anything about anything.  MacOS is in the same boat - even though
significant parts are actually FreeBSD, it is typically static and
lagging behind for extremely long times - as in, many years.

Carsten Kunze might implement them in Heirloom, if he finds time
and is interested; i don't know.  But Heirloom is not commonly used
as a manual page formatter as far as i'm aware.

> There are three things I have tried (and failed) multiple times to
> wrap my head around: TeX, emacs, and mdoc. Stuff like
> 
>       .Op Fl c Ar class Oo Fl p Ar end-class Oc Oo Fl s Ar subclass Oc

Not using line breaks is an easy way to make any code less readable,
one familiar technique in Perl golfing and code obfuscation contests.
The normal way to write that is

  .Oo
  .Fl c Ar class
  .Op Fl p Ar end-class
  .Op Fl s Ar subclass
  .Oc

Looks quite readable to me - "optional flag s with argument subclass, ..."

If you want, you can even use indentation, though BSD traditionally
doesn't do that:

  .Oo
  .  Fl c Ar class
  .  Op Fl p Ar end-class
  .  Op Fl s Ar subclass
  .Oc

How is that harder than:

  .RB [ \-c
  .I class
  .RB [ \-p
  .IR end-class ]
  .RB [ \-s
  .IR subclass ]]

> OTOH, I certainly wouldn't object if someone rewrote all the Groff man
> pages in mdoc. It might be a good warmup to whacking down that
> Texinfo beast. ;-)

Seems less urgent since on most systems, access to even low-portability
manual pages is easier than to texinfo that most people will
completely overlook (which is what started this subthread).  Less
urgent in particular now since mandoc supports the existing groff
manuals, so they now also work on BSD systems out of the box.  But
sure, if people want it, i can do that...  It would certainly make
many things better: more uniform and semantic markup, better HTML,
semantic search support for free (both on systems having mandoc
and on online on websites), and so on...

By the way, a texinfo2mdoc(1) program exists - even though the
output will require lots of manual postprocessing.  The toolchain
to get started with a man->mdoc conversion would probably be
doclifter(1), then docbook2mdoc(1) on the result, which is even
more fragile and will likely require at least as much manual
postprocessing.

Yours,
  Ingo



reply via email to

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