Re: Lengthy documentation in mdoc

[Jukka Ruohonen <jruohonen@iki.fi>]

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