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

−

__NOTITLE__

+

|Author=Drobbins

−

This page provides an overview of Funtoo Linux sub-architectures (also called ''subarches'',) designed for quick and easy reference. While this information is available in other places, such as Wikipedia, it often takes some time to study and cross-reference the various articles to get a good understanding of each type of sub-architecture, and this information generally isn't all collected neatly in one place. That is the purpose of this page. When possible, links to more detailed Wikipedia pages are provided. You are encouraged to help maintain this page as well as the Wikipedia articles referenced here.

+

|Previous in Series=The Gentoo.org Redesign, Part 1

+

|Next in Series=The Gentoo.org Redesign, Part 3

+

}}

+

== The doc system ==

−

== 64-bit Suport (Generic) ==

+

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.

−

=== generic_64 ===

+

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.

−

The '''generic_64''' subarch is designed to support 64-bit PC-compatible CPUs, such as the [[Wikipedia:AMD_K8|AMD K8-series processors]], which were introduced in late 2003. They were notable as the first processors that supported the [[Wikipedia:X86-64|AMD64 (also called X86-64) 64-bit instruction set]] for PC-compatible systems, which was introduced as a backwards-compatible 64-bit alternative to Intel's IA-64 architecture. Intel followed suit and also began supporting this 64-bit instruction set, which they called "[[Wikipedia:X86-64#Intel_64|Intel 64]]", by releasing X86-64 64-bit compatible CPUs from mid-2004 onwards (See [[Wikipedia:X86-64#Intel_64_implementations|Intel 64 implementations]].)

+

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.

−

AMD desktop 64-bit CPUs include the Athlon 64, Athlon 64 FX, Athlon 64 X2, Athlon X2, Turion 64, Turion 64 X2 and Sempron series processors. AMD server processors were released under the Opteron brand and have codenames SledgeHammer, Venus, Troy, Athens, Denmark, Italy, Egypt, Santa Ana and Santa Rosa. All Opterons released through late 2006 were based on the K8 microarchitecture with original X86-64 instructions.

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.

−

The '''amd64-k10''' subarch provides support for the [[Wikipedia:AMD_10h|AMD Family 10h processors]], which were released in late 2007 as a successor to the AMD K8 series processors.

+

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.

−

=== amd64-bulldozer ===

+

== cvs2cl.pl ==

−

The '''amd64-bulldozer''' subarch supports the [[Wikipedia:Bulldozer (microarchitecture)|AMD bulldozer microarchitecture]] CPUs, which were released from late 2011 through the first quarter of 2012 as a replacement for the [[Wikipedia:AMD_10h|K10 microarchitecture]] CPUs.

+

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:

−

Bulldozer desktop CPUs use the [[Wikipedia:Socket_AM3+|AM3+ socket]] and server CPUs use the [[Wikipedia:Socket_G34|G34 socket]].

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 '''amd64-piledriver''' subarch supports the [[Wikipedia:Piledriver (microarchitecture)|AMD Piledriver microarchitecture]] produced by AMD from mid-2012 through 2015, which is the successor to the [[Wikipedia:Bulldozer (microarchitecture)|AMD bulldozer microarchitecture]].

+

== The cvslog.sh script ==

−

Piledriver CPUs and APUs are available that use the [[Wikipedia:FM2 Socket|FM2 socket]]. Desktop Piledriver CPUs use the [[Wikipedia:Socket_AM3+|AM3+ socket]]. Server Piledriver CPUs use a variety of sockets, including [[Wikipedia:Socket_AM3+|AM3+]], [[Wikipedia:Socket_C32|C32]] and [[Wikipedia:Socket_G34|G34]].

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:

−

Piledriver adds several new instructions over bulldozer, so AMD bulldozer systems cannot run amd64-piledriver-optimized stages. However, this subarch is instruction-compatible with its successor, the, so amd64-piledriver stages can run on amd64-steamroller systems, and vice versa.

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 '''amd64-steamroller''' subarch supports the [[Wikipedia:Steamroller (microarchitecture)|AMD steamroller microarchitecture]], produced from early 2014. It is the successor to the [[Wikipedia:Piledriver (microarchitecture)|AMD Piledriver microarchitecture]].

+

== The documentation project ==

−

Steamroller APUs are available that use the [[Wikipedia:FM2+ Socket|FM2+ socket]] and [[Wikipedia:Socket_FP3|FP3 socket]] (mobile.)

+

−

Desktop steamroller APUs include the [[Wikipedia:AMD_Accelerated_Processing_Unit#Steamroller_architecture_.282014.29:_Kaveri|A-Series with codename Kaveri]], such as the quad-core AMD A10-7850K APU. Steamroller APUs are also available in mobile versions. Server steamroller APUs will include the codename Berlin APUs, which are expected to be released some time in 2015.

+

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.

−

Amd64-steamroller subarches are instruction-compatible with amd64-piledriver, but add new instructions over amd64-bulldozer.

+

== The Web-ready HTML ==

−

=== amd64-jaguar ===

+

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 '''amd64-jaguar''' (also called AMD Family 16h) subarch supports the [[Wikipedia:Jaguar (microarchitecture)|AMD jaguar microarchitecture]], which is targeted at low-power devices, including notebooks, tablets and small form-factor desktops and servers. It is perhaps most well-known for being the microarchitecture used for the [[Wikipedia:Playstation 4|Playstation 4]] and [[Wikipedia:Xbox One|Xbox One]], which each use custom 8-core Jaguar APUs.

+

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.

−

Socketed Jaguar APUs use the [[Wikipedia:AM1 Socket|AM1 socket]], and [[Wikipedia:Socket_FT3|FT3 socket]] for mobile devices. G-series [[Wikipedia:System_on_a_chip|"system on a chip" (SoC)]] APUs are available for non-socketed devices such as tablets and embedded system boards.

+

−

Desktop Jaguar APUs include the [[Wikipedia:List_of_AMD_accelerated_processing_unit_microprocessors#.22Kabini.22.2C_.22Temash.22_.282013.2C_28_nm.29|Kabini A-series APUs and Temash E-series APUs]], such as the Athlon 5150 and 5350 APUs, and Sempron 2650 and 3850.

+

== The spiffy new logo ==

−

Amd64-jaguar subarches use the MOVBE instruction which is not available on amd64-bulldozer, amd64-piledriver or amd64-steamroller. They are thus not instruction-compatible with any of these subarches.

+

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:

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.

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.

−

The '''atom_64''' (also known under the Intel code names Diamondville, Pineview, Cedarview and Centerton) subarch supports the [[Wikipedia:Bonnell_(microarchitecture)|Intel Bonnell microarchitecture]], representing a partial revival of the principles used in earlier Intel designs such as P5 and the i486, with the sole purpose of enhancing the performance per watt ratio. Successor to the [[Wikipedia:Stealey_(microprocessor)|Stealey_(microprocessor)]], which was derived from the [[Wikipedia:Pentium_M|Pentium M]], the Atom has been produced since 2008. Targeted at low-power devices, Atom processors can be found in a wide range of notebooks, tablets and small form-factor desktops and servers.

+

== DocBook vs. Guide ==

−

The Atom N2xx series Atom Diamondville models cannot support 64-bit operation, while the Pineview, Cedarview and Centerton only can "with a processor, chipset, BIOS" that all support [[Wikipedia:X86-64#Intel_64|Intel 64]]. This can lead to situations where non-Intel branded motherboards can have a 64-bit capable Atom processor which cannot run a 64-bit operating system. In this situation, you would need to use the [[subarches#atom_32|atom_32]] subarch.

+

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.

−

== 32-bit Suport (Generic) ==

+

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.

−

=== generic_32 ===

+

−

== 32-bit AMD Processors ==

+

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.

−

=== amd64-k8_32 ===

+

−

=== athlon-xp ===

+

−

== 32-bit ARM Processors ==

+

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.

−

=== armv5te ===

+

−

=== armv6j_hardfp ===

+

−

=== armv7a_hardfp ===

+

−

== 32-bit Intel Processors ==

+

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

−

=== atom_32 ===

+

−

=== core2_32 ===

+

−

=== i686 ===

+

−

=== pentium4 ===

+

+

== Wrapping it up ==

−

{{:Install/Footer}}

+

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.Looking for people interested in testing and documenting Docker support! Contact Daniel Robbins for more info.

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.

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:

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:

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.

The spiffy new logo

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 >>>

Support Funtoo and help us grow! Donate $15 per month and get a free SSD-based Funtoo Virtual Container.Looking for people interested in testing and documenting Docker support! Contact Daniel Robbins for more info.

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.