cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "von Schwerdtner, Thomas (GXS, FPI)" <Thomas.vonSchwerdt...@gxs.ge.com>
Subject [docs] Suggestions about <pre></pre> and/or <code></code> in the docs
Date Thu, 04 Apr 2002 14:58:38 GMT
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


Mime
View raw message