httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [Bug 57819] New: Need a conventions document
Date Wed, 15 Apr 2015 20:38:23 GMT

            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

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:
For additional commands, e-mail:

View raw message