Hey folks,
In my geeky web browsing, I sometimes come across web pages with code listings that is wide enough to cause horizontal scrolling problems. To be clear, the code listing is preformatted text, so if the line is long enough it widens the table it is in to go beyond the side of the browser window, which causes every paragraph in the page to adjust to that width, which makes each and every line of the content difficult to read.....and impossible to print for that matter (without manual editing)..
Point being, in some cases it is impossible to shorten the preformatted text (I most often see it with anon CSV -d lines, which are often fairly long), and although XML and even Java tend to display a bit "long winded", I think there are a few ways to alter them to make them readable.
(BTW: inspiration for this mail came from http://xml.apache.org/cocoon/developing/sunspot.html )
These are just suggestions (and they aren't foolproof):
1- Indent 2 spaces instead of 4
2- Keep indention consistent
3- Place attributes on separate lines where possible:
<color
formdescription="Hintergrundfarbe"
formpath="sunspotconf.0.0"
formtype="backgroundcolor">#aab9bf</color>
4- Place tag content on separate lines where possible, and where not possible mention why:
<some-tag>
Tag Content
</some-tag>
..instead of: <some-tag>Tag Content</some-tag>
...that's all that comes to mind.
For example, compare the first listing taken from the page, and the second edited for width (note, hopefully this is a plaintext email (Outlook has been giving me grief), if you have a HTML reader the formatting may be lost)
===========================================
<layout-profile>
<portal>
<layouts>
<layout>
<background>
<!-- no wrap on the <color></color> line, its very long -->
<color formdescription="Hintergrundfarbe" formpath="sunspotconf.0.0" formtype="backgroundcolor">#aab9bf</color>
</background>
<font>
===========================================
<layout-profile>
<portal>
<layouts>
<layout>
<background>
<color formdescription="Hintergrundfarbe"
formpath="sunspotconf.0.0"
formtype="backgroundcolor">#aab9bf</color>
</background>
<font>
===========================================
Make sense? Am I being anal?
I don't mean to offend, but I think its important to have readable documentation.
-Tom
