Lengthy documentation in mdoc

Lengthy documentation in mdoc

[Paul Onyschuk]

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

Re: Lengthy documentation in mdoc

[Ingo Schwarze]

Hi Paul,

Paul Onyschuk wrote on Sat, Jul 02, 2011 at 09:36:26PM +0200:

> 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,
  Ingo


> [1] http://hessling-editor.sourceforge.net/
> [2] http://hessling-editor.sourceforge.net/doc/comm/ADD.html
> [3] http://blinkkin.github.com/the/the.man
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Lengthy documentation in mdoc

[Kristaps Dzonsons]

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

Re: Lengthy documentation in mdoc

[Paul Onyschuk]

On Sat, 2 Jul 2011 22:37:40 +0200
Ingo Schwarze <schwarze@usta.de> wrote:

> 
> 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 isn't more complicated than vi/emacs, it's just diffrent and less
popular. I don't have problems with using nvi/mg. I'm more interested in
editors history and why they become what is know today. This [1] isn't
100% accurate, but gives you idea about vi/emacs/xedit.

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

You're probably right here. Moving this to beginning, means it can also
be used as some kind of index.

> 
> That looks reasonable.  Maybe it's a bit verbose, it could be
> cut down, but that's merely a matter of style, like:
> 
> 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.
>

That is very useful input, less is more :]

> 
> Maybe.  As you like.  :)
> But working with a single file like ksh.1 is not that hard, either.
> 

Right now documentation is embedded into the source as comments e.g.:

>
> /*
> **man-start**
> (...)
> **man-end**
> */
>

Makefile (grep etc) is used to create plain text and then html/pdf.
Most docs are in files: "comm1.c comm2.c comm3.c comm4.c comm5.c
commset1.c commset2.c commsos.c". I just want to maintain this
structure by keeping seprate mdoc files e.g. "comm1/add.1.in" - it
seems it easier to keep them up to date this way (changes in comm1.c
means that you need update doc file in comm1/*).

On Sat, 02 Jul 2011 23:14:44 +0200
Kristaps Dzonsons <kristaps@bsd.lv> wrote:

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

Manual isn't the problem. Advocating mdoc/mandoc is the main issue, just
look at this [2]. Most selling points were obtained from BSDCan
presentations. Those informations aren't on mandoc web page and reaching
them isn't easy. Moreover mandoc can compete with tools other than man
page and roff specific (groff etc) in my opinion.

btw. Kristaps can you share slides from BSDCan?

Man pages tutorial on bsd.lv [3] is useful, still it's far from perfect.
I started from there and AFAIK this link was shared on Stack
Overflow and other sites on few occasions.

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

After rewriting THE documenation I planed to play with CSS/javascript.
Folding features for section/sub-sections in html shouldn't be much
trouble e.g. (current output has nice CSS structure):
- click [+] to unfold section COMMANDS, then [+] ADD command

Even creating preseantion slides (omitting pictures) should be easy if
default CSS/HTML output is sane enough.

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

I thinked about using perl-modules-like sections just for this reason.
mandoc-tools (mandoc-cgi few days ago) is so much better than any tool
available right now, that I really thinked about splitting THE
documentation in separate man pages. Option to search just specific man
page? Dunno...

> Anyway, enjoy!

I'm Textile [4] fan and in my humble opinion mdoc is lightweight markup
of documentation world. I enjoyed it to very last drop ;)

I'm subscribed to the list, so no need for CC-ing mails to me directly.
 

[1] https://github.com/blinkkin/the/wiki/Editors-and-keyboards
[2] https://github.com/blinkkin/blinkkin.github.com/wiki/man-vs-mdoc
[3] http://manpages.bsd.lv/
[4] http://en.wikipedia.org/wiki/Textile_(markup_language)

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

Re: Lengthy documentation in mdoc

[Jukka Ruohonen]

On Sat, Jul 02, 2011 at 10:37:40PM +0200, Ingo Schwarze wrote:
> > 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.

I beg to disagree. In NetBSD we have actively tried to split huge pages into
smaller pieces while providing an introductory summary page (for an example
see [1]). When viewed from a terminal, anything longer than say three pages
does not serve well the whole man page format. Also: the search capabilities
generally suck.

- Jukka.

[1] http://netbsd.gw.com/cgi-bin/man-cgi?mqueue++NetBSD-current
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Lengthy documentation in mdoc

[Kristaps Dzonsons]

On 03/07/2011 11:31, Jukka Ruohonen wrote:
> On Sat, Jul 02, 2011 at 10:37:40PM +0200, Ingo Schwarze wrote:
>>> 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.
>
> I beg to disagree. In NetBSD we have actively tried to split huge pages into
> smaller pieces while providing an introductory summary page (for an example
> see [1]). When viewed from a terminal, anything longer than say three pages
> does not serve well the whole man page format. Also: the search capabilities
> generally suck.

Jukka,

Sounds like more of a problem with the tools than the format.  Can you 
imagine any ways to fix this?  If anything constructive comes to mind, 
chime in and maybe it'll be worth some effort in mandoc-tools to field 
alternatives to mandoc | less.

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

Re: Lengthy documentation in mdoc

[Jukka Ruohonen]

On Sun, Jul 03, 2011 at 01:38:13PM +0200, Kristaps Dzonsons wrote:
> Sounds like more of a problem with the tools than the format.  Can you 
> imagine any ways to fix this?  If anything constructive comes to mind, 
> chime in and maybe it'll be worth some effort in mandoc-tools to field 
> alternatives to mandoc | less.

Yes and no.

Partially this stems from the fact that large documents just are not that
well suited for a terminal. And partially this is caused by the BSD
man-page template that favors relatively short, concise documentation. 
Something like uvm(9) or sysctl(7) are prime examples that presumably just
scare the potential readers away.

> On Sun, Jul 03, 2011 at 05:52:18PM +0200, Ingo Schwarze wrote:
> First time i heard that people are doing that on purpose,
> and i'd still consider it useless overhead.  The introductory
> summary page will just keep people away from the real information,
> and reading one chunk, you have a hard time moving to another (let
> alone back).

No. It is exactly the opposite. See above.

> But even if we disagree on this finer point whether usability is  
> better for small or large pages, i think we can agree that mdoc(7)
> is technically up to the job of dealing with both small and large
> pages.

I disagree. The mdoc.samples(7) (or equivalent) is not good for large
documents, and it has presumably never even meant to account such things.

> But for searching within a single page?  I'd say the '/' command
> in less(1) is just fine.

Heh, I disagree also here. Searching with $PAGER has always been suboptimal.
Actually, Joerg's one old idea has been a sort-of small "man-page reader",
but that is another story.

> Looks like that server is completely dead:

Can not reproduce.

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

Re: Lengthy documentation in mdoc

[Ingo Schwarze]

Hi Jukka,

Jukka Ruohonen wrote on Sun, Jul 03, 2011 at 12:31:34PM +0300:
> On Sat, Jul 02, 2011 at 10:37:40PM +0200, Ingo Schwarze wrote:

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

> I beg to disagree. In NetBSD we have actively tried to split huge pages
> into smaller pieces while providing an introductory summary page (for an
> example see [1]).

First time i heard that people are doing that on purpose,
and i'd still consider it useless overhead.  The introductory
summary page will just keep people away from the real information,
and reading one chunk, you have a hard time moving to another (let
alone back).

> When viewed from a terminal, anything longer than say three pages
> does not serve well the whole man page format.

No idea why you say that.  I'd say that up to about 5000 lines,
manuals are just fine: mandoc is fast.  Above that, they may become
slow on slower architectures, like VAX, m68k or hp300.

> Also: the search capabilities generally suck.

For finding the right manual:  Yes, definitely, and we are working on
that.  By the way, that's a cause *against* splitting.
But for searching within a single page?  I'd say the '/' command
in less(1) is just fine.

But even if we disagree on this finer point whether usability is
better for small or large pages, i think we can agree that mdoc(7)
is technically up to the job of dealing with both small and large
pages.

> http://netbsd.gw.com/cgi-bin/man-cgi?mqueue++NetBSD-current

Looks like that server is completely dead:

  ischwarze@isnote $ date
  Sun Jul  3 09:47:54 MDT 2011
  ischwarze@isnote $ ping netbsd.gw.com      
  PING netbsd.gw.com (204.80.150.129): 56 data bytes
  --- netbsd.gw.com ping statistics ---
  9 packets transmitted, 0 packets received, 100.0% packet loss
  ischwarze@isnote $ sudo tcptraceroute netbsd.gw.com 80
  [...]
 5  gsb175-3-130.backbone.ualberta.ca (129.128.3.130)  0.598 ms  0.483 ms  0.599 ms
 6  edtnabxmdr00.bb.telus.com (207.229.13.209)  1.472 ms  1.109 ms  0.845 ms
 7  edtnabkdgr01.bb.telus.com (205.233.111.108)  78.179 ms  45.939 ms  1.506 ms
 8  75.154.223.182  52.096 ms  51.877 ms  51.973 ms
 9  te0-7-0-4.ccr21.jfk05.atlas.cogentco.com (154.54.10.237)  52.297 ms  52.183 ms  52.257 ms
10  te0-3-0-5.mpd21.jfk02.atlas.cogentco.com (154.54.26.61)  52.601 ms  52.051 ms  52.132 ms
11  te0-1-0-2.ccr21.bos01.atlas.cogentco.com (154.54.44.6)  4295093.734 ms  126.253 ms  126.211 ms
12  te0-2-0-1.ccr21.lpl01.atlas.cogentco.com (154.54.31.190)  123.794 ms  123.509 ms  123.577 ms
13  te0-3-0-7.mpd21.ams03.atlas.cogentco.com (154.54.37.77)  133.411 ms  4295100.670 ms  133.581 ms
14  te0-3-0-0.ccr21.ham01.atlas.cogentco.com (130.117.50.54)  145.036 ms  144.992 ms  144.702 ms
15  * * *

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

Re: Lengthy documentation in mdoc

[Paul Onyschuk]

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