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

[Eric S. Raymond]

Ralph Corderoy <address@hidden>:
> Important though a lightweight input format is, a lightweight set of
> tools for rendering it in the comman output formats is also needed.
> From others' comments it appears asciidoc doesn't give that at the
> moment.

Nor does Texinfo, if the same standards were applied.

> This still leaves the irony that groff's documentation is written in
> non-groff, lessening contributions from the audience.

I think it is also relevant that Texinfo markup is peculiar and
idiosyncratic.

> > While this won't directly solve the stub problem, it will at least
> > break the full documentation for GNU projects out of the ghetto they
> > have been living in onto the Web.
> 
> Hasn't the info documentation been on the web for a long time?
> https://www.gnu.org/software/groff/manual/html_node/index.html

Yes, HTML output from makeinfo does exist (I have contributed code to
that mode of makeinfo myself).  It's a  kludge, though, and not much
used.  Tellingly, the various pieces of HTML you can produce from
Texinfo sources are not even properly cross-linked to *each other*, 
let alone to the rest of the Web.

> > The functional win here is not so much HTML's display capabilities as
> > the fact that everything will be living in the same URLspace.
> 
> Do you mean the same schema, i.e. http, or that info and man don't have
> well-defined schemas of their own?

Yes, I mean the same schema.  "Well-defined schemas of their own" are
exactly what I mean by saying "ghettos".  Stock browsers can't
navigate those schemas.
 
>                                                      The "stubs" are
> because writing documentation is boring for volunteers that didn't write
> the code.

You're missing the forest for the trees.  Why wasn't "link to the long
form of the documentation" the right answer?  That would have been
easier than writing the stubs, if the technical capability to support
it were there.

What we have now in the Linux/Unix documentation world is a large
pre-hypertext pile of documents with no link structure (manual pages) 
and a smaller, weirder one (info) with a sort-of half-assed link structure.
My goal is to level the walls around both and merge them into the Web.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>