Hi,
The Application Server convention of using
<replaceable>default-value</replaceable> in the Synopsis section of man pages
has led to bugs against several man pages.
Although the text is formatted as a placeholder in the PDF and html, the text is
unformatted when asadmin command --help is run. The bugs indicate that there is
a hardcoded value for the option when there shouldn't be. For an example bug,
see
http://monaco.sfbay/detail.jsf?cr=6535959.
This convention is a deviation from man-page style, where only genuine
placeholders are used in <replaceable> in synopsis.
Should the doc group replace the default values in the synopses with placehoders
(for example [--acceptorthreads acceptor-threads])?
I understand that this convention is based on a UIRB recommendation. Can anybody
remember the details of this recommendation, or point me to the UIRB opinion
that contains this recommendation?
If we agree to conform with man page style, the doc group would make the
following changes for all the App Server man pages:
- Reserve <replaceable> in synopses for placeholders.
- Replace all deafult values in synopses with placeholders.
- State the default in the description.
For consistency with the man pages, command usage text might also have to be
modified.
Perhaps we could discuss this issue further at Monday's Admin I-Team meeting.
Thanks.
--
Paul Davies, Senior Technical Writer, Sun Microsystems, Inc.
http://blogs.sun.com/techscribe/