Re: [groff] groff as the basis for comprehensive documentation?

[Nate Bargmann]

* On 2018 19 Apr 18:47 -0500, James K. Lowden wrote:
> On Fri, 20 Apr 2018 01:44:06 +1000
> John Gardner <address@hidden> wrote:
> 
> > > You might like to believe that eqn, tbl, and pic could be processed
> > > with grohtml
> > 
> > I've seen grohtml's complexity and was bewildered.  Hence why I
> > intend to write my own. The procedures for inferring structural or
> > semantic metadata from low-level intermediate output commands will be
> > an entertaining challenge. =)
> 
> For lack of a better term, I think it's an abstraction mismatch.  The
> ditroff language presupposes a dot-addressable canvas, onto which lines
> and strings of text are drawn.  That model fits most printers (these
> days) and terminals.  But it doesn't describe HTML at all.  
> 
> I discussed HTML output with Ted Faber, of grap, upon a time.  He
> produces HTML from a handful of his own macros.  ISTM ms macros map
> onto HTML pretty well:
> 
>       .SH     => <h1>
>       .PP     => <p>
>       .I      => <i>
>       .B      => <b>
> 
> and so on.  But what, for example, is HTML to do with line
> justification, and why should the browser honor the (implied) line
> breaks, when it has its own line-wrapping logic and style sheet, and
> the page size is dynamic?

I suppose it depends on what one expects from the generated HTML.  As
one who reads pages more than writes them, I've been impressed with the
presentation on the man-pages project Web site (hosted at kernel.org).
For example, here is the rendering of groff_man(7):

    http://man7.org/linux/man-pages/man7/groff_man.7.html

I couldn't find the generator being used in the Git repository and a lot
of it may be done with CSS.  The text is rendered using the <pre> tag so
it looks much like tty output though it is not fully justified yet the
text blocks are indented.  Aside from the justification, the rest looks
very familiar to me.  Links to other hosted man pages are present.

I, for one, do not expect an HTML rendered version of *anything* to
be a faithful representation of a printed page.  The output of
"groff -man -Thtml ..." is reasonable for my purposes, except that I'd
like to be able to generate relative links in a page to other pages in
my project.  Maybe I just need to do some sed(1) transformation after
groff is done.

Note that I am only working with Groff's man macro package and do
understand that other macro packages may have greater demands on the
HTML generator.

- Nate

-- 

"The optimist proclaims that we live in the best of all
possible worlds.  The pessimist fears this is true."

Web: http://www.n0nb.us  GPG key: D55A8819  GitHub: N0NB

signature.asc
Description: PGP signature