Re: Extension for more general documents

[Ingo Schwarze <schwarze@usta.de>]

Hi David,

David Holland wrote on Sat, Jul 05, 2014 at 08:50:08PM +0000:
> 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.

>> 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.

Two changes in the upcoming mandoc-1.13.1 release might help with
this project:

 1) mandoc-1.13.1 no longer discards content preceding the first
    .Sh section header, as mandoc-1.12.3 did.

 2) mandoc-1.13.1 has partial support for the
    .Bd -centered
    display.  While that display ought to be set in fill mode,
    mandoc uses no-fill mode for now.  For title & author blocks,
    that's no problem at all.

So, you are welcome to test the document appended below with
mandoc-1.13.1 - i think it looks reasonable both in -Tascii
and in -Tpdf mode.  Note that mandoc doesn't need the .br
requests right now, but you should put them for compatibility,
or other implementations might re-wrap the lines.

Admittedly, this is not completely portable.  With groff, the
output looks less nice than with mandoc.

> 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?),

Usually, not a problem.  Now and then, some obscure tbl(7) features
crop up and we need to add them to the mandoc(1) implementation,
and sometimes tbl(7) isn't exactly top priority.  But usually such
stuff is not impossible to get supported.

> and at least one each uses eqn

If that's only used for trivial formulas, mandoc(1) might be good
enough.  If there are substantial mathematical equations,
probably not.  Basically, mandoc only has a terminal engine
for eqn(1), even when writing PS/PDF.  While the parser is quite
good, it's just impossible to adequately render equations in
ASCII text output.

> and pic.

No way.

> Some have bibliography and/or references,

That can probably be converted to .Rs, unless it requires some
kind of database data source with autogeneration or it is of
massive size (like many dozens or even hundeds of references).

> and also bottom-of-page footnotes.

That won't work in mandoc, and i wouldn't know where to start
supporting it.

> 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.

No idea regarding those two, that would need inspection of the actual
documents.  Margin tags certainly doesn't sound mdocish.

> At least one article contains floating figures; does mandoc handle
> those? I'm guessing not.

No way.  No figures.  No floats.

> There's also one that wants to have block
> headers on subsections, which I think is difficult in -mdoc.

Block headers?  Not quite sure what that is...

> 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.

The mdoc(7) language currently has no markup for generating an index.

Well, there is the non-standard ms(7) .IX macro, a variant of which
appears as a home-grown user-defined macro in pod2man(1) man(7)
output.  The main problem with all this is to come up with a
reasonable design what indexing in manual pages is even supposed
to do.  I mean, a manual page has no concept of page numbers.
Where do you want to point?  To line numbers?  To section and
subsection headers?  To .Bl -tag entries?  This all seems far
from obvious to me...

Yours,
  Ingo


.Dd July 28, 2014
.Dt DHOLLAND-EXAMPLE 1
.Os
.Bd -centered
Building and Debugging NetBSD Kernels
.br
David A. Holland
.br
August 17, 2009
.Ed
.Sh NAME
.Nm dholland-example
.Nd example of a title and author block for dholland
.Sh DESCRIPTION
some text
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv