Re: Lengthy documentation in mdoc

[Ingo Schwarze <schwarze@usta.de>]

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