Re: [Chicken-users] Centralized documentation
> 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: > > > XML > > > Edit > > Agreed. :-) > 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. Right. > 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 ..., 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. Agreed. > 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. Yes, at some point we should definitely do this. > 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. Right. Good idea. > 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. Right. Good point. > You're welcome. I hope I managed to convince you of the use of > semantically correct HTML and to use it in svnwiki. You certainly did, I agree with all the points you raised. At some point I will start cleaning up the HTML we produce, probably with the generate-backwards-compatible-markup flag you propose. Thank you for your message. Alejo. http://azul.freaks-unidos.net/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Centralized documentation
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:
> >
> >
> > XML
> >
> >
>
> The 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 , 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:
>
> >
> >
> > XML
> >
> >
> > Edit
> >
> > ...
> >
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:
XML
Edit
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 ..., 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 #99. */
> > #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
Re: [Chicken-users] Centralized documentation
On 2/20/07, Alejandro Forero Cuervo <[EMAIL PROTECTED]> wrote: > >I've spent a couple of hours hacking the CSS. The result can be viewed > >at http://frohike.homeunix.org/stream-wiki.html > >Feel free to snarf the CSS and plug it in the current wiki. > > I like this quite much. Alejandro, would this be acceptable to you? Absolutely; I like it as well. I just replaced the previous common-css with this one. Excellent. Thanks, Alejandro! cheers, felix ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Centralized documentation
> I've spent a couple of hours hacking the CSS. The result can be viewed
> at http://frohike.homeunix.org/stream-wiki.html
> Feel free to snarf the CSS and plug it in the current wiki.
Beautiful. Thanks for the improvement. :-)
> 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.
> A small example straight from the source:
>
>
> XML
>
>
The 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)?
The , 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:
>
>
> XML
>
>
> Edit
>
> ...
>
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'.
> 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 #99. */
> #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. 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.
Thanks for your suggestions.
Alejo.
http://azul.freaks-unidos.net/
___
Chicken-users mailing list
Chicken-users@nongnu.org
http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Centralized documentation
> >I've spent a couple of hours hacking the CSS. The result can be viewed > >at http://frohike.homeunix.org/stream-wiki.html > >Feel free to snarf the CSS and plug it in the current wiki. > > I like this quite much. Alejandro, would this be acceptable to you? Absolutely; I like it as well. I just replaced the previous common-css with this one. Thanks. Alejo. http://azul.freaks-unidos.net/ Ps: In the future, feel free to CC me directly, as that will get the messages to me faster than just sending them to the list. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Centralized documentation
On 2/14/07, Peter Bex <[EMAIL PROTECTED]> wrote: I've spent a couple of hours hacking the CSS. The result can be viewed at http://frohike.homeunix.org/stream-wiki.html Feel free to snarf the CSS and plug it in the current wiki. I like this quite much. Alejandro, would this be acceptable to you? cheers, felix ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Centralized documentation
On Tue, Feb 13, 2007 at 05:00:27PM -0500, Alejandro Forero Cuervo wrote:
> * Any improvements to the CSS used by the wiki would be more than
> welcome. :-)
I've spent a couple of hours hacking the CSS. The result can be viewed
at http://frohike.homeunix.org/stream-wiki.html
Feel free to snarf the CSS and plug it in the current wiki.
I tried to match the eggdoc default CSS colorscheme. call/cc.org uses
this colorscheme as well.
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.
A small example straight from the source:
XML
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.
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 (bad name since the id of the thing is also an info-box. Classes
should rarely, if ever, shadow ids), 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 #99. */
#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 hope this info helps. But please make your HTML code semantically correct,
worry about targeting it with CSS later. The ids and classes should be
semantically *meaningful*, not simply aids to help you target them in CSS.
If you'd like some more pointers to websites/books to read, let me know.
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
pgp1kSIv0c7ea.pgp
Description: PGP signature
___
Chicken-users mailing list
Chicken-users@nongnu.org
http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Centralized documentation
Just a few thoughts that I believe would be good to keep on mind on the discussion on centralized documentation: * Egg authors have the choice between using eggdoc or using the wiki. Originally all eggs used eggdoc and few started using the wiki as their authoritative repository. * When an egg uses the wiki, whenever a new version of the egg is produced, the HTML page is generated automatically from whatever is in the wiki. This page is uploaded to call/cc as well as included in the tarball * The process of generating the HTML page for an egg from the wiki only supports documentation stored as a single wiki page, but I suppose it would be easy to extend egg-post-commit to support eggs having multiple wiki pages as their associated documentation. * I kinda agree that it doesn't make that much sense to keep a potentially outdated documentation page in call/cc when it is also available in the wiki. Then again, I don't see this as that big an issue, since the pages in call/cc do begin with a disclaimer pointing to the wiki page. * It should be kept in mind that some documentation for the eggs should be included with them. For those with the documentation on the wiki, the best bet is probably to continue to do what we do now (include a render to HTML of whatever is available in the wiki when the egg is generated/uploaded). * Any improvements to the CSS used by the wiki would be more than welcome. :-) There. Alejo. http://azul.freaks-unidos.net/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Centralized documentation
Felix and I have had related discussions. I don't mean to steer the conversation away from the topic (how to do egg documentation) -- but I would like to make sure we move in the direction of making things more coherent and usable. Part of that should be that whatever is decided for egg documentation should be something that will last us a good long while. What I would like to see (and have been working on parts of, ever so slowly in my free time): * Merge callcc.org functionality into call/cc.org layout/content (making both URLs serve the same purpose, either by mirroring or redirection) * Merge the wiki into call/cc.org so that all chicken stuff (except trac) is available at a URL that begins "call/cc.org". (E.g., call/cc.org/wiki perhaps.) * Unify documentation procedures. All of Chicken, including Eggs, should have indexes of their functions/variables/API that are easily machine-readable (a simple alist or something would be nice, or perhaps embed some kind of markup into the wiki, although I cringe at the thought of much xml). Ultimately, all of this would bring Chicken back to one main website, and it would have mostly editable pages and full search ability. The three URLs we have now (call/cc.org, callcc.org, and galinha) would continue to work, but would serve up the same content, thereby allowing us to move to one canonical URL (or perhaps an easy to remember system of mirror URLs, e.g. us1.callcc.org, br1.callcc.org, de1.callcc.org, etc. (Trac would stay sort of separated, but that's fine because most developers are used to a separate "developer" site.) -- Toby Butzon ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Centralized documentation
On 2/12/07, Peter Bex <[EMAIL PROTECTED]> wrote: I was having an e-mail discussion with Mario Domenech Goulart about Spiffy and the conversation turned towards egg documentation. The discussion started because Spiffy's documentation is starting to grow beyond what fits comfortably on one webpage (which is the case at this moment). We both agreed the best place would probably be on the wiki, perhaps like lighttpd does it (http://www.lighttpd.net) I agree that a single place for the docs is the proper thing to do. Zbigniew will probably kill me for this, but if we have the choice between eggdoc and wiki, I prefer wiki, simply in the hope of delegating as much as possible of the work. We also need a better CSS for the egg-documentation that is generated from the wiki format. Any volunteers? And last, but not leasst: svnwiki has to become more reliable. cheers, felix ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Centralized documentation
2007/2/12, Peter Bex <[EMAIL PROTECTED]>: Hi everybody, I was having an e-mail discussion with Mario Domenech Goulart about Spiffy and the conversation turned towards egg documentation. The discussion started because Spiffy's documentation is starting to grow beyond what fits comfortably on one webpage (which is the case at this moment). We both agreed the best place would probably be on the wiki, perhaps like lighttpd does it (http://www.lighttpd.net) Here's the relevant part of the discussion: - Forwarded message from Mario Domenech Goulart <[EMAIL PROTECTED]> - > > > How would [keeping a synched copy of the documentation from the wiki > > > on call/cc.org] work if we use more than one page? > > > > Hmmm. I don't know. I'd expect we'd have an index page (which would > > be copied to call/cc.org's eggs directory) and the links would point > > to galinha. But I don't know if it is the right way. > > What's the point of duplicating the index then? We could just point to > galinha and be done with it. That would be the more atraightforward alternative. > Saves us the trouble of updating the call/cc page every time. Maybe > Felix should think about ditching the egg pages altogether and > simply linking to Galinha as the one and only resource for egg > documentation. It would remove a lot of overhead and duplication, > IMHO. I never liked having two systems which do the same thing > (which is one reason why I despise GNU's policy wrt info pages over > manpages). It confuses me. Where do you look for the most recent > info? Who sees what system as authoritative? Do people think to > update the other version at all? Do some people switch their > standpoint sometime later, changing which system I need to look at? > > This is definitely not good for newbies. They might be scared away in > confusion. You might think this is silly, but if I think it, I'm sure > there are others. I see your point. My guess is that Felix wants to keep the official documentation at call/cc.org. But it's just a guess. We have to ask him. > > Do you think the Spiffy documentation and this documents containing > > tips should be the same? > > It could be a section in the documentation. Since it's a wiki, the nature > of documentation is a lot more volatile. I'm not sure what's best yet. Ok. So let's try to solve the case of the canonical Spiffy documentation in a way we can accomodate further documents in the future. - End forwarded message - What do you think would be the best way to go from here? I really believe one canonical place for documentation is a benefit both for experienced developers as well as for newbies and the documentation maintainers. Having two or more places where documentation can be found or generated (wiki syntax, eggdoc format and plain HTML) causes a lot of confusion and duplication of work. The current situation conveys chaos and disagreement to outsiders, I think. If we want to attract more developers to get more work done (we all agree on that being a good thing), a sane documentation system would go a long way towards at least giving the appearance of a well-engineered and structured project. (Having a ticket tracking system helps similarly and I wish to thank Felix and Arto for setting it up. I agree with Felix that everybody should register a login there) Should eggdoc be deprecated in favor of svnwiki? Should the wiki be deprecated instead? Should we stick with the status quo? (IMHO, no, but I can imagine some people might feel the same about this as about version control systems) Any other ideas would be welcome. 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 Hi, I'm really not aware of the situation but here's two things: Documentation on a wiki is nice to read and for collaboration but if it's sufficiently good to be added to the main doc (which ships with the code/library), it could be ennoying to manage. It would be practical for the maintainers to see some kind of diff between the wiki edited doc and the main doc, although for the reader there's no difference. (From another point of view, wiki pages have to belong to the doc, not to the wiki. If we add a lib or remove it, its doc is automatically added or removed) The fact there's multiple sites must not be a concern for the maintainer. Any sync has to be performed by the sites themselves, thus needing one kind of doc system. Hope it makes sense for the above questions... Cheers, thu ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
[Chicken-users] Centralized documentation
Hi everybody, I was having an e-mail discussion with Mario Domenech Goulart about Spiffy and the conversation turned towards egg documentation. The discussion started because Spiffy's documentation is starting to grow beyond what fits comfortably on one webpage (which is the case at this moment). We both agreed the best place would probably be on the wiki, perhaps like lighttpd does it (http://www.lighttpd.net) Here's the relevant part of the discussion: - Forwarded message from Mario Domenech Goulart <[EMAIL PROTECTED]> - > > > How would [keeping a synched copy of the documentation from the wiki > > > on call/cc.org] work if we use more than one page? > > > > Hmmm. I don't know. I'd expect we'd have an index page (which would > > be copied to call/cc.org's eggs directory) and the links would point > > to galinha. But I don't know if it is the right way. > > What's the point of duplicating the index then? We could just point to > galinha and be done with it. That would be the more atraightforward alternative. > Saves us the trouble of updating the call/cc page every time. Maybe > Felix should think about ditching the egg pages altogether and > simply linking to Galinha as the one and only resource for egg > documentation. It would remove a lot of overhead and duplication, > IMHO. I never liked having two systems which do the same thing > (which is one reason why I despise GNU's policy wrt info pages over > manpages). It confuses me. Where do you look for the most recent > info? Who sees what system as authoritative? Do people think to > update the other version at all? Do some people switch their > standpoint sometime later, changing which system I need to look at? > > This is definitely not good for newbies. They might be scared away in > confusion. You might think this is silly, but if I think it, I'm sure > there are others. I see your point. My guess is that Felix wants to keep the official documentation at call/cc.org. But it's just a guess. We have to ask him. > > Do you think the Spiffy documentation and this documents containing > > tips should be the same? > > It could be a section in the documentation. Since it's a wiki, the nature > of documentation is a lot more volatile. I'm not sure what's best yet. Ok. So let's try to solve the case of the canonical Spiffy documentation in a way we can accomodate further documents in the future. - End forwarded message - What do you think would be the best way to go from here? I really believe one canonical place for documentation is a benefit both for experienced developers as well as for newbies and the documentation maintainers. Having two or more places where documentation can be found or generated (wiki syntax, eggdoc format and plain HTML) causes a lot of confusion and duplication of work. The current situation conveys chaos and disagreement to outsiders, I think. If we want to attract more developers to get more work done (we all agree on that being a good thing), a sane documentation system would go a long way towards at least giving the appearance of a well-engineered and structured project. (Having a ticket tracking system helps similarly and I wish to thank Felix and Arto for setting it up. I agree with Felix that everybody should register a login there) Should eggdoc be deprecated in favor of svnwiki? Should the wiki be deprecated instead? Should we stick with the status quo? (IMHO, no, but I can imagine some people might feel the same about this as about version control systems) Any other ideas would be welcome. 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 pgpOuvHASFJac.pgp Description: PGP signature ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
