cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Conal Tuohy <con...@paradise.net.nz>
Subject RE: [PATCH] docs pages containing <source> are sometimes too wide
Date Sun, 09 Nov 2003 18:57:57 GMT
First I want to say "thanks" to David for putting the "text-wrap" sample
together.

> ------- Additional Comments From joerg.heinicke@gmx.de
> 2003-11-09 01:58 -------
> Sorry for being destructive, but I do not see a real problem.
> Or better said
> this problem resulting from trying to handle all types of
> using <source> is to
> complex and I would not do it.

Agree.

> I had no look on the code, only on the samples, where David
> shows the possible
> use cases - and these are really extreme samples :-)

<there-are-some-funny-examples-there-alright-no-doubt-about-it/>

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

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="http://apache.org/cocoon/directory/2.0" and in a fixed-width
font these are much wider than they need to be.

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.

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.

NB the same long lines are in the PDF version of the docs too, see
http://cocoon.apache.org/2.1/userdocs/concepts/modules.pdf


Mime
View raw message