Bug 57819 - Need a conventions document
Summary: Need a conventions document
Status: NEW
Alias: None
Product: Apache httpd-2
Classification: Unclassified
Component: Documentation (show other bugs)
Version: 2.5-HEAD
Hardware: All All
: P2 normal (vote)
Target Milestone: ---
Assignee: HTTP Server Documentation List
Depends on:
Reported: 2015-04-15 20:38 UTC by Rodent of Unusual Size
Modified: 2015-04-15 21:06 UTC (History)
0 users


Note You need to log in before you can comment on or make changes to this bug.
Description Rodent of Unusual Size 2015-04-15 20:38:23 UTC
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..
Comment 1 Rodent of Unusual Size 2015-04-15 21:06:54 UTC
Oh, and come up with (and use) some consistent argument-type keywords, like

* FILE-PATH (and describe in the user conventions that these are ServerRoot-
  relative if not absolute)
* KEYWORD (like "temp", "permanent", "ExecCGI", ...)
* GLOB (do we have anything that does this?)
* IDENTIFIER (like the name given to a rewrite map specification)
* URL (local or full)

There should be a way of indicating that an argument can interpolate
variables or regex group values, such as the first argument to RewriteCond
or the second argument to RewriteRule (or any of the *Match directives).

Noodling in the bug report..