Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: Apache: Docs

Syntax Highlighting

 

 

Apache docs RSS feed   Index | Next | Previous | View Threaded


i.galic at brainsware

Apr 20, 2012, 5:49 AM

Post #1 of 20 (858 views)
Permalink
Syntax Highlighting

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

--
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic [at] brainsware
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


rumble at cord

Apr 20, 2012, 5:54 AM

Post #2 of 20 (828 views)
Permalink
Re: Syntax Highlighting [In reply to]

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
>
Yes, +1 (heck, +2) to this. Manually highlighting the examples is a pain
in the behind, especially when you make a mistake and you have to do it
all over again because you can't spot where to insert your corrected
lines due to all the <code> clutter.

I've tried looking at the XSLT stuff we use, but I just wound up being
even more confused. If there's anyone out there who can help, please,
please speak up :)

With regards,
Daniel.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


rumble at cord

Apr 24, 2012, 4:31 AM

Post #3 of 20 (822 views)
Permalink
Re: Syntax Highlighting [In reply to]

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 [at] httpd
For additional commands, e-mail: docs-help [at] httpd


rbowen at rcbowen

Apr 24, 2012, 5:04 AM

Post #4 of 20 (822 views)
Permalink
Re: Syntax Highlighting [In reply to]

On Apr 24, 2012, at 7:31 AM, Daniel Gruno wrote:

> 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>

A great big +1 to this in concept. At the very least, worth experimenting with in trunk. However, remember that the build stuff is the same in all branches, so changes affect everywhere.

What other languages are available for syntax coloring? Trying to remember what other examples we might have in the docs. Perl, I expect.

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache


i.galic at brainsware

Apr 24, 2012, 5:31 AM

Post #5 of 20 (821 views)
Permalink
Re: Syntax Highlighting [In reply to]

> What other languages are available for syntax coloring? Trying to
> remember what other examples we might have in the docs. Perl, I
> expect.

httpd.conf syntax hilighting would be a good thing to have.

> --
> Rich Bowen
> rbowen [at] rcbowen :: @rbowen
> rbowen [at] apache

i

--
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic [at] brainsware
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


rumble at cord

Apr 24, 2012, 6:10 AM

Post #6 of 20 (822 views)
Permalink
Re: Syntax Highlighting [In reply to]

On 24-04-2012 14:31, Igor Galić wrote:
>
>> What other languages are available for syntax coloring? Trying to
>> remember what other examples we might have in the docs. Perl, I
>> expect.
>
> httpd.conf syntax hilighting would be a good thing to have.
>
>> --
>> Rich Bowen
>> rbowen [at] rcbowen :: @rbowen
>> rbowen [at] apache
>
> i
>
The specific highlighter I chose (mainly because it is quite lightweight
compared to some other solutions) is SHJS, which also supports well, any
language you may want to highlight. For a specific list, you can view it
at http://shjs.sourceforge.net/ - adding a new language is as simple as
including one of the language files in our documents (
http://shjs.sourceforge.net/lang/ ) and, for example to highlight Perl
scripts, use:
<pre class="sh_perl">
print($foo, $bar);
</pre>

With regards,
Daniel.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


i.galic at brainsware

Apr 24, 2012, 6:20 AM

Post #7 of 20 (822 views)
Permalink
Re: Syntax Highlighting [In reply to]

----- Original Message -----
> On 24-04-2012 14:31, Igor Galić wrote:
> >
> >> What other languages are available for syntax coloring? Trying to
> >> remember what other examples we might have in the docs. Perl, I
> >> expect.
> >
> > httpd.conf syntax hilighting would be a good thing to have.
> >
> >> --
> >> Rich Bowen
> >> rbowen [at] rcbowen :: @rbowen
> >> rbowen [at] apache
> >
> > i
> >
> The specific highlighter I chose (mainly because it is quite
> lightweight
> compared to some other solutions) is SHJS, which also supports well,
> any
> language you may want to highlight. For a specific list, you can view
> it
> at http://shjs.sourceforge.net/ - adding a new language is as simple
> as
> including one of the language files in our documents (
> http://shjs.sourceforge.net/lang/ ) and, for example to highlight
> Perl
> scripts, use:
> <pre class="sh_perl">
> print($foo, $bar);
> </pre>

Cool. Should be easy enough to create our own then.

> With regards,
> Daniel.

i

--
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic [at] brainsware
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


rbowen at rcbowen

Apr 24, 2012, 6:20 AM

Post #8 of 20 (822 views)
Permalink
Re: Syntax Highlighting [In reply to]

>>
> The specific highlighter I chose (mainly because it is quite lightweight
> compared to some other solutions) is SHJS, which also supports well, any
> language you may want to highlight. For a specific list, you can view it
> at http://shjs.sourceforge.net/ - adding a new language is as simple as
> including one of the language files in our documents (
> http://shjs.sourceforge.net/lang/ ) and, for example to highlight Perl
> scripts, use:
> <pre class="sh_perl">
> print($foo, $bar);
> </pre>


So, it doesn't currently support httpd syntax, but could be persuaded to probably. Looking at the code ...

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache


rbowen at rcbowen

Apr 24, 2012, 6:25 AM

Post #9 of 20 (823 views)
Permalink
Re: Syntax Highlighting [In reply to]

On Apr 24, 2012, at 9:20 AM, Igor Galić wrote:

> Cool. Should be easy enough to create our own then.



Yep. Syntax looks pretty simple. Just a bunch of regexes mapped to styles. Should be fairly easy to create a httpd.conf mapping.

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache


nd at perlig

Apr 24, 2012, 6:30 AM

Post #10 of 20 (822 views)
Permalink
Re: Syntax Highlighting [In reply to]

> 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>

I'd prefer a different element on xml side. Like <highlight language="perl">
or <syntax>.
Otherwise I like the javascript solution.

nd

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


rumble at cord

Apr 24, 2012, 7:22 AM

Post #11 of 20 (821 views)
Permalink
Re: Syntax Highlighting [In reply to]

On 24-04-2012 15:30, André Malo wrote:
>> 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>
>
> I'd prefer a different element on xml side. Like <highlight language="perl">
> or <syntax>.
> Otherwise I like the javascript solution.
>
> nd
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe [at] httpd
> For additional commands, e-mail: docs-help [at] httpd
>
The idea of a separate <highlight> tag sounds like a good idea.
I have uploaded some css/js files to the trunk for some testing, and I'm
sending two patches for common.dtd and common.xsl (in the style/ and
style/xsl directories) so people that wish can try out this solution and
give some feedback to the proposition.

The changes will allow for syntax highlighting of C, Perl, Python and
shell scripts using something similar to this:

<highlight language="perl">
print($foo, $bar);
</highlight>

Any new languages we wish to add can be done so dynamically, as the
scripts are loaded according to which languages are put into the
<highlight> tags.

With regards,
Daniel.
Attachments: common.dtd.patch (0.84 KB)
  common.xsl.patch (2.02 KB)


rumble at cord

Apr 24, 2012, 9:15 AM

Post #12 of 20 (819 views)
Permalink
Re: Syntax Highlighting [In reply to]

After hearing some concerns expressed over whether we could include a
GPL3 licensed script in our documentation, I have looked for alternate
solutions, and found a syntax highlighter that it Apache 2.0 licensed.

This requires a small change to the common.xsl file (revert the previous
changed and apply this new patch instead, if you want to try it out),
and two additional files, which I have placed in the trunk (a js and a
css file).

An example of a file built with this new highlighter can be seen at
http://www.humbedooh.com/apache/modguide.html.en#snippets

The syntax is still the same, although this new "test subject" is more
agile and can highlight most code without the need for importing
external language definitions;

<highlight language="c">
static void* foo_function(bar, NULL)
{
printf("Hello, world!");
}
</highlight>

With regards,
Daniel.
Attachments: common.xsl.patch (1.90 KB)


nd at perlig

Apr 24, 2012, 11:06 AM

Post #13 of 20 (821 views)
Permalink
Re: Syntax Highlighting [In reply to]

* Daniel Gruno wrote:

> After hearing some concerns expressed over whether we could include a
> GPL3 licensed script in our documentation, I have looked for alternate
> solutions, and found a syntax highlighter that it Apache 2.0 licensed.

Oh, well.

> This requires a small change to the common.xsl file (revert the previous
> changed and apply this new patch instead, if you want to try it out),
> and two additional files, which I have placed in the trunk (a js and a
> css file).

The patch looks ok, just minor comments from me:

- Please avoid unrelated whitespace changes

+ if (prettyPrint) {

this won't work in case of missing external JS. You need to check for
window.prettyPrint or typeof(prettyPrint)!==undefined.

nd
--
Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook.
Ook! Ook? Ook. Ook? Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook.
Ook. Ook. Ook. Ook. Ook? Ook. Ook! Ook! Ook? Ook! Ook. Ook? Ook. Ook.
Ook. Ook. Ook. Ook. Ook! Ook. Ook! Ook! Ook! Ook! Ook! Ook.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


i.galic at brainsware

Apr 25, 2012, 3:13 AM

Post #14 of 20 (819 views)
Permalink
Re: Syntax Highlighting [In reply to]

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

----- Original Message -----
> * Daniel Gruno wrote:
>
> > After hearing some concerns expressed over whether we could include
> > a
> > GPL3 licensed script in our documentation, I have looked for
> > alternate
> > solutions, and found a syntax highlighter that it Apache 2.0
> > licensed.
>
> Oh, well.
>
> > This requires a small change to the common.xsl file (revert the
> > previous
> > changed and apply this new patch instead, if you want to try it
> > out),
> > and two additional files, which I have placed in the trunk (a js
> > and a
> > css file).
>
> The patch looks ok, just minor comments from me:
>
> - Please avoid unrelated whitespace changes
>
> +    if (prettyPrint) {
>
> this won't work in case of missing external JS. You need to check for
> window.prettyPrint or typeof(prettyPrint)!==undefined.
>
> nd
> --
> Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook.
> Ook! Ook? Ook. Ook? Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook.
> Ook. Ook. Ook. Ook. Ook? Ook. Ook! Ook! Ook? Ook! Ook. Ook? Ook. Ook.
> Ook. Ook. Ook. Ook. Ook! Ook. Ook! Ook! Ook! Ook! Ook! Ook.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe [at] httpd
> For additional commands, e-mail: docs-help [at] httpd
>
>

--
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic [at] brainsware
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


rumble at cord

Apr 25, 2012, 3:26 AM

Post #15 of 20 (821 views)
Permalink
Re: Syntax Highlighting [In reply to]

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 [at] httpd
For additional commands, e-mail: docs-help [at] httpd


mads at toftum

Apr 25, 2012, 5:50 AM

Post #16 of 20 (822 views)
Permalink
Re: Syntax Highlighting [In reply to]

On Wed, Apr 25, 2012 at 10:13:46AM -0000, 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
>
>
Not a fan at all. I'm not too keen on having javascript be part of
rendering the docs and there's a very fine line between config
highlighting and looking like a neon sign. It's not too bad in a larger
section, but I find it less readable on short snippets of only a few
lines. To see what I'm talking about, look at the 3 line snippet at the
end of the section - there I think the color takes up too much
attention.
So my preference would be clearly in favor of only coloring code and if
we must, some of the larger Configuration examples.

vh

Mads Toftum
--
http://soulfood.dk

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


rbowen at rcbowen

Apr 25, 2012, 6:10 AM

Post #17 of 20 (819 views)
Permalink
Re: Syntax Highlighting [In reply to]

On Apr 25, 2012, at 8:50 AM, Mads Toftum wrote:

> there's a very fine line between config
> highlighting and looking like a neon sign.

Yes. This I agree with, and it's why I always cart my .vimrc around with me, because I find many of the default themes to be eye-bleeding-inducing.

Syntax highlighting contributes to understanding, when it's done well, and contributes to overlooking important, but poorly color-coded, parts of the text when it's not done well.

We should tweak the CSS until we arrive at something that is the former - pointing out the different "parts of speech", but not in such a way that it's jarring.

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache


rumble at cord

Apr 27, 2012, 8:28 AM

Post #18 of 20 (821 views)
Permalink
Re: Syntax Highlighting [In reply to]

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-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


DRuggeri at primary

Apr 27, 2012, 7:00 PM

Post #19 of 20 (819 views)
Permalink
Re: Syntax Highlighting [In reply to]

On 4/27/2012 10:28 AM, Daniel Gruno wrote:
> 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.

Do you have a few examples of different highlighters for different
languages?
http://httpd.apache.org/docs/trunk/mod/mod_proxy.html and
http://httpd.apache.org/docs/trunk/mod/core.html ... seem to be great
examples of httpd config highlighting. This. Looks. Awesome.
FWIW, I noticed a little weirdness on mod_proxy.html#envsettings (where
"proxy" seems to be highlighted out of context).

http://httpd.apache.org/docs/trunk/mod/mod_asis.html ... is an HTML
highlighter an option?

--
Daniel Ruggeri


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


rumble at cord

Apr 27, 2012, 11:01 PM

Post #20 of 20 (823 views)
Permalink
Re: Syntax Highlighting [In reply to]

On 28-04-2012 04:00, Daniel Ruggeri wrote:
> Do you have a few examples of different highlighters for different
> languages?
> http://httpd.apache.org/docs/trunk/mod/mod_proxy.html and
> http://httpd.apache.org/docs/trunk/mod/core.html ... seem to be great
> examples of httpd config highlighting. This. Looks. Awesome.
> FWIW, I noticed a little weirdness on mod_proxy.html#envsettings (where
> "proxy" seems to be highlighted out of context).
>
> http://httpd.apache.org/docs/trunk/mod/mod_asis.html ... is an HTML
> highlighter an option?
>
I'm unsure what you mean by different highlighters. If you mean
different types of software, then no - we kind'a had to stick with one
that was licensed with ASL, and the one we picked felt like the best
choice for an all-round highlighting.

If you merely mean how the existing highlighter works with different
languages, then there's plenty of examples in the docs:

Lua: http://httpd.apache.org/docs/trunk/mod/mod_lua.html
Perl: http://httpd.apache.org/docs/trunk/howto/cgi.html#writing
C: http://httpd.apache.org/docs/trunk/developer/modguide.html#snippets

As I probably mentioned, these different languages can be styled
individually, so if anyone feels strongly about a specific style, we can
accommodate that.

As for HTML highlighting, it is possible by simply changing the
<example> in mod_asis.xml to <highlight language="html">, but I'm having
some difficulty building the file after I do that, so I'll have to link
off-site for an example:
http://www.humbedooh.com/apache/mod_asis.html.en

As for the weirdness, I have ironed that out for the moment by making
the lexer a bit stricter when it comes to section directives, but some
further tweaking is still needed, as the httpd config highlights are,
surprise surprise, not part of the standard highlighting feature, so we
had to build that ourselves. I hope this answers your questions, and if
not, just write back and such :)

With regards,
Daniel.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd

Apache docs RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.