On Mon, 17 Jul 2000, Greywolf wrote:

>On Mon, 17 Jul 2000, Mike Cheponis wrote:
>
># If the man pages were html, with links to deeper documentation levels (even 
># automatically generated documentation), that would be better.
>
>Sure.  EVERYone can run an X connection through their firewall, right?

EXCUSE ME?  I NEVER SAID ANYTHING ABOUT NEEDING TO RUN X.  NOTHING AT ALL.
IT MAKES IT VERY DIFFICULT TO DISCUSS AN ISSUE IF PEOPLE DO NOT READ WHAT
HAS BEEN WRITTEN.

Sorry for shouting, but this is the 2nd message that somehow saw something
that I didn't say; I find it difficult enough dealing with objections to
what I -have- proposed.


># I propose junking man pages as we know them, keeping all documentation in
># html, and making the man command essentially a stripped-down lynx (or other
># specialized text-based browser).
>
>Whoa, hold it, there.  Talk like this suggests that your next proposal
>will be to abandon ffs in favour of ext2fs for our native filesystem. ;-,

I don't see how they are connected.  The reason?  THEY ARE NOT CONNECTED.

WE ARE TALKING ABOUT MAN PAGES.  WE ARE ***NOT*** TALKING ABOUT FILE
SYSTEMS.

Sorry for shouting again, but I am not accustomed to this "sniper" style
of shooting down an argument by using red herrings.

OK, I've taken my medication now, and I see your ;-,  ...  '-)  So I'll
ignore your comment on this, OK? ...



>I disagree STRONGLY with this direction.  I don't WANT any fancy overhead
>just to look up a man page; and there exist far and away too many

Ahh, perhaps you haven't noticed, but when you do "man foo" it often
says "man: Formatting manual page..."  as it grinds away... If you type
"lynx README.html" in one of the /usr/pkgsrc/<whatever> directories,
it snaps up instantly.  (This is on a 32M 486-dx2/66 w/scsi disk).

So it looks like I've shot down the "performance" argument...


>"specialized" tools these days.  Info, while cool, is just not a suitable
>replacement for man.  

Info in in the right direction, but html is more universal.


>I could see an htman or some such, with this (as always) AN OPTION,
>but don't you _dare_ be so presumptuous as to suggest that we do such
>a thing as to make man(1) completely obsolete.  Telnet/ssh sessions are,
>after all, typically 80 columns wide ASCII.


Look, there was a suggestion by somebody here saying that the docs should
be man + source code.  Excuse me!!!

Has anybody here actually looked at Microsoft's documentation?  Frankly,
it is head and shoulders above what we have. 

Another cool thing about html-based documentation is that not only can it
trivially use local files, but it can also access data over the net; this
can be helpful for small systems that have a net connection but do not 
want to waste local disk space for doc, or as a place where documentation
updates are placed.


>It isn't broken (modulo some small changes that I keep bitching about
>but they're discarded out of hand in the name of filesystem security);
>what are you trying to really fix, here, and why?
>
># -Mike
># 
># p.s. As precedent for using html, the READMEs in pkgsrc are html.
>
>How often do we reference the READMEs in pkgsrc?!?  Far less often than
>we reference man pages, believe you me.

So what?  The fact remains, they are html.  


>Would you also introduce a totally new way of constructing manual pages,
>as opposed to a low-level format from which higher-level formats can
>be derived?  (Hint:  It's much harder to go the other way).

How is that?

># On 17 Jul 2000, Mirian Crzig Lennox wrote:
># >
># >NetBSD's man pages, omissions and all, are about as good as it gets in
># >terms of clarity and readability; let's preserve that.
>
>I'll support this in a heartbeat.
>
># >--Mirian
>
>
>				--*greywolf;
>--
>Microsoft:	"Where do you want to go today?"
>Linux:		"Where do you want to be tomorrow?"
>BSD:		"Are you guys coming, or what?"



The existing man pages leave much to be desired.

-Mike