Re: [groff] Release Candidate 1.22.4.rc3

[Larry Kollar]

Ingo Schwarze <address@hidden> wrote:
> 
>> 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.

OK, point taken. I still feel like it’s a corner case, but one that could trip
people up. Sticking macros in manpages is Bad Form, IMO, especially
if there are non-roff formatters involved as you mention.


>> I for one wouldn't mind semantic extensions to groff_man(7).…
> 
> 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.
> …
> 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.

Yeah. Even Mojave (the latest MacOS) has Groff 1.19.2. I basically have
to recompile and overwrite the base install after every system update.


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

Cool. Believe it or not, that’s the first time I’ve seen mdoc options done
that way. ‘Most everyone seems to run them together on a single line,
despite your counter-examples being a lot easier to understand. It’s
certainly easier to read than a DITA <syntaxdiagram>. :-)  With that in
mind, I’ll give mdoc another shot. If it works out this time, I’ll rewrite the
Tines manpages in mdoc.


> By the way, a texinfo2mdoc(1) program exists - even though the
> output will require lots of manual postprocessing. …

That’s a given. At work, we’ve finished the bulk of a conversion to DITA,
and there’s a bunch of cleanup to be done even using a high-end
conversion vendor. I was able to shell-script a lot of cleanup (thank God
and RedHat for Cygwin, because they make us use Dozeboxes at work),
fortunately. But yeah, converting anything to anything isn’t going to be
seamless. Tools like doclifter and Pandoc are a lot of help, but not an
end to all troubles.

What would *really* be fun would be:

        cat manpage | doclifter | pandoc -f docbook -t man

And see if anything readable comes out the other end. :D

        Larry