Lengthy documentation in mdoc

[Paul Onyschuk <blink@bojary.koba.pl>]

Hello, I'm looking into rewriting THE [1] (The Hessling Editor)
documentation in mdoc (for mandoc in mind). Some explanations:

Current state:
- THE documentation contains plain text files converted to html/pdf
(bad quality output)
- man page isn't useful at all

Why mandoc?
- one format and multiple outputs with better quality
- documentation in one place (semi-formats like markdown with pandoc
or POD only complicates situation)

Before jumping at me (Why you use tool that needs so much
documentation!?), be aware that THE comes from very different culture -
mainframes.

The good thing is that every command [2] in documentation has very
man-page-like structure.

So what's the problem? As I mentioned before, THE documentation is
mainly plain text, but it's about ~12k lines long [3].

I looked into multiple scenarios:
- splitting man page like zsh
- custom section like perl modules e.g. 3pm
- one big man page

And third options seems like best of worst. Navigation of big man page
can be problematic, but splitting it up doesn't help at all. Adding
another section to man pages isn't option at all.

Another reason for one fat page, are documentation references as seen in
ADD command. I came up with idea of abusing sub-sections (every command
is sub-section) and using Sx macro for references.

Example template would look more-or-less like this:

> .Sh COMMANDS
>   (...)
> .Ss ADD
> add blank line
> .Bl -tag -width 1m
> .It Syntax:
> .Cm Add Op Ar n
> .It Description:
> If
> .Sx SET NEWLINES
> is set to ALIGNED, the cursor is positioned
>   (...)
> .It Compatibility:
> XEDIT: Compatible.
> .Pp
> KEDIT: Compatible.
> .It Default:
> 1
> .It See Also:
> .Sx SOS ADDLINE
> .It Status:
> Complete
> .El
>   (...)
> .Sh OPTIONS
> .Ss SET NEWLINES
>   (...)

This way html output and so on will use sub-sections references as
links. Although this requiers few dozen sub-sections (I wouldn't be
surprised if number is 200+).

So end users will enjoy (?) one fat man page, but developers will work
on smaller files. Every command will be separate file "cated" by
makefile at build time. It easier to work on smaller chunks.

I'm looking for opinions from people with more experience in working
with mdoc. Maybe there is better solution for this? Am I creating
another man-page abomination or using wrong tool?

Overall I wanted to ask this questions, before actual work.

btw. Thank you Kristaps and Ingo for creating/maintaining great tool
and everyone else involved with mandoc. Apologies for my "english"
writing.


[1] http://hessling-editor.sourceforge.net/
[2] http://hessling-editor.sourceforge.net/doc/comm/ADD.html
[3] http://blinkkin.github.com/the/the.man

-- 
Paul Onyschuk <blink@bojary.koba.pl>
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv