bin/7249
Erik E. Fair
should every system call manual page list every possible
error that can be returned by that call?
For example, this means that any system call dealing with a
descriptor (file, socket, whatever) would need to list all filesystem
error codes, plus all socket (network) error codes, and so on. It
would be a fairly exhaustive list.
If we decide "yes" then we need to go through section 2 pretty thoroughly.
The alternative is to list the error codes in one place, and give a
general description of when to expect them, with pointers to the
right subset from each system call man page.
Or we could just say UTSL with a pointer to /usr/include/errno.h
comments?
Erik <fa...@clock.org>
matthew green
what's wrong with intro(2) ?
Erik E. Fair
man page for that system call (in section 2). I'm asking for
discussion here as to whether that's reasonable (it is gonna be a
maintenance headache, unless we find some automated way to produce it
from the code paths).
Erik <fa...@clock.org>
Robert Elz
From: "Erik E. Fair" <fa...@clock.org>
Message-ID: <v04220812b59656359aff@[216.240.40.200]>
| The PR wants every error that a given system call can return in the
| man page for that system call (in section 2). I'm asking for
| discussion here as to whether that's reasonable
Since you asked ... no, it isn't.
For two reasons .. first, if it pretends to be exhaustive, then people
will start to rely on no other errors ever being possible, which makes
it real hard to extend the system, or even just change the implementation.
And, as you say, it is horrid to maintain, and also fills all the man pages
with needless garbage.
The man pages should cover the most common errors, and any that have
anything other than the standard common error meanings. Beyond that
they should all just 'see also" intro(2) for a general explanation of
all the errors that can occur.
Eg: for open(2) it is reasonable to explain EACCES, ENOENT, EOPNOTSUPP,
EEXIST, and maybe one or two more, but others (ENOTDIR, EFAULT, ...)
are just a waste of energy - ENOTDIR only occurs because namei() chasing
the path found something not a directory before the final segment, which
is exactly the same as can happen with stat() link() unlink() rename()
and about 20 or 30 other system calls. Repeating the same stuff over
and over is tedious... The same is true for EFAULT EIO ELOOP EINTR
ENXIO, ...
To some extent that's done already - that is, the man page for open(2)
doesn't mention any of the NFS related errno's that can be returned
(ESTALE, etc) - which is good, but it does insist on mentioning EFAULT
and EIO and a bunch more errors that are just as irrelevant as the NFS ones.
kre
Chuck McManis
On the "spec" side, the argument goes something like this:
"The man pages are the specification for the system, by making them
exhaustively complete one can insure compliance through testing to
the agreed upon standard. This aids interoperability and
compatibility
amongst different implementations."
On the "guide" side, the argument goes something like this:
"The man pages are a guide for the programmer who is using the
system. They help him or her to write programs that will run
under the system and identify the most common error conditions
that might prevent the program from running. For really
complex errors the source is always available."
Having had some experience at Sun on the "spec" side of the argument I can
assure you that the NetBSD project doesn't have nearly enough resources to
maintain a NetBSD specification. Therefore, unless you can do this for all
man pages (ie spec mode) then it will be no better than guide mode, thus
I'm going to suggest that the answer is guide mode.
In that mode it is important to cover the error conditions that are most
likely to occur and to reference the definitive documentation (ie the
source). So perhaps a good compromise would be a new MAN section
"IMPLEMENTED IN" which identifies where in the source tree you can find the
function.
--Chuck
At 10:57 AM 7/15/00 -0700, Erik E. Fair wrote:
>The PR wants every error that a given system call can return in the man
>page for that system call (in section 2). I'm asking for discussion here
Bill Sommerfeld
>
> should every system call manual page list every possible
> error that can be returned by that call?
>
> For example, this means that any system call dealing with a
> descriptor (file, socket, whatever) would need to list all filesystem
> error codes, plus all socket (network) error codes, and so on. It
> would be a fairly exhaustive list.
Not exactly. "read" will never return EROFS or EPROTONOSUPPORT unless
a driver is playing games with us..
> If we decide "yes" then we need to go through section 2 pretty thoroughly.
>
> The alternative is to list the error codes in one place, and give a
> general description of when to expect them, with pointers to the
> right subset from each system call man page.
we certainly shouldn't rip out the errno descriptions from the
existing manual pages -- EINVAL means different things for different
syscalls. What's there already should not be removed. Maybe a
semi-boilerplate "additional error codes may be returned, see
driver/filesystem/protocol-family-specific man page for details".
> Or we could just say UTSL with a pointer to /usr/include/errno.h
uhh, no.
Berndt Josef Wulf
> The PR wants every error that a given system call can return in the
> man page for that system call (in section 2). I'm asking for
> discussion here as to whether that's reasonable (it is gonna be a
> maintenance headache, unless we find some automated way to produce it
> from the code paths).
I believe that a complete description of error messages for system
calls are important, especially for the less experienced programmers.
It shouldn't be too difficult, as one would build a template of
a list containing all error descriptions, using cut and paste techniques to
insert this list into the man-pages, deleting sections that are not
relevant to this call and correct those which may have different
meanings.
I relize that this still means a lot of work, but it could be done
progressively whenever a man-page needs updating.
cheerio Berndt
--
Name : Berndt Josef Wulf | +++ With BSD on Packet Radio +++
E-Mail : wu...@ping.net.au | tfkiss, tnt, dpbox, wampes
ICQ : 18196098 | VK5ABN, Nairne, South Australia
URL : http://www.ping.net.au/~wulf | MBOX : vk5abn@vk5abn.#lmr.#sa.au.oc
Sysinfo : DEC AXPpci33+, NetBSD-1.4.2 | BBS : vk5abn.#lmr.#sa.aus.oc
Matt Thomas
>Erik E. Fair wrote
> > The PR wants every error that a given system call can return in the
> > man page for that system call (in section 2). I'm asking for
> > discussion here as to whether that's reasonable (it is gonna be a
> > maintenance headache, unless we find some automated way to produce it
> > from the code paths).
>
>I believe that a complete description of error messages for system
>calls are important, especially for the less experienced programmers.
I don't. Our man pages should document the common cases and differences
from XPG4 or the relavant standard. If one is doing serious programming
then I'd expect them to buy a XPG4 or whatever book telling them in detail
what things do. We document where we differ.
--
Matt Thomas Internet: ma...@3am-software.com
3am Software Foundry WWW URL: http://www.3am-software.com/bio/matt/
Cupertino, CA Disclaimer: I avow all knowledge of this message
Giles Lean
> The PR wants every error that a given system call can return in the
> man page for that system call (in section 2). I'm asking for
> discussion here as to whether that's reasonable (it is gonna be a
> maintenance headache, unless we find some automated way to produce it
> from the code paths).
There has been some inconclusive discussion in the past with respect
to documenting errors listed in the standards that we don't/can't
return.
I would like to see the project's policy on this documented somewhere,
once it is decided. (Assuming that at least -core can come to some
consensus, even if the general mailing lists can't. :-)
So that I'm not sitting on the fence, I think:
1. all known error returns should be documented
2. all error returns listed in the standards should be documented
("which" standards? Um ...)
I would treat #1 as a goal and update manual pages as and when someone
notices an omission or extraneous listing. #2 is easy enough to do
for any standard for which an online copy is available.
I'm a bit dubious that an automated check of the source tree will be
able to do the right thing for #1, since functions called through
pointers will be hard to manage. Not to mention system calls that can
use functionality provided by LKMs ... anything is possible for those.
Regards,
Giles
Kevin P. Neal
> Having had some experience at Sun on the "spec" side of the argument I can
> assure you that the NetBSD project doesn't have nearly enough resources to
> maintain a NetBSD specification. Therefore, unless you can do this for all
> man pages (ie spec mode) then it will be no better than guide mode, thus
> I'm going to suggest that the answer is guide mode.
(Sorry, I'm a little behind.)
How about having man pages list the potential errors that each syscall can
return, but not give explanations (refer the reader to intro)?
Descriptions for some of the errors in the syscall-specific pages wouldn't
go away, of course.
--
Kevin P. Neal http://www.pobox.com/~kpn/
Seen on bottom of IBM part number 1887724:
DO NOT EXPOSE MOUSE PAD TO DIRECT SUNLIGHT FOR EXTENDED PERIODS OF TIME.
Mirian Crzig Lennox
by software which parses through syscalls looking for error codes
I just want to add my two cents about that, which is that this is
the sort of thing (similar) which Sun does with its Java documentation,
and the result is a lot of... well, STUFF which crowds out the actual
meaningful documentation. I much prefer a couple of paragraphs of
carefuly-written and coherent documentation to reams of generated
boilerplate.
NetBSD's man pages, omissions and all, are about as good as it gets in
terms of clarity and readability; let's preserve that.
--Mirian
Greywolf
# On Sat, Jul 15, 2000 at 02:41:30PM -0700, Chuck McManis wrote:
# > Having had some experience at Sun on the "spec" side of the argument I can
# > assure you that the NetBSD project doesn't have nearly enough resources to
# > maintain a NetBSD specification. Therefore, unless you can do this for all
# > man pages (ie spec mode) then it will be no better than guide mode, thus
# > I'm going to suggest that the answer is guide mode.
#
# (Sorry, I'm a little behind.)
#
# How about having man pages list the potential errors that each syscall can
# return, but not give explanations (refer the reader to intro)?
That's not always appropriate, as the generic intro(2) explanation may
cover several cases. The programmer would then be expected to deduce
exactly what happened (which ain't all bad, mind you -- they're programmers,
after all)...
But aren't there some specific special-cased errors which exist outside
the scope of normalcy?
# Descriptions for some of the errors in the syscall-specific pages wouldn't
# go away, of course.
--*greywolf;
--
NetBSD, Net Profit.
Mike Cheponis
If the man pages were html, with links to deeper documentation levels (even
automatically generated documentation), that would be better.
I'm not trying to start a flamewar here, but man pages, a wonderful
innovation 30 years ago, seem to be showing their age.
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).
-Mike
p.s. As precedent for using html, the READMEs in pkgsrc are html.
Jim Reid
Mike> The problem, of course, is that it's a single "flat file"
Mike> type of man database. If the man pages were html, with
Mike> links to deeper documentation levels (even automatically
Mike> generated documentation), that would be better.
Not better, just different. Some people like and want to be able to
read things without needing to have a computer swtich pixels on and
off so that the information can be seen.
Mike> I propose junking man pages as we know them, keeping all
Mike> documentation in html, and making the man command
Mike> essentially a stripped-down lynx (or other specialized
Mike> text-based browser).
What's *really* wrong with the printed word?
The idea of putting documentation only in HTML format is utterly
repulsive. [Let's not even consider the dubious arguments about
whether HTML is an appropriate medium for documentation or has the
required functionality.] Why should someone be forced to have to bring
up X and start a core-guzzling browser, *just to read some man page*?
The idea is nuts. [Don't forget that some netbsd platforms can't/won't
run X.] What next, require that browser to have sundry plug-ins, just
so the documentation can be read in whatever fad-of-the-month happens
to be in vogue today? Inventing a special lynx reader as an
alternative to that is just silly. The concept of man pages is not
broken IMHO, so it doesn't need fixing. And what if the man page you
want to read is for the web browser that you can't get to start or
display man pages properly? Putting all the man pages into HTML (and
only HTML) is about as sensible as putting them all into Word
format. In fact, Word format would be slightly better in some respects
because it does have some (admittedly flawed) concepts for supporting
document structure.
Note that I'm not against the idea of offering an HTML capability.
But this should be an extension - not a replacement! - to the current
documentation that has served us so well for so long. If man pages
were good enough for Ken & Dennis, they should be good enough for you
and me.
Someone once said that if the only tool you had was a hammer, every
problem would look like a nail. Well, UNIX systems have more tools
available than a just web browser.
Tom Rushworth
> On Mon, 17 Jul 2000, Jim Reid wrote:
>
> > >>>>> "Mike" == Mike Cheponis <m...@Wireless.Com> writes:
> >
> > Mike> The problem, of course, is that it's a single "flat file"
> > Mike> type of man database. If the man pages were html, with
> > Mike> links to deeper documentation levels (even automatically
> > Mike> generated documentation), that would be better.
> >
> > Not better, just different. Some people like and want to be able to
> > read things without needing to have a computer swtich pixels on and
> > off so that the information can be seen.
>
>
>
> > Mike> I propose junking man pages as we know them, keeping all
> > Mike> documentation in html, and making the man command
> > Mike> essentially a stripped-down lynx (or other specialized
> > Mike> text-based browser).
I still remember the first time I had a boot problem on Sun HW after
Sun switched to the "Answerbook". I knew where the answers I needed
were, but the only way I could read them was to take the Answerbook CD
to another Sun system (several blocks away), read them there, come
back to the problem system, try something....
"man" format serves more than one purpose. It contains information of
use when you want to program or install something new, from a working
system. It also provides information of use when things are broken and
you are trying to get them working again. For this second use, the less
you need to have running, the better. I've read man pages with "ed", in
single user mode, with no nroff or pager available.
A better approach than "junking" man format would be to look at a way
to generate the HTML, or gnu info format, from the man format. E.g. use
the nroff macros as indicators of structure or links. The important
thing is that "man" has to come _first_, or you have lost your access
to the information on a crippled system.
Yes, I know HTML can also be "read" with ed. What I'm saying is that
lynx has more components than man, and is thus more likely to get hit
when a system gets broken. Keep the lifeboat function as simple as
possible.
--
Tom Rushworth
Greywolf
# 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?
# I'm not trying to start a flamewar here, but man pages, a wonderful
# innovation 30 years ago, seem to be showing their age.
"Well, I didn't MEAN to burn down the building, in spite of having poured
gasoline all over it?"
# 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 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
"specialized" tools these days. Info, while cool, is just not a suitable
replacement for man.
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.
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.
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).
# 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?"
Greywolf
# >The concept of man pages is not
# > broken IMHO, so it doesn't need fixing. And what if the man page you
# > want to read is for the web browser that you can't get to start or
# > display man pages properly? Putting all the man pages into HTML (and
# > only HTML) is about as sensible as putting them all into Word
# > format. In fact, Word format would be slightly better in some respects
# > because it does have some (admittedly flawed) concepts for supporting
# > document structure.
#
# FWIW, all Microsoft DDK documentation is in HTML.
And your point is *what*, exactly? The entire microsoft concoction is
so irrevocably linked to a GUI that if the system were to suddenly be
only available in CLI mode, it wouldn't be usable.
UNIX, thank the Gods, does NOT suffer from this malady, not even in
the relatively minor form you are seeking to inflict upon it.
# > Note that I'm not against the idea of offering an HTML capability.
# > But this should be an extension - not a replacement! - to the current
# > documentation that has served us so well for so long. If man pages
# > were good enough for Ken & Dennis, they should be good enough for you
# > and me.
#
# If it was good enough for Ken and Dennis 30 years ago, is it -still- good
# enough for Ken and Dennis -today- ?
It's small. It's reliable. You can always use a formatter to go to,
as i posted earlier, a higher level. _You_ _must_ _expend_ _more_ _effort_
_to_ _convert_ _from_ _one_ _high_ _level_ _format_ _to_ _another_, than
you would need to do _if_ _you_ _started_ _from_ _a_ _lower_ _level.
Your point of having a specialized lynxalike just on hand to read man
pages is blinking ludicrous, and IMNSHO, unacfsckingceptable.
Just how far down do you want to dumb things, Mike?
# > Someone once said that if the only tool you had was a hammer, every
# > problem would look like a nail. Well, UNIX systems have more tools
# > available than a just web browser.
#
# I'm afraid I don't understand this at all.
Clue: Don't htmlize things by fiat. Make it AN EXTENSION (hey, what
a novel concept, giving users/administrators *options* on their config-
urations), an OPTION.
$ ls -l /usr/bin/groff /usr/bin/more /usr/bin/eqn /usr/local/bin/lynx \
> /usr/bin/tbl
-r-xr-xr-x 1 root wheel 100628 Feb 12 10:57 /usr/bin/eqn
-r-xr-xr-x 1 root wheel 50984 Feb 12 10:57 /usr/bin/groff
-r-xr-xr-x 3 root wheel 73296 Feb 12 10:32 /usr/bin/more
-r-xr-xr-x 1 root wheel 80800 Feb 12 10:57 /usr/bin/tbl
-r-xr-xr-x 1 root wheel 1016416 Jun 17 21:05 /usr/local/bin/lynx
$ size /usr/bin/eqn /usr/bin/groff /usr/bin/more /usr/bin/tbl \
> /usr/local/bin/lynx
text data bss dec hex filename
79323 18720 3668 101711 18d4f /usr/bin/eqn
41345 7412 3672 52429 cccd /usr/bin/groff
68158 3000 9212 80370 139f2 /usr/bin/more
71315 7292 1832 80439 13a37 /usr/bin/tbl
925330 87768 136716 1149814 118b76 /usr/local/bin/lynx
$
Which one do YOU think is a wiser use of resources? (This might be a
straw man, but it seemed relevant to me: Note that the first four programs,
both in disk size and load size, even added up, do not add up to the bulk
of lynx.)
It'd be bloatware. If I want followable man links and the like, I can
always grab tkman. Or we can write a supplemental tmac package, tmac.anhtml,
to augment the man pages and generate them into a separate hierarchy.
# -Mike
BSD has historically been a very clean layout compared to the fettucine
alfredo which is Linux. If you are going to insist on putting lynx,
even stripped down, in /usr/bin, I'll suggest you find an alternate play-
ground on which to do your dealing, because from my POV as a BSD user
long enough to border on cretaceous, bells and whistles on a stock system
are just that and no more. They should not be relied upon, as nice as
they are when they are there.
--*greywolf;
--
BSD: Network Your World.
Mike Cheponis
>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
Mirian Crzig Lennox
Mike Cheponis <m...@Wireless.Com> wrote:
>
>> Note that I'm not against the idea of offering an HTML capability.
>
>If it was good enough for Ken and Dennis 30 years ago, is it -still- good
I realize you probably meant this as a rhetorical question, but in fact,
the straight answer to that is "yes": the bulk of Plan 9's documentation
is indeed in the form of man pages.
--Mirian
matthew green
So it looks like I've shot down the "performance" argument...
except that netbsd ships with pre-formatted man pages and has for
some years now, so this rarely happen anymore.
html is f*cking *horrible* format to create documentation in. as
an author of many pages of netbsd documentation, i *totally* do not
want to go to html documentation. i would probably support something
else that wasn't so broken (such as docbook) and lacking in features
that i currently use often, but i'm honestly quite happy with the
way man pages work today. writing `mandoc' man pages is *really*
nice to do, on the scale of documentation writing. they format nicely,
particularly into postscript for printing, unlike html in the general
case.
please, take this html idea away and shoot it in the head before it
spreads.
Herb Peyerl
> nice to do, on the scale of documentation writing. they format nicely,
> particularly into postscript for printing, unlike html in the general
> case.
html is easy. all you need to know is "<pre>".
Mike Cheponis
>
> So it looks like I've shot down the "performance" argument...
>
>
>
> except that netbsd ships with pre-formatted man pages and has for
> some years now, so this rarely happen anymore.
Except with newly-installed packages from /usr/pkgsrc/, like emacs.
> html is f*cking *horrible* format to create documentation in. as
> an author of many pages of netbsd documentation, i *totally* do not
> want to go to html documentation. i would probably support something
> else that wasn't so broken (such as docbook) and lacking in features
> that i currently use often, but i'm honestly quite happy with the
> way man pages work today. writing `mandoc' man pages is *really*
> nice to do, on the scale of documentation writing. they format nicely,
> particularly into postscript for printing, unlike html in the general
> case.
>
>
> please, take this html idea away and shoot it in the head before it
> spreads.
Then, for consistency, we must remove all hmtl from eveywhere in NetBSD,
and, in particular, we must rid ourselves of that vile and disgusting
html crap in /usr/pkgsrc; it is difficult to believe that the entire
NetBSD distribution has not been completely and utterly polluted by
association with html, ewwwwwu! Grab the Lysol!
Screw it that the rest of the world is going to html and xml, we're NetBSD!
We're the old guard! We keep using crap that should have been discarded
decades ago, because Ken and Dennis like it!
(Sorry, that's a bit over the top, I know, I know... it's called "humor"
in some circles...)
But here's the short of it:
The problem presented was: are all the error codes put into man pages, or
are man pages kept "as is" where some of the more common error codes are
documented, and you then grovel through the source code when you come
up against an error not mentioned in the man page?
Then consensus seems to be to -not- put all the error codes into the man
pages, because it clutters it up.
I pointed out that it clutters the man page because man pages are a simple
flat-file documentation style.
Therefore, some hierarchical documentation approach would both allow
uncluttered "front pages" of documentation, -and- would allow, for example,
a "link" to more detail (in those cases where you actually -did- want to
see all the error codes).
Why html? Because it's everywhere and it has the required propertities,
and because it allows updates over the net, or indeed, the entire doc tree
to be off your machine in an easy-to-access way.
If there is something superior to html, please, suggest it.
-Mike
Joseph Sarkes
>
> Then, for consistency, we must remove all hmtl from eveywhere in NetBSD,
> and, in particular, we must rid ourselves of that vile and disgusting
> html crap in /usr/pkgsrc; it is difficult to believe that the entire
> NetBSD distribution has not been completely and utterly polluted by
> association with html, ewwwwwu! Grab the Lysol!
>
> Screw it that the rest of the world is going to html and xml, we're NetBSD!
> We're the old guard! We keep using crap that should have been discarded
> decades ago, because Ken and Dennis like it!
>
It seems to me that as long as a standard format is kept to, it should be
a minor effort to make a program that can generate man pages from an html
file, and vice versa (obviously the man pages wouldn't contain, graphics,
etc.) I think the a2ps printer driver does a good job of bolding, etc. of
man pages as I recall. Hmmmm, doesn't Xman do the same thing? This should
give a basic html format to start from. I also expect that there are html
tools that could be adapted by/for the person that is html-izing the man
pages, and as long as those of us that prefer a quick text version can
run the de-html-izer program on the files (mk.conf switch?) then everyone
should be able to be happy. Maybe a pkgsrc html-man thing for those that
want the hyperlinked/cross indexed/source tagged man page edition with
the 8x10 color glossies with a paragraph on the back of each one describing
the crime in detail.
I know that for normal use, I don't want to wait for lynx to start up,
never mind something like netscape, just to get the proper switch letter
I need for a command. Not running an up to date machine, I prefer the less
resource intensive man pages for normal use.
--
Joseph Sarkes jsa...@tiac.net
James MacKinnon
On Mon, 17 Jul 2000, Greywolf wrote:
snip...
> It's small. It's reliable. You can always use a formatter to go to,
> as i posted earlier, a higher level. _You_ _must_ _expend_ _more_ _effort_
> _to_ _convert_ _from_ _one_ _high_ _level_ _format_ _to_ _another_, than
> you would need to do _if_ _you_ _started_ _from_ _a_ _lower_ _level.
>
I agree - it is much easier to coerce raw man into html than the other
way round, and raw man should *ALWAYS* be the primary source IMHO. If
you want html, well hey, go for it, but do it from the bottom up.
...snip...
>
> Just how far down do you want to dumb things, Mike?
Reminds me of a brilliant quotation I once heard somehwere :-)
"Unfortunately, we have evolved from a situation
where a bunch of smart people sat in front of dumb
terminals into a situation where a bunch of dumb
people are sitting in front of smart terminals."
And it's true, most people generally nowadays are blithering computer
idiots and have lost the fundamental core concepts of what a computer is.
It's a shame that some people who may profess to be computer wunderkids
have also fallen into the same pitiful boat as the vast masses of ordinary
users.
Cheers,
--
James S. MacKinnon Office: P-139 Avadh-Bhatia Physics Lab
Team Physics Voice : (780) 492-8226 [old AC 403]
University of Alberta email : Jim.Ma...@Phys.UAlberta.CA
Edmonton, Canada T6G 2N5 WWW : http://www.phys.ualberta.ca/
for all that we know the universe could cease to exist at any mo
Lucio De Re
>
> I realize you probably meant this as a rhetorical question, but in fact,
> the straight answer to that is "yes": the bulk of Plan 9's documentation
> is indeed in the form of man pages.
>
<http://plan9.bell-labs.com/magic/man2html/8/httpd>
(ironical, isn't it?) that seems to undergo regular maintenance
(not surprising).
Imagine, you could have had the best of both worlds, and no flame
war by simply being told this earlier :-)
++L
Lucio De Re
>
> The problem presented was: are all the error codes put into man pages, or
> are man pages kept "as is" where some of the more common error codes are
> documented, and you then grovel through the source code when you come
> up against an error not mentioned in the man page?
>
NetBSD user who _uses_ man pages is not dumb. I would find it
confusing to have each possible error, no matter how obvious, listed
for each function in man.2. I would be deeply offended if I discovered
this to be an attempt at insulting my intelligence and that of my peers,
one of the reasons I dislike the Microslob documentation you seem hell-
bent on emulating.
There is sense in HTML, but it is a dreadfully disturbing format to
code text in, and mere <pre>s, as you suggest, are more than inadequate,
I presume that was you shooting from the hip, rather than a considerate
response.
Now go look at Plan 9's doc <http://plan9.bell-labs.com/sys/doc/> and
see what we can all learn (and possibly improve on) from there.
> Why html? Because it's everywhere and it has the required propertities,
> and because it allows updates over the net, or indeed, the entire doc tree
> to be off your machine in an easy-to-access way.
>
> If there is something superior to html, please, suggest it.
>
You're lost :-) "man" and "ms" are superior, and, as greywolf
suggested, they are at a lower level, which makes it possible, not
just easier, to convert them to other styles. TeX may be another
option, but I suspect it is not sufficiently better to warrant
migrating to.
man2html and similar friends are the tools you're after, not
hotmetal (consider producing html documentation without a graphic
tool).
Just for curiosity's sake (a) have you ever looked at html2ps as
an indication of html's shortcomings, and (b) how do you propose
to track html's continued evolution in NetBSD's information page
display program - something I, at least, consider critical to
the operating system deployment?
++L
Lucio De Re
>
> I know that for normal use, I don't want to wait for lynx to start up,
> never mind something like netscape, just to get the proper switch letter
> I need for a command. Not running an up to date machine, I prefer the less
> resource intensive man pages for normal use.
>
the convention of a "-man" (or is it --man?) option to each command
to read its man page.
<http://www.research.att.com/sw/tools/uwin>
++L
Hauke Fath
>The important thing is that "man" has to come _first_, or you have
>lost your access to the information on a crippled system.
Strongly seconded.
And don't even think about force-feeding html on vax or m68k class machines.
"But everyone uses a PIII/600 these days?!" Not.
hauke
--
"It's never straight up and down" (DEVO)
Jim Reid
Mike> I'm afraid you didn't read or possibly didn't understand my
Mike> post.
I'm afraid I understood it only too well.
Mike> In fact, I consider "man" (a troff filter) to be
Mike> mechanically just like lynx. Don't you see why?
No. First of all, man is not a troff filter. Secondly, lynx (or some
bogus lynx-like man page browser) isn't a filter. Thirdly, the
paradigm behind troff man pages is that the formatted output can be
printed legibly. [Try doing that with web pages that were usually
written by clueless webmasters obsessed with visuals, feature-rich and
bandwith-sapping multimedia crap and similar eye-candy.]
Mike> FWIW, all Microsoft DDK documentation is in HTML.
I see/ Because M$ does something, that automatically means it's the
best/only way do that job and the rest of the world must immediately
follow that fad. Right.
Mike> If it was good enough for Ken and Dennis 30 years ago, is it
Mike> -still- good enough for Ken and Dennis -today- ?
Yes. Look at the Plan9 and Inferno documentation.
>> Someone once said that if the only tool you had was a hammer,
>> every problem would look like a nail. Well, UNIX systems have
>> more tools available than a just web browser.
Mike> I'm afraid I don't understand this at all.
The only tool you seem to care or know about is a web browser. So, to
you, every problem can only be solved by making it produce data that
can be fed to said browser. [Whether that browser is the right tool
for the job or not is neither hear nor there. That's *all* you've got,
so everything has to be mangled into that paradigm.] Meanwhile there
are other tools - which you don't care about - that are more than
capable of handling the data properly. If only you knew they existed
and what they get used for.
Jim Reid
Mike> 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?
Mike> EXCUSE ME? I NEVER SAID ANYTHING ABOUT NEEDING TO RUN X.
You implied it. You suggested scrapping man pages and turning them
into HTML. [An amazingly stupid and badly thought-out idea.] HTML is
unreadable mush unless it's fed to GUI. That means X on a UNIX system.
The fact that you made this suggestion shows the depths of your
ignorance and cluelessness about documentation. You seem to think
there's nothing wrong with using an X server and a web browser - two
of the chubbiest applications on a UNIX system - just so someone can
get a readable version of a man page. This is utterly nuts. You don't
even appreciate just how stupid that idea is. Then you proposed a
custom lynx-like utility, which is an even more stupid idea. What if
someone wants to read man pages in single-user mode. Or - perish the
thought! - read them on paper without having to start a computer.
Mike> Ahh, perhaps you haven't noticed, but when you do "man foo"
Mike> it often says "man: Formatting manual page..." as it grinds
Mike> away... If you type "lynx README.html" in one of the
Mike> /usr/pkgsrc/<whatever> directories, it snaps up instantly.
Mike> So it looks like I've shot down the "performance"
Mike> argument...
No. It looks like you didn't install preformatted man pages. Or allow
the man command to install preformatted versions on the fly.
Mike> Another cool thing about html-based documentation is that
Mike> not only can it trivially use local files, but it can also
Mike> access data over the net; this can be helpful for small
Mike> systems that have a net connection but do not want to waste
Mike> local disk space for doc, or as a place where documentation
Mike> updates are placed.
This is a valid, but fallacious argument. What if the user's computer
isn't on the net? [Suppose someone's working when they're in a plane
or train.] Why does someone's computer have to somehow be plugged in
to the phone system, just so they can read a man page? Have you any
idea how nonsensical that is? Or what if that computer has a low-speed
internet link? Why should someone have to depend on so many
unnecessary diversions just so they can read a man page? And what if
the man page they need to read is the one describing their PPP daemon
or its config files? Suppose these things are broken and you're
trying to find out how to get them working again: how do you access
the documentation? You just don't get it, do you?
Jim Reid
Lucio> man2html and similar friends are the tools you're after,
Lucio> not hotmetal (consider producing html documentation without
Lucio> a graphic tool).
Indeed. Another point is that when someone uses such-and-such a
graphic tool, they assume (sometimes unconsciously) that everyone
reading whatever they write has the same GUI as they have. This is how
we end up with useless web sites that require everyone to have upmteen
plug-ins for their web browser, LAN-speed internet access, Java cruft
enabled, etc, etc. One of the whole ideas of UNIX systems was to
arrange the output from one tool could be fed into another, even if
the designers of both tools hadn't envisioned that their code would be
used in that way. It seems that important lesson has been forgotten.
Roger Brooks
>Has anybody here actually looked at Microsoft's documentation? Frankly,
>it is head and shoulders above what we have.
Do you really think so? In my experience it looks very pretty, but has
bugger-all useful content, and what there is, is so fragmented that it is
almost impossible to read all about a topic without following several dozen
hyperlinks.
For a more extreme example of what is wrong with hypertext, try using the
online documentation [sic] which comes with Borland C++ Builder. Here, the
writers seem to be trying to handle the problem of dumbed-down morons with
limited attention spans by having no page which is much larger than about
3 paragraphs. But it's a bit difficult to document a C++ class in 3
paragraphs, and as a result you once again have to find your way through
a twisty maze of hyperlinks, all very similar. As someone in the Computer
Science department here once commented rather memorably "The trouble with
hypertext is that it's a lot of hype about not very much text".
Something like the C++ Builder documentation is probably just about usable
by someone who already knows what all the components do, and just needs
to check details occasionally. But as someone who had never done any
Windoze (or C++) programming I found it fscking useless. You want to see
ALL the description of a component, including all it's methods, all at the
same time? Sorry, the hypertext system doesn't do that. You want to see
ALL the description of two similar components, so you can decide which is
better suited to your requirements? Forget it -- you can only see one
snippet at a time.
Whenever I've started to work on a new system I've always browsed the
printed documentation to see what is available, and to get a rough idea
what each "thing" can do. If you don't do this there's always a great
danger that you'll re-invent a wobbly version of a wheel which already
exists, or use a hammer to insert a screw (because you didn't realise
that you were supposed to use a screwdriver). But try getting a printed
version of the C++ Builder crap. I did this and got thousands of pages,
each documenting a single method or exception, printed in random order.
I sat on the floor in the middle of my office for two days trying to
sort this crap before giving up and throwing the whole lot in the bin.
I'm not saying hypertext can't ever work; just that I've seen a lot of
examples where it doesn't. The good examples can be printed as a paper
document and read easily. This means, for example, that hypertext links
should read "see Section A.B.C for more information about foo()", so
that the link makes sense in the printed copy. But to get this sort of
detail right you have to discipline yourself to produce a printed copy
(and probably have someone else proof-read it). I think the other main
failing is to break a single topic up into child-sized portions in the
mistaken belief that this will make it easier to read.
So I agree completely with Greywolf that man pages shouldn't go away.
I've nothing against adding extensions which allow the troff source to
contain hyperlinks so that it can be processed into HTML, but I don't
think there is anything wrong with the existing format of man pages.
Printed manuals are NOT obsolete, particularly when you need rapid access
to several different sections.
>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.
I've always found that an NFS mount of /usr/share/man (or whatever) works
quite well for this.
Roger
------------------------------------------------------------------------------
Roger Brooks (Systems Programmer), | Email: R.S.B...@liv.ac.uk
Computing Services Dept, | Tel: +44 151 794 4441
The University of Liverpool, | Fax: +44 151 794 4442
PO Box 147, Liverpool L69 3BX, UK |
------------------------------------------------------------------------------
Mike Pelley
People who suggest that Mike implied X in his original post appear not to have read the original message, part of which is quoted below.
> 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).
It seems quite clear to me.
I prefer man pages to html myself, but I think exploring the options is worthwhile. The abuse, however, seems unnecessary and counterproductive.
Mike.
Jim Bernard
>
> If the man pages were html, with links to deeper documentation levels (even
Of course, the (mdoc) man pages are trivially converted to html via, e.g.,
nroff -mdoc2html /usr/share/man/man1/man.1
since /usr/share/tmac/tmac.doc2html has been in the tree for quite some time.
It even has a macro for generating links (Lk), though it appears not to have
been used in any of the NetBSD man pages, and it's not documented on the
mdoc man page.
Tom Rushworth
> >>>>> "Mike" == Mike Cheponis <m...@Wireless.Com> writes:
This is starting to get a lot more intense and personal than I
think it warrants. People are starting to say things like
"you said use X" when Mike said no such thing - his original
post said:
"stripped down lynx (or other specialized text-based
browser".
(I'm quoting his _exact_ words here.) His proposal is not totally
unreasonable - I don't like it, but it is _not_:
"[An amazingly stupid and badly thought-out idea.]"
Searchable, properly linked documentation can be very useful, and is
a _possible_ solution to the original problem of documenting all
the error codes returned by various syscalls or library routines.
Instead of flaming away at each other, why don't we spend the time
profitably, by looking at the plan9 man2html, and seeing if it
really can solve the "too many error codes to document" problem
without a huge penalty? That way, folks like me, who want to use
man, and are willing to use "SEE ALSO", can do so, and folks who
prefer to follow links can install the appropriate package (call it
manlynks :) ?), run the converter and live happily ever after.
If it's done with a converter the "links" people can fall back to
"man" when the system is too restricted or broken to support the
text browser. Who knows, if the package is reliable, I might even
try it and like it :).
--
Tom Rushworth
David Brownlee
( I'd like to second this, and I'm only sorry I wasn't
( online to comment earlier.
( I am very disappointed by the inappropriately agressive
( replies that seemed to be based on the most cursory glance
( at the original post.
I like manpages, but I agree there are a couple of obvious
features missing compared to some other formats:
- Follow references to other documents
- Jump to, or even see an index of sections
- Sanely search for implemented commands or similar
(eg: Just try to lookup the 'complete' syntax in tcsh(1))
Switching the man page source format to html would address some of
those issues, at a tradeoff many people are not willing to make.
( It is unfortunate that some of them seem unable to express
( their feelings in a rational manner, and interesting to note
( that some of the same set may have in the past expressed
( amusement at similar behaviour on linux lists..
Alternative options include:
a) Having an easy way, possibly even a package, to convert all the
manpages on an existing system to html. I personally would set
this up on some of my servers for others here. Documenting the
.Xr macro would be a good addition to this.
b) Provide all manpages in 'text' and 'html' output by default.
c) Allowing new manpages to be written in DocBook or some other
'real' document language.
d) Produce a slightly modified nroff output which could be
processed by a slightly modified more to allow following
of references to other docs, and jumping to index sections.
I would love to see a) - it helps those who want to read in html,
without annoying those who prefer to write in mdoc.
David/absolute
-- www.netbsd.org: A pmap for every occasion --
Bill Studenmund
> You guys sure showed him. He'll think twice before his next post.
Indeed, in quite a viperic manner.
> People who suggest that Mike implied X in his original post appear not
> to have read the original message, part of which is quoted below.
>
> > 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).
>
> It seems quite clear to me.
>
> I prefer man pages to html myself, but I think exploring the options
> is worthwhile. The abuse, however, seems unnecessary and
> counterproductive.
I concure with Mike P. here. Mike C. was suggesting a way to make our
documentation system better. While I don't fully agree with his proposal,
the abuse was really unwaranted.
Take care,
Bill
Bill Studenmund
> On Mon, Jul 17, 2000 at 01:05:32PM -0700, Mike Cheponis wrote:
> >
> > If the man pages were html, with links to deeper documentation levels (even
> > automatically generated documentation), that would be better.
I have to (politely) disagree with Mike here. I think HTML's ability to
have links to other pages is a good thing and something we should
explore. However I think that html would be a horrid language to use to
actually maintain the page. It'd be kinda like using PostScript to
maintian the document. :-)
HTML is great at being a markup language - it tells a program how to
display a document. It's not great at retaining concepts. Look at the
existance of things like DocBook. Many folks have gone to not using HTML
in the raw, but using some sort of document language which can be turned
into html. Because HTML doesn't retain the concepts of what it's marking
up.
> Of course, the (mdoc) man pages are trivially converted to html via, e.g.,
>
> nroff -mdoc2html /usr/share/man/man1/man.1
>
> since /usr/share/tmac/tmac.doc2html has been in the tree for quite some time.
> It even has a macro for generating links (Lk), though it appears not to have
> been used in any of the NetBSD man pages, and it's not documented on the
> mdoc man page.
My, don't we all look smart, arguing about somethign Ross put into the
tree like 18 months ago, and which is in 1.4. :-)
I think this would be the best solution. Having man pages made with this
would keep our man pages in mdoc and yet give us ready html. And with the
Lk macro (which I haven't looked at), we could embed the links which HTML
is good for. :-)
All this would mean is: 1) adding links to existing man pages, and
2) generating make infrastructure to make html man pages.
Note: I'm not suggesting we ship them by default, just that we have
machinery to automatically build them if desired, both from source and
from installed raw man pages. When we get the base install packaged, then
we can put them into the base. :-)
Thoughts?
Take care,
Bill
d...@mail.lns.cornell.edu
> Why html? Because it's everywhere and it has the required
> propertities, and because it allows updates over the net, or indeed,
> the entire doc tree to be off your machine in an easy-to-access way.
I occasionally have to write a bit of documentation, and IMHO HTML
doesn't have the required properties for a documentation project the
size of the NetBSD man pages. I'll address just a few points here:
1) One of the great strengths of the Unix man pages is the conventional
structure--NAME, SYNOPSIS, PARAMETERS, DESCRIPTION, RETURN VALUES, etc.
Seriously, I'm not kidding--consistency in technical documentation is
*highly* desirable, and the man pages have a structure that, for the
most part, works well. If we're going to consider replacing them, the
replacement ought to directly support, even enforce, the conventional
structure. HTML doesn't, and switching to HTML rather than tmac.man
would most likely encourage people to depart from the documentation
conventions.
2) HTML as it is today--a poorly structured, undisciplined presentation
language--is very difficult to extract information from. Several
people have already pointed out that HTML doesn't print as nicely as
troff. More to the point, it can be very hard to extract meaning from
HTML documents (one reason why search engines are so hard to do well).
The current man page conventions offer some implicit support for
representing and extracting meaning, via the structuring conventions,
the '-' convention used to construct the 'whatis' index, the
conventions used in the 'RELATED INFORMATION' section, etc. Any
replacement ought to make this information explicit rather than
conventional.
3) HTML tomorrow won't be the same as it is today. Any change in
format must take that into consideration, most plausibly by rewriting
the man pages into a format that captures the structure of the
documents, and which can then be automatically converted into
semantically poorer presentation formats like roff and HTML.
In short, I think any format conversion ought to take into account
long term maintenance, conversion into varying presentation formats,
and explicitly representing the semantic content of the document
structure. HTML is horrible on all counts. The LinuxDoc folks
realized all this, which is why they're using SGML rather than HTML.
If I were planning a commercial NetBSD (or had a horde of volunteers)
and wanted to be trendy, I'd be looking at converting the man pages
into a man page XML DTD that captures the conventional structure of
man pages, and which could then be automatically converted into HTML,
WAP, etc., or even back into man format. However, that's a lot of
work, and there are probably more pressing needs than converting all
the man pages into XML.
The only lesser step that makes any sense to me would be better
support for automatic conversion of the existing man pages into HTML.
Switching to HTML as the native format looks like a big step
backwards.
wrt to info pages, info and .texinfo are ok for what they were
designed for--info pages--but info pages are not man pages, nor are
they an adequate replacement for man pages (and yes, I think it's a
shame that a lot of the GNU utilities do not have supported man
pages).
--
Dan Riley d...@mail.lns.cornell.edu
Wilson Lab, Cornell University <URL:http://www.lns.cornell.edu/~dsr/>
"History teaches us that days like this are best spent in bed"
Greywolf
# You guys sure showed him. He'll think twice before his next post.
One would hope so.
# People who suggest that Mike implied X in his original post appear not
# to have read the original message, part of which is quoted below.
Okay, that was a misread. My comments on using a mangled lynx-alike
stand on their own merit, and I'm using _fast_ hardware. Never mind
the folks who are actually using the otherwise obsolete hardware to
which NetBSD was ported in order to extend its lifespan.
#
# > 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).
#
# It seems quite clear to me.
#
# I prefer man pages to html myself, but I think exploring the options is
# worthwhile. The abuse, however, seems unnecessary and
# counterproductive.
You just hit the ten million credit word: "options".
He's proposing ditching man pages in their current format. I (and,
from the looks of it, others) find that this would be but a nonsensical
move.
And he said something about the performance argument being shot down,
after I mentioned something about "overhead".
Who generated the patently silly notion that "overhead" and "performance"
are exclusively synonymous? My hardware may be fast, and I might have 20G of
disk, but I tend to think along smaller lines (excess of disk space is not
an excuse to bloat the system -- data is a different matter).
"Overhead" is, to me, disk real estate and RAM footprint. I'll let the
CPU sort it out.
# Mike.
--*greywolf;
--
BSD: Got source?
Greywolf
# Date: Tue, 18 Jul 2000 11:06:18 -0700
# From: Tom Rushworth <t...@mannynkapy.net>
# Reply-To: t...@acm.org
# To: Jim Reid <j...@rfc1035.com>
# Cc: Mike Cheponis <m...@wireless.com>, Greywolf <grey...@starwolf.com>,
# tech...@netbsd.org
# Subject: Re: bin/7249 - slow down, take a deep breath...
#
# On Tue, Jul 18, 2000 at 11:43:06AM +0100, Jim Reid wrote:
# > >>>>> "Mike" == Mike Cheponis <m...@Wireless.Com> writes:
# [Many angry words obscuring a few ideas snipped.]
On reflection, some were angry. I'll take that off line.
But some were incredulous. I think that the ability to do this
as an extension and an option are fine. To replace, outright,
man pages and the manner in which they are viewed would be folly.
(Just to be sure, did everyone catch the words "extension" and "option"?
I'm not negating the idea, is that clear?)
--*greywolf;
--
NetBSD, Net Improvement.
Robert Elz
From: Richard Rauch <r...@rkr.kcnet.com>
Message-ID: <Pine.NEB.4.21.000719...@rkr.kcnet.com>
I disagree with this part of your message...
| Some kind of linking mechanism would be nice, though. See also's don't
| really cut it: [...]
Man pages should be concise, precise, and complete documentation of any
single system feature (except where being complete would take hundreds
of pages - there external doc should fill in the details, and the man
page should give an overview).
If you have to go view some other page to get the specific details of a
particular system feature, then the man page is broken. See Also references
give other related, or background information that can be useful for
general understanding, or which provide documentation on something that
is likely to be useful in conjunction with the subject of the current page.
To put this into the context of the errno value discussion - anything that
is specific to a particular sys call needs to be fully documented in the
man page for that sys call. On the other hand, anything which is just
general common error information, not specific to the sys call being
documented should not be mentioned (or at least, need not be mentioned).
A "see also" should refer to intro(2) where general information about all
system calls is to be found, including a complete list of all the possible
errors.
Under no circumstances should reading a man page be even suggesting that
readers should perhaps go read some other man page or doc in order to
complete the information about the thing being documented (with the
sole exception of referring to some complete system doc where the complete
doc would be too much for the man page - like for programming languages,
editors, etc).
On the other hand ...
| Perhaps instead of trying to force the man pages to support _all_ system
| documentation, we could revive the PSD/USD/etc. documents [...]
That I agree with completely - as much as possible, we should have
architecture, and other docs, and be making those available (eg: someone
should ask Kirk for permission to include his softdeps paper, ...)
kre
Chris Pinnock
> 1) One of the great strengths of the Unix man pages is the conventional
> structure--NAME, SYNOPSIS, PARAMETERS, DESCRIPTION, RETURN VALUES, etc.
> Seriously, I'm not kidding--consistency in technical documentation is
> *highly* desirable, and the man pages have a structure that, for the
> most part, works well. If we're going to consider replacing them, the
> replacement ought to directly support, even enforce, the conventional
> structure.
I agree with this totally. The on-line documentation on the NetBSD
system is very good compared with documentation on other systems. It
is reasonably easy to find what one wants. I wouldn't like to see
the NetBSD documentation spoilt in favour of a new format.
However, I would not be against having the option of documentation in
other formats on the system, __provided__ that we don't end up in
the situation of other systems, where I have to use man, info, and look
in /usr/doc in 3-4 different formats. Perhaps a /usr/share/doc/html
directory or something like that?
--
Chris
Christopher Reid Palmer
> To replace, outright, man pages and the manner in which they are viewed
> would be folly.
Consider two new environment variables that a new man(1) checked:
$MAN_FORMAT and $MAN_VIEWER.
If `man some_program' shot out plain text and fed it to $PAGER, by
default, would you be not unhappy with a new man(1) really being quite
different than it is now?
To wit:
$MAN_FORMAT=text|dvi|ps|html|...
$MAN_VIEWER=lynx|$PAGER|netscape|gv|...
I agree that removing the current functionality--plain text to a pager to
a terminal--should never, ever, go away. My other post did not mean to
suggest that. Just like you say, I want to extend and add options, not
take away the reasonable defaults and good functionality that exist.
--
Chris
www.innerfireworks.com
Bill Studenmund
> Bill Studenmund <wrst...@zembu.com> writes:
>
> I think SGML (DocBook DTD when we speak about programming or system
> documentation) would be the best choice: ability to get in the output
> almost any reasonable format (plain text, TeX, html, xml, PostScript,
> PDF or what you really want) is a big win. I see only two dark sides:
>
> * converting between SGML and requested format is relatively slow
> especially on the old or slow technique (but we could have at least
> preformatted text manuals and use them instead of direct SGML
> processing). Even more, PostScript and PDF require TeX installed
> somewhere.
>
> * SGML processor should imported into system source tree and requires
> maintaining. At least sometimes.
I think these dark sides are quite dark actually. :-) While I think
DocBook is great for how-to's & such, I don't think we're there yet for
turning all of the man pages into it.
Needing TeX in the base install is a big downer. While I LOVE LaTeX and
would use it almost exclusivly, I don't think it's appropriate for the
main system.
Are there any SGML editing tools? There's LyX for LaTeX, but I've seen
nothing for SGML or DocBook.
Also, to further muddle the waters, you can get DocBook for xml too. :-)
Take care,
Bill
AnorEXia
> On Tue, 18 Jul 2000, Mike Pelley wrote:
>
> > You guys sure showed him. He'll think twice before his next post.
> >
> > People who suggest that Mike implied X in his original post appear not to have read the original message, part of which is quoted below.
> >
> > > 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).
> >
> > It seems quite clear to me.
> >
> > I prefer man pages to html myself, but I think exploring the options is worthwhile. The abuse, however, seems unnecessary and counterproductive.
> >
> > Mike.
> >
>
>
>
Greg A. Woods
> Subject: Re: bin/7249
>
> Incidentally, I took the reference to "go look in the source" to be a joke,
> no-one is seriously suggesting that (or if they have, they have never attempted
> to work out what errors the kernel can generate from reading the source - it
> is not at all easy to do, even if you know the sources fairly well).
>
> The real discussion that started this is whether or not each man page should
> attempt to have a complete list of all the errors, or whether most of them
> should be incorporated by reference to the intro(2) page, which contains all
> of the errno values, and their standard meanings. Clearly when a kernel
> interface uses an error number in a non-standard way (almost the rule for
> ENXIO) then it needs to be documented on that page - but there really is
> no need to have EROFS mentioned in the pages for link(), open(), creat(),
> mkdir(), rmdir(), unlink(), socket(), ... on and on, all those functions
> return the error in the same circumstance, the definition of the error in
> EROFS in intro(2) is just fine. That read() can't rationally return EROFS
> is really immaterial - anyone reading its description ("An attempt was made
> to modify...") will see that since read() doesn't modify the file, that
> error will not occur.
It is indeed damn near impossible to always work out exactly what errno
values the kernel can potentially return from any given system call (or
indeed a libc function), even by examination of the source as you say
above. I firmly believe it is critical that all API manual pages
document at least the list of error codes that the developers believe
are possible. It's not necessary to fully describe what each code means
when the meaning is indeed identical to the generic description given in
intro(2) (or intro(3)), and indeed such descriptions should probably not
be given in order to avoid the maintenance headache of duplicating and
changing this description. Certainly I agree that any unique meaning
must be documented explicitly in the associated manual page.
I for one will continue to submit fixes for manual pages that do not at
least list all error codes thought possible....
--
Greg A. Woods
+1 416 218-0098 VE3TCP <gwo...@acm.org> <robohack!woods>
Planix, Inc. <wo...@planix.com>; Secrets of the Weird <wo...@weird.com>
Greywolf
# It is indeed damn near impossible to always work out exactly what errno
# values the kernel can potentially return from any given system call (or
# indeed a libc function), even by examination of the source as you say
# above. I firmly believe it is critical that all API manual pages
# document at least the list of error codes that the developers believe
# are possible. It's not necessary to fully describe what each code means
# when the meaning is indeed identical to the generic description given in
# intro(2) (or intro(3)), and indeed such descriptions should probably not
# be given in order to avoid the maintenance headache of duplicating and
# changing this description. Certainly I agree that any unique meaning
# must be documented explicitly in the associated manual page.
What's wrong with using the .so directive, and perhaps splitting out
the definitions into smaller files? It would solve the problem of duplicity.
# I for one will continue to submit fixes for manual pages that do not at
# least list all error codes thought possible....
--*greywolf;
--
BSD: Microsoft ask you where you want to go. BSD gets you there.
Greg A. Woods
> Subject: Re: bin/7249
> What's wrong with using the .so directive, and perhaps splitting out
> the definitions into smaller files? It would solve the problem of duplicity.
Yeah, but ".so" is a nasty and unportable hack (thus soelim). Groff
does implement ".so" internally, and adds ".mso" which would be closer
to what one would want, but I still feel it is a bad hack. (There's
even ".pso"! ;-)
Besides there's already a link that causes "man errno" to display up
intro(2). When you combine this fact with the goal of keeping manual
pages concise and simple, I think the best compromise is to simply list
errno values/codes that have their common meaning and to only describe
in detail those that have unique meanings for the given function. There
could be a "SEE ALSO" entry pointing at errno(2) for pedants, I suppose.
Greywolf
# Date: Thu, 20 Jul 2000 20:07:27 -0400 (EDT)
# From: Greg A. Woods <wo...@weird.com>
# Reply-To: NetBSD Kernel Technical Discussion List <tech...@netbsd.org>
# To: NetBSD Kernel Technical Discussion List <tech...@netbsd.org>
# Subject: Re: bin/7249
#
# [ On Thursday, July 20, 2000 at 16:06:46 (-0700), Greywolf wrote: ]
# > Subject: Re: bin/7249
# >
# > What's wrong with using the .so directive, and perhaps splitting out
# > the definitions into smaller files? It would solve the problem of duplicity.
#
# Yeah, but ".so" is a nasty and unportable hack (thus soelim). Groff
# does implement ".so" internally, and adds ".mso" which would be closer
# to what one would want, but I still feel it is a bad hack. (There's
# even ".pso"! ;-)
What's hackish about it? Do you consider #include to be a hack, or a
functional part of the preprocessor?
I guess I don't understand why it is not portable -- is it one of those
not-implemented-everywhere things, or what?
# Besides there's already a link that causes "man errno" to display up
# intro(2). When you combine this fact with the goal of keeping manual
# pages concise and simple, I think the best compromise is to simply list
# errno values/codes that have their common meaning and to only describe
# in detail those that have unique meanings for the given function. There
# could be a "SEE ALSO" entry pointing at errno(2) for pedants, I suppose.
Well, it still would have solved the duplicity problem.
--*greywolf;
--
BSD is much like a tipi: No windows, no gates, and an apache inside.
Greg A. Woods
> Subject: Re: bin/7249
>
> What's hackish about it? Do you consider #include to be a hack, or a
> functional part of the preprocessor?
>
> I guess I don't understand why it is not portable -- is it one of those
> not-implemented-everywhere things, or what?
Indeed it's not portable. I think groff was/is the only *roff to ever
implement .so internally. (Mabye sqtroff had some support....)
Another issue is the fact that none of the troff preprocessors (eg. tbl
or eqn, etc.) implement .so meaning that you still can't always do
everything you want in any way you want even if .so is built into troff
itself. (Geqn does have an ``include'' command, but no pre-processor
can rightly take over the '.so' directive from any other without causing
confusion at the best....)
The "soelim" program (or some more advanced macro processor) is the way
to get around both of these problems at the same time, but it's yet
another slowdown to run it for manual pages, and though it could be used
in /etc/man.conf, traditionally it isn't because nobody ever expects
manual pages to use ".so"....
Robert Elz
From: wo...@weird.com (Greg A. Woods)
Message-ID: <20000721013...@proven.weird.com>
| Indeed it's not portable. I think groff was/is the only *roff to ever
| implement .so internally. (Mabye sqtroff had some support....)
Hmmm - .so is just about as ancient *roff as .br is ... I have been using
nroff for a long long time, and .so has always been there (I haven't been
using troff quite as long, as I used nroff back before I had any kind of
method of displaying troff output - but .so was in troff too).
There's nothing even slightly "not portable" about .so
However ...
| Another issue is the fact that none of the troff preprocessors [...]
Yes, .so is preprocessor grief - though it need not be. soelim helps
with that (unless the *roff code is broken (ie: the doc source) it
should always be possible to replace a .so by the contents of the named
file.
But soelim was really built to assist spell if I remember correctly - without
it, the included files never got spell checked.
kre
Greg A. Woods
> Subject: Re: bin/7249
>
> There's nothing even slightly "not portable" about .so
Oh, of course! I must have been so hung up on the problems of .so for
preprocessors that I've trained myself to ignore its presence in troff!
> But soelim was really built to assist spell if I remember correctly - without
> it, the included files never got spell checked.
Now there's an interesting piece of trivia. Soelim sure has been abused
for other uses since -- I've seen it used in lots of places where troff
and freinds were nowhere to be found!