[dholland@netbsd.org: Re: Extension for more general documents]

[Thomas Klausner <wiz@NetBSD.org>]

Some comments from David (who's not subscribed, so I've forwarded his
mail; please cc him on replies).

----- Forwarded message from David Holland <dholland@netbsd.org> -----

let's see if I can post on this list...

On Sat, Jun 14, 2014 at 02:16:00PM +0200, Ingo Schwarze wrote:
 > Thomas Klausner wrote on Fri, Jun 13, 2014 at 10:35:36AM +0200:
 > 
 > > We'd really like to move away the documents in NetBSD's base system
 > > from the groff -ms and -me macro sets to anything else that can be
 > > easily converted to txt, html, and pdf.
 > > 
 > > We already have mandoc in the base system and it supports these output
 > > formats. So it seems to be a good candidate, and mdoc already provides
 > > the formatting options we need (AFAIK).
 > > 
 > > We probably would just need to add a mode to mandoc where it doesn't
 > > insist on a man page header and instead supports some article
 > > information like a title.
 > 
 > Uh, oh.  Indeed i misunderstood this request completely.
 > 
 > So let's look at how the csh document currently looks like,
 > as an example:
 > [snip]
 >
 > I would consider the repeated page headers (USD:4-2  An Introduction
 > to the C shell) useless, we deliberately didn't implement these in
 > mandoc(1).  For ABSTRACT (and other headers), .Sh and .Ss could be
 > used; losing the centering doesn't seem like a grave problem.
 > So what remains is the title and author.  The title could just be
 > provided by Nd, and the author information moved to the end into
 > the AUTHORS section, and no changes to the mdoc(7) language would be
 > required at all.

While I think that would work adequately for some of the documents, it
will not work with others. There are some papers among the documents
that really need to be typeset as papers with proper title and author
headings.

 > In case you don't consider this good enough, what exactly do you
 > think is required, so which changes/options/features would you
 > consider the minimum that would need to be changed in mandoc
 > or added to mandoc?

A way to produce an article title and author block that looks like a
title and author block. I think that's all.

It is not clear at the moment what other typesetting features these
articles might need - many use tbl (but that's not a problem, right?),
and at least one each uses eqn and pic. Some have bibliography and/or
references, and also bottom-of-page footnotes. Also, at least one
contains a context-free grammar that currently comes out pretty
ratty-looking. One also uses little marker tags in the left margin,
but that can probably be edited out.

At least one article contains floating figures; does mandoc handle
those? I'm guessing not. There's also one that wants to have block
headers on subsections, which I think is difficult in -mdoc.

Several documents also have indexes, most of which currently appear to
be broken. It would be nice to repair/extend these but it isn't really
a top priority.

-- 
David A. Holland
dholland@netbsd.org

----- End forwarded message -----
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv