https://bz.apache.org/bugzilla/show_bug.cgi?id=57819
Bug ID: 57819
Summary: Need a conventions document
Product: Apache httpd-2
Version: 2.5-HEAD
Hardware: All
OS: All
Status: NEW
Severity: normal
Priority: P2
Component: Documentation
Assignee: [email protected]
Reporter: [email protected]
We should have a document that defines conventions for the documentation, and
then apply & follow it. For example, in some places <em> is used where <var>
occurs elsewhere; occasionally <strong> appears *inside* code segments, "<br
/>" sometimes appears in code blocks, etc.
I suggest we come up with conventions patterned after those already pioneered
by books (like O'Reilly), or man pages, or *some*thing.
We probably need two documents: one for the documentation writers
defining how stuff should be written, and one for users explaining
how to interpret styles in the documentation.
* Distinguish between keywords and arbitrary user-supplied text;
* What arguments should be quoted? (I vote for filesystem paths,
URLs, AuthName values, and regexes..) Sometimes it's unclear when
quotation marks are optional, recommended, or required -- and when
they're illegal (think RAW_ARGS directive arguments).
* When to use <em> as opposed to <var>.
* Consistent indentation.
This is just a start..
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
