[dev] syntax to use for documenting directives

[Cliff Wells]

On Sun, 2008-01-06 at 15:31 +0100, Manlio Perillo wrote:
> Hi.
> 
> There seems to be not uniform syntax rules for documenting nginx directives.
> 
> As an example, for the http proxy module we have:
> 
> syntax: proxy_buffering on|off
> syntax: proxy_ignore_client_abort [on|off]
> 
> 
> Since a value is always required, the [] should not be used, IMHO.

Agreed.

> Moreover directives values have strong emphasis in the original 
> documentation, but no emphasis at all in the english documentation.

That's a lot of editing for a rather minor cosmetic change, but I
suppose if someone is removing square brackets from directive values,
then both could be done at once.  

I think you'll notice enough cosmetic differences between Igor's
documentation and the wiki that it's fairly pointless to debate
font-weights :P

> Lastly, the RestructuredText pages formatted by MoinMoin are not very
> good.
> 
> http://wiki.codemongers.com/NginxNgxWSGIModule

This isn't an easy fix at the wiki level: either we change every page on
the wiki to match what the Restructured Text module expects to output,
or we fix the Restructured Text module to output what has been being
done on the wiki.  Neither of these sounds like a quick undertaking.

Another option would be to generate Moin syntax from the Restructured
Text *prior* to inserting it into the wiki.

> Maybe the documentation format should be more "standardized".

I think the informal "by example" way is fine.  We just need reviewers
to make certain that updates follow existing conventions.  

Also, if we want consistent documentation, we should probably stick to a
single formatting engine rather than supporting a mashup of everyone's
favorite.  

Cliff