On Mon, 23 Aug 1999 18:46:58 -0700 (PDT) Ross Harvey <ross@ghs.com> wrote
> > From: Bernd Salbrechter <bernd@mycity.at>
> > On Fri, 20 Aug 1999 17:29:37 -0700 (PDT) Ross Harvey <ross@ghs.com> wrote
> > > > From: Lou Glassy <glassy@caesar.cs.montana.edu>
> > > >
> > > > dear all,
> > > >
> > > > I'd like to take the 'Package.txt' documentation for 
> > > > the NetBSD package system, and transmogrify it into 
> > > > a *roff document (which with other magic, could be 
> > > > converted into TeX, HTML, etc)...
> > > >
> > > > Question:  what *roff macro package would you recommend
> > > > to use for this sort of documentation?
> > > >
> > > > It looks like some of the docs under /usr/share/doc/psd
> > > > use the me package.  Is this the recommended one to use
> > > > for new documentation?
> > > 
> > > No, it should be done in -mdoc (see `man 7 mdoc', and `man 7 mdoc.samples')
> > > for a variety of reasons.
> 
> > I would say that this sort of documentations need a "table of contents"
> > and benefit from "decimal numbered sections", which -me and -ms provide,
> > but -mdoc not. Or have I missed some thing in -mdoc?
> 
> mdoc does provided numbered lists, and adding a number sequence to a document
> using troff number registers is trivial. A table of contents is a bit more
> work, but not difficult.
> 
> I would think that, these days, hypertext references are more important
> than page number references for the dead tree edition. At the moment, only
> mdoc provides a section cross reference directive, and this is automatically
> translated into hypertext links by -mdoc2html.

That really depends. I tent to read this documents in the train or at
the lake (no ocean in Austria) and there the pros for "dead tree edition"
at this places are:
  * much less heavy then a notebook.
  * Much more robust, have you ever tried to read a file on a soaked
    notebook ;-). I have read about destroyed hard-disks from permanent
    magnets mounted on the table instead on the front seat in German
    trains - genius engineering ;-).

But for "Package.txt" -mdoc will be the better way, because the HTML
edition is a must.

> But, point taken. A set of "NetBSD TOC macros" might be a good thing.

Is someone working on this? If not, what do you think about an -msdoc
(s for supplementary documentation), which include -mdoc and add decimal
number sections and TOC like -me. Full preprocessor support (eqn, pic,
tbl, refer) and footnotes are also a good idea to add. The layout
describing parts from -me, should not go into -msdoc.

I can work out a proposal and do the work, but without a time frame,
because we got a baby in yesterday and I have no idea how much time
will be left for fun like hacking roff macros.

...

> > >     *	we have the -mdoc2html macros in-tree
> > A few days ago I saw an article in <news://gnu.groff.bug> about an html
> > back end and that someone starting up to maintain groff. (If someone is
> > interest in the thread, I have saved at least the interesting parts.)
> 
> I believe that text conversion at the back-end level is misguided; it's an
> attempt to get a lot of bad html at low cost.
> 
> The approach taken by -mdoc2html is to translate at the request level.
> Consequently, information as to the structural nature of the marked-up
> text is still available. This information is completely filtered out by
> the time a post-markup text-domain (i.e., back end) tool gets to it.
> 
> These tools do things like scan for http:// in text and make them links.
> Such a tool can't do relative section linking, because it doesn't actually
> know what is a cross reference and what isn't. It can only guess...

You are right and I know HTML is a little bit more than just an other
printer, even it can be abused as such. My impression on the thread,
is they have a back-end to handle the low level request, and a modified
macro set can do its job at the request level. After looking at the
source I think there is support for HTMLified macros, but no macro set
is converted this way yet, but it's an alpha version.

...

> It has already been done for INSTALL, although, without a page-numbered
> TOC.

I really have to install NetBSD-1.4.x :-).

Have a nice day
Bernd Salbrechter