POD documentation

Russ Allbery rra at stanford.edu
Wed Jul 18 17:22:21 UTC 2007


Julien ÉLIE <julien at trigofacile.com> writes:

> By the way, I have two little questions:

> * is there a preferred use between (for instance) "B<ctlinnd>" and
>   "ctlinnd(8)" in the middle of a sentence?

Use B<ctlinnd> for general references to the ctlinnd program.  Use
ctlinnd(8) for specific references to the man page.  ctlinnd(8) gets a lot
of markup and I find it distracting for every reference to a program to be
a link to a man page.  People are generally able to go find the man page
if they have a specific question, and the link isn't useful unless
something about the text specifically points the user to go look at that
page.

> * should it be written "if set to true" or "if set to C<true>"? (I see
>   both of them in the current documentation -- and more generally, should
>   C<> be more extensively used?)

I usually try to use C<> for specific text and specific values, including
numbers (although I'm bad about always remembering to use it for numbers).
It shouldn't be used for general concepts.  In this case, "if set to true"
is usually talking about the general concept of a true value, given that
INN supports literal values of C<true>, C<on>, and C<1> that all mean the
same thing as the concept of true.  So I probably wouldn't use C<> there.

-- 
Russ Allbery (rra at stanford.edu)             <http://www.eyrie.org/~eagle/>

    Please send questions to the list rather than mailing me directly.
     <http://www.eyrie.org/~eagle/faqs/questions.html> explains why.


More information about the inn-workers mailing list