On 20-04-2012 14:49, Igor Galić wrote: > > Hey folks, > > for all those who haven't seen them yet, Daniel has started > working on developer documentation: > > http://httpd.apache.org/docs/trunk/developer/modguide.html > > this also contains syntax highlighting. > I'm a sucker for syntax highlighting, mostly because I couldn't > survive without. > > If you've looked at the source code however... > > > https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/manual/developer/modguide.xml > > you'll notice that the current solution is sub-optimal. > There are a lot of syntax-highlighters. enscript being the > first to come to my mind. > > Does someone who know our docs-build system well enough > to modify it so to automagickally highlight <example> > sections? If not, maybe we could organize a session (on > IRC) to do some reverse-engineering. > > In any case, we should document the process or the outcome, > so those coming after us won't be put before the exact same > problems. > > So long, > > i > After some fruitful discussions on IRC yesterday, I have tried out various ways of making syntax highlighting available for our documentation, and I've come across a method of doing so using JavaScript. The results seem to be very good, and before everybody runs away screaming because I mentioned the evil J-word, bear in mind that although this method requires a small fraction of a second to properly display the colors in your browser, it has the advantage of much smaller page sizes on our side, as we won't need to pre-pack our documents with a thousand class tags within each example source code.
I have put up a test of highlighting using JS at http://www.humbedooh.com/apache/modguide.html.en which displays a similar result to what is achieved using the manual highlighting I have previously been using, with the added benefit of smaller size AND no more complaining from the build system that the XML is invalid, provided we adopt the following changes: 1) Modify common.dtd to allow classes inside <pre> tags 2) Modify common.xsl to include the style sheet and scripts used for highlighting the source code examples in our documentation. To create syntax highlighted source code examples, the only requirement would be that you use the following syntax: <pre class="sh_c"> code_goes_here(foo); </pre> As precedent, I can mention that the Apache Pivot project has been using a similar method for a while. I have the necessary patches at the ready, should people find this solution viable. Please do respond with pluses and minuses or whichever response you find appropriate. With regards, Daniel. --------------------------------------------------------------------- To unsubscribe, e-mail: docs-unsubscr...@httpd.apache.org For additional commands, e-mail: docs-h...@httpd.apache.org
