rane 05/10/10 19:11:26
Modified: xml/htdocs/doc/en/articles l-redesign-1.xml
Added: xml/htdocs/doc/en/articles l-redesign-2.xml l-redesign-3.xml
l-redesign-4.xml
Log:
4 new articles from #104015
Revision Changes Path
1.3 +3 -3 xml/htdocs/doc/en/articles/l-redesign-1.xml
file :
http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/articles/l-redesign-1.xml?rev=1.3&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain:
http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/articles/l-redesign-1.xml?rev=1.3&content-type=text/plain&cvsroot=gentoo
diff :
http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/articles/l-redesign-1.xml.diff?r1=1.2&r2=1.3&cvsroot=gentoo
Index: l-redesign-1.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/articles/l-redesign-1.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- l-redesign-1.xml 9 Oct 2005 17:13:23 -0000 1.2
+++ l-redesign-1.xml 10 Oct 2005 19:11:26 -0000 1.3
@@ -1,6 +1,6 @@
<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header:
/var/cvsroot/gentoo/xml/htdocs/doc/en/articles/l-redesign-1.xml,v 1.2
2005/10/09 17:13:23 rane Exp $ -->
+<!-- $Header:
/var/cvsroot/gentoo/xml/htdocs/doc/en/articles/l-redesign-1.xml,v 1.3
2005/10/10 19:11:26 rane Exp $ -->
<guide link="/doc/en/articles/l-redesign-1.xml" disclaimer="articles">
<title>The gentoo.org redesign, Part 1: A site reborn</title>
@@ -24,8 +24,8 @@
document is an updated version of the original article, and contains
various improvements made by the Gentoo Linux Documentation team -->
-<version>1.1</version>
-<date>2005-10-09</date>
+<version>1.0</version>
+<date>2005-10-10</date>
<chapter>
<title>An unruly horde</title>
1.1 xml/htdocs/doc/en/articles/l-redesign-2.xml
file :
http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/articles/l-redesign-2.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain:
http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/articles/l-redesign-2.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo
Index: l-redesign-2.xml
===================================================================
<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/articles/l-redesign-2.xml,v
1.1 2005/10/10 19:11:26 rane Exp $ -->
<guide link="/doc/en/articles/l-redesign-2.xml" disclaimer="articles">
<title>The gentoo.org redesign, Part 2: A site reborn</title>
<author title="Author">
<mail link="[EMAIL PROTECTED]">Daniel Robbins</mail>
</author>
<abstract>
Have you ever woken up in the morning to the realization that your personal
development Web site isn't really that great? If so, you're in good company. In
this series, Daniel Robbins shares his experiences as he redesigns the
www.gentoo.org Web site using technologies like XML, XSLT, and Python. Along
the way, you may find some excellent approaches to use in your next Web site
redesign. In this, the second installment, Daniel shows off the new
documentation system and sets up a daily CVS-log mailing list.
</abstract>
<!-- The original version of this article was first published on IBM
developerWorks, and is property of Westtech Information Services. This
document is an updated version of the original article, and contains
various improvements made by the Gentoo Linux Documentation team -->
<version>1.0</version>
<date>2005-10-10</date>
<chapter>
<title>The doc system</title>
<section>
<body>
<p>
If you've read the <uri link="/doc/en/articles/l-redesign-1.xml">first
installment</uri> of my series on the gentoo.org redesign, then you know that
I'm the Chief Architect of Gentoo Linux, making me responsible for the Gentoo
Linux Web site. And right now, the site leaves a lot to be desired. Yes, it
does look somewhat attractive, but when you look beyond the cute graphics you
will see that it really doesn't serve the needs of its primary target audience:
Gentoo Linux developers, users, and potential users.
</p>
<p>
Last time, I used a user-centric design approach to create a set of priorities
for the site, and then used these priorities to create an action plan for
revamping gentoo.org. Two things were at the top of the priority list: new
developer documentation and a new mailing list to communicate to developers
changes made to our CVS repository. While adding the new CVS mailing list was
relatively easy (though, as you will see, it was more difficult than I
thought), the new developer documentation required a lot of planning and work.
</p>
<p>
Not only did I need to create some actual documentation (a task that I had been
ignoring for too long), but I also had to choose an official XML syntax that
our new master documentation would use. You see, until a few weeks ago, I was
creating the documentation in raw HTML. This was definitely a naughty thing to
do, because by doing this content was being mixed (the actual information) with
presentation (the display-related HTML tags). And what did I end up with? An
inflexible mess, that's what. It was hard to edit the actual documentation and
extremely difficult to make site-wide HTML improvements.
</p>
<p>
In this article, I'll proudly demonstrate the site's new flexible XML
documentation solution. But first, I'll recap my experiences in adding the CVS
log mailing list to our site.
</p>
</body>
</section>
<section>
<title>Adding the CVS log mailing list</title>
<body>
<p>
The goal of the CVS log mailing list is to inform developers of new commits
made to our CVS repository. Since I already had the mailman mailing list
manager (see <uri link="#resources">Resources</uri>) installed, I thought that
creating this new list would be easy. First, I would simply create the mailing
list, then add the proper "hook" to the CVS repository so that e-mails would be
automatically generated and sent out, describing the changes to our sources as
they happened.
</p>
<p>
I first started researching a special file in my repository's CVSROOT called
"loginfo." Theoretically, by modifying this file, I could instruct CVS to
execute a script when any commit (and thus, modification) was made to the
repository. So I created a special loginfo script and plugged it into my
existing repository. And it did indeed send out e-mails to the new "gentoo-cvs"
mailing list whenever modifications were made to our sources.
</p>
<p>
Unfortunately, this solution wasn't all I'd hoped it would be. First of all, it
generated lots of e-mail messages -- one for each modified file -- and
secondly, the messages were cryptic and sometimes even empty! I quickly removed
my loginfo script and put the gentoo-cvs mailing list project on hold. It was
clear that CVS's loginfo hook wasn't appropriate for my needs, and I had a hard
time tracking down any loginfo-related documentation that could help me solve
my problem.
</p>
</body>
</section>
<section>
<title>cvs2cl.pl</title>
<body>
<p>
Several weeks later I started looking for an alternative to loginfo. This time
I did the smart thing and headed over to <uri>http://freshmeat.net</uri>. There
I quickly found just what I was looking for: the incredibly wonderful
<path>cvs2cl.pl</path> perl script available from
<uri>http://red-bean.com</uri> (see <uri link="#resources">Resources</uri>).
Instead of using the loginfo hook, <path>cvs2cl.pl</path> uses the <c>cvs
log</c> command to connect directly to the repository and extract the
appropriate relevant log information. Also, rather than spitting out relatively
cryptic CVS log messages, it does a great job of reformatting everything into a
readable ChangeLog format:
</p>
<pre caption="Output generated by cvs2cl.pl">
2001-04-09 20:58 drobbins
* app-doc/gentoo-web/files/xml/dev.xml: new fixes
2001-04-09 20:47 drobbins
* app-doc/gentoo-web/: gentoo-web-1.0.ebuild,
files/pyhtml/index.pyhtml, files/xml/gentoo-howto.xml: new gentoo-howto
fixes
2001-04-09 20:03 drobbins
* app-doc/gentoo-web/files/xml/dev.xml: typo fix
2001-04-09 20:02 drobbins
* app-doc/gentoo-web/files/pyhtml/index.pyhtml: little update
</pre>
<p>
<path>cvs2cl.pl</path> can also be instructed to generate output in XML format,
and in my next article I'll take advantage of this by incorporating an
up-to-date ChangeLog into the new developer section of our site.
</p>
</body>
</section>
<section>
<title>The cvslog.sh script</title>
<body>
<p>
Here's the script I now use to generate the daily ChangeLog e-mails. First, it
changes the current working directory to the location of my checked-out CVS
repository. Then, it creates $yesterday and $today environment variables that
contain the appropriate dates in RFC 822 format. Notice that both date
variables have the time set to either "00:00" or midnight. These variables are,
in turn, used to create a $cvsdate variable that is then passed to cvs2cl.pl to
specify the date range that I'm interested in -- the span of time from
yesterday at midnight to today at midnight. Thus, the $cvsdate variable
contains a datespec that informs <path>cvs2cl.pl</path> to log only changes
made yesterday, but not others.
</p>
<p>
In addition, I also created a $nicedate variable (used in the mail subject line)
and use the mutt mailer (in mailx compatibility mode [see Resources]) to send
the e-mail to the gentoo-cvs mailing list:
</p>
<pre caption="cvslog.sh script">
#!/bin/bash
cd /usr/portage
cvs -q update -dP
yesterday=`date -d "1 day ago 00:00" -R`
today=`date -d "00:00" -R`
cvsdate=-d\'${yesterday}\<${today}\'
nicedate=`date -d yesterday +"%d %b %Y %Z (%z)"`
/home/drobbins/gentoo/cvs2cl.pl -f /home/drobbins/gentoo/cvslog.txt -l
"${cvsdate}"
mutt -x gentoo-cvs -s "cvs log for $nicedate" <\
/home/drobbins/gentoo/cvslog.txt
</pre>
<p>
Using cron, I run this script every night at midnight. Thanks to
<path>cvs2cl.pl</path>, my developers now get accurate and readable daily CVS
updates.
</p>
</body>
</section>
<section>
<title>The documentation project</title>
<body>
<p>
Now, for the Gentoo Linux documentation project. Our new documentation system
involves two groups of people or target audiences: the documentation creators
and the documentation readers. The creators need a well-designed XML syntax
that doesn't get in their way; the readers, who couldn't care less about the
1.1 xml/htdocs/doc/en/articles/l-redesign-3.xml
file :
http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/articles/l-redesign-3.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain:
http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/articles/l-redesign-3.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo
Index: l-redesign-3.xml
===================================================================
<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/articles/l-redesign-3.xml,v
1.1 2005/10/10 19:11:26 rane Exp $ -->
<guide link="/doc/en/articles/l-redesign-3.xml" disclaimer="articles">
<title>The gentoo.org redesign, Part 3: A site reborn</title>
<author title="Author">
<mail link="[EMAIL PROTECTED]">Daniel Robbins</mail>
</author>
<abstract>
Have you ever woken up one morning and suddenly realized that your cute little
personal development Web site isn't really that great? If so, you're in good
company. In this series, Daniel Robbins shares his experiences as he redesigns
the www.gentoo.org Web site using technologies like XML, XSLT, and Python.
Along the way, you may find some excellent approaches to use for your next Web
site redesign. In this installment, Daniel creates a new look for the site as a
whole.
</abstract>
<!-- The original version of this article was first published on IBM
developerWorks, and is property of Westtech Information Services. This
document is an updated version of the original article, and contains
various improvements made by the Gentoo Linux Documentation team -->
<version>1.0</version>
<date>2005-10-10</date>
<chapter>
<title>The new main pages</title>
<section>
<title>The site so far</title>
<body>
<p>
So far, www.gentoo.org is showing marked improvement. In the <uri
link="/doc/en/articles/l-redesign-2.xml">last article</uri>, I designed a new
documentation system using XML and XSLT, so all our site documentation is
looking great and is serving the needs of our visitors. However, the look of
the site as a whole hasn't changed; that's because I haven't really touched the
HTML that users see when they initially visit our site. Our main page still
looks the same as it did before.
</p>
<p>
Well, it's time for that to change. As I mentioned in the <uri
link="/doc/en/articles/l-redesign-2.xml">first article</uri>, our main page is
getting too congested and we have no room for expansion. As you can see, I've
packed quite a bit of content into <uri
link="/images/docs/l-redesign-13.gif">the page</uri>.
</p>
<p>
I can't continue piling important links and paragraphs onto the main page --
there isn't any room! Fortunately for us, real estate on the Web is absolutely
free.
</p>
<p>
So, to solve this problem, I'll split our single main page (index.html) into
several subject-specific category pages (index-about.html, index-download.html,
etc.) and create a menu system that will allow the user to easily move from one
category page to another. The default page that loads when a user visits
<b>http://www.gentoo.org</b> will be the "About Gentoo Linux" category page.
This is an excellent choice because it provides general information about the
project that will be of interest to first-time visitors.
</p>
</body>
</section>
<section>
<title>Site goals</title>
<body>
<p>
Now, I'm going to outline the goals of this new "category page" system, as well
as some general design goals that you can apply to your own projects. Then,
we'll take a look at how the category page redesign meets these goals.
</p>
</body>
</section>
<section>
<title>Modularity</title>
<body>
<p>
The new category page system needs to be modular. What does this mean, exactly?
Well, at the moment I have "About Gentoo Linux" and "Download/Install"
categories in mind, but in the future I may need to add "About the Team" or
"Support" categories as well. Having the ability to easily add new categories
in the future requires that accommodations be put in place during the design
stage. I'll have to make sure that there's room for additional category links
on my navigation menu, and that the layout of the page is general-purpose
enough so that it can be used to present many different kinds of information.
Then, adding new categories will be relatively easy and I'll be able to avoid
completely redesigning the site, if in a few months I once again find that
things don't fit.
</p>
<p>
There is a very important second step to modular design -- the use of XML and
XSLT to separate presentation from content. If you've read part 2 of this
series, then you're at least familiar with this type of design. Once I have the
proper XSL template created, I can generate as many category pages as I like by
simply providing the proper XML. And unlike the HTML, my XML will contain no
display-related information; it's pure content. We'll take a look at the
XML/XSLT implementation of the category pages in the fourth and final
installment in this series.
</p>
</body>
</section>
<section>
<title>General style guidelines</title>
<body>
<p>
It's also very important that the new category layout be visually appealing.
Remember, when a user types in http://www.gentoo.org, the "About Gentoo Linux"
category page will appear first, so I want this to be an attractive page. Now,
the word "attractive" means different things to different people, but this
article presents a few good general guidelines that I am using during the
design of the new category page that should apply to almost any Web site.
</p>
</body>
</section>
<section>
<title>That boxy look</title>
<body>
<p>
For general page layout, simple is best. If you're going to organize a bunch of
complicated information, why not use a master table to split the page into
various regions? This will also help to ensure that various parts of the page
line up, which makes for a clean, attractive design. For example, this
particular type of page layout is generally not very appealing:
</p>
<figure link="/images/docs/l-redesign-03.gif" caption="A sub-optimal page
layout"/>
<p>
However, if the same information is presented using a common master grid, the
site starts looking a lot cleaner:
</p>
<figure link="/images/docs/l-redesign-04.gif" caption="Aligned to a grid,
things become less confusing"/>
<p>
And remember, the simpler your layout, the more information you'll be able to
pack into the page without annoying your visitors
</p>
</body>
</section>
<section>
<title>Text and background color</title>
<body>
<p>
Next, we come to color choice. I have to admit that I happen to find bright
green text on a dark blue background very appealing. But let's face it -- no
matter how exotic and nifty they may look, dark backgrounds are a poor choice
for text regions on a Web site. People expect to see dark text on a light
background, and I for one think we should give them what they want.
</p>
<p>
Well, I should clarify my position. Using light text on a dark background is a
horrible choice for presenting paragraphs of information, but can be quite
attractive and functional for your menu bar, or a small list of links. In other
words, inverted text can be a great accent, but go with a traditional color
scheme for your main text content areas; you'll thank me later. This will also
help to ensure that your site looks good on paper.
</p>
</body>
</section>
<section>
<title>Contrast</title>
<body>
<p>
Besides the dark text/light background issue, there aren't many hard rules when
it comes to Web site design. If you like dark colors, it's perfectly fine to
make the top part of the page dark blue, for example. Now, hear me correctly:
If you make the entire page dark blue, you've done a bad thing. If you make a
portion of the page (preferably a portion of the page that doesn't have much
text in it) dark blue, you might actually be doing a very good thing, because
that dark blue will contrast nicely with your white text area and add some
additional drama to your new site. In fact, a large portion of your page can
contain saturated or dark colors; again, just make sure that your main text
content is presented in a traditional fashion.
</p>
1.1 xml/htdocs/doc/en/articles/l-redesign-4.xml
file :
http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/articles/l-redesign-4.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain:
http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/articles/l-redesign-4.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo
Index: l-redesign-4.xml
===================================================================
<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/articles/l-redesign-4.xml,v
1.1 2005/10/10 19:11:26 rane Exp $ -->
<guide link="/doc/en/articles/l-redesign-4.xml" disclaimer="articles">
<title>The gentoo.org redesign, Part 2: A site reborn</title>
<author title="Author">
<mail link="[EMAIL PROTECTED]">Daniel Robbins</mail>
</author>
<abstract>
Have you ever woken up one morning and suddenly realized that your cute little
personal development Web site isn't really that great? If so, you're in good
company. In this series, Daniel Robbins shares his experiences as he redesigns
the Gentoo Linux Web site using technologies like XML, XSLT, and Python. This
article: Daniel completes the conversion to XML/XSLT, fixes a host of Netscape
4.x browser compatibility bugs, and adds an auto-generated XML Changelog to the
site.
</abstract>
<!-- The original version of this article was first published on IBM
developerWorks, and is property of Westtech Information Services. This
document is an updated version of the original article, and contains
various improvements made by the Gentoo Linux Documentation team -->
<version>1.0</version>
<date>2005-10-10</date>
<chapter>
<title>The final touch</title>
<section>
<title>A new look, but...</title>
<body>
<p>
At the end of the previous article, the Gentoo Linux Web site had a completely
new look, but there are still some things that aren't quite complete. In this
article, the final installment in this series, I finally put those finishing
touches on the site, resulting in a fully-functional, refined, and modular
XML-based site that's ready for the future. Here's what was missing from the
site since the last article:
</p>
</body>
</section>
<section>
<title>Loose ends</title>
<body>
<p>
First, while the site has a completely new look, only the documentation portion
of the site is XML-based. The main "category" pages are still in raw HTML and
need to be converted to an XML/XSLT solution to make things more maintainable
and expandable.
</p>
<p>
Also, my developers have found several problems with the raw HTML itself. The
site looks particularly bad when viewed under Netscape 4.77 -- obviously, this
is a problem. Also, there are a number of other minor rendering problems that
appear in more modern browsers, the most annoying of which is a thin vertical
black line that does not extend completely down the entire page, ruining the
illusion that the main content area is being spoken by our flying-saucer guy.
Also, our documentation pages don't completely match the more refined look of
our new main category pages -- clearly something worth updating.
</p>
</body>
</section>
<section>
<title>The goal</title>
<body>
<p>
Here's the plan for the final rework of the Gentoo Linux site. First, we'll
totally rework the main page HTML, keeping the same overall look, but making
the page more browser-compatible. At the same time, we'll add a few
presentation-related refinements suggested by our visitors, and also fix
browser compatibility problems with our existing "guide" documentation system.
</p>
<p>
Next, we'll completely move the site over to XML and XSLT. By the end of this
article, any change made to the site will be made by modifying XML or XSLT
rather than directly editing HTML, which will now be generated automatically
with the help of xsltproc. This will make the site a whole lot easier to
maintain. Because Gentoo Linux is a community-developed project, this will, in
turn, allow our developers (and me) to maintain and improve the site as needed.
I'm really excited about this since it will save us a bunch of time and ensure
that our visitors are greeted with up-to-date content.
</p>
</body>
</section>
<section>
<title>Compatibility issues</title>
<body>
<p>
While Netscape 4.x is still a very widely used browser, it is difficult for me
to decide exactly how many hoops to jump through in order to make the site look
better when viewed through this browser. Should I merely ensure that the site
is readable (without any major glitches) or should I do everything I can to
make sure the site looks absolutely perfect under Netscape 4.x, even if that
means using less or no CSS and adding strange compatibility hacks to the
existing HTML?
</p>
<p>
In the end, I decide to make several major changes to the HTML so that the site
will still look quite good under Netscape 4.x without focusing too much on
minor bug-related table spacing and font-rendering issues. Here are some of the
changes made to the site's HTML to get everything 4.x compatible. (The Gentoo
Linux development team has submitted several of these fixes.)
</p>
<p>
First, Netscape 4.x has a bug that causes CSS background colors of block
elements to be displayed incorrectly. For example, here's how a particular
portion of a guide document is supposed to be rendered:
</p>
<figure link="/images/docs/l-redesign-07.gif" caption="A sample guide document
in IE5"/>
<p>
And, here is how Netscape 4.x renders this same portion when background colors
are specified using CSS:
</p>
<figure link="/images/docs/l-redesign-08.gif" caption="A sample guide document
in Netscape 4.7; some fixes are needed"/>
<p>
This is ugly. To fix it, existing block-level elements, such as this one...
</p>
<pre caption="Sample paragraph">
<p class="note">This paragraph doesn't look so good in 4.x</p>
</pre>
<p>
...were replaced with tables, as follows:
</p>
<pre caption="Sample table">
<table width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
<td bgcolor="#ddffff"><p class="note">
This looks a whole lot better in 4.x</p></td>
</tr>
</table>
</pre>
<p>
This hack fixes the background-rendering problem. However, this "fix" also
requires color information to be included in the HTML, which undermines the
benefits of using CSS in the first place. This is an unfortunate situation,
especially for fans of CSS like myself, but is required for Netscape 4.x
compatibility.
</p>
</body>
</section>
<section>
<title>Rebuilding the HTML</title>
<body>
<p>
Now it's time to deal with the black vertical line that doesn't always extend
all the way to the bottom of the screen. I have been unable to find a solution
to this problem that works in both a 4.x and 5.x browser; every 5.x version has
triggered bugs in Netscape 4.x, and every 4.x-compatible version looks horrible
in a 5.x browser. So, I decide to simply remove the black line entirely:
Finally, the site works in all popular browsers. Next, I will to create a
guide-like syntax for creating the main pages.
</p>
</body>
</section>
<section>
<title>Approaching the XML</title>
<body>
<p>
Instead of implementing a completely new tagset for the main page, I think it
would be a good idea to try to use as many of the "guide" XML documentation
tags as possible (see part 2 of this series for more information on the guide
XML format). So, I hack away at some new XSL, using my guide XSL as a template
for my work. After an hour or two, I have a fully-functional set of XSL
transformations for turning a guide-like syntax into an HTML main page.
Revision 2 of the new main page looks like this:
</p>
<figure link="/images/docs/l-redesign-09.gif" caption="The new main page
revision"/>
<p>
--
[email protected] mailing list
