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.
Moreover directives values have strong emphasis in the original
documentation, but no emphasis at all in the english documentation.
Lastly, the RestructuredText pages formatted by MoinMoin are not very
good.
http://wiki.codemongers.com/NginxNgxWSGIModule
Maybe the documentation format should be more “standardized”.
Thanks Manlio P.
On Sun, 2008-01-06 at 15:31 +0100, Manlio P. wrote:
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 
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
Cliff W. ha scritto:
done on the wiki. Neither of these sounds like a quick undertaking.
single formatting engine rather than supporting a mashup of everyone’s
favorite.
Right, this is the best solution.
But, is this possible using a wiki?
Or should we create a documentation repository, and then generate the
html pages from that?
This documentation repository can be integrated with future
documentation about nginx internals.
Cliff
Manlio P.