Here's another one for all us consistency freaks:
The "Syntax" entry in the directive definitions is all
over the map at the moment.
For example, all three of these directives have the same syntax,
but they are specified differently:
Syntax: AuthAuthoritative < on(default) | off >
Syntax: ContentDigest on|off
Syntax: RewriteEngine {on,off}
So, here is a proposal for a style-guide entry on directive Syntax (for an
as-yet non-existent style guide):
<p>The syntax entry contains the name of the directive followed by its
arguments. Optional arguments are enclosed in square brackets. Where an
argument may take more than one possible value, the options should be
separated by a vertical bar "|" with no space on either side of the
bar.</p>
<p>Where the syntax specifies literal text, this should be in an ordinary
font. Text defining the "type" of argument (such as <em>filename</em> or
<em>url</em>) should be emphasized. If at all possible, the type should
be a single, simple word, which should be further defined in the directive
definition. If the type must be more than one word, the words should be
joined by dashes. Arguments are separated by spaces, so there should
never be a space in the definition of an argument.</p>
<p>Directives which take a variable number of arguments should repeat the
variable argument twice, with the last argument enclosed in square
brackets to indicate that it is optional, and three dots at the end of the
line.</p>
<p>Samples:</p>
<blockquote>
Syntax: SampleDirective1 <em>MandatoryArg</em> [<em>OptionalArg</em>]<br>
Syntax: SampleDirective2 on|off|default<br>
Syntax: SampleDirective3 <em>hostname</em> [<em>hostname</em>] ...
</blockquote>
Comments welcome.
Joshua.
