On Sunday 24 July 2005 6:03 pm, Antonio S. de A. Terceiro wrote:
> All the three ocurrances mean "-1" as a return code in methods
> documentation, but changing the source code for this isn't reasonable to
> me.
Nor should it be, but does that need to be expressed that way in the manpage?
> N: Manual page seems to contain a hyphen where a minus sign was intended.
> N: '-' chars are interpreted as hyphens (U+2010) by groff, not as minus
> N: signs (U+002D). Since options to programs use minus signs (U+002D),
> N: this means for example in UTF-8 locales that you cannot cut&paste
> N: options, nor search for them easily.
Now, as I read that, the emphasis on options rather than return code and the
example of searching through the manpage makes it unlikely that an explicit
return value was intended to match the warning. (Thereagain, manpages I've
written also don't tend to mention the return value.)
I'd be tempted to change the source of the manpage to "negative", or "negative
1", or "minus 1" . i.e. Program returns negative on error, otherwise zero.
I use doxygen for source code documentation but DocBook for manpages - I
haven't used doxygen for both. In the doxygen comments, it is v.common to use
-1 - does doxygen work with the recommended escape value?
> N: '-' must be escaped ('\-') to be interpreted as minus. If you really
/** \brief func
\return \-1 on error, otherwise 0
*/
> * escape the hyphens manually with sed during build?
> * try to make doxygen do the "right thing" with those hyphen's ?
That's worth a try, the escape is the simplest method.
--
Neil Williams
=============
http://www.data-freedom.org/
http://www.nosoftwarepatents.com/
http://www.linux.codehelp.co.uk/
Attachment:
pgpP7cVdVbGs3.pgp
Description: PGP signature