To build a HTML from the XML source code, you will see the following steps:

To build HTML do the following:

To build a PDF from the XML source code, you will see the following steps:

To build a PDF do the following:

If you work on only one chapter, transforming the whole book is a waste of time. You can save time if you use the ROOTID parameter. For example, if you have a chapter with an id attribute value of chap.foo, use the following procedure:

In a PDF with lots of pages, it can be difficult to find the correct file if you find an error. For this purpose, we inserted the Debugging Mechanism.

You only need to set an environment variable, and the process automatically generates a PDF with filenames in it. Of course, this PDF is only for debugging purposes and is not to be published!

To create a PDF with filenames in it, do the following:

Validation errors are fatal when they appear in the profiled source code. If some error occurs, you must modify the original source code in a way that the profiled code becomes valid. Therefore, you have to fix the error in a completely different file than where it is found in the first place. There are two mechanisms that may be used to validate the profiled source code:

The target make bigfile is a workaround for a bug in xmllint that occurs in versions before 2.6.15. When you use this target, you find the complete book in tmp/$(BOOK).xml. The only way to handle errors then is to look up the error in this huge file, and then find the same error somewhere in the xml sources to fix it.

If you call make validate, all validation errors will be listed with the filename and line number of the profiled sources. This means that, depending on the profiling options, the error might be exactly at the same place in the source files, or in a later line. If you have problems finding the error, you can look up the profiled sources at the specified line number and then find the same lines in the original files.

If you get an error that says that, some element does not follow the DTD, you have another way to search for the problem:

Element table content does not follow the DTD, expecting
(title , tgroup), got (tgroup )
Document profiled/x86-amd64-em64t_slprof-slpers_0_0/MAIN.box.xml does not validate

In this example, the error first says, that the problem occurs in a table. The error also tells you which XML structure has been found, and what was expected. In this case, the DTD expected a title element inside the table before starting with the actual table content.

Another common problem is having data outside of XML tags. Such an error may looks like the following:

Element table content does not follow the DTD, expecting
(title , tgroup), got (title CDATA tgroup )
Document profiled/x86-amd64-em64t_slprof-slpers_0_0/MAIN.box.xml does not validate

In this example, there is a character, that is not whitespace between the title of a table and the table content. Please note that sometimes such characters are not displayed because they might not be a printable characters. In such cases, the easiest fix is to remove all whitespace, and then format the xml again.

Most of the problems are found by make validate, but a view things are not detected by this method. The FO-processor XEP detects at least one more type of problem: whether index ranges have matching start and end elements. This kind of error is quite clearly described in the output of XEP. If you have any doubt, please compare the specified elements with the original English version.

If you build a PDF and XEP complains about some missing fonts you didn't install the configuration file for XEP. Look at Procedure 4, “Building PDF” and begin with Step 2.

The command line utility make reads a file Makefile that includes a rule set for creating and converting files. The Makefile in a project directory just includes the file common.mk in suselx/novdoc/make.

First, select which project to work on. This is done by sourcing an ENV- file that contains the needed information to build a certain book.

source ENV-styleguide

After this, you can use the build environment in your current shell.

Before you transform your XML document, you must take care that the complete document is valid. If only one file is invalid, the process stops and you do not get your desired output format. This has nothing to do with the make process itself. It is the design of XML. You can only get predicted results if the input files adhere to a certain structure.

If you want to validate your document without building, use the command

make validate

The make process takes care of profiling the files then validates the entire document. To validate only single files, use:

make validatesingle

	Validating Single Files
Validating single files can give unexpected results. In general, some sections or files depend on others. This can make validation difficult.

Add new images under images/src in the subdirectory of the correct format. Currently, two formats are supported.

If you have a format that is not listed above, convert it into the supported format. For historical reasons, there is a FIG format, too. New files should be created and saved as SVG or PNG.

	Support for Other Formats
There is no need to use formats other than PNG. Other bitmap formats, like JPEG or GIF, can easily be converted into PNG. Make sure that you always use PNG. For other vector formats, check if your graphic program allows exporting SVG. If this is not possible, export to PNG. When in doubt, ask the authors of this guide.

Our books can be transformed into two target formats: HTML and PDF. Use HTML for online versions and PDF for a nice printout. To create HTML, type:

make html

To create PDF, type:

make pdf

This creates lots of messages. The HTML files are saved into html. To view it, point a browser to index.html in this directory.

For creating a PDF, just enter make. The resulting PDF appears in the current directory and has the name $(BOOK).pdf.

You need to read this section only if you want to support a new language that is not available in our Subversion repository. Other users can skip this section.

XEP supports hyphenation in different languages. It uses the same algorithm as LaTeX. Therefore you can use the same files from LaTeX in XEP.

We distinguish between these two possible options:

Our XML source code contains comments in two forms: as XML comments and as remark elements. Both are used frequently and look like this:

<!-- This is an XML comment -->
... 
<remark>Here comes a remark comment</remark>

You do not need to translate comments. They are only informative text for writers or even for you. Sometimes there is language-specific information, so we inform you about these issues in a comment or remark.

Computer output and input often contains whitespace (space and linebreaks). Make sure that you do not insert or delete spaces inside a screen element. Every space here is considered essential.

In general, screen contents should be translated only in rare cases.

Entities are placeholders for text or other XML structures. An entity name must never be translated! An entity looks like: &entityname;.

Copy id attributes from the original English source code to the target language. This is important. If you omit this step, correct references cannot be created. An id attribute looks like this (bold text):

<sect1 id="sec.foo">
...
</sect1

The “normal” text occurs inside the para element. However, there are some locations where text is not allowed. For example, a description of a menu item is marked up with menuchoice and guimenu. See Example 2, “Correct use of menuchoice”.

<menuchoice>
  <guimenu>Alt</guimenu>
  <guimenu>F2</guimenu>
</menuchoice>

Don't insert text between </guimenu> and <guimenu> like in Example 3, “Incorrect use of menuchoice”.

<menuchoice>
  <guimenu>Alt</guimenu> with
  <guimenu>F2</guimenu>
</menuchoice>