Re: Extension for more general documents

[Ingo Schwarze <schwarze@usta.de>]

Hi Thomas,

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:

 ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 -----

ischwarze@isnote $ groff -ms -Tascii -P-c tabs csh.*

                    An Introduction to the C shell

                             William Joy
                 (revised for 4.3BSD by Mark Seiden)
                      Computer Science Division
      Department of Electrical Engineering and Computer Science
                  University of California, Berkeley
                      Berkeley, California 94720

                               ABSTRACT

               Csh is a new command language interpreter for
          UNIX(R) systems.  It incorporates good features of
                                 [...]

     Introduction

          A shell is a command language interpreter.  Csh is the
     name of one particular command interpreter on UNIX.  The
     [...]
          In addition to this document, you will want to refer to
     a copy of the UNIX User Reference Manual.  The csh


     USD:4-2                       An Introduction to the C shell


     documentation in section 1 of the manual provides a full
     description of all features of the shell and is the
     [...]

 ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 -----

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.  For example:

 ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 -----

ischwarze@isnote $ cat csh.mdoc

.Dd $Mdocdate$
.Dt CSH-INTRO 1
.Os
.Sh NAME
.Nm CSH-INTRO
.Nd An Introduction to the C shell
.Sh ABSTRACT
.Nm csh
is a new command language interpreter for UNIX systems.
It incorporates good features of other shells and a history
mechanism similar to the
.Sq redo
of INTERLISP.
[...]
.Sh AUTHORS
.An -nosplit
.An William Joy
(revised for 4.3BSD by
.An Mark Seiden )
.br
Computer Science Division,
Department of Electrical Engineering and Computer Science,
University of California, Berkeley
.br
Berkeley, California 94720

schwarze@isnote $ mandoc csh.mdoc

CSH-INTRO(1)               OpenBSD Reference Manual               CSH-INTRO(1)

NAME
     CSH-INTRO - An Introduction to the C shell

ABSTRACT
     csh is a new command language interpreter for UNIX systems.  It
     incorporates good features of other shells and a history mechanism
     similar to the `redo' of INTERLISP.  [...]

AUTHORS
     William Joy (revised for 4.3BSD by Mark Seiden)
     Computer Science Division, Department of Electrical Engineering and
     Computer Science, University of California, Berkeley
     Berkeley, California 94720

OpenBSD 5.5                      June 14, 2014                     OpenBSD 5.5

 ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 -----

So that adds the not strictly required header and footer lines,
the word "NAME", and the identifier "CSH-INTRO".  Do these do any
harm?  If you choose to install the document as a man page, they
may even be useful.

Regarding the AUTHORS, you might also move them to the top, right
after NAME, if you are not using any of the standard sections like
SYNOPSIS, DESCRIPTION, and so on.

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?  Please try to provide a list that is complete
and as specific as possible, that will make it easier to judge the
effort required (and maybe to provide an implementation that
actually does what you want).

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv