Difference between pages "Package:Spectrwm" and "The Gentoo.org Redesign, Part 2"

(Difference between pages)
 
 
Line 1: Line 1:
{{Ebuild
+
{{Article
|Summary=A small, dynamic tiling window manager for X11.
+
|Summary=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.
|CatPkg=x11-wm/spectrwm
+
|Author=Drobbins
|Maintainer=
+
|Previous in Series=The Gentoo.org Redesign, Part 1
|Homepage=https://opensource.conformal.com/wiki/spectrwm
+
|Next in Series=The Gentoo.org Redesign, Part 3
 
}}
 
}}
{{Note|Spectrwm was previously known as Scrotwm.}}
+
== The doc system ==
==== Introduction ====
+
From their page:
+
spectrwm is a small dynamic tiling window manager for X11. It tries to stay out of the way so that valuable screen real estate can be used for much more important stuff. It has sane defaults and does not require one to learn a language to do any configuration. It was written by hackers for hackers and it strives to be small, compact and fast.
+
==== Installation ====
+
<console>
+
# ##i##emerge x11-wm/spectrwm
+
</console>
+
Xlockmore is also needed
+
<console>
+
# ##i##emerge x11-misc/xlockmore
+
</console>
+
  
 +
If you've read the first installment 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.
  
==== Setup ====
+
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.
===== xinitrc =====
+
Edit ~/.xinitrc:
+
<pre>
+
exec spectrwm
+
</pre>
+
Copy /etc/spectrwm.conf to your home dir as an hidden file.
+
<console>
+
$ ##i## cp /etc/spectrwm.conf ~/.spectrwm.conf
+
</console>
+
You can edit spectrwm.conf to suit your needs. The file is thoroughly commented so you won't feel lost.
+
  
==== Bindings (default) ====
+
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.
{{Note|Usually the M (Modus) key is either alt or the super key.}}
+
From the man page:
+
  
BINDINGS
+
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.
  
    spectrwm provides many functions (or actions) accessed via key or mouse
+
== Adding the CVS log mailing list ==
    bindings.
+
  
    The current mouse bindings are described below:
+
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 Resources) 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.
{| class="wikitable sortable"
+
|-
+
! Mouse binding  !! description
+
|-
+
| M1 || Focus window
+
|-
+
| M-M1 || Move window
+
|-
+
| M-M3|| Resize window
+
|-
+
| M-S-M3|| Resize window while maintaining it centered
+
|}                     
+
  
    The default key bindings are described below:
+
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.
  
          M-S-<Return>        term
+
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.
          M-p                menu
+
          M-S-q              quit
+
          M-q                restart
+
          M-<Space>          cycle_layout
+
          M-S-<\>            flip_layout
+
          M-S-<Space>        stack_reset
+
          M-h                master_shrink
+
          M-l                master_grow
+
          M-,                 master_add
+
          M-.                 master_del
+
          M-S-,               stack_inc
+
          M-S-.              stack_dec
+
          M-<Return>          swap_main
+
          M-j, M-<TAB>        focus_next
+
          M-k, M-S-<TAB>      focus_prev
+
          M-m                focus_main
+
          M-S-j              swap_next
+
          M-S-k              swap_prev
+
          M-b                bar_toggle
+
          M-S-b              bar_toggle_ws
+
          M-x                wind_del
+
          M-S-x              wind_kill
+
          M-<1-9,0,F1-F12>    ws_<1-22>
+
          M-S-<1-9,0,F1-F12>  mvws_<1-22>
+
          M-<Keypad 1-9>      rg_<1-9>
+
          M-S-<Keypad 1-9>    mvrg_<1-9>
+
          M-<Right>          ws_next
+
          M-<Left>            ws_prev
+
          M-<Up>              ws_next_all
+
          M-<Down>            ws_prev_all
+
          M-a                 ws_next_move
+
          M-S-<Left>          ws_prev_move
+
          M-S-<Up>            ws_prior
+
          M-S-<Right>        rg_next
+
          M-S-<Left>          rg_prev
+
          M-s                screenshot_all
+
          M-S-s              screenshot_wind
+
          M-S-v              version
+
          M-t                float_toggle
+
          M-S-<Delete>        lock
+
          M-S-i              initscr
+
          M-w                iconify
+
          M-S-w              uniconify
+
          M-S-r              always_raise
+
          M-v                button2
+
          M--                width_shrink
+
          M-=                width_grow
+
          M-S--              height_shrink
+
          M-S-=              height_grow
+
          M-[                move_left
+
          M-]                move_right
+
          M-S-[              move_up
+
          M-S-]              move_down
+
          M-S-/              name_workspace
+
          M-/                search_workspace
+
          M-f                search_win
+
  
The action names and descriptions are listed below:
+
== cvs2cl.pl ==
  
          term              Spawn a new terminal (see PROGRAMS above).
+
Several weeks later I started looking for an alternative to loginfo. This time I did the smart thing and headed over to http://freshmeat.net. There I quickly found just what I was looking for: the incredibly wonderful cvs2cl.pl perl script available from http://red-bean.com (see Resources). Instead of using the loginfo hook, cvs2cl.pl uses the cvs log 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:
          menu              Menu (see PROGRAMS above).
+
 
          quit              Quit spectrwm.
+
{{file|desc=Output generated by cvs2cl.pl|body=
          restart          Restart spectrwm.
+
2001-04-09 20:58  drobbins
          cycle_layout      Cycle layout.
+
       * app-doc/gentoo-web/files/xml/dev.xml: new fixes
          flip_layout       Swap the master and stacking areas.
+
2001-04-09 20:47  drobbins
          stack_reset       Reset layout.
+
       * app-doc/gentoo-web/: gentoo-web-1.0.ebuild,
          master_shrink    Shrink master area.
+
       files/pyhtml/index.pyhtml, files/xml/gentoo-howto.xml: new gentoo-howto
          master_grow       Grow master area.
+
      fixes
          master_add        Add windows to master area.
+
2001-04-09 20:03  drobbins
          master_del        Remove windows from master area.
+
      * app-doc/gentoo-web/files/xml/dev.xml: typo fix
          stack_inc        Add columns/rows to stacking area.
+
2001-04-09 20:02  drobbins
          stack_dec        Remove columns/rows from stacking area.
+
      * app-doc/gentoo-web/files/pyhtml/index.pyhtml: little update
          swap_main        Move current window to master area.
+
}}
          focus_next        Focus next window in workspace.
+
 
          focus_prev        Focus previous window in workspace.
+
cvs2cl.pl 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.
          focus_main        Focus on main window in workspace.
+
 
          swap_next        Swap with next window in workspace.
+
== The cvslog.sh script ==
          swap_prev        Swap with previous window in workspace.
+
 
          bar_toggle        Toggle overall visibility of status bars.
+
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 cvs2cl.pl to log only changes made yesterday, but not others.
          bar_toggle_ws    Toggle status bar on current workspace.
+
 
          wind_del          Delete current window in workspace.
+
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:
          wind_kill        Destroy current window in workspace.
+
 
          ws_n              Switch to workspace n, where n is 1 through
+
{{file|name=cvslog.sh|body=
                            workspace_limit.
+
#!/bin/bash
          mvws_n            Move current window to workspace n, where n is 1
+
cd /usr/portage
                            through workspace_limit.
+
cvs -q update -dP
          rg_n              Focus on region n, where n is 1 through 9.
+
yesterday=`date -d "1 day ago 00:00" -R`
          mvrg_n            Move current window to region n, where n is 1
+
today=`date -d "00:00" -R`
                            through 9.
+
cvsdate=-d\'${yesterday}\<${today}\'
          ws_next          Switch to next workspace with a window in it.
+
nicedate=`date -d yesterday +"%d %b %Y %Z (%z)"`
          ws_prev          Switch to previous workspace with a window in it.
+
/home/drobbins/gentoo/cvs2cl.pl -f /home/drobbins/gentoo/cvslog.txt -l "${cvsdate}"
          ws_next_all      Switch to next workspace.
+
mutt -x gentoo-cvs -s "cvs log for $nicedate" <\
          ws_prev_all      Switch to previous workspace.
+
/home/drobbins/gentoo/cvslog.txt
          ws_next_move      Switch to next workspace with the current window.
+
}}
          ws_prev_move      Switch to previous workspace with the current
+
 
                            window.
+
Using cron, I run this script every night at midnight. Thanks to cvs2cl.pl, my developers now get accurate and readable daily CVS updates.
          ws_prior          Switch to last visited workspace.
+
 
          rg_next          Switch to next region.
+
== The documentation project ==
          rg_prev          Switch to previous region.
+
 
          screenshot_all    Take screenshot of entire screen (if enabled)
+
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 XML, want generated HTML documentation that is both functional and attractive. The implementation challenge is to put together a complete system that addresses the needs of both audiences. Oh, and I suppose there is a third "audience" -- me, the webmaster and the person designing the new system. Since I'm going to be interacting with the new doc system whenever the site is upgraded, I need it to be reliable and flexible.
                            (see PROGRAMS above).
+
 
          screenshot_wind  Take screenshot of selected window (if enabled)
+
== The Web-ready HTML ==
                            (see PROGRAMS above).
+
 
          version          Toggle version in status bar.
+
First, let's talk a bit about the Web-ready HTML that'll be generated from my master XML files. To make great, readable documentation, I'll need to have support for the proper XML tags. For example, the ability to insert notes, important messages, and warnings into the body of the document (and have them prominently displayed in the resultant HTML) is a must. Also, I must be able to insert blocks of code, and it would be great if actual user input could somehow be offset from program output. I could even add tags that highlight the source code comments in an alternate color so that the code blocks are more readable.
          float_toggle      Toggle focused window between tiled and floating.
+
 
          lock              Lock screen (see PROGRAMS above).
+
The documents should have a table of contents (with hyperlinks to the appropriate chapters), a synopsis, a revision date, version, and an authors list at the top of the document. And, of course, every document should have a header at the extreme top of the page containing a small Gentoo Linux logo. Clicking on this logo should bring you back to the main Gentoo Linux page. Last but not least, every document should have a footer that contains copyright information, along with a contact e-mail address.
          initscr          Reinitialize physical screens (see PROGRAMS
+
 
                            above).
+
== The spiffy new logo ==
          iconify          Minimize (unmap) currently focused window.
+
 
          uniconify        Maximize (map) window returned by dmenu
+
This was a hefty list of requirements, and I decided to focus on the most entertaining part first, the new Gentoo Linux logo that would appear in the upper-left corner of every Gentoo Linux document. I used the "g" from the "gentoo" graphic (created using the excellent and free Blender 3D program) on our main page as the basis for the new smaller logo. I tweaked the extrusion settings a bit and then added a chrome environment map. Finally, I positioned the lights and camera just so, and the new logo was complete. After importing it into Xara X (see Resources) and adding some text, this was the result:
                            selection.
+
 
          always_raise      When set tiled windows are allowed to obscure
+
[[File:L-redesign-02.gif|frame|class=img-responsive|caption=The new Gentoo Linux logo]]
                            floating windows.
+
 
          button2          Fake a middle mouse button click (mouse button
+
I used this new logo as inspiration for the rest of the HTML color scheme, using a purplish theme throughout. I made heavy use of cascading style sheets (CSS) to control font attributes and spacing. Once I had a decent HTML prototype in place, I started focusing on the guts of the new documentation -- the new XML syntax. I wanted the syntax to be as simple as possible, so I created just enough XML tags to allow for the proper organization of the document, but no more. Then I started working on the XSLT to transform the XML into the target HTML.
                            2).
+
 
          width_shrink      Shrink the width of a floating window.
+
== The result! ==
          width_grow        Grow the width of a floating window.
+
 
          height_shrink    Shrink the height of a floating window.
+
After much tweaking and a good amount of feedback from one of my developers, the new documentation system reached the point where it was ready for use. I immediately began work on our first new development guide, "The Gentoo Linux Documentation Guide" (xml-guide.html), which contains a complete description of the new XML format. Not only did this allow other developers to begin work on the new-style documentation, but it also served as an excellent example of the new documentation system in action. Be sure to read this guide to get a complete understanding of our new XML syntax.
          height_grow      Grow the height of a floating window.
+
 
          move_left        Move a floating window a step to the left.
+
== DocBook vs. Guide ==
          move_right        Move a floating window a step to the right.
+
 
          move_up          Move a floating window a step upwards.
+
If you're working on your own documentation solution, you may also want to consider the DocBook XML and SGML formats (see Resources). DocBook is well-suited for large-scale technical documentation and book projects, is very flexible, and has many (maybe too many) features. In addition, there are a number of existing packages that can be used to convert DocBook XML/SGML to man pages, texinfo files, Postscript, PDF, and, of course, HTML formats.
          move_down        Move a floating window a step downwards.
+
 
          name_workspace    Name the current workspace.
+
I didn't choose DocBook because a lightweight XML syntax worked best for Gentoo's needs. Right now, our XML guide syntax has around 20 tags and about 10 attributes. The limited tagset makes guide XML easy to transform into other formats such as HTML, and also ensures a certain level of consistency throughout our entire documentation set, since the format is so simple. Because I have my own XML format, I'll be able to extend the format with new tags as needed. I like having that level of control. I view XML as a technology that should be used by people to structure their data in ways that they find most helpful. In other words, the ability to define our own elements and attributes is a precious thing, and I should take full advantage of it. After all, it's the defining feature of XML.
          search_workspace  Search for a workspace.
+
 
          search_win        Search the windows in the current workspace.
+
Of course, creating your own XML syntax is not always the best solution, especially when data interchange is important to you. Amid all the XML hype, one thing that is often overlooked is that conversion to and from different XML formats can be extremely difficult. In many cases, the two formats won't be 100% compatible, and you'll have the unpleasant choice of either throwing away data and/or metadata, intentionally avoiding use of certain elements or attributes, or creating a "super-format" that will accommodate the data and metadata from both XML formats. In the documentation world, DocBook is a pretty good choice as a "super-format" because it's so flexible; it can easily accommodate documentation imported from a variety of sources.
{{EbuildFooter}}
+
 
 +
However, DocBook's richness and flexibility can also create problems. For example, there may be hundreds of tags that you may never need, and supporting all these tags in your XSLT can make conversion to other formats more difficult. So, while DocBook is a great container for documentation converted from other formats, your own minimal XML syntax will almost always be easier to convert to other formats.
 +
 
 +
The most important thing is to carefully evaluate any potential solution while keeping the needs of your target audience(s) in mind.
 +
 
 +
== Wrapping it up ==
 +
 
 +
With the new doc system in place, I converted all our docs to the new format and posted the new docs on our existing site. In addition, I created a link to the gentoo-cvs mailing list subscription page. The key point here is that I integrated these features into the existing site so that users could benefit from the improvements right away.
 +
{{ArticleFooter}}

Revision as of 05:00, January 1, 2015

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.

Support Funtoo and help us grow! Donate $15 per month and get a free SSD-based Funtoo Virtual Container.

The doc system

If you've read the first installment 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.

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.

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.

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.

Adding the CVS log mailing list

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 Resources) 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.

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.

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.

cvs2cl.pl

Several weeks later I started looking for an alternative to loginfo. This time I did the smart thing and headed over to http://freshmeat.net. There I quickly found just what I was looking for: the incredibly wonderful cvs2cl.pl perl script available from http://red-bean.com (see Resources). Instead of using the loginfo hook, cvs2cl.pl uses the cvs log 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:

- 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

cvs2cl.pl 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.

The cvslog.sh script

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 cvs2cl.pl to log only changes made yesterday, but not others.

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:

cvslog.sh
#!/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

Using cron, I run this script every night at midnight. Thanks to cvs2cl.pl, my developers now get accurate and readable daily CVS updates.

The documentation project

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 XML, want generated HTML documentation that is both functional and attractive. The implementation challenge is to put together a complete system that addresses the needs of both audiences. Oh, and I suppose there is a third "audience" -- me, the webmaster and the person designing the new system. Since I'm going to be interacting with the new doc system whenever the site is upgraded, I need it to be reliable and flexible.

The Web-ready HTML

First, let's talk a bit about the Web-ready HTML that'll be generated from my master XML files. To make great, readable documentation, I'll need to have support for the proper XML tags. For example, the ability to insert notes, important messages, and warnings into the body of the document (and have them prominently displayed in the resultant HTML) is a must. Also, I must be able to insert blocks of code, and it would be great if actual user input could somehow be offset from program output. I could even add tags that highlight the source code comments in an alternate color so that the code blocks are more readable.

The documents should have a table of contents (with hyperlinks to the appropriate chapters), a synopsis, a revision date, version, and an authors list at the top of the document. And, of course, every document should have a header at the extreme top of the page containing a small Gentoo Linux logo. Clicking on this logo should bring you back to the main Gentoo Linux page. Last but not least, every document should have a footer that contains copyright information, along with a contact e-mail address.

This was a hefty list of requirements, and I decided to focus on the most entertaining part first, the new Gentoo Linux logo that would appear in the upper-left corner of every Gentoo Linux document. I used the "g" from the "gentoo" graphic (created using the excellent and free Blender 3D program) on our main page as the basis for the new smaller logo. I tweaked the extrusion settings a bit and then added a chrome environment map. Finally, I positioned the lights and camera just so, and the new logo was complete. After importing it into Xara X (see Resources) and adding some text, this was the result:

caption=The new Gentoo Linux logo

I used this new logo as inspiration for the rest of the HTML color scheme, using a purplish theme throughout. I made heavy use of cascading style sheets (CSS) to control font attributes and spacing. Once I had a decent HTML prototype in place, I started focusing on the guts of the new documentation -- the new XML syntax. I wanted the syntax to be as simple as possible, so I created just enough XML tags to allow for the proper organization of the document, but no more. Then I started working on the XSLT to transform the XML into the target HTML.

The result!

After much tweaking and a good amount of feedback from one of my developers, the new documentation system reached the point where it was ready for use. I immediately began work on our first new development guide, "The Gentoo Linux Documentation Guide" (xml-guide.html), which contains a complete description of the new XML format. Not only did this allow other developers to begin work on the new-style documentation, but it also served as an excellent example of the new documentation system in action. Be sure to read this guide to get a complete understanding of our new XML syntax.

DocBook vs. Guide

If you're working on your own documentation solution, you may also want to consider the DocBook XML and SGML formats (see Resources). DocBook is well-suited for large-scale technical documentation and book projects, is very flexible, and has many (maybe too many) features. In addition, there are a number of existing packages that can be used to convert DocBook XML/SGML to man pages, texinfo files, Postscript, PDF, and, of course, HTML formats.

I didn't choose DocBook because a lightweight XML syntax worked best for Gentoo's needs. Right now, our XML guide syntax has around 20 tags and about 10 attributes. The limited tagset makes guide XML easy to transform into other formats such as HTML, and also ensures a certain level of consistency throughout our entire documentation set, since the format is so simple. Because I have my own XML format, I'll be able to extend the format with new tags as needed. I like having that level of control. I view XML as a technology that should be used by people to structure their data in ways that they find most helpful. In other words, the ability to define our own elements and attributes is a precious thing, and I should take full advantage of it. After all, it's the defining feature of XML.

Of course, creating your own XML syntax is not always the best solution, especially when data interchange is important to you. Amid all the XML hype, one thing that is often overlooked is that conversion to and from different XML formats can be extremely difficult. In many cases, the two formats won't be 100% compatible, and you'll have the unpleasant choice of either throwing away data and/or metadata, intentionally avoiding use of certain elements or attributes, or creating a "super-format" that will accommodate the data and metadata from both XML formats. In the documentation world, DocBook is a pretty good choice as a "super-format" because it's so flexible; it can easily accommodate documentation imported from a variety of sources.

However, DocBook's richness and flexibility can also create problems. For example, there may be hundreds of tags that you may never need, and supporting all these tags in your XSLT can make conversion to other formats more difficult. So, while DocBook is a great container for documentation converted from other formats, your own minimal XML syntax will almost always be easier to convert to other formats.

The most important thing is to carefully evaluate any potential solution while keeping the needs of your target audience(s) in mind.

Wrapping it up

With the new doc system in place, I converted all our docs to the new format and posted the new docs on our existing site. In addition, I created a link to the gentoo-cvs mailing list subscription page. The key point here is that I integrated these features into the existing site so that users could benefit from the improvements right away.

Next >>>

Read the next article in this series: The Gentoo.org Redesign, Part 3

Support Funtoo and help us grow! Donate $15 per month and get a free SSD-based Funtoo Virtual Container.

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.
About the Author

Daniel Robbins is best known as the creator of Gentoo Linux and author of many IBM developerWorks articles about Linux. Daniel currently serves as Benevolent Dictator for Life (BDFL) of Funtoo Linux. Funtoo Linux is a Gentoo-based distribution and continuation of Daniel's original Gentoo vision.

Got Funtoo?

Have you installed Funtoo Linux yet? Discover the power of a from-source meta-distribution optimized for your hardware! See our installation instructions and browse our CPU-optimized builds.

Funtoo News

Drobbins

IP Space Migration Continues

All Funtoo user containers in the 8.28 IP space will be moving into our new IP space (172.97) over the next few days. If you have DNS set up -- be sure to watch your container and update to the new IP! container.host.funtoo.org DNS will be updated after the move.
2015-08-27 by Drobbins
Drobbins

Funtoo Hosting IP Move

Funtoo user containers with IPs in the 72.18.x.x range will be gradually migrating to new IP addresses this week. If you have DNS entries for your containers, please be aware that your DNS will need to be updated.
2015-08-11 by Drobbins
Drobbins

New ARM Stages

New ARM Stages, built with a new toolchain, are now hitting mirrors. Existing ARM users should re-install using these stages (dated Aug 3, 2015 or later,) rather than upgrade using emerge.
2015-08-06 by Drobbins
More...

More Articles

Browse all our Linux-related articles, below:

A

B

F

G

K

L

M

O

P

S

T

W

X