Date: Thu, 30 May 2002 00:47:47 +0300 From: Giorgos Keramidas <keramida@freebsd.org> To: Tom Rhodes <trhodes@freebsd.org> Cc: freebsd-doc@freebsd.org Subject: (man page || manpage) => manual page Message-ID: <20020529214746.GA67346@hades.hell.gr>
next in thread | raw e-mail | index | archive | help
Hello there,
Nice to see someone has taken it upon himself to finish the job I left
in the middle (by completing only the articles/ part) a while ago.
> config file with the appropriate entries. See the
> - <samp>stl(4)</samp> man page and the appropriate section of the
> + <samp>stl(4)</samp> manual page and the appropriate section of the
When &man.xxx.y; references are being made I prefer the style that
Jeroen suggested to me a long time ago. Instead of writing:
"see the foo(n) manpage"
You can simply use "see foo(n)", since it should be apparent that this
is a reference to a manual page. Repeating in every such place that
it "is a manual page" is a bit of an overkill.
> would generate such a set of context diffs for the given
> - source file or directory hierarchy. See the man page for
> + source file or directory hierarchy. See the manual page for
> &man.diff.1; for more details.</para>
Another example of a case where dropping "manpage" altogether gives
actually more aesthetically pleasing results. Compare the text above
with the following:
See diff(1) for more details.
> <para>This chapter was written by &a.murray; with selections from a
> - variety of sources including the intro(4) man page by
> + variety of sources including the intro(4) manual page by
> &a.joerg;.</para>
I guess this can safely be replaced with &man.intro.4;.
> - handbook, the man page or from the ppp.conf.sample file.
> + handbook, the manual page or from the ppp.conf.sample file.
Now that I see this... You might want after you've done the manpage
changes to wrap ppp.conf.sample in <filename> tags. Or I'll do it,
but in a few days, to avoid making you merge stuff again and again.
> Additional encoding options can be found by consulting the
> - lame man page.</para>
> + lame manual page.</para>
Since `lame' is used in IRC to denote 'silly', 'idiot', or similar,
you will probably want to change this part. Make it something like:
by consulting
<citerefentry>
<refentrytitle>lame</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>.
This emulates the functionality of &man.lame.1;. You can even make
this a local entity in the file that references the manpage, by adding
to the <!DOCTYPE> element the proper stuff:
[ <!ENTITY man.lame.1 "<citerefentry/<refentrytitle/lame/<manvolnum/1//"> ]
and then using &man.lame.1; as usual.
> -in your ppp configuration file (refer to the man page for details).</para>
> +in your ppp configuration file (refer to the manual page for details).</para>
I would make the manpage reference more explicit here, and use
&man.ppp.1; in the parenthesized text:
... (refer to &man.ppp.1; for details).</para>
Well, that's all. I hope it hasn't started to get annoying yet ;)
- Giorgos
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?20020529214746.GA67346>