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..
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", ...) * REGEX or PATTERN * GLOB (do we have anything that does this?) * EXPRESSION * 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..
This should go in the https://httpd.apache.org/docs-project/ site, which is mostly still accurate, but is somewhat light on detail, and doesn't make it exactly easy to get started. A style/convention guide would indeed be a very good start to that.