As some of you may have noticed, there has been quite a lot of traffic
in commits@ these past few days. We have been testing out the new syntax
highlighting feature, and decided to give it an actual go, rolling out
highlighting for the entire trunk. The response has been quite positive,
and we (Rich, Igor, myself and others who have responded on IRC, Twitter
and other non-docs@ sources) are confident that this is a big boost in
user friendliness.
This email is to describe the changes that have been going on:
1) We have added a syntax highlighter in JavaScript, making it possible
to disable the highlighting by simply disabling JavaScript for
httpd.a.o. The files added for this are prettify.js, an ASL highlighter
which has been heavily modified by us to accommodate our needs and
prettify.css, which takes care of the CSS requirements and allows us to
style each language (C, Perl, Lua and Apache Config) separately.
2) A new tag has been added to the XSLT system called <highlight>. To
enable highlighting of a configuration example, all you need to do is
write, for example:
<highlight language="config">
NameVirtualHosts *:80
</highlight>
To make an example with a title, you can nest highlights within
<example> tags like so:
<example>
<title>Title goes here</title>
<highlight language="config">
DocumentRoot "/foo/bar"
</highlight>
</example>
Please note that this translates into a <pre> tag, so it does not nest
within already existing <pre> tags. Also, as this is a <pre> tag, code
should not have leading spaces unless you need to show nesting of code,
as this will not translate pretty (at least not yet). You can review the
XML changes to see exactly what is meant by this.
3) All valid httpd directives are known by this new highlighting system,
which also makes for an easy way to spot mistyped directives in your
examples.
4) To the best of my knowledge, all documents in trunk have been updated
to use the new <highlight> tag instead of the old combinations of
<example>, <pre>, <code> or whichever system was being used on a
specific page. The various <indent> and <br /> tags have similarly been
removed, leaving leaner and easier to edit examples. And should we
decide to revert some or all of the highlighting, we can simply disable
the JavaScript for those portions and everything will look like it did
before.
I hope you will all check out these changes to our documentation, and
give it some time to sink in. I know that these changes may seem like a
big change to some of you, but I assure you that we only have the best
intentions for our users in mind when we do major overhauls like this,
and even though something has been out there for 10 years, it can still
be in need of an update now and then :).
So, check it out, give some feedback and let's see where the wind takes us.
With regards,
Daniel.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscr...@httpd.apache.org
For additional commands, e-mail: docs-h...@httpd.apache.org
