As described elsewhere, one of the primary intended results of the FreeSA project is a tutorial book that describes the entire process of constructing the FreeSA distribution, so that it's easier for other people to do the same sort of thing with different hardware. The goal is to have something kind of like Linux From Scratch, but with more explanatory text about, for example, what's going on when building a cross-toolchain; and more focused on the particular platform we are using.

Ideally, someone who is reasonably familiar with Linux should be able to pick up the FreeSA book, read it, and understand the entire process of setting up the system enough that none of it seems like black sorcery any longer -- without having to figure out any arcane build processes or read three dozen Makefiles or anything like that. Because Random really likes printed output, he's keen to have one of the output formats for the book be an actual book, nicely typeset and everything. Eric likes things to be accessible over the web, so he's more enthusiastic about HTML or XHTML as an output format.

Since we also want to automate the entire process of constructing a FreeSA system, as much as possible, it would be great if the source files for the book were in some sort of literate programming-style form that could be mechanically transformed into a set of scripts that actually do the work of constructing a FreeSA system. One important reason to automate the process is to make keeping the book up to date more feasable; it is important to lower the effort to test the combined build as various packages are updated over time.

And, of course, since we are lazy, we'd like it to be as easy as possible to write the actual book, with a source format that doesn't get in our way or require us to learn anything new.

This page is here to provide a place for discussing how we might achieve all of those goals.

XML

The first thing that leaps to mind when considering a document format that can easily produce multiple types of output and can be mechanically transformed is XML. That's what the Linux From Scratch guys use, for example, and it seems to work pretty well for them.

If you start by thinking about XML, the next thing that comes to mind is what kind of XML format (DTD or XSD or whatever) to use. One such format that seems to be pretty popular is Docbook. Another format, come to think of it, is the one used by Linux From Scratch. Both are at least somewhat worth considering; but Random leans toward Docbook on the grounds that it is used all over the place.

Can docbook be used or extended in such a way that code and shell-command snippets can be easily extracted from the source files and assembled into automated scripts? How hard will it be to write a program that does that extraction and assembly? Should we use XSLT for that, or something else, like (say, for example) Ruby?

What's a good editor to use for large and reasonably-complicated docbook books?

Are there existing tools that convert a docbook book into TeX or LaTeX for typesetting?

LaTeX

LaTeX is great for printed books and lousy for essentially everything else. However, the LyX editor looks like it is reasonably nice to use, and can apparently export to Docbook and possibly other formats. Maybe it deserves a look?

Text

A format that doesn't get a lot of attention when thinking about the source format for a book is plain text, presumably with a very simple markup scheme like WikiFormatting or markdown. Plain text has some advantages: everyone already knows how to use it, and has proficiency with editors that support it.

The downside is that there aren't really any tools that support transformation of arbitrary plain text into anything neat.

Wiki

We could put everything in a wiki, like maybe a MediaWiki?. Then it would be easy for anyone to change bits of it, for example. It's not totally clear how you'd convert a big pile of wiki pages into a book, though.

None of the Above

Maybe we should just create (using test-driven development) enough of a literate programming environment that we can maintain a single canonical source form for the book, and extrude PDFs (through a docbook publishing chain, or through a LaTeX publishing chain) or scripts as needed?