Re: Lengthy documentation in mdoc

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

I followed feedback provided by Ingo.  Here is small preview of what
has been done [1] (mdoc source is not yet ready for sharing).  Still it
is very early work, so grammar mistakes are common and formating is
not finished.  Some reasoning:

- Describe status only if command is not complete.
- Provide information about XEDIT/KEDIT only if command is
incompatible or has different behavior in former.
- Write about default behavior in description.
- Avoid describing command by name (e.g. "The BACKWARD command
scrolls ...").

This way command references are much less verbose and easier to read.
I'm not sure about one thing: enclosing commands in angle brackets.  I
started with this:

>
> Syntax:
> .Ic CURsor Ar Column
>

And it didn't work out - some commands had more than one version.  Good
exmaple is CURSOR [2].  In original, structure used was like "command,
command... description, description...".

My version uses "command, description ..." layout to gain some
readability, but this way distinguishing separate commands can be
problematic.  "Syntax:" every two line doesn't help, so I came up with
idea of using angle brackets.

I also tried using blocks with offset for commands and then for
description.  Longer commands are unnecessary splitted across multiple
lines and offset for description is just poor idea.

Maybe it's totally wrong approach, so I'm looking once again for
feedback.

As for other things, Rexx variables as seen in ALERT and DIALOG,
doesn't belong in commands listing.  Currently most of them can be
found in query section [3].  Personally I think that it is the only
part (Rexx variables), that can be safely moved to separate man page.
Those variables requires knowledge of Rexx, so rexx(1) and other man
pages are probably needed anyway.

Some commands (like ALL) provides also examples, but this is small
problem.  They can be moved to EXAMPLES later if needed.

As for mdoc(7), I feel much more comfortable with sources right now,
than few days ago.  One thing I'm missing is something like style(9)
just for mdoc.  I found myself looking into other man pages on more
than one occasion.  Many times I was just looking for improvements in
source readability (style of comments and so on), not formating which
is well explained in mdoc(7).


[1] http://blinkkin.piasta.pl/the/index.html
[2] http://hessling-editor.sourceforge.net/doc/comm/CURSOR.html
[3] http://hessling-editor.sourceforge.net/doc/misc/query.html

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