RE: [PATCH] docs pages containing are sometimes too wide

[Conal Tuohy <co...@paradise.net.nz>]

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

Re: [PATCH] docs pages containing are sometimes too wide

[Joerg Heinicke <jh...@virbus.de>]

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 
possible
 >>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="http://apache.org/cocoon/directory/2.0" 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 
http://www.w3.org/Style/CSS/ (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

<pre>
   <root>
     <child>
     </child>
   </root>
</pre>

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

with

<p class="pre">
   <root><br/>
     <child><br/>
     </child><br/>
   </root><br/>
</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 :-)

Joerg