directive "syntax"

[Joshua Slive <sl...@finance.commerce.ubc.ca>]

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.

Re: directive "syntax"

[Rodent of Unusual Size <Ke...@Golux.Com>]

Chris Pepper wrote:
> 
> >Note also that there is already a Default definition that appears with
> >each directive, so it is not necessary to specify the default in the
> >Syntax definition.
> 
> I like having the Default also visible in the Syntax section,
> and suggest that the default value always appear first.

I disagree.  In some cases the default isn't a keyword but a
value.  And in those cases where it's a keyword, the order
can look funky:

Syntax: DirOne on|off
Syntax: DirTwo off|on

I prefer that the syntax list things in a canonical order.
-- 
#ken    P-)}

Ken Coar                    <http://Golux.Com/coar/>
Apache Software Foundation  <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed"   <http://ApacheUnleashed.Com/>

Re: directive "syntax"

[Chris Pepper <pe...@mail.reppep.com>]

At 9:45 PM -0500 2000/12/04, Rich Bowen wrote:
>Joshua Slive wrote:

>  > <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>

>Note also that there is already a Default definition that appears with
>each directive, so it is not necessary to specify the default in the
>Syntax definition.

	I like having the Default also visible in the Syntax section, 
and suggest that the default value always appear first. In other 
words, if WhackyDirective defaults to on, Syntax would be:

Syntax: WhackyDirective on|off<br>

	If off is the default, that should go first. I'd like the 
defaults bold too, but that might be too busy.


						Chris

-- 
Chris Pepper     | Shooting Gallery Interactive | 212 905-2200
Mac OS X Software:   <http://www.mosxsw.com/>

Re: directive "syntax"

[Rich Bowen <rb...@rcbowen.com>]

Joshua Slive wrote:
> 
> Here's another one for all us consistency freaks:
...
> <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>

I'm definately in favor of this. This has long been a source of
irritation for me. These are reasonable, and pretty standard, ways of
specifying these things.

Note also that there is already a Default definition that appears with
each directive, so it is not necessary to specify the default in the
Syntax definition.

Rich
-- 
Rich Bowen
Author: Apache Server Unleashed - www.apacheunleashed.com
Director of Web Application Development - http://www.cre8tivegroup.com/