[PATCH] for elements that are too wide

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

Some of the pages in the Cocoon HTML-format documentation are too wide to
display on screen, or print in portrait-orientation on paper, because of
<source> elements with very long lines.

The document2html.xsl stylesheet renders <source> elements as HTML <pre>
elements, which can make the resulting pages too wide to see on screen or
print. A web page that is wider than the screen is a complete bastard to
read - you have to scroll left and right all the time. And printing in
landscape orientation is not very nice either.

The problem is:

1) Browsers usually render <pre> elements in a fixed-width font, which are
always wider than normal fonts.

2) There is no line-wrapping in a <pre> element, so a single long line of
source can make the web page very wide.

The patched stylesheet includes an extra template (and a couple of helper
templates) to render simple <source> elements (i.e. those which contain only
text content) as a <div> containing a sequence of <p> elements. The font
name itself is not specified, so it will generally be a proportional font.
The font size is reduced ("smaller"). The template uses CSS "style"
attributes to retain the original indentation while still allowing for
line-wrapping. A single space of indentation is rendered as a 4pt indent.
Where a line of source wraps, the wrapped part of the line is further
indented by 8pt (i.e. equivalent to 2 spaces). The template also attempts to
keep quoted string literals together on one line, by converting spaces
inside quotes into non-breaking spaces.

This new XSL code treats the content of the <source> element as a single
string, so the old template should be left in place to handle <source>
elements that do contain extra markup. Hence this new code is purely
additional to the existing stylesheet - it doesn't replace anything.

I originally submitted this bugfix to Cocoon but found that of course the
Cocoon docs are now generated with Forrest. So I tracked down the equivalent
stylesheet in Forrest:

xml-forrest/src/core/context/skins/common/xslt/html/document2html.xsl

... and I found it had changed since the Cocoon version. So I'm not sending
the Diff I made for the Cocoon version: instead I'm just enclosing the extra
templates that could be added to this stylesheet. NB: I haven't used Forrest
at all, I don't have it installed, and I'm not in a hurry to do so, and in
fact I subscribed to the list just now, but I would like to fix this little
bug anyway - I hope that the format of this contribution will not be an
obstacle.

Con

RE: [PATCH] for elements that are too wide

[David Crossley <cr...@indexgeo.com.au>]

Conal Tuohy wrote:
> Nicola Ken Barozzi wrote:
> >
> > At some point, we already had a stylesheed that broke the
> > source tag in
> > many, but it used too much memory so we disabled it.
> 
> This template doesn't seem to use too much memory (I've not
> had any problems with it) ...

Thanks Con, i will try to apply your contribution today.
--David

RE: [PATCH] for elements that are too wide

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

Nicola Ken Barozzi wrote:

> Conal Tuohy wrote:
>
> > Some of the pages in the Cocoon HTML-format documentation
> are too wide to
> > display on screen, or print in portrait-orientation on
> paper, because of
> > <source> elements with very long lines.

> ...

> At some point, we already had a stylesheed that broke the
> source tag in
> many, but it used too much memory so we disabled it.

This template doesn't seem to use too much memory (I've not had any problems
with it) and though I haven't seen the template you disabled, I suspect my
template does less than the template you disabled: it does NOT actually
break lines of source: it merely transforms lines which are already
delimited by line-break characters into HTML paragraphs. However, by
transforming each line into a paragraph, it does allow the browser to wrap
lines which are very long. In order to prevent the browser making such
line-breaks within string literals, the template replaces spaces in string
literals with non-breaking spaces. So XML attribute values, and Java string
constants won't be broken by the browser.

> The fact is that wrapping is dependant on the language used, so it
> should really be done by a real parser. This means that IMHO it's
> correct to keep <pre> as is for default.

Although this template is not a sophisticated parser, it does in fact do a
reasonable job with both XML and Java source. I wrote it with both of these
in mind, particularly XML, since the particular itch I was scratching was
the Cocoon documentation, which is full of very wide sitemap etc snippets.
Generally line breaks are not significant in Java, but as it stands, this
template would allow a browser to wrap a Java // comment if it was very
wide, which would look wrong, I concede. Maybe I could adjust it to handle
// comments as well ...

On the other hand, if people copy and paste from an HTML page generated from
the template, the long lines would still exist  since they would still exist
as HTML paras.

> What should instead be done, is that this kind of source, for example:
>
>   <source type="java">
>     import...
>     class...
>   </source>
>
> gets transformed in highlighted java code. If someone does a
> patch for
> this, I'll insert it in Forrest in no time :-)

I realise that the <source> element could enclose any kind of source ... and
I'm reluctant to write a full Java parser in XSLT :-)

XML is a different story though: perhaps if I changed it to "sniff" XML
content in the source then it would be suitable? Perhaps:

<xsl:template match="source[starts-with(.,'&lt;') or @type='xml']">

I would even add XML highlighting to the template if that would make it
acceptable.

Cheers

Con

Re: [PATCH] for elements that are too wide

[Nicola Ken Barozzi <ni...@apache.org>]

Conal Tuohy wrote:

> Some of the pages in the Cocoon HTML-format documentation are too wide to
> display on screen, or print in portrait-orientation on paper, because of
> <source> elements with very long lines.
...
> The patched stylesheet includes an extra template (and a couple of helper
> templates) to render simple <source> elements (i.e. those which contain only
> text content) as a <div> containing a sequence of <p> elements. The font
> name itself is not specified, so it will generally be a proportional font.
> The font size is reduced ("smaller"). The template uses CSS "style"
> attributes to retain the original indentation while still allowing for
> line-wrapping. A single space of indentation is rendered as a 4pt indent.
> Where a line of source wraps, the wrapped part of the line is further
> indented by 8pt (i.e. equivalent to 2 spaces). The template also attempts to
> keep quoted string literals together on one line, by converting spaces
> inside quotes into non-breaking spaces.

At some point, we already had a stylesheed that broke the source tag in 
many, but it used too much memory so we disabled it.

The fact is that wrapping is dependant on the language used, so it 
should really be done by a real parser. This means that IMHO it's 
correct to keep <pre> as is for default.

What should instead be done, is that this kind of source, for example:

  <source type="java">
    import...
    class...
  </source>

gets transformed in highlighted java code. If someone does a patch for 
this, I'll insert it in Forrest in no time :-)

For a hint, there is a highlighter example in Cocoon CVS already IIRC, 
with Chaperon (that Forrest already uses for the Wiki Format).

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------