Re: Lengthy documentation in mdoc

[Kristaps Dzonsons <kristaps@bsd.lv>]

>> 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)
>
> Yes.  I think that rationale makes sense, and mdoc(7) is a good tool
> for the task at hand.
>
>> Before jumping at me (Why you use tool that needs so much
>> documentation!?), be aware that THE comes from very different
>> culture - mainframes.
>
> Well, most editors have lots of interactive commands,
> even nvi and mg look similar.  Besides, we want writing
> documentation to be simple and efficient even for tools that
> are themselves complicated.
>
>> The good thing is that every command [2] in documentation has very
>> man-page-like structure.
>
> Actually, that doesn't help much, unless...
>
>> 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
>
> ... you go that way, which i don't recommend at all.
> It causes many problems.  For example, you can't search in a manual
> like that, and moving about it is a pain in general.
> In OpenBSD, we even lumped openssl(1) all into one page
> when importing it from upstream.
>
>> - custom section like perl modules e.g. 3pm
>
> Well, the stuff in 3p is prepared with pod2man(1) and man(7);
> you shouldn't use that as a model for modern documentation.
> It works, but it is not nice.
>
>> - one big man page
>
> Yes, i think that will work.
>
>> 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.
>
> Right.  Do not mess with sections, like (1THE).
> That would cause different issues with different operating systems
> and different roff and man implementations.
>
>> 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.
>
> Yes, you can do that, i wouldn't call that abuse.
> Look at mdoc(7) for an example on how to use .Ss/.Sx for commands.
>
>> Example template would look more-or-less like this:
>>
>>> .Sh COMMANDS
>>>    (...)
>>> .Ss ADD
>>> add blank line
>
> I'd probably convert this line to a complete sentence and move it
> to the beginning of the description, or just drop it if its already
> there.  A full mdoc(7) page needs an .Nd, but a mere .Ss subsection
> doesn't.
>
>>> .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
>
> That looks reasonable.  Maybe it's a bit verbose, it could be
> cut down, but that's merely a matter of style, like:
>
> .Sh COMMANDS
> .Ss ADD
> Syntax:
> .Cm Add Op Ar n
> .Pp
> Insert
> .Ar n
> blank lines after the current line, if issued from the command line,
> or after the focus line, if issued from the file area or prefix area.
> By default, one single line is added.
> .Pp
> The
> .Cm Add
> command is compatible with XEDIT and KEDIT.
> .Pp
> See also
> .Sx SOS ADDLINE .
>
> Sometimes less markup and formal structure is easier on the eye.
> I'm not sure "Status: Complete" needs to be mentioned at all.
> In a manual, that should go without saying.  Of course, you
> should mention the limitations if something is *not* fully
> implemented.
>
>> 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+).
>
> No problem with that.
>
>> 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.
>
> Maybe.  As you like.  :)
> But working with a single file like ksh.1 is not that hard, either.
>
>> 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?
>
> No.  All this sounds quite sane.
>
>> 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.
>
> You are welcome!
> (And nothing is wrong with your English, as far as i can see.)
>
> Have fun with mandoc,

Paul,

Ingo's pretty much said it all.  If you have any questions, don't 
hesitate to ask on the list---and do feel especially free to voice any 
questions regarding the mdoc(7) manual.

When it comes to generating HTML output, speak up if you have ideas for 
exploiting inter-page linkage.  For example, I had wanted to generate 
<LINK> elements for the section and subsections of a document.  But 
browsers don't usually account for this, so it would be wasted effort 
(pity!).  Another idea is an `-Otoc' option (or whatever) that would 
cause -Thtml to generate a table of contents along with the page output. 
  OpenBSD's man.cgi does this now at the bottom of the page; however, I 
think this is kind of ugly and unwieldly for large documents.

Come to think of it, a nice feature for http://mdocml.bsd.lv/mandoc-cgi/ 
would be jumping to a table of contents and/or semantic index (a la ptx) 
for individual manuals... hmmm...

Anyway, enjoy!

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