httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Daniel Gruno <rum...@cord.dk>
Subject Re: Syntax Highlighting
Date Wed, 25 Apr 2012 10:26:52 GMT
On 25-04-2012 12:13, Igor Galić wrote:
> 
> We had some discussion on IRC, and Daniel fixed up a test with
> syntax highlighting for Configuration sections. Rich suggested
> we keep it with the bluish grey that we've trained people to
> look for. The outcome is this:
> 
>   http://www.humbedooh.com/apache/perf-scaling.html.en#Caching%20Content
> 
> It looks very nice and subtle.
> 
> I would like to suggest we apply it to existing configs.
> 
> This is also a good chance to revisit our configuration examples
> to follow our own best-practices :)
> 
> So long,
> 
> i
> 
+1 to this!

First off, since this is done via JavaScript, people that do not like it
can simply turn off JS on httpd.a.o and it won't bother them, so that's
a good thing compared to making it permanent inside the html code.

Secondly, it makes (for my part at least) the configurations easier to
read, since we have tweaked the lexer to recognize valid httpd
directives and enclosures. When looking at the example you linked, and
comparing it to the original, there is no doubt in my mind, that -
regardless of what people might think of the colors used - it is far
easier to read the configuration that is styled than the plain text version.

Thirdly, as pointed out by wrowe on IRC, this may also be a good
incentive to write properly formed configuration examples, as the better
they are written, the better they will be styled. As an example, using
quotation marks around a path in a directive will make it stand out as a
string literal, which will both be easier to distinguish as well as a
good practice for especially porting examples to Windows, where there is
often a space or two in the paths, which would require quotations. For
instance, _DocumentRoot "/foo/bar/baz"_ would be preferable to
_DocumentRoot /foo/bar/baz_ as the former can be ported to systems where
the path might be "/some spaces/here and there/apache".


Finally, it means we can get rid of all the <indent> and <br/> code in
our examples, which will make editing (especially C/Lua/Perl source
code) a whole lot easier.

So, to conclude, I'm all for us trying this out.

With regards,
Daniel.


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org


Mime
View raw message