Subject: Re: Proposal: syntax highlight in html manual
From: Peter Eisentraut <peter_e@gmx.net>
To: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Cc: pgsql-docs@postgresql.org
In-Reply-To: <BANLkTi=C=-zur9gxi75o45Mq38dBsf4Bvw@mail.gmail.com>
References: <BANLkTi=C=-zur9gxi75o45Mq38dBsf4Bvw@mail.gmail.com>
Content-Type: text/plain; charset="UTF-8"
Date: Wed, 13 Apr 2011 21:34:48 +0300
Message-ID: <1302719688.11858.2.camel@vanquo.pezone.net>
Mime-Version: 1.0
Content-Transfer-Encoding: 7bit

On ons, 2011-04-13 at 11:31 +0100, Daniele Varrazzo wrote:
> If there is, I think the rendering should be performed as a
> post-processing step on the html output and should be a totally
> optional phase: we may do it for the website but have the docs
> generation not to fail if the tools (python, pygments) are missing.
> There would be the need to tag every snippet in the docs with the
> correct language: I think the correct way is to use the "role"
> attribute in the docbook tags generating the snippets (screen,
> programlisting, synopsis...): its value can be propagated to the html
> (e.g. as a css class) using a suitable docbook configuration (see
> <http://www.sagehill.net/docbookxsl/HtmlCustomEx.html#CustomClassValues>,
> albeit a test I've done in that direction failed - but I'm completely
> clueless about debugging the docbooc tool chain).

I guess the verdict is that we shouldn't do it by default, but what we
could do anyway is language tag the code as you describe.  Then users
could either hook in client-side Javascript to do the highlighting or
whoever wants to can produce an alternative colorful pygments-based
version.