Re: [Groff] man pages (tangential to Future Redux)

[Ingo Schwarze]

Hi Eric,

while i appreciate your intention to get rid of info(1),
what you are proposing here looks like throwing the baby
out with the bathwater...

Eric S. Raymond wrote on Fri, Feb 28, 2014 at 12:15:35PM -0500:

> Where we're probably going is that (a) info will die, to be replaced
> by HTML browsed from within Emacs, and

That's two bad ideas in half a sentence.  Most free software is also
portable software.  Emacs is restrictively licensed (GPL), so you
cannot assume it is available on the systems where the software will
be used.  Even systems that support installing emacs as an add-on
cannot use it for manual display because manual display has to be
part of the base system, not something dependent on third-party
add-on software.

And you are certainly aware that distributing system documentation
as HTML will meet strong resistance in many communities.  In some
because they consider HTML as overkill for manuals, in others - like
the groff community - because typesetting quality resulting from it
is inferior.  This has just been discussed here.

> (b) Texinfo will be replaced by a modern lightweight format that
> can render to both print and HTML; most likely asciidoc.

That's another really terrible idea.  The asciidoc package is not
lightweight at all, it depends on docbook-xsl and python.  Besides,
it's about the slowest documentation formatting system i'm currently
aware of.  It is so slow that its use can cause serious increases
of build times in ported software builds.  Often, merely formatting
documentation with asciidoc consumes build times of comparable order
of magnitude needed for compiling the software itself.  It is much,
much slower than groff for formatting manuals (and note that while
groff is a really fast typesetting system, it is relatively slow
when used as a mere manual formatter).

So, many systems will continue to require man(7) or mdoc(7) manuals
for installation.  With pushing portable software authors towards
using asciidoc(1), you are doing the world a very serious disservice,
because among all automatic man(7) code generators i'm aware of,
DocBook has by far the poorest output quality, so by all means, we
should try to push people *away* from asciidoc, not towards it.

Fortunately, what you are campaigning for is not likely to happen.
Take the OpenBSD ports tree as an example.  Currently, it contains
8743 software packages.  Out of these, 16 use asciidoc; that's
below 0.2%, and i hope it will stay like that.  Even with this
low number, i remember multiple complaints regarding the quality
of these manuals, and multiple bogus mandoc bug reports that
were actually asciidoc's or DocBook's fault, i.e. broken code
generation.

> Because the man-page stubs were a kludge to get around the complications of
> browsing info outside of Emacs, I expect they'll quickly be perceived as
> unnecessary after this transition and abolished in favor of Web pointers
> to the real documentation.

I doubt very much that is ever going to happen.  Web pages are not
a replacement for documentation installed on the local machine.  I
do want to have access to manuals of installed software when offline,
and i certainly do not want links out of locally installed software
documentation to point to the web.  That would be much worse than
pointing me at the locally installed info(1) utility, which will
at least be available and document the actual version of the software
if have.

> 1. Jawbone all the world's man page authors into cleaning up their
> markup so doclifter can interpret it structurally to clean XML and
> (through that) HTML.  I've been pretty successful at this: see
> http://www.catb.org/~esr/doclifter/bugs.html for details and
> statistics.
> 
> 2. Some time ago I added to Linux man(1) the capability to recognize
> HTML pages in the man hierachy and kick them over to the user's Web
> browser.  All Linux and *BSD distributions now ship this code.

I'm not quite sure what you mean by Linux man(1); i failed to find
your name here:  http://git.savannah.gnu.org/cgit/man-db.git/log/

Anyway, i'm quite sure OpenBSD man(1) doesn't contain code you
wrote, and a quick check of NetBSD, FreeBSD, and DragonFly didn't
reveal anything, either.  Note that FreeBSD man(1) is implemented
in a different programming language than the three others.  That
already excludes code sharing.

Besides, the functionality you propose here would almost certainly
be rejected in the BSD communities, even if patches were sent.  The
man(1) utility is supposed to be fully functional without a browser.

> Where I want us to be is that when users call man(1) the normal
> behavior is to render through the browser.

That is most definitely not going to happen in OpenBSD, and i would
be very surprised if any other BSD would follow.  Not all environments
are running X, not all environments are fit for running a browser,
but you want manuals everywhere.  And i doubt that any people even
*want* to see manuals in a browser.  Very few people use PostScript
or PDF viewers in some cases, but i never heard about anybody wanting
manuals in their browser - even though it is easily feasible with
current tools, just have man(1) write to a tempfile and call the
browser on that, using the usual man.conf(5) or manpath(1) or
whatever mechanisms.

So, if you will ever start to push this, you are likely to
end up with even worse fragmentation than we have now.

Yours,
  Ingo