Date: Tue, 7 Aug 2001 17:00:37 -0700 From: Murray Stokely <murray.stokely@windriver.com> To: freebsd-doc@FreeBSD.org Subject: rethinking man page references in the Handbook Message-ID: <20010807170037.O23183@windriver.com>
next in thread | raw e-mail | index | archive | help
I think there are two problems with the way we currently refer to
man pages in the FreeBSD Handbook. First of all, there is no
consistency to how we refer the user to a man page for more
information :
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.
Do we want to add a standard section to the back of each chapter
that lists the relevant man pages that contain more information? Or
should we continue to add these in an ad-hoc fashion throughout most
of the book (with at least a little more standardization).
The second problem is that we simply use &man.cmd.sec; entities too
often. There are many paragraphs that contain the same man entity 4-5
times which is very distracting. These entities are very useful but I
think that we should only use them them the first time that a command
is mentioned in a section, and then markup the command in <command>
for future references in that paragraph and following ones.
Thoughts?
- Murray
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?20010807170037.O23183>