Re: Where to put mandoc roff documentation?

[Jason McIntyre <jmc@kerhand.co.uk>]

On Sat, Nov 27, 2010 at 07:45:03PM +0100, Ingo Schwarze wrote:
> Hi Jason,
> 
> i'm looking for your advice regading the question how to organize
> mandoc roff documentation.  By that term, i'm referring to man pages
> explaining:
> 
> 1. Common features of the mdoc(7) and man(7) languages
>    being common because they are actually features of the roff
>    language - currently, there is quite some duplication.
>    Topics include:
>     - basic request and macro syntax
>     - permitted input characters
>     - comment syntax
>     - predefined special characters and strings
>     - predefined escape sequences, for example regarding text decoration
>     - basics of whitespace handling
>     - scaling widths
>     - end-of-sentence spacing
> 
> 2. Common macros
>    being common because they are actually roff macros or even
>    roff requests, for example:
>     - .br
>     - .sp
> 
> 3. Low-level roff requests that are not mdoc(7) or man(7) macros,
>    for example:
>     - .de
>     - .ds
>     - .if
>     - .ig
>     - .nr
>     - .rm
>     - .rn
>     - .so
>    And also:
>     - user-defined macros
>     - user-defined strings
> 
> 4. Common aspects of the usage of the mdoc(7) and man(7) languages
>    being common because they do not depend on the language at all.
>    Topics include:
>     - manual sections
>     - general advice about writing manuals
> 
> In particular, running mandoc -Tlint on Perl, Xenocara, and typical
> ports manuals, i expect improving low-level roff support will be the
> focus of mandoc development in the near future.  Hence, most of the
> new documentation to be written will probably be category 3, and
> perhaps some 2.
> 
> I consider moving roff.7 from /usr/src/usr.bin/mandoc/
> to /usr/src/share/man/man7/ and getting it ready for installation
> by moving documentation of the categories 1, 2 and 3 into it.
> But i'm not 100% sure whether all of this - with the exception
> of mandoc_char(7), of course - should really go into the same
> document.
> 
> I'm also hesitant regarding the name.  The current name roff(7) seems
> fitting on the one hand, because this document would indeed document
> features of the roff language, and nothing else.  On the other hand,
> that name feels presumptuous, because we will hardly ever document 
> the roff language as a whole, and because calling it roff(7) would
> hide the rather interesting roff(7) manual once we update our
> groff port to a recent version, see:
> 
>   http://www.manpagez.com/man/7/roff/
> 
> Yet on the other hand, even though that document is interesting,
> it is perhaps named badly and should be installed as roff_history(7),
> or not at all, because however interesting, it is not a real manual.
> 
> Finally, i feel quite at a loss about what to do with category 4.
> Maybe move it to a manuals(7) manual, like the one Kristaps once
> started, and .Xr to it?  Or leave it in mdoc(7), because that's
> where we send people writing new manuals, and point to it from
> man(7)?  Or just maintain two copies for good?
> 
> Thoughts?
> 
> Yours,
>   Ingo
> --
>  To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

it sounds like one page is a good idea for this stuff - roff, troff,
whatever. i wouldn;t worry about squashing a groff page - the port could
be tweaked to install under a different name.

so i;d say yes, stick 1, 2, and 3 in a roff page.

if there's stuff more suited to mdoc (or repeated), i'd leave it in mdoc
and have roff point to it (i.e. point 4).

we don;t have to worry too much - if it evolves into something else, we
can change it in the future.

jmc
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv