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 Tue, 24 Apr 2012 11:31:44 GMT
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-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org


Mime
View raw message