cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joerg Heinicke <>
Subject Re: [PATCH] docs pages containing <source> are sometimes too wide
Date Tue, 11 Nov 2003 19:58:11 GMT
Answering David's and Conal's mails in one mail:

On 09.11.2003 04:34, David Crossley wrote:

 >>I had no look on the code, only on the samples, where David shows the 
 >>use cases - and these are really extreme samples :-)
 > They are deliberately extreme to ensure that the bugs get triggered.
 > Did i go overboard?

No, nothing bad. Only *impressive* :-)

 >>It's almost not possible to handle both indenting and line length for 
every type
 >>of source. IMO we should simply replace the <pre>s with some simple 
<p>s and
 >>replace the line breaks in the text nodes of the <pre>s with <br>s -

this way we
 >>do it in our intranet. The layout is up to the browsers.
 > The problem is that that is going to break a lot of existing websites,
 > because they probably rely on the current behaviour of <source>
 > rendering.

In which way breaking them? The possible fix is only about additional 
linebreaks, everything else stays the same. But, yes, while writing 
this, the styling could change, because they don't style this paragraphs 
like pre's. I would add a class="pre" or similar.

On 09.11.2003 19:57, Conal Tuohy wrote:

>>It's almost not possible to handle both indenting and line
>>length for every type of source.
> Absolutely true.
> We just need XSLT templates to handle specific types of <source>. I don't
> think it's too hard for a type-specific template to recognise it's own
> flavour of <source>, and the actually existing <source> template can handle
> anything else.

Sounds good in general.

> The DTD says that <source> is normally displayed in a fixed-width font, so
> in general I think authors have the right to expect <pre>. But for sitemap
> snippets etc. this is really not good, because there are long class-names
> like org.apache.cocoon.generation.WebServiceProxyGenerator and attributes
> like xmlns:dir="" and in a fixed-width
> font these are much wider than they need to be.

Here I don't go with you. Reading sources in non-fixed-with fonts (how 
are they called? proportional?) is a pain IMO. But of course we can 
provide alternative stylesheets and the user can select them as at (in Mozilla: View > Use Style > ...).

> The wrap2para.xsl which I wrote was originally for Cocoon's docs in which
> the <source> elements almost always contain representations of XML markup. I
> think it does a reasonable job of that, though it could of course be
> improved.

Eh, did I miss something or what is wrap2para.xsl? At the bug there is 
only a patch to document2html.xsl.

> But it turned out that <source> has a wider applicability than I realised.
> My suggestion is clearly no good for the "ascii-art" example of a
> file-system hierarchy. That kind of <source> requires a fixed-width font,
> and the current templates are fine for that.
> So I plug for the "sniff content" option, and
> 1) for <source> which is xml/html/dtd use wrap2para.xsl
> 2) for everything else use the actually existing stylesheet (i.e. pre)
> I don't think there's much need for split.xsl, but it could be used for (2)
> where I guess it would usually produce the same output, and would
> occasionally have to split a long line.
> Potential enhancements would be:
> For XML:
> Allow browser to wrap lines only in the whitespace inside element tags.
> Syntax highlighting of elements and attributes.
> For Java:
> Prevent line-wrapping in //-style comments.
> Syntax highlighting for string literals, operators, comments, etc.

The problem I see is that there is no structured content. It's only 
text. You always have to parse that stuff. Isn't it exaggerated?

I suggest replacing


(elements inside <pre> must be escaped of course)


<p class="pre">

(elements from above must be escaped, <br/>s not.)

So you have normal text flow and must only scroll vertical if there is 
an attribute="reeeeeeeaaaaaaallllllllyyyyyyllllllloooooonnnnnnnggggggg" 
or something similar.

The above is really simple and a light weight solution. But it's 
additionally support to committer's ability to forget the line legnths :-)


View raw message