Another attempt at wrapping code lines

[Sylvain Wallez <sy...@apache.org>]

Hi all,

I looked at David's "text-wrap" sample and added another attempt: every 
sequence of two consecutive spaces is replaced by a non-breaking space 
and a regular space.

This keeps the text indentation that would be obtained with a <pre> 
while still allowing line wrapping.

I tried to find a CSS trick to add a mark at the beginning of a 
continuation line, but CSS only has ":first-line" and no ":other-lines".

Please have a look at it, it seems to be to be a good compromise between 
keeping code indentation and readability of wrapped lines.

Sylvain

-- 
Sylvain Wallez                                  Anyware Technologies
http://www.apache.org/~sylvain           http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
Orixo, the opensource XML business alliance  -  http://www.orixo.com

Re: Another attempt at wrapping code lines

[Bertrand Delacretaz <bd...@apache.org>]

Le Samedi, 6 déc 2003, à 14:04 Europe/Zurich, David Crossley a écrit :

> ...Anyway, can you recall your suggestion, Bertrand?

I don't have an ICQ log, but what I suggested was creating a 
transformer to wrap text.

Writing a TextWrappingTransformer which processes configurable element 
names (<pre> for example) might make it easier to do all kinds of 
wrapping, and it can be of general use.

-Bertrand

Re: Another attempt at wrapping code lines

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

Yesterday on IRC for FirstFriday, Bertrand mentioned another
approach to the text wrap issue. However, as a newbie to IRC
i quit the session before responding to that part and lost my trace.
Is there a session log?

Anyway, can you recall your suggestion, Bertrand?

--David

RE: Another attempt at wrapping code lines

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

> -----Original Message-----
> From: Sylvain Wallez [mailto:sylvain@apache.org]
> Sent: Saturday, 15 November 2003 04:57
> To: dev@cocoon.apache.org
> Subject: Another attempt at wrapping code lines

<snip/>

> I tried to find a CSS trick to add a mark at the beginning of a
> continuation line, but CSS only has ":first-line" and no
> ":other-lines".

Hi Sylvain

What about a marker at the start of every line - or is that too intrusive
where (as is usual) there's no wrapped lines at all?

I had a play with your code. I tried one way to indicate wrapped lines by
colour-coding alternate lines light grey. This way if a <code> element is
wrapped then you can see a double-height line (either grey or white). I
don't know that it really works visually though. It looks a bit like that
traditional fan-fold paper with alternate-coloured lines: ugly :-)

But anyway! I updated my dev site to use docnbsp.xsl as modified above.

NB almost all of the <source> in Cocoon's docs is markup, for which I'm
using the syntax-highlighting template, and of the remaining <source>
elements, almost all of them are really narrow, so you have to look hard to
find any wrapped lines. But see the DTD at the bottom of this page for a
wide non-xml source element (esp if you narrow your browser window):
http://203.79.120.217/cocoon212/docs/catalog-test.html

And the installation page has lots of narrow non-xml source:
http://203.79.120.217/cocoon212/docs/userdocs/installation/index.html

And there's always the text-wrap sample with very wide (though less
realistic) data:
http://203.79.120.217/cocoon212/samples/text-wrap/

RE: Another attempt at wrapping code lines

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

Hi Sylvain

I've checked out your new attempt "docnbsp.xsl" and compared with the other
approaches in the text-wrap sample.

Your attempt is definitely superior to the current approach ("no special
handling" in the sample) implemented by raw.xsl, which uses just HTML <pre>.
The raw.xsl often leads to infeasibly long lines, which have the effect of
making the entire web page too wide to print, or view without horizontal
scroll.

Your attempt is also better than the split.xsl result in that it maintains
the original lines of source and allows the browser to break lines where
necessary to fit into the HTML container width. It's more appropriate for
the browser to make decisions on line lengths. If your browser is wide
enough and/or you have a small enough font, then no line break will ever
happen. So you can still copy and paste snippets of source code from the
docs and immediately use it (this is important in my opinion).

So I think docnbsp is the best candidate for a detault <source>-handling
template.

The part of the text-wrap sample which I did, "wrap2para", uses a similar
approach to yours in that it retains each line of the original source (as
HTML <p>...</p>, rather than as <code>...</code><br>, but pretty similar).
My xsl also replaced all spaces inside double-quotes with &nbsp; to prevent
the browser wrapping inside quoted strings, which is a similar idea. But
others pointed out that to make these decisions optimally you need to know
the type of the <source> e.g. xml, java, etc.

I also think that for <source> containing quoted XML a fixed-width font is
not important, and a variable-width font would be much more readable, as
well as narrower which wwould greatly reduce the need for line-breaks in the
first place. I realise this can't be done in general, because part of the
contract of <source> is that it is generally rendered in a fixed-width font,
but I think if it can be made to apply only to e.g. XML or Java, then it
would be OK.

I've also been working on another template, based on wrap2para, which only
matches <source> elements which start with &lt; and ends with &gt;, and then
adds XML syntax highlighting. I'll merge and upload a patch shortly. It uses
a FSM in XSLT to parse the quoted XML markup. I've got it running on my
machine at home in the meantime, installed as the stylesheet driving the
Cocoon docs, so it handles everything under:

http://203.79.120.217/cocoon212/docs/index.html

Take a look! I haven't checked every page, but it works for the ones I've
read, and in particular, it's a big improvement for the modules page which
was really wide:

http://203.79.120.217/cocoon212/docs/userdocs/concepts/modules.html

... but I think it's more readable and better even for the narrow <source>.
I like syntax highlighting :-)

So my suggestion is, that we should make your docnbsp.xsl the default source
handler, and my highlightmarkup.xsl the handler specifically for source
containing XML.

Any other types of source should also be dealt with by more specific
stylesheets. Nicola Ken Barozzi suggested a syntax highlighter for Java on
the Forrest list, but I was more keen to do XML first since the "itch" that
I was scratching was precisely the Cocoon docs, which have mostly
XML-flavoured <source>; sitemap snippets, xslt, basically every kind of xml
namespace... I think Java would be only about the same complexity though:
for highlighting, say, comments, keywords, strings, numbers, and punctuation
symbols. It's not necessary to do a deep parse, just a simple tokenising
really.

Cheers

Con

> -----Original Message-----
> From: Sylvain Wallez [mailto:sylvain@apache.org]
> Sent: Saturday, 15 November 2003 04:57
> To: dev@cocoon.apache.org
> Subject: Another attempt at wrapping code lines
>
>
> Hi all,
>
> I looked at David's "text-wrap" sample and added another
> attempt: every
> sequence of two consecutive spaces is replaced by a
> non-breaking space
> and a regular space.
>
> This keeps the text indentation that would be obtained with a <pre>
> while still allowing line wrapping.
>
> I tried to find a CSS trick to add a mark at the beginning of a
> continuation line, but CSS only has ":first-line" and no
> ":other-lines".
>
> Please have a look at it, it seems to be to be a good
> compromise between
> keeping code indentation and readability of wrapped lines.
>
> Sylvain
>
> --
> Sylvain Wallez                                  Anyware Technologies
> http://www.apache.org/~sylvain           http://www.anyware-tech.com
> { XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
> Orixo, the opensource XML business alliance  -  http://www.orixo.com
>
>
>