Re: [Chicken-users] Centralized documentation

[Peter Bex]

On Tue, Feb 20, 2007 at 02:50:44PM -0500, Alejandro Forero Cuervo wrote:
> Beautiful.  Thanks for the improvement. :-)

You're very welcome.

> > This CSS was prepared on the basis of the original HTML as it was
> > found on the wiki.  I'd give this a huge overhaul, if possible,
> > though.  It's very unsemantic and suffers from a disease
> > webdevelopers call "divitis", which means there are too many
> > DIVs/SPANs thrown in for no reason, or as substitutes for UL/OLs.
> > Also, there is a lot of class abuse.
> 
> I agree with this.  This huge overhaul that you speak of would be very
> welcome.  In fact, it's already started.  But keep reading for some
> disclaimers.

That's good news.

> > A small example straight from the source:
> > <div id="info-box" class="info-box">
> >   <span class="info-box">
> >     <a class="info-box" href="xsvnwiki-atom/stream-wiki">XML</a>
> >   </span>
> > </div>
> 
> The <span> could, *probably*, be removed, but leaving it as it is may,
> perhaps, simplify some tasks (eg. draw some decorations around the
> links that aren't part of the link themselves)?

I agree that the span is needed, and I would keep it like that *if* you
were to keep the div/span, but read on:

> The <div>, on the other hand, surrounds *all* the info-box links, not
> each individual one, as your example implies.  So, IMO, it shouldn't
> be removed.  A more correct example would be:
> 
> > <div id="info-box" class="info-box">
> >   <span class="info-box">
> >     <a class="info-box" href="xsvnwiki-atom/stream-wiki">XML</a>
> >   </span>
> >   <span class="info-box">
> >     <a class="info-box" href="foo">Edit</a>
> >   </span>
> >   ...
> > </div>

You misunderstood my point.  It wasn't about the nesting, it was about the
tags you're using.  It would be more semantically correct to do something
like this:
<ul id="actions">
  <li>
    <a href="xsvnwiki-atom/stream-wiki">XML</a>
  </li>
  <li>
    <a href="foo">Edit</a>
  </li>
</ul>

The id of "info-box" is not very semantic.  There's no info in the info-box!
(it only has links)  The fact that it's a box is only visually correct in
the case of a normal browser.  If you'd use a screenreader or
braille-terminal or simply a non-CSS aware browser, it wouldn't even _be_
a box.  At least, it wouldn't be displayed as such.

It contains a list of actions you can apply to the current page, so a
different id would be better.  Also, since it's a list of things to do,
you would do better to put it in a list.  Observe that the nesting depth
is the same as your <div><span><a>...</a></span></div>, but just by looking
at the HTML (which is supposed to be purely the information you're supplying
and should not include ANYTHING that has to do with how it's presented) you
can see much better what is intended.

There are many bloggers who write about these things.  For an introduction,
see http://www.thefutureoftheweb.com/blog/2006/2/writing-semantic-html
and http://www.clagnut.com/blog/228/

Two great blogs about semantic and proper webdesign (and CSS styling) are:
http://www.456bereastreet.com/
http://www.alistapart.com/

> I agree with your #1 statement:
> 
> > 1) It's pointless to define both a class and an id on the toplevel DIV.
> > Just the id should suffice since there's only one info-box on the page, 
> > ever.
> 
> In
> 
>   http://freaks-unidos.net/azul-home/src/svnwiki/trunk/shared.scm
> 
> you'll find the following comment:
> 
>    ; 'class' attribute is deprecated for unique elements: header, toc-links,
>    ; content-box info-box, content, last-update and credits.  The 'id' 
> attribute
>    ; should be used instead
> 
> We switched from 'class' to 'id' around 2006-06.
> 
> Are you proposing that we break all the CSS files of all svnwiki users
> that relied on the 'class' attributes that were provided previously,
> before svnwiki was changed to using 'id'?
> 
> If that's what you're proposing, I'd say I agree, but I'll do it in
> the future, giving other users of svnwiki that have created their own
> CSS files more time to adapt them to depend on 'id' rather than
> 'class'.

Well, that's what we call "progress" :)
Just up the major version number and tell people clearly about it.
People who work in the web industry would welcome this change with open
arms, I'm sure.

Perhaps an idea is to provide a parameter for backward compatibility, that
injects these pointless classes everywhere you used to have them if it is
set to true, and set it to false by default?  Then phase it out over one
or two major releases.

> > 2) It's pointless to define the same class on all sub-elements of
> > the info-box.  If you're trying to be generic and target all things
> > of class info-box (...), you'll get into trouble because you're
> > actually targeting more than you want to target.
> >
> > 3) If I want to target the inner link, I don't have to have a class to
> > target it:
> > 
> > /* Target the direct descendent of a span which is a direct descendent of
> >    anything with id info-box and give it the color #666699. */
> > #info-box > span > a {
> >    color: #669;
> > }
> > 
> > Or, more generic:
> > 
> > /* Target any descendent (at any level) below anything with an id of 
> > info-box */
> > #info-box a {
> >   color: #669;
> > }
> >
> > 4) If I give the #info-box a font, for example, the span and a will inherit
> > it from the #info-box.  Anything that isn't defined in #info-box is 
> > inherited
> > from its parent, and so on.  (this doesn't apply to link color and
> > text-decoration because links have some sort of special status; they're
> > always colored differently, so you'll have to explicitly target them in CSS)
> 
> I see (2), (3) and (4) as exactly the same issue.

The difference between 2 and 3 is that I thought once you read 2, you'd start
by simply renaming the inner classes to different names.  The fact that these
have the same name (2) means they tangle up your CSS.  The fact that there are
so many of them is just useless since you don't need all those classes (3).
Yes, (4) is more like an explanation of how to do it if you would fix (2)
and (3), since you would lose a lot of handles in your CSS.

> And yes, I agree
> with this: its kinda pointless to use the same class in sub-elements.
> 
> On the other hand, I don't think it hurts.  It certainly didn't
> prevent you from making your CSS and I would think it didn't even make
> it *harder* for you to make it.  Whereas changing this would probably
> break some many CSS files.

It makes the HTML content a big soup of classes and ids, which means the
semantics are hard to obtain from the code.  Also, if I were to define a
styling for, say, any warning message so it has a border, I'd get into
trouble.  Suppose you have this:

<div class="warning">Here are some <em class="warning">important</em>
warnings: <span class="warning">warning 1</span>, <span class="warning">
warning 2</span></div>

Then I could only give the _outer_ warning a border by explicitly saying:

div.warning { border: 1px solid red; }

Then, if you have another page with a paragraph that warns the user about
something:

<p class="warning">This tool comes with absolutely <em class="warning">no
warranty</em> etc etc</p>

I'd have to go back into my CSS and add a new, specific line for this warning:
div.warning, p.warning { border: 1px solid red; }

The whole point of naming _classes_ is that you want to style a whole
CLASS of things that have the same meaning, even if their html happens
to be slightly different.  Ideally, you'd say:
.warning { border: 1px solid red; }

This is of course very much like hardcoding values in your code instead
of defining proper constants.  It's all about maintainability and
genericness.  You describe your information in a format you don't have to
throw away whenever you make a slight change, and you also describe it so
you don't have to throw away the CSS whenever you _add_ something.  The point
is that you style in such a generic way that you never need to touch your
CSS if you keep adding new HTML.  Only when that new HTML needs some extra
styling, you should need to touch the CSS, not when you _don't_ want your
old CSS to apply to this new HTML.

So in conclusion, I'd have to say it wasn't _because_ of the many classes and
ids that I got my CSS to work, but rather _in spite of_ the many classes and
ids.  (but that's just because I had to style even worse HTML markup in
some very popular Content Management Systems we have to use at work)

> Thanks for your suggestions.

You're welcome.  I hope I managed to convince you of the use of semantically
correct HTML and to use it in svnwiki.

Regards,
Peter
-- 
http://sjamaan.ath.cx
--
"The process of preparing programs for a digital computer
 is especially attractive, not only because it can be economically
 and scientifically rewarding, but also because it can be an aesthetic
 experience much like composing poetry or music."
                                                        -- Donald Knuth

pgp0asNDyoANK.pgp
Description: PGP signature