Source Structure

Course sources are stored in the "src/" directory using a modular architecture.

Each book is contained in a directory. All resources core to a book reside in this directory. Resources common to all books are stored in the root of "src/".

The driver file of a book is named by the same name as the directory. For example: The "System Administration Course" resides under "src/sys-admin/". The driver file is therefore called "sys-admin.xml". All information pertaining to a book is included in "sys-admin.xml" by entity reference.

All document sources are stored in Docbook XML format. We always try keep to the latest OASIS version of the DTD.

To contribute, you should have knowledge of Docbook. If you don't, then use any word processor to author your documents and ask somebody on the list if they can convert it to Docbook XML. Open a ticket for it in Issue Tracker and attach your file to it. However, to make optimim use of the project sources we suggest you start to learn about Docbook. The Docbook web site is a good place to start.

XML Declaration

All documents begin with an XML declaration. Specification of the version of XML ensures that future changes to the XML specification will not alter the semantics of this document. Specification of the encoding method ensures that all documents will be encoded using a recognized Unicode standard. Unicode provides a unique number for every character, no matter what the platform, no matter what the program, no matter what the language. To ensure a common encoding standard, all English versions of course documents are encoded as "UTF-8".

<?xml version="1.0" encoding="UTF-8"?>

Document Type Declaration

The document type declaration identifies the DTD that will be used by the document and what the root element of the document will be. A typical doctype declaration for a Docbook document looks like this.

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.docbook.org/xml/4.3/docbookx.dtd" [ <!ENTITY % globalents SYSTEM "../global.ent"> %globalents; ]>

The entity "globalents", references to "global.ent". This is a single file used to store all project entities. Read this file to get an idea of the entities used in the project. Add new entities to this file if required.

All documents use this file. When creating new documents, adjust your internal subset to reference these files.

With the exception of files that are included into a "bookinfo" element structure, all files must define a Document Type Declaration. Files included by entity reference will have the Document Type Declaration commented, since a "DOCTYPE" is not allowed in a document included by entity reference.

<!-- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.docbook.org/xml/4.3/docbookx.dtd" [ <!ENTITY % globalents SYSTEM "../global.ent"> %globalents; ]> -->

While editing you can simply uncomment the "DOCTYPE" to allow validation checks without having to continuosly open or swith to the books' driver file.

Document Roots

The highest root element used in the project is the "book" element. Documents of type "book" are driver files that include "chapter" documents. With the exception of structures contained within the "bookinfo", we do not further refine the modularity at this time.