Date: 07 Aug 2001 19:04:50 -0700 From: swear@aa.net (Gary W. Swearingen) To: Murray Stokely <murray.stokely@windriver.com> Cc: freebsd-doc@FreeBSD.ORG Subject: Re: rethinking man page references in the Handbook Message-ID: <5bn15btigt.15b@localhost.localdomain> In-Reply-To: <20010807170037.O23183@windriver.com> References: <20010807170037.O23183@windriver.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Murray Stokely <murray.stokely@windriver.com> writes:
> 1) Please see sio(4).
> 2) For more information see sio(4).
> 3) For more information see the sio(4) man page.
> 4) For more information see the man page sio(4).
> 5) For more information see the sio(4) manual page.
>
> It wouldn't be too much work to pick one of these and standardize on
> it throughout the Handbook. #1 definitely doesn't work for the
> printed output, so those need to be changed anyway.
See Chapter 10 of
/usr/share/doc/en_US.ISO_8859-1/books/fdp-primer/book.html
It calls for either
"See man csh for more information."
with "man csh" using unnamed typewriter-looking tag, or
"See csh(1)"
using <citerefentry>, with the latter (the one that "doesn't work
for the printed ouput") being the "preferred" choice. "See man
csh" doesn't work for things like "See man shutdown" which gives
you shutdown(2) instead of the expected shutdown(8).
The meaning of "See man(#)" is such a common thing in Unix and
would be common in the handbook, that it would be a shame to have
to use all that "for more information see the xxx manual page"
verbage all over the place for the sake of very newbies that haven't
bothered to read (and remember, of course) the intro section where
"see man(1)" is explained. They'd catch on soon enough anyway.
As for "man" versus "manual", I think the same thing holds. The
short term is such an entrenched part of Unix jargon that it's
not worth while trying to stamp it out. Maybe a (short-as-possibe)
Handbook Jargon section would be useful, but I fear it would grow
into a huge Hacker's Dictionary.
...
> is mentioned in a section, and then markup the command in <command>
...
> Thoughts?
I hope you don't mind my rudeness, but I'd like to see the handbook
avoid hacker tendency to use nouns like markup, setup, lookup, shutdown,
as verbs. I see a lot of them, but I plan to not write PRs on them
(though I might slip a few changes of them into other PRs).
Or is my dictionary too old?
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?5bn15btigt.15b>