On Mon, 17 Jul 2000, Mike Cheponis wrote:

# Date: Mon, 17 Jul 2000 18:23:58 -0700 (PDT)
# From: Mike Cheponis <mac@Wireless.Com>
# To: Greywolf <greywolf@starwolf.com>
# Cc: tech-kern@netbsd.org
# Subject: Re:  bin/7249
# 
# 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.

HTML usually involves a GUI.  _Usually_.

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

Your proposal is not sound in any way, shape or form, unless man2html
is included as the option by which html pages are generated.

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

Hint:  Another Opensource OS seems bent on discarding man in favour of info,
assuming that everyone will magically be brainwashed and want to switch.

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

Mmmm, mm mm mm MM!  Man, herrings on wry bread are SUCH a treat.  But I
need something that will cut the mustard, here.

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

Oooh, you do meds.  Mike on meds is very good.

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

Hm.  Mine are preformatted.  And, as I will point out (again), I read man
pages far more frequently than the READMEs in pkgsrc.

Besides that, I also have a local hack which allows the man pages to
be formatted and saved (a la SunOS).  If anyone wants the hack, I'll
make it available.  It's gross, and should be probably written in
to the man source, with man made setgid "man" or some such to avoid the
DoS security hole...but I digress.  My ultimate goal is to have man
check to see if the formatted page is out of date with respect to
the source page, re-formatting and reinstalling the page if necessary,
displaying from previously formatted pages if not.

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

Check the bottom of your shoe before you take another step.

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

Info should also check its shoes.

HTML is more universal if you're living inside a browser.  I don't.
I live inside a command line.  The only reason I use X in the first place
is the eye candy (a pleasant-looking desktop is kind of relaxing) while I
get four ttys up on the screen at once.  The four ttys is the important
part.

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

Have you looked at Microsoft's WORLD?  It blatantly forces a GUI on the
user.  They built the GUI into the fscking kernel.  What if -- just roll
with me here, on this one -- I decide that (GASP!) _I don't want to use
a GUI?_ [WAIT before you respond!]

Same thing with their doc system.  Their doc system is bloated as hell.
What's the matter, you can't follow something that says SEE ALSO?  Something
that is a command with a parenthesized number after it doesn't make you
curious?  You're running the wrong OS, man.  Go use that microshaft
stuff, the virtues of which you seem to be extolling.
 
# 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.

Now THAT is something which could make a potential case to have the tool,
but, again, not as part of the stock system.  You want it?  Go get/build
it and install it.  Fine.

Such a tool would take up space on my disk (my systems all happen to
have space for man pages, so I install them.  I should centrally locate
them and NFS them).

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

So build/install/use lynx.  NOTHING is stopping _you_.  I will stick to
my battle cry (which apparently meshes with most other sane minds):
"Do not force me to use your solution."  This is especially true since
this particular solution does not have the support that the great, grand,
damn-near-NetBSD-splitting issue recently had.

My man pages, last I looked, are NOT html, and I don't expect that I
will be turning them into HTML any time soon.

And I *still* read them more often than the README.html I find in pkgsrc.
You don't think that's relevant?

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

Hello?  Are we existing in the same world here?  It is MUCH easier to
take a low-level source and generate multiple formats than it is to
figure out precisely what is intended on the high-end output ant trans-
late it to another high-end format.  What part of that didn't you get?

It is, at the very least, more versatile to do so.

# The existing man pages leave much to be desired.

Informationally speaking, possibly.  Formatting, though?  I don't
think so.

# -Mike

				--*greywolf;
--
BSD: Use the ENTIRE computer!