Hacking the BLFS Book

So you've decided that you'd like to help develop the BLFS book. Or maybe there's something broken that the editors are being too slow with and you've decided to fix it yourself. Good for you! This page will try to describe the BLFS editing process for those who aren't familiar. A much more in depth guide can be found in the BLFS Editor's Guide.

Getting the Tools

The source of the BLFS book is written in XSL and is stored in a Subversion repository, so you'll first need to build the right tools to get anything accomplished.

First, build Subversion using the instructions in the BLFS SVN book:

http://www.linuxfromscratch.org/blfs/view/svn/basicnet/subversion.html

Next, you need to get the tools in place to work with XSL. You'll need the xmllint and xsltproc programs, which are part of libxml2 and libxslt, respectively:

http://www.linuxfromscratch.org/blfs/view/svn/general/libxml2.html
http://www.linuxfromscratch.org/blfs/view/svn/general/libxslt.html

In order to do anything with these tools, you'll need to use XSL stylesheets, which are used to describe the formatting of the BLFS book. This requires the DocBook XML DTD and DocBook XSL Stylesheets:

http://www.linuxfromscratch.org/blfs/view/svn/pst/xml.html
http://www.linuxfromscratch.org/blfs/view/svn/pst/docbook-xsl.html

Finally, you'll need HTML Tidy if you want to clean up the generated HTML (you'll want this if you're using the Makefile in the BLFS sources):

http://www.linuxfromscratch.org/blfs/view/svn/general/tidy.html

Working With the Source

Now you've finally got all the tools in place and it's time to do some editing. The procedure below is described in much more detail in the BLFS Editor's Guide.

First, check out the BLFS trunk, which contains the book and bootscripts:

svn co svn://svn.linuxfromscratch.org/BLFS/trunk blfs

This will create a blfs directory with a BOOK subdirectory. Change into the BOOK directory. The file general.ent contains most of the XSL "variables", which are called entities. When the book date is bumped or a package upgrade occurs, the entities here change.

The instructions for the individual packages are in their own files, and these files usually correspond to individual HTML pages in the formatted book. For instance, suppose you wanted to edit the libpng page. The associated XSL file is general/graphlib/libpng.xml. To get started, just view this file and follow the formatting there. A discussion of XSL formatting is beyond the scope of this page.

The top of the file contains the package specific entities like the download URLs and the build size. Next, a <sect1> tag begins the actual formatting of the page. Text within <title>, <para> and <screen> tags are what you see in the formatted HTML, among others. This is where you'd be most likely to make changes if you wanted to fix something in the book. If you're familiar with HTML formatting, XSL is very similar. Here's a snippet from the libpng page:

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make install &amp;&amp;
install -v -m755 -d /usr/share/doc/libpng-&libpng-version; &amp;&amp;
install -v -m644 README libpng.txt /usr/share/doc/libpng-&libpng-version;</userinput></screen>

A couple notes on style. Use spaces instead of leading tabs. Also, try to wrap any text before 80 characters if it will not break the book formatting.

To check your changes, you can see what's changed in the SVN repository:

svn diff

Checking Your Changes

Assuming you figured out how the BLFS book formatting works, you should now check that the changes you made are doing what you expect. There is a Makefile in the BOOK directory that contains all the targets needed to work with the XSL tools. Move to that directory to use it. The first thing to do is check that you haven't broken the formatting of the book.

make validate

This command will return succesfully with no output if the XSL is formatted correctly. Next, you may want to see what your change will look like in the formatted HTML. This is the default target of the Makefile and will generate the book in ~/public_html/blfs-book-xsl by default. Kick off this long process:

make

Open up a browser and point it to the formatted HTML directory to see your results.

Sharing Your Changes With the Editors

The best way to describe the change you'd like to see is in patch format.

svn diff > my-changes.diff

Now, attach this diff to an email to blfs-dev describing what the issue is and how your patch addresses it. Or, attach the diff to an appropriate ticket. Now you can sit back and wait to see if the editors will still ignore you or not. :)

Happy hacking!