Where to put mandoc roff documentation?

Where to put mandoc roff documentation?

[Ingo Schwarze]

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

Re: Where to put mandoc roff documentation?

[Jason McIntyre]

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

Re: Where to put mandoc roff documentation?

[Ingo Schwarze]

Hi Jason,

Jason McIntyre wrote on Sat, Nov 27, 2010 at 09:18:08PM +0000:

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

Good, so i shall soon move roff.7 to share/man/man7 and start
polishing it such that we can install it once we feel it is ripe.
I assume Kristaps won't object to keeping the name either,
because he was the one initially choosing it.  :)

Once we will be installing it, we can then start moving class 1
stuff there.

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

Oh, yes, pointing that way didn't occur to me yet, but may also be
an option for some cases.

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

Good, so let's see where we get.

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