5.6.1. Mass insertion of cross-references in LyX

If you have to add hundreds of cross-references in just one section (e.g. more than 500, as in Credits for version 2.0 of the PHP-Nuke HOWTO), you will soon notice that, although a single cross-reference is inserted very easily in LyX (just choose Insert->Cross-reference from the menu, then choose the label of the reference you want), it becomes a real pain if you have to enter hundreds of them.

My solution to this was to write a script that reads a LyX file and outputs another LyX file that contains references to all labels of the first one. It was then easier to copy the references from the file thus created, paste them in Credits for version 2.0 of the PHP-Nuke HOWTO and then delete the unneeded ones, than try to insert all cross-references by hand using the LyX menu.

The following script, call it lyxrefs, will print a LyX file in standard output, containing cross-references to each and every label of the LyX file whose name was passed on the command line as argument:

#!/bin/bash
#
AWK="/usr/bin/awk"
function preample() {
cat <<-EOF
#LyX 1.2 created this file. For more info see http://www.lyx.org/
\lyxformat 220
\textclass article
\language english
\inputencoding auto
\fontscheme default
\graphics default
\paperfontsize default
\papersize Default
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default
EOF
}
function label() {
n=$1
echo ""
echo "\layout Standard"
echo ""
echo ""
echo "\begin_inset LatexCommand \label{cit:$n}"
echo ""
echo "\end_inset"
}
preample
# Output LyX commands for Chapter "All references"
cat <<-EOF
\layout Section
All references
EOF
# Output all references.
$AWK 'BEGIN {FS=" "} /\\begin_inset LatexCommand \\label{/ {gsub("label","ref");
printf("\n%s\n\n%s%s\n\n%s\n","\\layout Standard",
"\\begin_inset LatexCommand",$3,"\\end_inset")}' $1 > all-references.tmp
cat all-references.tmp
rm all-references.tmp
# Output LyX commands for Chapter "All references"
cat <<-EOF
\layout Section
All figure references
EOF
# Output only the figures.
$AWK 'BEGIN {FS=" "} /\\begin_inset LatexCommand \\label{fig-/ {gsub("label","ref");
printf("\n%s\n\n%s%s\n\n%s\n","\\layout Standard",
"\\begin_inset LatexCommand",$3,"\\end_inset")}' $1 > fig-references.tmp
cat fig-references.tmp
rm fig-references.tmp
# Output LyX commands for Chapter "All references"
cat <<-EOF
\layout Section
All table references
EOF
# Output only the tables.
$AWK 'BEGIN {FS=" "} /\\begin_inset LatexCommand \\label{tab-/ {gsub("label","ref");
printf("\n%s\n\n%s%s\n\n%s\n","\\layout Standard",
"\\begin_inset LatexCommand",$3,"\\end_inset")}' $1 > tab-references.tmp
cat tab-references.tmp
rm tab-references.tmp
echo "\the_end"

The script will even create three sections, with cross-references to all labels, all figures and all tables respectively. If you named it lyxrefs, you would call it as follows:

lyxrefs some-LyX-file.lyx > refs.lyx

Then refs.lyx will contain cross-references to all labels of some-LyX-file.lyx. You can open refs.lyx with LyX, copy all or part of the cross-references there and paste them in some-LyX-file.lyx. The cross-references in Credits for version 2.0 of the PHP-Nuke HOWTO were entered this way.

5.7.1. Inline graphics

I will disappoint you: there is no way to include inline graphics with the method described in this document - see Section 7.1.6 for the reason.

Well, almost...

You have always the possibility to write SGML in LyX: just create an environment (Section 5.1) of type SGML and enter your text (in <para> elements), followed by

<inlinemediaobject>
   <![ %output.print.png; [
   <imageobject>
      <imagedata fileref="./images/1.png" format="PNG">
   </imageobject>
   ]]>
   <![ %output.print.pdf; [
   <imageobject>
      <imagedata fileref="1.pdf" format="PDF" scale="65">
   </imageobject>
   ]]>
   <![ %output.print.eps; [
   <imageobject>
      <imagedata fileref="1.eps" format="EPS">
   </imageobject>
    ]]>
   <![ %output.print.bmp; [
   <imageobject>
      <imagedata fileref="1.bmp" format="BMP">
   </imageobject>
    ]]>
   <textobject>
      <phrase>Inline graphic</phrase>
   </textobject>
</inlinemediaobject>

Substitute “1” with the basename of the inline graphic (i.e. the name without path information and without ending). Of course all necessary formats (PNG, EPS, PDF and BMP) with the right density settings must be available under the ./images directory, see Section 4.9.

Caution:

You must insert the above SGML code without introducing newline characters, which in LyX will produce <para> elements when exported to SGML. Thus, for the above sentence and inline icon, you would have to enter <para>Well, almost...<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>

5.15.1. Labels as filenames

You should always put a label after the chapter/section/subsection/subsubsection title (from the LyX menu: Insert-->Label). The text you use for the label will become the name of the HTML file that contains that chapter/section etc. See Section 7.1.5 for the code that controls this setting in the stylesheets (it is the use-id-as-filename DSSSL parameter. that does this).

SEO (Search Engine Optimization) tips

There is circumstancial evidence that the search engines (especially Google) weigh substantially the keywords that appear between <H1>, <H2>, <H3> tags (that's the chapter's and sections' titles) especially if they also appear as part of the HTML filename. You are thus well advised to follow some simple rules for your titles (er...filenames): Always create a label. Failing to do so, will produce and automatic, nothing-saying filename. You loose a potential (although small) ranking boost from the search engines, if your section is about, say, blue widgets, but is called x543.html, instead of blue-widgets.html. The label should contain the same text as the title. The title you enter in LyX will automatically be the HTML title in the header part of the resulting HTML file (this is a meta-information, not visible to you, but very well visible to the search engines), as well as the title inside the <H1>, <H2>, or <H3> tag that is produced in the HTML body automatically as well. If the label is similar to the title, then the HTML filename will be similar to the titles (meta-title and actual text title) of the text inside it. This wil be rewarded with more weight in the search engine ranking, resulting in a higher place in the SERPS (Search Engine Result Pages). And believe me, even if you hate search engines, it is much easier to find a chapter by reading "talking" filenames, like blue-widgets.html, than cryptic ones like x543.html! Dont'use blanks. Use hyphen “-” instead. This makes use of the fact that for most search engines “-” is equivalent to a blank. This is not the case for underscore “_”. Don't use illegal characters, i.e. characters that are not allowed in HTML filenames.

5.15.2. Cool labels don't change!

There is one thing to keep in mind when regrouping: chapter and section labels - DON'T change existing ones! You may change their position, but please not the label. Subsection and subsubsection labels can be changed without problem.

Why? Because chapters and sections will become separate HTML documents. There is a DSSSL stylesheet setting which controls how deep a level will still produce a separate HTML document (see the decription of chunk-section-depth in Section 7.1.5). The name of the documents will be the label of the chapter and section respectively. This is a behaviour we explicitly set in the DSSSL stylesheets (see Section 7.1.5) through the use-id-as-filename DSSSL parameter..

Obviously, you can move a section around, without affecting the HTML name of the resulting file, if you don't change its label. You can of course change its contents, put it somewhere else as a section of a different chapter etc., but you should leave the label untouched.

The problem is that, if the document is already on the Web and is receiving a lot of visits, most of them (experience suggests a number around two-thirds of the total number of visits) will be from search engines. If you change the section label, the HTML name changes. Consequently, the link from the search engines is no longer valid. The same is true for private bookmarks, or public bookmark lists.

But there is more to it: it's not only a matter of waiting 2-3 weeks for the new HTML document that contains the old (a bit reorganized) content to be indexed by the search engines. It's that the old name might have been at page 1 of the SERPS (Search Engine Result Pages) of some search engine for some keyword, because a lot of other people linked to it. Now, with a changed label and, consequently, a new HTML file name, those links do not reference the new document, and it gets a ranking close to "nowhere" (because search engines, notably Google, take links to a document to mean "votes" for that document and rank that document accordingly). The result: nobody finds it.

It's not a question of sacrificing quality!

I am not trying to tie up your hands in favour of a higher search engine ranking here! This discussion is not one of quality vs. ranking, but one of consistency. All I am advocating is: keep your labels (and consequently your filenames) consistent between various releases of your document! Once you have chosen a label for a chapter of section, stick with it. Please also note that we are not talking about the title of a chapter or section, but its label. "Label" is LyXese for the "SGML id". You get a label from the "Insert -> Label" menu of LyX. Don't confuse title and label in this discussion!

For example, suppose a chapter with the title “Blue widgets” is at around place 6 out of 2,5 million (!) for "blue widgets" on Google. If you change the label of the chapter from "blue-widgets" to something else, then the original URI will disappear and you loose readers. Of course, changing the title also affects the SERPS (Search Engine Result Pages), but not as drastically as to eliminate the document altogether. However, Google likes a title that is correlated to the file name, so a title "Blue widgets" and a label "blue-widgets" are optimal from the SEO (Search Engine Optimization) point of view (see Section 5.15.1).

“But you are talking me into subjecting my writing to the whims of a search engine!”, you might counter. Nothing more far away than that! The point is not to restrict your writing. The point is: you write whatever you like, however you like and structure it as you please. There are rules for good writing that you might choose to observe, or not. There are also rules for good “copy” , from the point of view of keywords, search engines and ranking - which you are also free to observe or defy.

Then, at some point, you decide to put the document on the web. People will come, read it and, hopefully, find it good. Those people may like your document so much, as to go into the trouble to say something like "there's a cool document on blue widgets in this link here" - and link to it. Hundreds of people may do this perhaps - even thousands. Imagine the effort!

Now you come up with a new restructuring of you document - fine! You change the content - also fine! Then you change the label from:

<sect1 id="blue-widgets"><title>Blue widgets</title>

to:

<sect1 id="blue-widgets-2"><title>Blue widgets revisited</title>

In LyX, this is equivalent to changing the title from “Blue widgets” to “Blue widgets revisited” and the label from “blue-widgets” to “blue-widgets-2”. Perhaps you thought it would be a nice idea to change the title to reflect the reorganization. This will affect your ranking too, but then, almost everything that you write will affect it, so we will not discuss it here. (Actually, it will affect it a little more because it's on the title - but that's again not the point.).

But by changing that label from “blue-widgets” to “blue-widgets-2” you just managed to throw your document from place 6 to place 600 (or 6000, or...) in the SERPS. You just killed all the efforts of thousands of people that linked to your document!

Why?

Because labels become filenames in the document process from SGML to HTML (see Chapter 7 for a detailed explanation of this process). The document that would be blue-widgets.html now is blue-widgets-2.html. The original blue-widgets.html is nowhere to be found in your domain - hundreds, or even thousands of links on the Web now point to vacuum!

Google - and every other search engine - sees this and takes the old URL out of the index. Of course, it indexes the new one. But the new one does not have any links pointing to it - not yet. And perhaps people will not be willing to go into the trouble of changing all their documents, just because you wanted to keep your freedom of choosing (and changing!) the label (and the resulting HTML filename) at your whim. Thus, noone points to the new "reorganized" document. It is rated very low and appears at place...uhmm 1 million something, out of 2,5 million results for "blue widgets", where nobody will find it and nobody will read it. Remember, the original document ranked at place 6 out of 2,5 million!

You might think that, since the label-to-filename connection exists only for the “chunked” version (the version where openjade is instructed to split the document into separate HTML files, one per chapter or section, the so-called “chunks”, as explained in Section 7.1.4.6), the “unchunked” document will save you from this disaster. You are correct, the "single chunk documents" (single, big HTML file, TXT, PDF or PS versions) will not be affected .

If you only make the big HTML file, or the TXT, PDF and PS versions of your document available on the web, then you are not affected. But if you also made the chunked HTML version available at some point, the search engines will prefer to return results from this version, than from the others.

There are various reasons for this, one of them being that search engines don't read a document that is too long till the end and will thus index small chunks much better than huge textst. Another reason is that you need more links to a PDF document, to force a search engine to consider it important for indexing.

So forget about the huge, one-chunk docs as a search engine strategy. If you want to be found by the SEs, you must rely on the chunked versions - and perhaps a little on PDF, but only a little.

However, my point goes even further: we are not talking about a user who is searching for a unique, multiple keyword phrase that identifies the content of your reorganized document. We are talking about a user who just searches for, two keywords: “blue widgets”. If you change the label, you change the filename of the chunked version. If you do so, the search engine will NOT think "Ahh...the file blue-widgets.html is not there, let's present the huge document that contains all chapters, including the one on blue widgets - at the same ranking place"! There are three resons that this will not happen - and you should not rely on it:

1. First, the search engine does not know that blue-widgets.html is just a chunk of some "whole" document, book1.html. There is nothing that a search engine does to find this out - not with today's technology. The two documents are different from the search engine point of view.

2. Second, the big one, book1.html, contains much more text, therefore the importance of the "blue widgets" chapter is "diluted" from the surrounding, irrelevant text (irrelevant to what the user is searching with those keywords, namely "blue widgets"). This has to do with “ keyword density”, titles, structure and other “on-page” factors that the search engine calculates and takes into account for each page. Therefore, the document will rank at a place that is way back - invisible to all but the most determined searchers, practically dead.

3. Third, if you are a HOWTO author, you may put your document on The Linux Documentation Project, which is a great place with good exposure to the Web, but that alone does not guarantee good ranking. What is also important, is that people link to it. But if you change an existing label, thus changing the filename of the chunked version (which is the most important one from the search engine point of view for the reasons stated above), then you kill all the links to the previous URL. You destroy what you were able to gather up to that point in terms of search engine visibility. You start anew.

Use permanent redirects, if you do choose to change the label!

Let me put a preemtive disclaimer here: I know that you can put a "HTML permanent redirect" in your .htaccess file to indicate that the resource is now somewhere else, under a different name. But this makes URL management difficult for a webmaster. How on earth shall the webmaster know which labels some author, whose document he hosts on his website, changed in his last reorganization? Is he supposed to do nothing else a whole day, other than chasing diff outputs and editing .htaccess files? Just because the author wants to keep his freedom of changing labels at his whim? Remember, if it is a free document, it will find its way to other people's websites. People may link to files of those websites containing your document, even more often than they do to yours. When you release a new version with changed labels (and accordingly, filenames), do you send a list of changed labels to all those webmasters who host it, with the request to update their .htaccess files? Certainly not. Nevertheless, if you are the author and have decided to change the label of some chapter or section, don't let your web server send an "Error 404: not found" for the old URI. Let it send a “permanent redirect” instead. See Managing URIs and the links therein, for the preferred ways to handle this situation. But again, a redirect has to be in your .htaccess file (or web conf file) until the last request has been seen in your web logs for the old URI (theoretically, at least, otherwise you loose the visitor). How long is this? One year? Ten years? How big does your .htaccess become if an author starts "reorganizing" his labels(!) every other week? How much of a performance penalty will you have to pay for your web server having to read and process huge .htaccess files on every page request? Thus, every redirect will hurt you, either in terms of visibility in the SERPS, or in terms of complexity, or both. But if you change a label, don't forget the permanent redirect.

For the above reasons, most of the time, you will not feel the need to change labels while reorganizing, but think doubly about it if you must. Your best bet is to choose a label wisely (for the same reasons that you would Choose URIs wisely), perhaps with a name that is a bit more general than you might wish, but will still fit if you choose to change content, or even title, later on.

Cool URIs don't change. Cool labels don't change either.

5.19.1. Bibliography without RefDB

As stated in Section 3.11, you are not confined to using RefDB whith my lyxtox script. If you don't feel like building your own bibliographic database, you can just supply a bibliography. lyx file together with your LyX document. Set the process_RefDB variable in lyxtox to "0" and it will use your own bibliography. lyx to produce a bibliography.sgml file, instead of trying to create one automatically through RefDB. The bibliography. lyx file should then contain the SGML code for the references list, in the SGML environment of LyX. The GNU/Linux Command-Line Tools Summary HOWTO uses this approach, for example.

This means that if you don't want to use RefDB, but still want to have a bibliography, your bibliography. lyx file should look like:

<bibliography id="references" title="References"> 
<bibliodiv>
<biblioentry xreflabel="KARAKAS1992">
<biblioset>
<author>
<surname>Karakas</surname>
<firstname>Chris</firstname>
</author>
<title>Neuronale Lernregeln und andere Methoden für lineare Assoziation und Trennung</title>
<publisher>
<publishername>BoD GmbH, Norderstedt</publishername>
</publisher>
<abstract>
<para>
An examination of neural network methods and methods from classic optimization theory for solving the problem of linear association and separation. After a formal mathematical definition of neural networks, the linear association problem and some so-called "learning rules" for its solution are considered: 
...more Abstract text here.
</para>
</abstract>
</biblioset>
</biblioentry>
...
more <biblioentry> elements here
...
</bibliodiv>
</bibliography>

The whole code should be in the LyX SGML environment (see Section 5.1 for an explanation of LyX environments). You can even insert URLs and cross-references the usual LyX way (from the LyX Insert menu) and they will be correctly exported to SGML. The layout of bibliography. lyx should be “ DocBook Chapter (SGML)” (to be set from the LyX Layout menu). You don't need anything in the preample or elsewhere. See the bibliography.lyx file in the Formats section of GNU/Linux Command-Line Tools Summary HOWTO for an example.

To cite a reference from a reference list created this way, you have to switch to the SGML environment for the whole paragraph containing the citation, then write as in the following example:

<para>
Consult <citation>KARAKAS1992</citation> for more details on
neural learning rules.
</para>

Note that we use the value of the xreflabel attribute to refer to the reference entry.

Formatting your Reference List.

Note that this way of creating a Reference List and citations does NOT cover formatting of either citations or the entries in the Reference List itself. Note also that each journal (or medium) has its own formatting expectations as far as the Bibliogrphy is concerned. You will have to write your own DSSSL driver file to accomodate for this need. RefDB (10) (Section 5.19.2) takes this burden out of your work for the slight overhead of setting up a database and installing the RefDB package (Section 3.11).

5.19.2. Bibliography with RefDB

You don't need to care about a bibliography.sgml file if you use RefDB - the lyxtox file will create it automatically with the help of RefDB, totally transparently to you. All you need is install and set up RefDB (see Section 3.11 and Section 4.13 respectively), and set the following variables in lyxtox:

• Process_RefDB to “1”.

• RefDB_db to the name of the RefDB database containing the bibliographic entries you plan to cite (you created this database in Section 3.11, the name in the example was “ck_refdb” and is the default one in lyxtox - you should of course change this).

• REFDB_style to the style of the journal you want your Bibliography to conform to.

Note that this name must contain a dot at the end, because lyxtox will create, the file ${REFDB_style}dsl.

Example: for REFDB_style="J.Biol.Chem.", lyxtox will automatically create (through RefDB) the file J.Biol.Chem.dsl, i.e. the “dsl” ending is appended without any extra dot. The default value is “J.Biol.Chem.”, one of the two standard styles shipped with RefDB, and should get you starting. See How to manage bibliography styles for more details on bibliography styles in RefDB.

The only thing that remains is... cite of course!

Citing with RefDB in LyX is a bit tricky, since LyX does not allow citing the way RefDB is expecting it: with a role attribute with the value “REFDB” in the SGML citation code. Of course, we could use a pure SGML environment as in Section 5.19.1 and write:

<para>
Consult <citation role="XXXX"><xref linkend="KARAKAS1992"></citation> 
for more details on neural learning rules.
</para>

each time we want to cite something. But there is a better way: RefDB can create that SGML code automatically, if it finds something like:

<para>
Consult <citation role="XXXX">"KARAKAS1992"</citation> 
for more details on neural learning rules.
</para>

in the SGML file. But how can we convince LyX to output something like the above for each citation when it exports our file to SGML?

The solution I found to this is:

1. Export all the bibliographic entries you plan to use in a file, say refdb.ris (see Section 4.13 on how to do this).

2. Use the awkscr_cit AWK script to create a new LyX file from refdb.ris:

   awkscr_cit refdb.ris > citlabels.lyx

   The citlabels.lyx file is a LyX file containing only labels, one for each bibliographic entry in refdb.ris. The labels have the prefix "cit:" to distinguish them from true labels. To stay with the above example, the bibliographic entry with ID “KARAKAS1992” will produce a label “cit:KARAKAS1992” in the citlabels.lyx file created by awkscr_cit.

3. Open the citlabels.lyx file in LyX, together with your document.

4. To cite an entry, you (mis)use the “Insert Cross-Reference” feature of LyX: from the LyX menu, choose “Insert -> Cross Reference”. In the upcoming dialog box there is a drop-down list field called “Buffer”. The Buffer serves as the source of the labels you want to reference. Usually, “Buffer” is set to the current file. You change this to “citlabels.lyx” by clicking on the dropdown field and choosing the citlabels.lyx file. Now you are presented with all labels of citlabels.lyx. Choose the label containing the ID of the RefDB bibliographic entry you want to cite. In our example, you choose “cit:KARAKAS1992”, if you want to cite the entry with ID “KARAKAS1992”.

That's all! Don't worry about that “cit:” prefix, sedscr takes care about it. For every cross-reference to a label of the form “cit:IDsome”, sedscr will create a citation of the form:

<citation role="REFDB">"IDsome"</citation>

in the exported SGML file. Then, lyxtox will call the aproppriate RefDB tools to transform this citation to

<citation role="REFDB"><xref linkend="IDsome"></citation>

or some more complex form according to the bibliographic style in use. Again, you don't have to worry about this procedure. Just create the citlabels.lyx file as shown above and insert cross-references to its labels in place of your citations. You don't have to bother about SGML code and you can't get the ID's wrong since you get a list of all available labels in citlabels.lyx to choose from. On the other hand, you can't get anything but “simple” citations this way, but at the moment I can live with that. See Section 7.1.10 for a detailed explanation of what lyxtox and RefDB do for you in the background to produce correctly formatted citations and a correctly formatted Reference List.

More elaborate solutions (using a citlabels.lyx file containing two or more labels for each bibliographic ID, each one with a different prefix, serving different citation purposes, "simple" or "complex" ones) are possible, but my hope is that this work will convince the LyX development team to incorporate RefDB directly in LyX in a future version. In the meantime, the method presented works fine - here and now.

5.20.1. Automatic Index generation

LyX provides an easy way to insert an Index entry (see Section 5.20): from the menu, choose either Insert-->”Index entry of preceding word” (which I personally find easier), or Insert-->”Index entry”, then enter the required word. This method works fine - if you have a small document, with only a few keywords to insert. But what if your document has grown to hundreds of pages, with hundreds (or even thousands) of index entries to insert? See the Index of the PHP-Nuke HOWTO for an example of an Index that cannot be generated manually - unless you want to drive yourself crazy!

Clearly, for a comprehensive Index of large documents, an automatic procedure is necessary. However, the general problem of automatic Index generation is subject of extensive (and still not conclusive) research and I am not going to address it in its full generality here. For our purposes, even a semi-automatic procedure would be very helpful. To this end, I have created the following 4 scripts:

• sedscr_list_index_items: lists all index entries contained in a LyX document.

• sedscr_delete_index_items: deletes all index entries from a LyX document.

• awkscr_create_index_items: creates a list of words used in a LyX document. The list can be subsequently edited manually, mostly deleting unwanted or uninteresting words, to yield a list of words that are used in the document and are interesting enough to be part of its Index.

• awkscr_insert_index_items: uses an externally supplied document containing a list of index entries to insert an index entry in a LyX document for every word appearing in that list.

They can be used in the following semi-automatic Index generation procedure:

1. Optional: create a list of all existing index entries in your document. This is useful not only because you are going to eliminate all index entries from the document in the next step, but also as a backup of the index entries that were currently in use - you might want to reuse them in some later step.

   To create a list of all existing index entries in your document, type:

   sedscr_list_index_items document.lyx > indexitems

   The generated indexitems file will contain a list of all index entries in document.lyx, one index entry per line, with a semicolon at the end of each line. The semicolon will be used later as a record delimiter in the awk scripts that follow, so don't let it irritate you.

   To get an alphabetically sorted list of index items, without duplicate entries and with all symbols at the beginning of the list, use the sort and uniq utilities as follows:

   cat indexitems | sort | uniq > indexitems.sorted mv indexitems.sorted indexitems

2. Remove all previous index entries from the LyX document. You need this preliminary step because, if you forget to remove already existing index entries, a subsequent run of the awkscr_insert_index_items script may substitute even the existing index terms (those already inside the LyX \index commands) with LyX \index commands. This may or may not happen, depending on the regular expressions used in the current implementation of awkscr_insert_index_items, but it is better to err on the side of caution. What will happen, however, is that repeated invocations of awkscr_insert_index_items will add index entries besides already existing ones. You will thus end up with a document that contains double index entries for each index term in your indexitems file.

   Besides, there is another reason why you might want to remove all index entries from your LyX document: a LyX text cluttered with index entries may still be a breeze to read for a computer, but quite a headache to read for humans.

   To remove all index entries from a LyX document, type:

   sedscr_delete_index_items document.lyx > document-noindexitems.lyx

   The generated document-noindexitems. lyx will contain everything from document.lyx - except the index entries.

3. Create a list of all index entries to be used in the LyX document. This is the most difficult part: as said above, this problem is not trivial. We will thus content ourselves with a list of all words used in the document. Once we have all words, we can still edit the list manually and delete all unwanted entries. This is what makes this procedure semi-automatic and not automatic. The idea is that it is still better having to delete 10000 lines from a 12000 line document, than having to insert 2000 index entries from the LyX Insert menu.

   To create a list of all words used in a LyX document, type:

   awkscr_create_index_items document.lyx > words

   There is even some code in awkscr_create_index_items that checks whether the current word is in some “trivia” list of trivial words and discards it. In such a case, you would call the script with two arguments, as follows:

   awkscr_create_index_items trivia document.lyx > words

   However, this part of the code is either too slow, or buggy, so it is commented for the moment (feel free to send corrections or suggestions).

   It is a good idea to sort your words alphabetically and delete double entries, so do:

   cat words | sort | uniq > words-unique mv words-unique words

   Once the list of all words of your document is created, all you have to do is open it with a text editor and delete all unwanted words or correct the ones that are in plural or have some punctuation at the end and so on. This is still hard if your document is large, but still a faster alternative than targeting the Insert menu with the mouse 8000 times (I guess each one of my 2000 index entries appears 4 times in my document, which gives me an estimate of 8000 menu selections with the mouse - unfortunately no keyboard bindings were found to work on my system).

   You should delete all lines containing characters that could be interpreted as metacharacters of regular expressions: *, +, ?, $, &, ^, \ - and probably many others. Don't try to escape them, it will not work: awkscr_create_index_items will replace the correct, string with the escaped string, adding an index entry for the escaped string too! This is not what you will want. What is rather needed here is a mechanism to search for the escaped string, but replaced it with the verbatim one (i.e. the string without the escaping backslashes). This is still work to be done (FIXME).

   Practically, this restriction means that you will have to add your index entries for symbols like *, +, ?, $, &, ^, \ manually, each time after you run awkscr_create_index_items.

4. Once you have a file, say indexitems, with all words that should appear in the Index of a LyX file, type:

   awkscr_insert_index_items indexitems - < document-noindexitems.lyx > document-indexitems.lyx

   to create from document-noindexitems. lyx a document with index entries (document-indexitems.lyx) for all words in indexitems.

	Long execution time!
	The current implementation of awkscr_insert_index_items takes really long to execute, if the indexitems file is large: For 3000 words in indexitems, producing about 9000 index entries in the final document (of which 3000 are duplicate), the script may well need 1-2 hours on a Pentium 3.4 GHz - go get a cup of coffe!

Some notes on awkscr_insert_index_items's mode of operation:

• The “-” in the above invocation is important: it forces the awk script to continue reading from standard input, after it has read indexitems. This, together with the code

  FILENAME == "indexitems" { n++ indexentry[$1] = $1 next }

  in awkscr_insert_index_items, causes the words in indexitems to be imported into the indexentry[] associative array.

• The file separator in awkscr_insert_index_items is set to the semicolon “;”, instead of the default, which is space. This makes it possible to enter index entries with more than one words. Accordingly, the awkscr_create_index_items script appends a semicolon at the end of each word it prints - you should leave these untouched!

• awkscr_insert_index_items follows a simple algorithm to insert the index entries at the right places in the document: to insert an index entry, we have to know what LyX environment (Section 5.1) we are in. In essence, this means we have to parse the LyX document. Since the \ layout commands in the LyX file do NOT have what we would call “closing tags” in other markup languages, we cannot tell awk “if you are between the start and the end of the Paragraph environment, do the following”, or anything like that - there is no easy way to find the “end “ of an environment, given all the environment nestings that are possible. Luckily, another easy way exists: whenever a \ layout command is encountered, we are in the environment specified by that \ layout command, so we only need to set a variable, call it layout, accordingly:

  /\\layout SGML/ { layout = "SGML"; print; next } /\\layout Chapter/ { layout = "Chapter"; print; next } /\\layout Section/ { layout = "Section"; print; next } /\\layout Subsection/ { layout = "Subsection"; print; next } /\\layout Subsubsection/ { layout = "Subsubsection"; print; next } /\\layout Standard/ { layout = "Standard"; print; next }

  ...and so on

• Clearly, we should not insert index entries everywhere, e.g. in the “Code” environment. That's why we check if we are in the "Standard", "Itemize", “Enumerate”, "Quotation", "Description" environment (warning: the way sedscr works currently, you should not insert index entries in the “Caption” environment) and, if we are (and only then), we substiture every word in the indexentry[] array with the LyX “insert index entry” command:

  { if ( ( layout == "Standard" || layout == "Itemize" || layout == "Enumerate" || layout == "Quotation" || layout == "Description" ) && ( inset == 0 ) ) { for (item in indexentry) { if (gsub(" " item " "," " item " \n\\begin_inset LatexCommand \\index{" indexentry[item] "}\n\n\\end_inset \n")) { continue } else if (gsub("^" item " "," " item " \n\\begin_inset LatexCommand \\index{" indexentry[item] "}\n\n\\end_inset \n")) { continue } else if (gsub(" " item "$"," " item "\n\\begin_inset LatexCommand \\index{" indexentry[item] "}\n\n\\end_inset \n")) { continue } else if (gsub(" " item ":"," " item ":\n\\begin_inset LatexCommand \\index{" indexentry[item] "}\n\n\\end_inset \n")) { continue } else if (gsub(" " item "\\."," " item ".\n\\begin_inset LatexCommand \\index{" indexentry[item] "}\n\n\\end_inset \n")) { continue } else if (gsub(" " item ","," " item ",\n\\begin_inset LatexCommand \\index{" indexentry[item] "}\n\n\\end_inset \n")) { continue } else if (gsub(" " item "\\?"," " item "?\n\\begin_inset LatexCommand \\index{" indexentry[item] "}\n\n\\end_inset \n")) { continue } else if (gsub(" " item ";"," " item ";\n\\begin_inset LatexCommand \\index{" indexentry[item] "}\n\n\\end_inset \n")) { continue } else if (gsub(" " item "\n"," " item "\n\n\\begin_inset LatexCommand \\index{" indexentry[item] "}\n\n\\end_inset \n")) { continue } else if (gsub(" " "\"" item "\""," " "\"" item "\"\n\\begin_inset LatexCommand \\index{" indexentry[item] "}\n\n\\end_inset \n")) { continue } } { print; next } } }

Some tips regarding the (necessary) manual editing of the words file, the file output by awkscr_create_index_items above:

• Leave the semicolons at the end of each line untouched! They are needed as record separators in the awk scripts.

• You will see a lot of words (or their declinations) that are not useful. It is one thing to have a lot of words and another to have a set of really useful words and phrases. That's the price we pay for the simplicity of our method.

• You may need to supply some extra terms you feel are missing from that file. Feel free to do this, awkscr_insert_index_items does not know how you created the indexitems file you give it.

• Keep backups of your word lists from subsequent runs of the scripts. Combine word lists from other projects. No matter how long your word list, only the terms that really appear somewhere, will make it to the Index, so don't worry if your list is too long - given enough computing time, that is.

• Take care to delete everything in your word list that looks like a regular expression with metacharacters - because it will be interpreted as such, with unpredictable results (unless you really know what you are doing). I once had “.*” on one line and I forgot to delete it. I then wondered how come that my document was full of index entries to “.*” while the text was almost gone! See regular expressions, for a brief introduction to regular expressions.

• Take out any “:”, “;”, “?” from the end of the words, as well as enclosing double quotes. Those characters are already taken care of when it comes to inserting the entries, i.e. the indexentries file should contain only the “pure” words, without any punctuation signs.

• Don't leave in “config” if your LyX file contains “config.php”. If you do, the latter will look ugly in the LyX editor, as it will contain an index entry for “config” just in the middle of it. This will not affect the rendered formats, however.

• Don't leave in words that might form parts of a LyX command. I once left “Enumerate” in my word list. The resulting LyX file contained an index entry for “Enumerate” in front of every item in every enumeration list! Clearly, the awk script awkscr_insert_index_items “sees” the LyX commands in the file that are invisible to you. This bug has been fixed in the current version of the script, but there maybe others lurking around.

Finally, there are a few known limitations of the collateindex script that creates the index (see Automatic Indexing with the DocBook DSSSL Stylesheets:

• Duplicate page numbers are not suppressed in the index. If the document contains three indexing hits on page 4, the generated index will contain 4, 4, 4.

• Ranges are not automatically constructed. If the document contains indexing hits on pages 4, 5, 6, and 7, the generated index will contain 4, 5, 6, 7 instead of 4-7.

6.3.1. The structure of TeX errors

The material in this section is taken from the structure of TeX errors.

TeX's error messages are reminiscent of the time when TeX itself was conceived (the 1970s): they're not terribly user-friendly, though they do contain all the information that TeX can offer, usually in a pretty concise way.

TeX's error reports all have the same structure:

• An error message

• Some 'context'

• An error prompt

The error message will relate to the TeX condition that is causing a problem. Sadly, in the case of complex macro packages such as LaTeX, the underlying TeX problem may be superficially difficult to relate to the actual problem in the "higher-level" macros. Many LaTeX-detected problems manifest themselves as 'generic' errors, with error text provided by LaTeX itself (or by a LaTeX class or package).

The context of the error is a stylised representation of what TeX was doing at the point that it detected the error. As noted in approaching errors, a macro package can tell TeX how much context to display, and the user may need to undo what the package has done. Each line of context is split at the point of the error; if the error actually occurred in a macro called from the present line, the break is at the point of the call. (If the called object is defined with arguments, the "point of call" is after all the arguments have been scanned.) For example:

\blah and so on

produces the error report

! Undefined control sequence.
l.4 \blah
          and so on

while:

\newcommand{\blah}[1]{\bleah #1}
\blah{to you}, folks

produces the error report

! Undefined control sequence.
\blah #1->\bleah
                 #1
l.5 \blah{to you}
                 , folks

If the argument itself is in error, we will see things such as

\newcommand{\blah}[1]{#1 to you}
\blah{\bleah}, folks

producing

! Undefined control sequence.
<argument> \bleah
l.5 \blah{\bleah}
                 , folks

The prompt accepts single-character commands: the list of what's available may be had by typing ?. One immediately valuable command is h, which gives you an expansion of TeXs original prcis message, sometimes accompanied by a hint on what to do to work round the problem in the short term. If you simply type 'return' (or whatever else your system uses to signal the end of a line) at the prompt, TeX will attempt to carry on (often with rather little success).

6.3.2. LaTeX errors

LaTeX output can be very verbose. Just for your reference, here is a (rather long) example of output (taken from the .log file that is created each time anew from every program involved in the process that uses TeX in the background)[10]:

This is TeX, Version 3.14159 (Web2C 7.3.1) (format=jadetex 2001.10.25)  7 JAN 2004 07:26
**EN-Book.tex
(EN-Book.tex
JadeTeX 2001/07/19: 3.11
LaTeX Font Info:    Try loading font information for T1+ptm on input line 1.
(/usr/share/texmf/tex/latex/psnfss/t1ptm.fd
File: t1ptm.fd 2000/01/12 PSNFSS-v8.1 font definitions for T1/ptm. 
)
(jadetex.cfg (/usr/share/texmf/tex/generic/babel/babel.sty
Package: babel 2001/03/01 v3.7h The Babel package
(/usr/share/texmf/tex/generic/babel/english.ldf
Language: english 2001/02/07 v3.3k English support from the babel system
(/usr/share/texmf/tex/generic/babel/babel.def
File: babel.def 2001/03/01 v3.7h Babel common definitions
\babel@savecnt=\count114
\U@D=\dimen131
)
\l@canadian = a dialect from \language\l@english 
))
(/usr/share/texmf/tex/generic/thumbpdf/thumbpdf.sty
Package: thumbpdf 2001/04/02 v2.10 Inclusion of thumbnails (HO)
Package thumbpdf Warning: You need pdfTeX in PDF mode for driver `pdftex'. 
) (/usr/share/texmf/tex/latex/ae/ae.sty
Package: ae 1998/11/17 1.0 Almost European Computer Modern
(/usr/share/texmf/tex/latex/base/fontenc.sty
Package: fontenc 2000/08/30 v1.91 Standard <application>LaTeX</application> package
(/usr/share/texmf/tex/latex/base/t1enc.def
File: t1enc.def 2000/08/30 v1.91 Standard <application>LaTeX</application> file
LaTeX Font Info:    Redeclaring font encoding T1 on input line 38. 
)
LaTeX Font Info:    Try loading font information for T1+aer on input line 96.
(/usr/share/texmf/tex/latex/ae/t1aer.fd
File: t1aer.fd 1997/11/16 Font definitions for T1/aer.
)))
(/usr/share/texmf/tex/latex/ae/aecompl.sty 
Package: aecompl 1998/07/23 0.9 T1 Complements for AE fonts (D. Roegel) 
)
Package hyperref Info: Option `plainpages' set `false' on input line 128.
Package hyperref Info: Option `colorlinks' set `true' on input line 128.
Package hyperref Info: Option `bookmarksopen' set `true' on input line 128.
Package hyperref Info: Option `colorlinks' set `true' on input line 128.
Package hyperref Info: Option `breaklinks' set `true' on input line 128.
Package hyperref Warning: Option `pagebackref' has already been used,
(hyperref)                setting the option has no effect on input line 128.
)
Elements will be labelled
Jade begin document sequence at 19

As you can see from the last line, Jade just started its work.

It goes on with font checking as follows:

(EN-Book.aux)
\openout1 = `EN-Book.aux'.
LaTeX Font Info:    Checking defaults for OML/cmm/m/it on input line 19.
LaTeX Font Info:    ... okay on input line 19.
LaTeX Font Info:    Checking defaults for T1/cmr/m/n on input line 19.
LaTeX Font Info:    ... okay on input line 19.
LaTeX Font Info:    Checking defaults for OT1/cmr/m/n on input line 19.
LaTeX Font Info:    ... okay on input line 19.
LaTeX Font Info:    Checking defaults for OMS/cmsy/m/n on input line 19.
LaTeX Font Info:    ... okay on input line 19.
LaTeX Font Info:    Checking defaults for OMX/cmex/m/n on input line 19.
LaTeX Font Info:    ... okay on input line 19.
LaTeX Font Info:    Checking defaults for U/cmr/m/n on input line 19.
LaTeX Font Info:    ... okay on input line 19.
LaTeX Font Info:    Checking defaults for PD1/pdf/m/n on input line 19.
LaTeX Font Info:    ... okay on input line 19.
LaTeX Font Info:    Checking defaults for T2A/cmr/m/n on input line 19.
LaTeX Font Info:    Try loading font information for T2A+cmr on input line 19.
 (/usr/share/texmf/tex/latex/cyrillic/t2acmr.fd
File: t2acmr.fd 1999/01/07 v1.0 Computer Modern Cyrillic font definitions
)
LaTeX Font Info:    ... okay on input line 19.
LaTeX Font Info:    Checking defaults for TS1/cmr/m/n on input line 19.
LaTeX Font Info:    Try loading font information for TS1+cmr on input line 19.
(/usr/share/texmf/tex/latex/base/ts1cmr.fd
File: ts1cmr.fd 1999/05/25 v2.5h Standard <application>LaTeX</application> font definitions
)
LaTeX Font Info:    ... okay on input line 19.
LaTeX Font Info:    Checking defaults for LECO/omseco/m/n on input line 19.
LaTeX Font Info:    ... okay on input line 19.
LaTeX Font Info:    Checking defaults for LECX/omsecx/m/n on input line 19.
LaTeX Font Info:    ... okay on input line 19.
LaTeX Font Info:    Checking defaults for LECY/omsecy/m/n on input line 19.
LaTeX Font Info:    ... okay on input line 19.
LaTeX Font Info:    Checking defaults for LEGR/omsegr/m/n on input line 19.
LaTeX Font Info:    ... okay on input line 19.
LaTeX Font Info:    Checking defaults for LEHA/omseha/m/n on input line 19.
LaTeX Font Info:    ... okay on input line 19.
LaTeX Font Info:    Checking defaults for LEIP/omseip/m/n on input line 19.
LaTeX Font Info:    ... okay on input line 19.
LaTeX Font Info:    Checking defaults for LELA/omsela/m/n on input line 19.
LaTeX Font Info:    ... okay on input line 19.
LaTeX Font Info:    Checking defaults for LETI/omseti/m/n on input line 19.
LaTeX Font Info:    ... okay on input line 19.
Package hyperref Info: Link coloring ON on input line 19.
(/usr/share/texmf/tex/latex/hyperref/nameref.sty
Package: nameref 2000/05/08 v2.18 Cross-referencing by name of section
\c@section@level=\count115
)
LaTeX Info: Redefining \ref on input line 19.
LaTeX Info: Redefining \pageref on input line 19.
LaTeX Font Info:    Try loading font information for T1+aess on input line 99.
(/usr/share/texmf/tex/latex/ae/t1aess.fd
File: t1aess.fd 1997/11/16 Font definitions for T1/aess.
) [1.0.37]
File: logo1.eps Graphic file (type eps)
 <logo1.eps>
File: logo2.eps Graphic file (type eps)
 <logo2.eps>
Overfull \hbox (2655.0092pt too wide) in alignment at lines 610--899

Somewhere from this point on, you will start seeing LaTeX processing the pages of your document one after the other - and outputting errors and warnings like the “ Overfull \hbox” above.

There are some fairly common error messages and warnings. I'll cover those here using material from the chapter on “ LyX and LaTeX errors” of the Extended Features manual for LyX, available from LyX' Help menu. You should look at a good LaTeX book for a complete listing.

• “ LaTeX Warning:“

  Anything beginning with these word is a warning message for the purpose of “debugging” the LaTeX code itself. You'll get messages like this if you added or changed cross-references or bibliography entries, in which case, LaTeX is trying to tell you that you need to make another run.

  You can by-and-large ignore these.

• “ LaTeX Font Warning:”

  Another warning message, this time about fonts which LaTeX couldn't find. The rest of the message will often say something about a replacement font that LaTeX used.

  You can safely ignore these.

• “ Overfull \hbox”

  LaTeX absolutely loves to spew these out. They are warning you about lines that were too long and run past the right margin. Almost always, this is unnoticeable in the final output. Or, only one or two characters extend past the margin. LaTeX seems to generate at least one of these messages for just about any document you write.

  You can ignore these stupid messages. Your eyes will tell you if there's a problem with something that's too wide; just look at the output.

• “ Underfull \hbox”

  Not quite as common as its cousin. LaTeX seems to like to print lines that are a bit too wide as opposed to ones that are a bit too narrow. We have no idea why.

  You can ignore these, too.

• “ Overfull \vbox” and “ Underfull \vbox”

  Warnings about troubles breaking the page. Once again, just look at the output. Your eyes will tell you where something has gone wrong.

• “ LaTeX Error: File ‘Xxxx’ not found”

  The file “Xxxx” isn't installed on this system. This usually appears because some package your document needs isn't installed. If you didn't touch the preamble or didn't use the \usepackage{} command, then one of the packages LyX tried to load is missing. Use Help->La TeX Configuration, to get a list of packages that LyX knows about. This file is updated whenever you reconfigure LyX (using Edit->Reconfigure) and tells you which packages have been detected and what they do.

  If you did use the \usepackage{} command, and the package in question isn't installed, you'll need to install it yourself.

• “ LaTeX Error: Unknown option”

  Error messages beginning with this are trying to tell you that you specified a bad or undefined option to a package. Check the package's documentation.

• “Undefined control sequence”

  If you've inserted LaTeX code into your document, but made a typo, you'll get one of these. You may have forgotten to load a package. In any case, this error message usually means that you used an undefined command.

• LaTeX Error: Undefined color `rtlred'

  Theoretically, you can define your own colours in jadetex.cfg. For example, the following block of code defines three new colours, rtlred, rtlblue and rtlgreen (the green being a bit darker than usual):

  \usepackage{color} \definecolor{rltred}{rgb}{0.75,0,0} \definecolor{rltgreen}{rgb}{0,0.5,0} \definecolor{rltblue}{rgb}{0,0,0.75}

  However, no matter where I position this code in jadetex.cfg (i.e. either before or after the call to hypersetup), I get the above error. For the time being, my remedy is to stick to the standard colours. Please inform me if you find a better solution.

  Andreas Ekenbäck (private communication) has found that by having double declarations of a colour:

  \newcmykcolor{abstractYellow}{0.02 0.02 0.35 0.0} \definecolor{abstractYellow}{cmyk}{0.02,0.02,0.35,0.0}

  in jadetex.cfg, it works. On his Fedora Core 4 workstation, he says, it is even enough to have the first declaration.

Further reading: see the chapter on “ LyX and LaTeX errors” of the Extended Features manual for LyX for tips on how to handle LaTeX errors and warnings.

6.3.3. TeX capacity exceeded

If you encounter TeX errors, especially

TeX capacity exceeded, sorry [main memory size=384000]

you may have to set in texmf.cnf (usually located in /etc/texmf, or where the TEXMFCNF environment variable (seeSection 7.1.3) shows):

main_memory = 3839999
main_memory.jadetex = 4999999
hash_extra.jadetex = 25000
pool_size.jadetex = 500000
save_size.jadetex = 15000
save_size = 8000

FYI, here's how much memory TeX used for this document (you may see such information in the .log file created by pdfjadetex which is deleted by default in lyxtox):

Here is how much of TeX's memory you used:
 4847 strings out of 15997
 36267 string characters out of 99016
 163640 words of memory out of 384000
 15827 multiletter control sequences out of 10000+15000
 68666 words of font info for 129 fonts, out of 400000 for 1000
 14 hyphenation exceptions out of 1000
 31i,12n,40p,1588b,3161s stack positions out of 300i,100n,500p,50000b,8000s

See my Jade Odyssey for more details and ideas on this and other related errors.

6.3.4. Fatal format file error; I'm stymied

Well...me too.

This what the TeX FAQ says about this error:

(La)TeX applications often fail with this error when you've been playing with the configuration, or have just installed a new version.

The format file contains the macros that define the system you want to use: anything from the simplest (Plain TeX) all the way to the most complicated, such as LaTeX or ConTeXt. From the command you issue, TeX knows which format you want.

The error message

Fatal format file error; I'm stymied

means that TeX itself can't understand the format you want. Obviously, this could happen if the format file had got corrupted, but it usually doesn't. The commonest cause of the message, is that a new binary has been installed in the system: no two TeX binaries on the same machine can understand each other's formats. So the new version of TeX you have just installed, won't understand the format generated by the one you installed last year.

Resolve the problem by regenerating the format; of course, this depends on which system you are using. On a teTeX-based system, run

fmtutil --all

or

fmtutil --byfmt=<format name>

to build only the format that you are interested in.

I got this error during the PDF processing (Section 7.1.4.7). Since pdftex is the program that was running at this stage, I tried both

fmtutil --all

or

fmtutil --byfmt=pdftex

but the problem remained.I had NOT upgraded to any new version for any of the programs involved. What I had done, was to add hundreds of cross-references (probably more than 500) in just one section (see it in Credits for version 2.0 of the PHP-Nuke HOWTO).

The solution was to upgrade pdftex from 0.13d to 1.11b (pdfTeX (Web2C 7.5.2) 3.141592-1.11b) and jadetex from 1.3 to 3.13. Note that upgrading pdftex was not enough, jadetex had to be upgraded too. Of course, you would still have to use fmtutil as above. After the upgrades, the error disappeared. As a nice by-product, document processing seems to be much faster now, although I didn't conduct any benchmarks.

6.3.5. Corrupted NFSS tables

(/usr/share/texmf/tex/latex/base/ts1cmr.fd)
! Corrupted NFSS tables.
wrong@fontshape ...message {Corrupted NFSS tables}
                                                  error@fontshape else let f...

I got this error after I used the RefDB (Section 3.11, Section 5.19, Section 7.1.10) DSSSL stylesheet modifications in the local DSSSL stylesheets (Section 4.2, Section 7.1.5) that control the output.

6.3.6. Missing $ inserted

You will probably get tons warnings like this one:

! Missing $ inserted.
<inserted text> 
                $
l.17245 ...b/a/bsd/2000/09/06/FreeBSD_Basics.html}
                                                  \endNode{}\endSeq{}\endNod...
I've inserted something that you may have forgotten.
(See the <inserted text> above.)

You can see them in the standard output, as well as in the .log file that is created automatically (if you don't see any .log file, maybe lyxtox currently deletes it - check the code). They mean that TeX tried to correct you , because it saw some character that is used in the mathematics mode and thought you might have forgotten to switch. So it inserts a $, which toggles math mode. If this is not what you intended (it will most probably not, if your .tex file is created through the procedure described here), then your only salvation is to escape the character that triggered this behaviour. This means that you may have to escape

• Slashes (/) in URLs, at least when they separate two numbers (not tested)

• Underscores (_)

• Carets (^)

• and generally everything that may have a math interpretation in TeX/LaTeX/LyX

FIXME: This needs testing! Till now, I didn't resort to escaping - and stil things work remarkably well...

6.3.7. Unprintable characters

Inevitably, sooner or later, you will hit a very nasty problem in document processing: some characters in your file will be unprintable! They may appear in the PDF as black boxes (for example , in the OT1 font encoding), or simply wrong. Here is what you can do to solve this problem:

If you are using the OT1 font encoding[11], i.e. if your jadetex.cfg file contains the line

\usepackage[OT1]{fontenc}

then you have to enter the following characters in math mode:

• (backslash)

• FIXME

If you are using the T1 font encoding, i.e. if your jadetex.cfg file contains the line

\usepackage[T1]{fontenc}

then you can use the ae and aecompl packages in order to be able to write almost every european character:

\usepackage{ae,aecompl}

You will not, however, manage to get the two symbols, , printed correctly. If your purpose was to get the french quote characters (the “guillemets”), then you could replace the ae and aecompl packages with the aeguill package, i.e. replace the above line in jadetex.cfg with:

\usepackage{aeguill}

If your purpose was to get two signs, one after another, just as if you were describing the effect of the “append” operator in

cat file1 >> file2

then you must enter the in math mode.

Note that the above holds for the standard LyX environment (see Section 5.1) and probably all other environments where you use the same font as in the body text. You don't need to worry about characters in the code environment, probably because programming code is usually written in the ASCII encoding and LyX uses CDATA in <screen> or <programlisting> environments, where ASCII (or, maybe the value of the SP_ENCODING environment variable) is the expected input encoding for Openjade.

For more information on fonts and their encodings, see FIXME.

6.4.1. Keywords not present in HTML

If you don't see the keywords in the HTML file, then this may be a bug in your stylesheets. There seems to be a bug in dbcommon.dsl (DocBook DSSSL stylesheets 1.73) that prevents this from happening for an article, where the <keywordset> in within <articleinfo>. The definition of "info-element" in dbcommon.dsl contains

((equal? (gi nd) (normalize "article")) 
  (select-elements (children nd) (normalize "artheader")))

but no reference to "articleinfo".

In dbcommon.dsl, which in my system resides in /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/common/dbcommon.dsl and belongs to packet docbook-dsssl-stylesheets-1.72-34, replace the definition of info-element with:

;; ======================================================================
(define (info-element #!optional (nd (current-node)))
  ;; Returns the *INFO element for the nd or (empty-node-list) if no
  ;; such node exists...
  (cond
   ((equal? (gi nd) (normalize "set"))
    (select-elements (children nd) (normalize "setinfo")))
   ((equal? (gi nd) (normalize "book"))
    (select-elements (children nd) (normalize "bookinfo")))
   ((equal? (gi nd) (normalize "section"))
    (select-elements (children nd) (normalize "sectioninfo")))
   ((equal? (gi nd) (normalize "sect1"))
    (select-elements (children nd) (normalize "sect1info")))
   ((equal? (gi nd) (normalize "sect2"))
    (select-elements (children nd) (normalize "sect2info")))
   ((equal? (gi nd) (normalize "sect3"))
    (select-elements (children nd) (normalize "sect3info")))
   ((equal? (gi nd) (normalize "sect4"))
    (select-elements (children nd) (normalize "sect4info")))
   ((equal? (gi nd) (normalize "sect5"))
    (select-elements (children nd) (normalize "sect5info")))
   ((equal? (gi nd) (normalize "refsect1")) 
    (select-elements (children nd) (normalize "refsect1info")))
   ((equal? (gi nd) (normalize "refsect2")) 
    (select-elements (children nd) (normalize "refsect2info")))
   ((equal? (gi nd) (normalize "refsect3")) 
    (select-elements (children nd) (normalize "refsect3info")))
   ((equal? (gi nd) (normalize "refsynopsisdiv"))
    (select-elements (children nd) (normalize "refsynopsisdivinfo")))
   ((equal? (gi nd) (normalize "article"))
   ;; Changed by root.
   ;; node-list-filter-by-gi and articleinfo inserted. 
   ;; Otherwise no keywords are created in articles.
    (node-list-filter-by-gi (children nd) (list
                                          (normalize "artheader")
                                          (normalize "articleinfo"))))
   (else ;; BIBLIODIV, GLOSSDIV, INDEXDIV, PARTINTRO, SIMPLESECT
    (select-elements (children nd) (normalize "docinfo")))))
;; ======================================================================

6.4.2. thumbpdf fails

Perhaps the most accurate indicator of a serious error in your document or settings is the failing of thumbpdf:

THUMBPDF 2.8, 2001/01/12 - Copyright (c) 1999-2001 by Heiko Oberdiek.
*** make png files / run Ghostscript ***
   **** This file has a corrupted %%EOF marker, or garbage after the %%EOF.
GNU Ghostscript 6.51: Unrecoverable error, exit code 1
!!! Error: Closing Ghostscript (exit status: 1)!

Although document processing will continue (and you might even get a quite usable document), I strongly recommend you to investigate the source of this failing and to either eliminate it, or revert to a configuration that is known to work.

However, there is an exception to this rule of thumb: if you see the error

Ghostscript internal error

the very first time you run lyxtox, don't panic. Let it finish. It is probably missing the pk fonts for the resolution of your standard printer and must generate them on the fly. This will be done later, while creating the postscript (PS) version of the document. After this is done once, you will never see this error again.

6.4.3. sed segmentation fault

On one occasion, I got the following very disturbing error:

/usr/local/bin/runsed: line 54: 27611 Segmentation fault sed -f $SEDSCR $x >/tmp/$y$$

Output of the corrected SGML file broke at a line for no apparent reason. Openjade complained (of course) with some errors, but processed the file. I noticed that something went wrong from the output of thumbpdf (see Section 6.4.2): thumbpdf prints the page number for each page it processes - and this time it only printed half that many. I was not able to find the reason for the segmentation fault. I guess it has to do with the exceptionally long line that sed had to process: LyX produces very long SGML lines. It does not break the lines at SGML tags and clutters them on one line for reasons unknown to me. That particular line was thus more than 3400 characters[12] long when it was output without the error. As soon as I added some innocent text that made it a little longer, it would cause the segmentation fault above. I guess this breaks some input line length limitation in sed. However, this is denied to be the case in the sed manual on the (non-)limitations on line length:

For those who want to write portable SED scripts, be aware that some implementations have been known to limit line lengths (for the pattern and hold spaces) to be no more than 4000 bytes. The POSIX.2 standard specifies that conforming SED implementations shall support at least 8192 byte line lengths. GNU SED has no built-in limit on line length; as long as SED can malloc() more (virtual) memory, it will allow lines as long as you care to feed it (or construct within it).

The only remedy if this limit does exist (as it seems to be in my case), is to shorten your text, or introduce a paragraph, admonition (see Section 4.7, Section 5.8), code or other environment (Section 5.1) that may persuade LyX to start a new SGML line in the exported SGML text.

6.4.4. Acrobat Reader 5 does not show thumbnails in Linux

The thumbpdf script creates thumbnails for the PDF document just fine (see Section 7.2.11). Things work fine even with a thumbpdf.tex of version 3.2 and a thumbpdf of version 2.8, i.e. even if the versions of these two files differ (in which case thumbpdf will issue a warning, see Section 6.2).

Yet, one day, I recomputed the PDF version of a document, only to discover that the thumbnails were appearing intermittently in the document: some (few) appeared, the rest showed just a blank thumbnail. After an extensive Internet search (with very few results on the subject...) and a check with both Acrobat Reader 5 for Linux and Acrobat Reader 7 for Windows, it became clear that this is a problem of Acrobat Reader 5 for Linux and large thumbnails (small thumbnails are displayed fine).

I guess there is nothing you can do about this problem, other than switch to small thumbnails (right-click on the thumbnail area to see the context menu that will allow you to choose this), or upgrade to a version of Acrobat Reader that does not suffer from this bug.

6.4.5. URLs with underscore display '&lowbar;' instead of '_'

Any URL that has an underscore in it (like the link to awkscr_insert_index_items) shows '&lowbar' in place of '_'. To correct this, you must check the checkbox “ HTML type” when you insert the URL in LyX, see Figure 6-1.

When you do this, you should NOT write underscores as '&lowbar;'. You should write an underscore as is, i.e. as '_', in both the URL and the Name fields Figure 6-1.

FIXME: This still does not solve the problem in PDFs: there, the underscore is interpreted mathematically, making the character following the underscore to appear as a subscript. Moreover, if the link does not have an ending, it gets the standard ending for PDFs, namely “.pdf” attached to it, which is definitely wrong. Try this link: awkscr_insert_index_items, in HTML and in PDF to see the difference!

6.4.6. sed: file sedscr_img line 2: Unknown option to `s'

You get the error:

editing mySGML.html
sed: file sedscr_img line 2: Unknown option to `s'
Output written to /tmp/mySGML.html_1402221460
Sed produced an empty file
- check your sedscript.
all done

When you check the offending line 2 of sedscr_img (remember that sedscr_img is dynamically generated each time you run lyxtox), you see:

s/<img src="\.\/images\/paper-sizes\.png">/<img src=".\/images\/paper-sizes.png" alt="ISO/DIN paper sizes." title="ISO/DIN paper sizes.">/g

Now it's clear what the error is: the caption to a figure contains a backslash (in "ISO/DIN"), which is used by sed as a regular expression delimiter.

The easiest solution to this seems to be: just avoid using backslash in figure captions! You cannot have everything in this world, it seems...

See Figure 4-2 for the corrected caption of this specific example.

7.1.1. Check number of parameters

As in every good script, a rudimentary parameter number check is the very first thing to do:

# Check arguments and issue a help statement, if wrong
#
if [ $# -eq 0 -o $# -gt 1 ]; then
  help 
  exit 1
elif [ $1 = "-h" -o $1 = "--help" ]; then
  help 
  exit 0
fi

If the number of parameters is not exactly 1, the output of the help() function is printed, which looks like this:

Usage: lyxtox [-h] [FILENAME_WITHOUT_.lyx_ENDING]
Creates HTML, PDF, RTF, TXT and PS output 
from a single LYX source.
Needs: lyx, runsed, sed, sedscr, jadetex.cfg, perl, openjade,
pdfjadetex, DocBook, TeX, LaTeX, thumbpdf, gzip, tar 
and all packages required from these.
See http://www.karakas-online.de/mySGML/ for a detailed 
description.
EXAMPLE
=======
If your file is myfile.lyx, then do
lyxtox myfile
go get a cup of coffee and be happy :-)
-h, --help    Display this help text

7.1.2. Set program locations

If the parameter number check is passed, some program locations are set (adapt them to our situation!):

# Program locations
# Adapt to your situation.
LYX="/usr/X11R6/bin/lyx"
SED="/usr/bin/sed"
AWK="/usr/bin/awk"
RUNSED="/usr/local/bin/runsed"
SEDSCR="sedscr"
SEDSCRMATH="sedscr_math"
SEDSCRABI="sedscr_abi"
SEDSCRAPP="sedscr_app"
SEDSCRBIB="sedscr_bib"
AWKSCRMATH="awkscr_math"
PERL="/usr/bin/perl"
COLLATEINDEX="/usr/share/sgml/docbook/docbook-dsssl-stylesheets/bin/collateindex.pl"
UNESCAPEMATH="/usr/local/bin/unescape_math.pl"
TEXMATH2PNGBMP="/usr/local/bin/texmath2pngbmp.pl"
THUMB_PDF="/usr/local/bin/thumbpdf"
OPENJADE="/usr/bin/openjade"
PDFJADETEX="/usr/bin/pdfjadetex"
JADETEX="/usr/bin/jadetex"
DVIPS="/usr/bin/dvips"
GZIP="/usr/bin/gzip"
TAR="/bin/tar"
TIDY="/usr/bin/tidy"
HTMLSPLIT="/usr/local/bin/htmlsplit.awk"
REFDBXP="/usr/bin/refdbxp"
RUNBIB="/usr/bin/runbib"
DATADIR="../"
DOMAIN="www.karakas-online.de"

Further, the stylesheet locations are set (adapt them to your situation too):

  HTML_CHUNKS_DSL="lyxtox-html.dsl"
  HTML_NOCHUNKS_DSL="lyxtox-onehtml.dsl"
  PRINT_PDF_DSL="lyxtox-print-pdf.dsl"
  PRINT_PS_DSL="lyxtox-print-ps.dsl"
  PRINT_RTF_DSL="lyxtox-print-rtf.dsl"
  PRINT_TXT_DSL="lyxtox-print-txt.dsl"

You only need to change this part, if at all. The RefDB part:

  HTML_DSL="refdb-html.dsl"
  HTML_CHUNKS_DSL="$HTML_DSL#html"
  HTML_NOCHUNKS_DSL="$HTML_DSL#onehtml"
  PRINT_DSL="refdb-print.dsl"
  PRINT_PDF_DSL="$PRINT_DSL#print-pdf"
  PRINT_PS_DSL="$PRINT_DSL#print-ps"
  PRINT_RTF_DSL="$PRINT_DSL#print-rtf"
  PRINT_TXT_DSL="$PRINT_DSL#print-txt"

works automatically and it is does not play any role how you name (or where you place) the HTML_DSL and PRINT_DSL files in this case - they will be automatically created through awkscr_refdb_html and awkscr_refdb_print with whatever filename you pass to them for their output respectively, see the source code of lyxtox.

7.1.3. Set environment variables

It's time to set some environment variables. This is where quite a lot of the “magic” is hidden! Although they are mentioned somewhere in the respective manpages, a newcomer will have probably never heard of them. The result: images cannot be found, no matter how “right” you did it, as well as some other annoyances regarding font mappings. This is because different tools read different environment variables for the same information, ignoring all the others! There is probably no way to accomodate this - other than write all relevant variables down correctly - since TeX/LaTeX were created in a different time, for different needs than SGML parsers or PDF software.

Since we entered the names of images without any path information in LyX, openjade needs to be informed of their location with the environment variable SGML_SEARCH_PATH:

# Environment variables
# openjade needs this!
# Both absolute and relative paths work!
# SGML_SEARCH_PATH="$PWD/images"
SGML_SEARCH_PATH="./images"
export SGML_SEARCH_PATH

pdftex (and pdfjadetex) will look at a different environment variable for the location of the image files: TEXPSHEADERS. For some reason which I don't fully understand, \ includegraphics with pdftex uses the TEXPSHEADERS environment variable for the additional paths to search. Also: TEXPSHEADERS contains the search path where pdftex looks up for font mapping file (pdftex.map) and encoding files (*.enc):

# pdftex (and pdfjadetex) need this.
# In my system pdftex.map is located in /var/lib/texmf/dvips/config/,
# while the .enc files are under /usr/share/texmf/dvips/base/.
# TEXPSHEADERS=":${PWD}/images//:/var/lib/texmf/dvips/config/:/usr/share/texmf/dvips/base/"
TEXPSHEADERS=":${PWD}/images//"
export TEXPSHEADERS

LaTeX, on the other side, will look at still another variable for the path to images: TEXINPUTS (TEXINPUTS is also defined in the texmf.cnf file, usually located in the directory pointed to by the TEXMFCNF environment variable):

# <application>LaTeX</application> & Co. need this!
# A relative path does NOT work!
# TEXINPUTS="$PWD/images:$TEXINPUTS"
TEXINPUTS=":${PWD}/images//"
export TEXINPUTS

The TEXMFCNF environment variable points to the directory that contains the configuration files for TeX:

TEXMFCNF="/etc/texmf/"
export TEXMFCNF

In /etc/texmf/texmf.cnf we read:

% pdfjadetex: Search path for font metric (.tfm) files.
TEXFONTS = .;$TEXMF/fonts/tfm//

The next environment variable we will have to set, is the one that passes options to thumbpdf (see Section 3.7), for the case that you wish to do so:

# You can pass options to thumbpdf through this environment variable
THUMBPDF=""
export THUMBPDF

Last but not least, openjade needs to know the locations of the SGML catalog files (see Section 4.5):

SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/sgml/CATALOG.iso_ent"
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/sgml/CATALOG.docbook-dsssl-stylesheets"
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/sgml/CATALOG.mathml-2.0"
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/sgml/CATALOG.svg-1.1"
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/sgml/CATALOG.docbook_4"
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/sgml/openjade/catalog"
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/refdb/refdb.cat"
export SGML_CATALOG_FILES

The SP_ENCODING environment variable tells Openjade in which encoding the input file is written in:

SP_ENCODING="ISO-8859-1" 
export SP_ENCODING

Encoding names are case insensitive. The following named encodings are available (see Handling of character sets in OpenSP):

For OpenSP, a suite of SGML/XML processing tools related to Openjade, there are two other environment variables that are related to SP_ENCODING (see Handling of character sets in OpenSP):

But since lyxtox does not use OpenSP, we don't need to care about these two, as the manual page of Openjade asserts:

	Openjade does not use SP_CHARSET_FIXED and SP_SYSTEM_CHARSET
	OpenJade ignores the SP_CHARSET_FIXED and SP_SYSTEM_CHARSET environment variables and always uses Unicode as its internal character set, as if SP_CHARSET_FIXED was 1 and SP_SYSTEM_CHARSET was unset. Thus only the SP_ENCODING environment variable is relevant to OpenJades handling of character sets.

7.1.4. Main part

In the main part, the hard work (for your computer) begins:

The document is exported from LyX to DocBook SGML:

$LYX -e docbook $1.lyx

The SGML that is produced by LyX has several shortcomings. They have to be corrected. This is done by calling runsed:

$RUNSED $SEDSCR $1.sgml

which is the subject of the next subsection.

	Alternative commands
	There are quite a few alternative invocations of the various tools at appropriate places in the lyxtox script, in the form of comments. These are there in order to show you how you can achieve an equivalent result through other tools.

---

7.1.4.1. Runsed, sed and sedscr

Runsed takes as argument the sedscript to run and the file against which to run it. It calls sed with sedscr as the “sed command file”. In the sedscr file itself there is another bunch of “magic” going on:

Important note:

The changes in LyX' SGML code presented here pertain strictly to LyX version 1.2.0! The 1.1.x versions needed slightly (and subtly) different changes and the same may be true for future versions of LyX. Examples of sed commands for previous LyX versions are presented in the sedscr file in comments. Use (or construct) the right sed commands for the right changes for your LyX version! The success of this method depends crucially on this.

The code

s/<\(sect[^>]*\)>\(<title>[^<]*\)<anchor \([^>]*\)>/<\1 \3>\2/g s/<\(chapter\)>\(<title>[^<]*\)<anchor \([^>]*\)>/<\1 \3>\2/g

tells sed to substitute[13]

< sect1 >< title > some title < anchor id="some label" >

with

<sect1 id="some label" ><title>some title

and

< chapter >< title > some title < anchor id="some label" >

with

<chapter id="somelabel"><title> some title

The code

/^.*<figure><title><graphic/{ s/<figure><title><graphic fileref="\([^"]*\)">[ ]*<anchor id="\([^"]*\)">\([^<]*\)<\/title>[ ]*<\/figure>/\ <figure id="\2">\ <title>\ \3\ <\/title>\ <mediaobject>\ <\!\[ \%output\.print\.png; \[\ <imageobject>\ <imagedata fileref="\.\/images\/\1.png" format="PNG">\ <\/imageobject>\ \]\]>\ <\!\[ \%output\.print\.pdf; \[\ <imageobject>\ <imagedata fileref="\1.pdf" format="PDF" scale="65">\ <\/imageobject>\ \]\]>\ <\!\[ \%output\.print\.eps; \[\ <imageobject>\ <imagedata fileref="\1.eps" format="EPS">\ <\/imageobject>\ \]\]>\ <\!\[ \%output\.print\.bmp; \[\ <imageobject>\ <imagedata fileref="\1.bmp" format="BMP">\ <\/imageobject>\ \]\]>\ <textobject>\ <phrase>\3<\/phrase>\ <\/textobject>\ <caption>\ <para>\3<\/para>\ <\/caption>\ <\/mediaobject>\ <\/figure>\ /g }

tells sed to substitute[14]

< figure >< title >< graphic fileref="imagename" > some blanks < anchor id="some id" >some title< /title >

with the more elaborate combination of figure and mediaobject elements:

<figure id="some id"> <title> some title </title> <mediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/imagename.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="imagename.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="imagename.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="imagename.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>some title</phrase> </textobject> <caption> <para>some title</para> </caption> </mediaobject> </figure>

There are some remarks due here:

• The title of the original SGML appears in three places of the new SGML: the title, the phrase for the alternative text and the caption. LyX uses the figure caption for the title and there is no way we can derive three different texts for the three different uses in the new SGML. That is why in the output document the figure title, the alternative text and the figure caption are identical.

• For the PNG format we must prefix the image file name, imagename.png, with the relative path (./images) to it, even though we set all environment variables correctly (see Section 7.1.3). This is not necesary for the other formats.

• We scale the PDF images to 100%. I used to scale them down to 65%, but this is no longer necessary, after some experimentation with various scale factors that seem to compensate for this need in the addd utility. See also Section 4.9.

• We make use of external SGML entities like %output.print.png; This is a topic of its own which is explained in detail in Section 7.2.2.

A mediaobject similar to the above (but without figure id and caption) is inserted whenever a “simple” image, i.e. one without the float element with caption, is encountered in LyX' SGML. It substitutes a line like[15]

< graphic fileref="imagename" >

with a mediaobject like

<mediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/imagename.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="imagename.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="imagename.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="imagename.bmp" format="BMP"> </imageobject> ]]> </mediaobject>

Notice that the text is now simply "Figure", since there was no caption. You may change it to something else. There is also no id available for this mediaobject, therefore you cannot cross-reference it. That's why I suggested floats in Section 5.7.

The following sed code

/^.*[^<]*<programlisting/s/<programlisting\([^>]*\)>/<screen\1>/g /^.*[^<]*<\/programlisting>/s/<\/programlisting\([^>]*\)>/<\/screen\1>/g

will substitute <programmlisting> with <screen>, while this one:

# Delete the <para> before the <tgroup> tag. s/<tgroup/<tgroup/g # Delete the </para> after the </tgroup> tag. s/<\/tgroup><\/para>/<\/tgroup>/g

will delete <para> before <tgroup> and </para> before </tgroup>.

For table captions and titles to be output correctly, you have to eliminate the <para> from any sequence </title><para><tgroup> AND you have to write a table float (see Section 5.10, in the inside of which you will have to set the title and the caption environment on one line, then press <enter>, set the environment to "Standard" (this will produce the <para> element we eliminate here) and continue with the table normally. A warning about an "end tag for element "TABLE" which is not open" is the less evil we can get and is harmless (a LyX bug in 1.2.0, not openjade's):

/<\/title><tgroup/s/<\/title><tgroup/<\/title><tgroup/

Further, for the cross-references to tables to work, we have to substitute[16]

< table >< title >< anchor id="some id" >

with

<table id="some id"><title>

This is done with the following sed code:

s/<table>[ ]*<title>[ ]*<anchor \([^>]*\)>/<table \1><title>/g

Some minor issues still remain:

Substitute 'ldquo' with 'quot' and 'rdquo' with 'quot':

s/\“/\"/g s/\”/\"/g

But we are not done with the quots yet: In <othercredit> we have to substitute[17]

& quot ;

with " :

/<othercredit/s/\&quot;/"/g

And: substitute[18]

& amp ; copy ;

with &copy. This will produce a Copyright symbol, instead of "&copy":

s/\©/\&copy/g

Also, substitute &xxxx; with the character it representes - somehow these entities do not work:

s/[/[/g s/]/]/g s/{/{/g s/}/}/g s/$/$/g s/%/%/g s/#/#/g s/|/|/g s/£/£/g s/_/_/g s/\/\\/g s/~/~/g

Finally, for the index to be created, we have to insert the index creation command. Comment this if you don't want an index: to substitute[19]

< /book >

with[20]

&index; < /book >

the following sed code is needed:

/<\/book>/s/<\/book>/\&index;\ <\/book>/

A similar sed code is there for the article document type. Currently, this part has been commented and transfered to the sedscr_abi script which inserts the entities for the Appendix, the Bibliography and the Index at once at the end of the document, before the closing </book> or </article> tags.

---

7.1.4.2. Tidying up the SGML code

Finally, two calls to runsed with sedscr_tidy and sedscr_tidy2 as the script files will “ tidy up” the SGML file:

$RUNSED $SEDSCRTIDY $1.sgml $RUNSED $SEDSCRTIDY2 $1.sgml

sedscr_tidy consists simply of the following lines:

# Author: Chris Karakas # http://www.karakas-online.de # # Part of the LyX-to-X project. # See http://www.karakas-online.de/mySGML/ for a detailed # description. # # Copyright (c) 2004, Chris Karakas # http://www.karakas-online.de # chris at mydomain dot de (see above for my domain) # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2, or (at your option) # any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; see the file COPYING. If not, write to # the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. { s/\([^\n]\)</\1\ </ s/>\([^\n]\)/>\ \1/ P D }

It does practically nothing else than insert a newline before an opening bracket (a "<") or a closing one (a ">"). After this transformation has taken place for the whole document, runsed is called with sedscr_tidy2 as the sed script:

# Author: Chris Karakas # http://www.karakas-online.de # # Part of the LyX-to-X project. # See http://www.karakas-online.de/mySGML/ for a detailed # description. # # Copyright (c) 2004, Chris Karakas # http://www.karakas-online.de # chris at mydomain dot de (see above for my domain) # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2, or (at your option) # any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; see the file COPYING. If not, write to # the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. /<entry/{ N s/<entry \([^>]*\)>[ \n\t]*<para>/<entry \1><para>/ p d } /<\/para/{ N s/<\/para>[ \n\t]*<\/entry>/<\/para><\/entry>/ p d } /DATA/{ N s/\n]]>/]]>/ P D } /<citation/{ N N s/\n//g p d }

sedscr_tidy2 will do some corrections, because the changes of sedscr_tidy went a bit too far:

• It will delete any newline before the closing "]]>" of CDATA elements

• and it will bring <entry> and <para> elements on the same line, i.e. it will delete any newlines between them. It will do the same for the closing </para> and </entry> pairs. Both pairs occur inside tables and due to the Pernicious Mixed Content Problem they should not contain any line feed or space in-between, or the parser will think that the table cell contains inline markup and issue the warning that the “ document type does not allow element <para>” at that place. See the discussion of the “ document type does not allow element <para>” error in Section 6.2, as well as in Openjade error: <para> not allowed after <entry>.

Tidy scripts mess up code snippets

The tidy scripts will mess up any part of your file that contains the < and > brackets. Especially code that is included verbatim (i.e. without the use of some external entity) and contains such brackets will look awkward. Callouts will also be affected. I have deactivated the call to the scripts in the lyxtox file until I find a better solution (BTW, nsgmls will break with errors so it does not lend itself to SGML code tidying either). If potentially affected code is included with the help of an external entity though, then the tidy scripts might work fine for you.

# Key combinations
#
# CTRL-X-Y
s/\([^-]\)CTRL-\([^-. &<]*\)-\([^-. &,)<]*\)/\1\
<keycombo>\
    <keycap>CTRL<\/keycap>\
    <keycap>\2<\/keycap>\
    <keycap>\3<\/keycap>\
<\/keycombo>\
<indexterm>\
    <primary>CTRL_\2_\3<\/primary>\
<\/indexterm>\
/g

<keycombo>
    <keycap>CTRL</keycap>
    <keycap>X<\/keycap>
    <keycap>Y<\/keycap>
</keycombo>
<indexterm>
    <primary>CTRL_X_Y</primary>
</indexterm>

# Acronyms
# PHP, GNU, EOF, Python, POSIX, GUI, LDP...
s/\([ .\t\r\n]\)PHP\([ .\t\r\n]\)/\1<acronym>PHP<\/acronym>\2/g
s/\([ .\t\r\n]\)GNU\([ .\t\r\n]\)/\1<acronym>GNU<\/acronym>\2/g
s/\([ .\t\r\n]\)EOF\([ .\t\r\n]\)/\1<acronym>EOF<\/acronym>\2/g
s/\([ .\t\r\n]\)Python\([ .\t\r\n]\)/\1<acronym>Python<\/acronym>\2/g
s/\([ .\t\r\n]\)POSIX\([ .\t\r\n]\)/\1<acronym>POSIX<\/acronym>\2/g
s/\([ .\t\r\n]\)GUI\([ .\t\r\n]\)/\1<acronym>GUI<\/acronym>\2/g
s/\([ .\t\r\n]\)LDP\([ .\t\r\n]\)/\1<acronym>LDP<\/acronym>\2/g
s/\([ .\t\r\n]\)IDE\([ .\t\r\n]\)/\1<acronym>IDE<\/acronym>\2/g
s/\([ .\t\r\n]\)RPM\([ .\t\r\n]\)/\1<acronym>RPM<\/acronym>\2/g
s/\([ .\t\r\n]\)PGP\([ .\t\r\n]\)/\1<acronym>PGP<\/acronym>\2/g
s/\([ .\t\r\n]\)GPG\([ .\t\r\n]\)/\1<acronym>GPG<\/acronym>\2/g
s/\([ .\t\r\n]\)ID\([ .\t\r\n]\)/\1<acronym>ID<\/acronym>\2/g
s/\([ .\t\r\n]\)BW\([ .\t\r\n]\)/\1<acronym>BW<\/acronym>\2/g
s/\([ .\t\r\n]\)ASCII\([ .\t\r\n]\)/\1<acronym>ASCII<\/acronym>\2/g
s/\([ .\t\r\n]\)CPU\([ .\t\r\n]\)/\1<acronym>CPU<\/acronym>\2/g

# Product names
# UNIX, Linux, Acrobat, Windows...
s/\([ .\t\r\n]\)UNIX\([ .\t\r\n]\)/\1<productname>UNIX<\/productname>\2/g
s/\([ .\t\r\n]\)Linux\([ .\t\r\n]\)/\1<productname>Linux<\/productname>\2/g
s/\([ .\t\r\n]\)Acrobat\([ .\t\r\n]\)/\1<productname>Acrobat<\/productname>\2/g
s/\([ .\t\r\n]\)Windows\([ .\t\r\n]\)/\1<productname>Windows<\/productname>\2/g
s/\([ .\t\r\n]\)Mandrake\([ .\t\r\n]\)/\1<productname>Mandrake<\/productname>\2/g
s/\([ .\t\r\n]\)SuSE\([ .\t\r\n]\)/\1<productname>SuSE<\/productname>\2/g

# Applications
# TeX, LaTeX, Acrobat Reader, PHP-Nuke
s/\([ .\t\r\n]\)TeX\([ .\t\r\n]\)/\1<application>TeX<\/application>\2/g
s/\([ .\t\r\n]\)LaTeX\([ .\t\r\n]\)/\1<application>LaTeX<\/application>\2/g
s/\([ .\t\r\n]\)Reader\([ .\t\r\n]\)/\1<application>Reader<\/application>\2/g
s/\([ .\t\r\n]\)PHP-Nuke\([ .\t\r\n]\)/\1<application>PHP-Nuke<\/application>\2/g
s/\([ .\t\r\n]\)Perl\([ .\t\r\n]\)/\1<application>Perl<\/application>\2/g
s/\([ .\t\r\n]\)Java\([ .\t\r\n]\)/\1<application>Java<\/application>\2/g

<acronym>GNU</acronym>

<productname>Linux</productname>

<application>TeX</application>

${SED} -n -f ${SEDSCRIMA} $1.sgml > ${SEDSCRIMG}

${SED} -n -e '/<\!ENTITY/s/.*graph\([^ ]*\) "\([^>]*\)".*>/s\/graph\1\/\2\/g/p' $1.sgml > ${SEDSCRGRA}

${RUNSED} ${SEDSCRGRA} ${SEDSCRIMG}

${RUNSED} ${SEDSCRAPA} ${SEDSCRIMG}

echo 's/"\.\/images\/icon_smile\.png">/".\/images\/icon_smile.png" alt="smile" title="smile">/g' 
>> ${SEDSCRIMG}
echo 's/"\.\/images\/icon_wink\.png">/".\/images\/icon_wink.png" alt="wink" title="wink">/g' 
>> ${SEDSCRIMG}
echo 's/"\.\/images\/icon_cool\.png">/".\/images\/icon_cool.png" alt="cool" title="cool">/g' 
>> ${SEDSCRIMG}
echo 's/"\.\/images\/icon_eek\.png">/".\/images\/icon_eek.png" alt="shock" title="shock">/g' 
>> ${SEDSCRIMG}
echo 's/"\.\/images\/icon_frown\.png">/".\/images\/icon_frown.png" alt="frown" title="frown">/g' 
>> ${SEDSCRIMG}

s/<img src="\.\/images\/general-info\.png">/<img src=".\/images\/general-info.png" 
alt="General document info." title="General document info.">/g
s/<img src="\.\/images\/paper-sizes\.png">/<img src=".\/images\/paper-sizes.png" 
alt="ISO-DIN paper sizes." title="ISO-DIN paper sizes.">/g
s/<img src="\.\/images\/insert-url\.png">/<img src=".\/images\/insert-url.png" 
alt="Insert URL with underscores in LyX." title="Insert URL with underscores in LyX.">/g
s/<img src="\.\/images\/page-area-model\.png">/<img src=".\/images\/page-area-model.png" 
alt="CSS page area model." title="CSS page area model.">/g
s/<img src="\.\/images\/fonts\.png">/<img src=".\/images\/fonts.png" 
alt="Document Info: Fonts." title="Document Info: Fonts.">/g
s/"\.\/images\/icon_smile\.png">/".\/images\/icon_smile.png" alt="smile" title="smile">/g
s/"\.\/images\/icon_wink\.png">/".\/images\/icon_wink.png" alt="wink" title="wink">/g
s/"\.\/images\/icon_cool\.png">/".\/images\/icon_cool.png" alt="cool" title="cool">/g
s/"\.\/images\/icon_eek\.png">/".\/images\/icon_eek.png" alt="shock" title="shock">/g
s/"\.\/images\/icon_frown\.png">/".\/images\/icon_frown.png" alt="frown" title="frown">/g

# Clean previous HTML files.
rm $1/*.html
# Clean previous image files.
rm -rf $1/images
# Clean rsync backup copies.
rm -rf $1/*~

rm index.sgml
$PERL $COLLATEINDEX -p -g -o index.sgml HTML.index

cp -av images $1/

$OPENJADE -t rtf -d $PRINT_RTF_DSL  -i "output.print.bmp" $1.sgml

$LYNX -dump -nolist $1.html > $1.txt

PRINTER="cmz"
export PRINTER
$OPENJADE -t tex -d $PRINT_PS_DSL -o $1.tex -i "output.print.eps" $1.sgml
# Compress PS
$GZIP $1.ps

$JADETEX $1.tex
$JADETEX $1.tex
$JADETEX $1.tex

$SGMLTOOLS -b ps -s sgmltools-ps -j "-i output.print.eps" $1.sgml

mv $1.txt $1.rtf $1.pdf $1.ps.gz $1/
mv $1.html $1/
rm $1.tpt $1.log $1.aux $1.out $1.tex
rm $1/images/*.pdf $1/images/*.eps $1/images/*.gif $1/images/*.jpg
rm $1/images/*/*.pdf $1/images/*/*.eps $1/images/*/*.gif $1/images/*/*.jpg
cp $1.sgml $1/

7.1.5. DSSSL stylesheets

In Section 4.2 we copied these .dsl files to the current working directory:

• lyxtox-print.dsl, lyxtox-print-pdf.dsl, lyxtox-print-ps.dsl, lyxtox-print-rtf.dsl, lyxtox-print-txt.dsl and lyxtox-print-howto.dsl. These control the style of the print formats (i.e. all formats except HTML).

• lyxtox-html.dsl: this file controls the HTML output in many HTML files (one HTML file per section).

• lyxtox-onehtml.dsl: this file controls the HTML output in one big HTML file (Jade option: nochunks).

Every change you wish to do should normally go in one of these three files - often even to more than one, e.g. when your change affects the HTML output for both one and many files (“chunks”). You should leave the original files that came with the Norman Walsh stylesheets unchanged and put your changes in the above files instead. Technically, this amounts to writing your own “driver” file. This is the easiest way to incorporate your preferences and remain flexible during upgrades.

TXT and HOWTO print targets

Currently, the lyxtox-print-txt.dsl and lyxtox-print-howto.dsl are not used, but are included here for your convenience and for the sake of completeness. You can thus see the common pattern used in all print stylesheets and use it for your own purposes. For the TXT format I currently use the “onehtml” target: after the one, big HTML file has been rendered, Lynx (the text browser) is called with the -dump and -nolist options to create a text version directly from HTML, without any stylesheet for text. Note that, for a very complex document like the PHP-Nuke HOWTO (more than 500 pages, 1000 links to external URLs, 1500 cross-references, 2500 Index entries, 400 files in the “chunked” HTML version), the call to sgmltools with the “-b txt” option breaks with an error (caused probably by too many warnings about cross-references), although it works with smaller and less complex documents. The “howto” print target is not used at all, but is included following the example of the print.dsl file that comes with the original sgmltools package.

The basic driver file looks like this (see Customizing the Stylesheets):

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY dbstyle SYSTEM "docbook.dsl" CDATA DSSSL>
]>
<style-sheet>
<style-specification use="docbook">
<style-specification-body>
;; your stuff goes here...
</style-specification-body>
</style-specification>
<external-specification id="docbook" document="dbstyle">
</style-sheet>

Make sure that you specify, in the system identifier, the full path to the docbook.dsl file that you want to customize; for example, /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/print/docbook.dsl (this is already done in the stylesheets provided, at least as long as your other settings, like Catalogs (Section 4.5) are correct).

You can add your own definitions, or redefinitions, of stylesheet rules and parameters where

;; your stuff goes here...

occurs in the example above.

A lot of work, research and experimentation has been invested in the above three stylesheet files, so let's explain some of the most important changes they introduce:

• To generate a Table of Contents for articles, %generate-article-toc% has been set to true:

  (define %generate-article-toc% ;; Should a Table of Contents be produced for Articles? #t)

• To get a title page for articles, %generate-article-titlepage% has been set to true:

  (define %generate-article-titlepage% ;; Should an article title page be produced? #t)

• The CSS has been set to “ck-style.css”:

  (define %stylesheet% ;; Name of the stylesheet to use ;; #f) "ck-style.css")

  Note that this setting will be overwritten by the technique described in Chapter 8. You will have to enter the correct CSS in part2 too. The CSS file used here, ck-style.css, is a CSS for DocBook, especially crafted for the classes that appear in the automatically generated HTML code of the DocBook stylesheets. It incorporates some other fine features as well, like an elaborate font-controlling mechanism that passes the accessibility tests (see Chapter 9) and is still browser-independent, or a user-specified icon as a list bullet - up to a rotating globe that appears besides links that do not belong to a user-specifiable “local” domain (i.e. links that point “outside” the document collection currently viewed). The CSS file is discussed in detail in Section 7.1.8.

• The width of the table that contains verbatim environments (like program listings) has been set to max. 95%. This is not the same as the value used in the CSS (see Section 7.1.8) for the PRE.SCREEN and PRE.PROGRAMLISTING environments, which should be 100%.

  (define ($table-width$) ;; REFENTRY table-width ;; PURP Calculate table width ;; DESC ;; This function is called to calculate the width of tables that should ;; theoretically be "100%" wide. Unfortunately, in HTML, a 100% width ;; table in a list hangs off the right side of the browser window. (Who's ;; mistake was that!). So this function provides a way to massage ;; the width appropriately. ;; ;; This version is fairly dumb. ;; /DESC ;; AUTHOR N/A ;; /REFENTRY (if (has-ancestor-member? (current-node) '("LISTITEM")) "90%" "95%"))

• “PDF” has been added to the list of mediaobject notations. Otherwise, no images will be displayed in PDF (see also Section 7.2.2):

  (define preferred-mediaobject-notations (list "PDF" "EPS" "PS" "JPG" "JPEG" "PNG" "linespecific")) (define preferred-mediaobject-extensions (list "pdf" "eps" "ps" "jpg" "jpeg" "png"))

• The default graphic extension has been changed to “png”:

  (define %graphic-default-extension% ;; REFENTRY graphic-default-extension ;; PURP Default extension for graphic FILEREFs ;; DESC ;; The '%graphic-default-extension%' will be ;; added to the end of all 'fileref' filenames on ;; 'Graphic's if they do not end in one of the ;; '%graphic-extensions%'. Set this to '#f' ;; to turn off this feature. ;; /DESC ;; AUTHOR N/A ;; /REFENTRY ;; #f) "png")

• “pdf” and “tex” have been added to the list of graphic extensions - otherwise you will get errors (see Chapter 6):

  (define %graphic-extensions% ;; REFENTRY graphic-extensions ;; PURP List of graphic filename extensions ;; DESC ;; The list of extensions which may appear on a 'fileref' ;; on a 'Graphic' which are indicative of graphic formats. ;; ;; Filenames that end in one of these extensions will not have ;; the '%graphic-default-extension%' added to them. ;; /DESC ;; AUTHOR N/A ;; /REFENTRY '("gif" "jpg" "jpeg" "png" "tif" "tiff" "eps" "epsf" "pdf" "tex"))

• Use graphics for admonitions (see Section 4.7) and callouts (see Section 4.8):

  (define %admon-graphics% ;; Use graphics in admonitions? #t) (define %callout-graphics% ;; If true, callouts are presented with graphics (e.g., reverse-video ;; circled numbers instead of "(1)", "(2)", etc.). ;; Default graphics are provided in the distribution. #t)

• The admonition graphics path has been set to “./images”:

  (define %admon-graphics-path% ;; Path to admonition graphics ;; Sets the path, probably relative to the directory ;; where the HTML files are created, to the admonition ;; graphics. ;; ;; This needs to be "./images/" for tar distributed articles ;; This needs to be "../images/" for tar distributed Newbiedoc book ;; This needs to be "../images/" for individual articles on our website "./images/")

• The callouts graphics path has been set to "./images/callouts/":

  (define %callout-graphics-path% ;; Sets the path, probably relative to the directory where the HTML ;; files are created, to the callout graphics. "./images/callouts/")

• The callout graphics extension has been set to “png”:

  (define %callout-graphics-extension% ;; REFENTRY callout-graphics-extension ;; PURP Extension for callout graphics ;; DESC ;; Sets the extension to use on callout graphics. ;; /DESC ;; AUTHOR N/A ;; /REFENTRY ".png")

• The code that produces the full name of admonitions has been changed:

  (define ($admon-graphic$ #!optional (nd (current-node))) ;; Admonition graphic file ;; Given an admonition node, returns the name of the ;; graphic that should be used for that admonition. (cond ((equal? (gi nd) (normalize "tip")) (string-append %admon-graphics-path% "tip." %graphic-default-extension%)) ((equal? (gi nd) (normalize "note")) (string-append %admon-graphics-path% "note." %graphic-default-extension%)) ((equal? (gi nd) (normalize "important")) (string-append %admon-graphics-path% "important." %graphic-default-extension%)) ((equal? (gi nd) (normalize "caution")) (string-append %admon-graphics-path% "caution." %graphic-default-extension%)) ((equal? (gi nd) (normalize "warning")) (string-append %admon-graphics-path% "warning." %graphic-default-extension%)) (else (error (string-append (gi nd) " is not an admonition.")))))

• In lyxtox-print.dsl (which uses elements taken from Mandrake's manual-print.dsl), in order to be able to have URLs in PDF:

  ;; Inserted in order to be able to get URLs in PDF documents. ;; Adapted from manual-print.dsl of <productname>Mandrake</productname>. ;; Include the flow object class "formatting-instruction" : ONLY for Jade (declare-flow-object-class formatting-instruction "UNREGISTERED::James Clark//Flow Object Class::formatting-instruction") ;; *** URLs *** ;; Original : dblink.dsl (element ulink (sosofo-append ;; If you allow process-children here, you will get the text printed once more! ;; (process-children) ;; Write the text with its format (anchor in HTML) (make formatting-instruction ;; Write : " \href{" + theUrl + "}{" + theText + "}" data: (string-append " \\href{" (attribute-string (normalize "url")) "}{" (data-of (current-node)) "}") ) ) ) ;; These three elements are from "dbindex.dsl". ;; Must be placed here because of the redifinition of "ulink". ;; Otherwise the Index entries will point to HTML files, ;; instead of page numbers. (element (primaryie ulink) (indexentry-link (current-node))) (element (secondaryie ulink) (indexentry-link (current-node))) (element (tertiaryie ulink) (indexentry-link (current-node)))

• To be able to use Computer Modern fonts:

  ;; Inserted in order to be able to use Computer Modern fonts in PS and PDF documents. ;; The font names _must_ be written exactly as follows ("Computer-Modern", ;; not "Computer Modern") for pdfjadetex to recognize them and use the T1 ;; fonts istead of the PK (Type 3) ones (which will look ugly on screen)! ;; ;; Gnuishly correct fonts... ;; (define %body-font-family% "Computer-Modern") (define %mono-font-family% "Computer-Modern-Typewriter") (define %title-font-family% "Computer-Modern-Sans") (define %admon-font-family% "Computer-Modern-Sans") (define %guilabel-font-family% "Computer-Modern-Sans")

• To use chapter/section/subsection labels as filenames for the respective HTML files:

  (define %use-id-as-filename% ;; Use <acronym>ID</acronym> attributes as name for component HTML files? #t)

• In lyxtox-html.dsl, to be able control what section levels get put into separate HTML files (chunks) in the chunked version, the chunk-section-depth has been included (taken from the html/dbchunk.dsl file, which on my system is /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/html/dbchunk.dsl with full name):

  (define (chunk-section-depth) 2)

  A value of 1 for chunk-section-depth means that the chunks are the individual SECT1 elements, i.e. the Sections. A value of 2 means that the chunks are the individual SECT2 elements, i.e. the SubSections and so on. SECT1, SECT2 and SECT3 are the SGML tags used to denote a Section, SubSection and SubSubSection respectively. There is no meaning in using chunk-section-depth with values higher than 3, at least not with LyX, since SubSubSubsections is the deepest level you can use in LyX (at least with the default settings).

• However, as painful experimentation has shown, setting a higher value for chunk-section-depth will have no effect, if “sect2”, “sect3” etc. are not contained in the chunk-element-list list. The list

  (define (chunk-element-list) (list (normalize "preface") (normalize "chapter") (normalize "appendix") (normalize "article") (normalize "glossary") (normalize "bibliography") (normalize "index") (normalize "colophon") (normalize "setindex") (normalize "reference") (normalize "refentry") (normalize "part") (normalize "sect1") (normalize "sect2") (normalize "section") (normalize "book") ;; just in case nothing else matches... (normalize "set") ;; sets are definitely chunks... ))

  contains the elements that constitute chunks. If you take an element out of the list, the chunk-section-depth above will not have any effect. Thus, to have chunks on sect2, sect3 etc., you must have them included in this list. chunk-element-list is originally defined in the html/dbchunk.dsl file (just like chunk-section-depth), which on my system is /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/html/dbchunk.dsl with full name. See also Naming of generated html code from sgml documents. Note that if you include “sect3” (SubSubSubsections) in the chunk-element-list list, you will get chunks on SubSubSubsections, no matter if your chunk-section-depth is only 2 and not 3!

• To force the table of contents to be on a separate HTML page and not contain any section:

  (define (chunk-skip-first-element-list) ;; forces the Table of Contents on separate page '())

  The reason that Norm added support for merging the first sect1 into the file with its parent is because the alternative is really ugly in the case that you have a chapter (title) immediately followed by a section (title) (see Use of <Para> within <ListItem> mangles list items).

  	Tip
  	That's why you should try to put at least some introductory text after a chapter title and before the first section of the chapter!

  FIXME: LyX inserts an extra </listitem> here, if I don't have this line...

• To get a list of figures at the start of the document, the generate-book-lot-list must contain “figure”, as in the following example:

  (define ($generate-book-lot-list$) ;; REFENTRY generate-book-lot-list ;; PURP Which Lists of Titles should be produced for Books? ;; DESC ;; This parameter should be a list (possibly empty) of the elements ;; for which Lists of Titles should be produced for each 'Book'. ;; ;; It is meaningless to put elements that do not have titles in this ;; list. If elements with optional titles are placed in this list, only ;; the instances of those elements that do have titles will appear in ;; the LOT. ;; ;; /DESC ;; AUTHOR N/A ;; /REFENTRY (list (normalize "table") (normalize "figure") (normalize "example") (normalize "equation")))

  The same must be the case if you want a list of tables (“table”), examples (“example”) or equations (“equation”). Normally, you will not have to touch this (i.e. your customization layer need not contain this code), as the above setting is the default one (for books).

• To be able to display “other credit”, “release info” and “publisher” information on a book's title page, these elements must be added to the book-titlepage-recto-elements list:

  (define (book-titlepage-recto-elements) ;; elements on a book's titlepage ;; note: added revhistory to the default list ;; note: added othercredit to the default list ;; note: added releaseinfo to the default list ;; note: added publisher to the default list (list (normalize "title") (normalize "subtitle") (normalize "graphic") (normalize "mediaobject") (normalize "corpauthor") (normalize "authorgroup") (normalize "author") (normalize "othercredit") (normalize "releaseinfo") (normalize "publisher") (normalize "editor") (normalize "copyright") (normalize "pubdate") (normalize "revhistory") (normalize "abstract") (normalize "legalnotice")))

• and the same must be done for the article-titlepage-recto-elements list, if we want to display them in articles' title pages too:

  (define (article-titlepage-recto-elements) ;; elements on an article's titlepage ;; note: added othercredit to the default list (list (normalize "title") (normalize "subtitle") (normalize "authorgroup") (normalize "author") (normalize "othercredit") (normalize "releaseinfo") (normalize "copyright") (normalize "pubdate") (normalize "revhistory") (normalize "abstract") (normalize "legalnotice")))

• and the following code must be added:

  (define (process-contrib #!optional (sosofo (process-children))) ;; print out with othercredit information; for translators, etc. (make sequence (make element gi: "SPAN" attributes: (list (list "CLASS" (gi))) (process-children)))) (define (process-othercredit #!optional (sosofo (process-children))) ;; print out othercredit information; for translators, etc. (let ((author-name (author-string)) (author-contrib (select-elements (children (current-node)) (normalize "contrib")))) (make element gi: "P" attributes: (list (list "CLASS" (gi))) (make element gi: "B" (literal author-name) (literal " - ")) (process-node-list author-contrib)))) (mode article-titlepage-recto-mode (element contrib (process-contrib)) (element othercredit (process-othercredit)) ) (mode book-titlepage-recto-mode (element contrib (process-contrib)) (element othercredit (process-othercredit)) ) (define (article-title nd) (let* ((artchild (children nd)) (artheader (select-elements artchild (normalize "artheader"))) (artinfo (select-elements artchild (normalize "articleinfo"))) (ahdr (if (node-list-empty? artheader) artinfo artheader)) (ahtitles (select-elements (children ahdr) (normalize "title"))) (artitles (select-elements artchild (normalize "title"))) (titles (if (node-list-empty? artitles) ahtitles artitles))) (if (node-list-empty? titles) "" (node-list-first titles))))

• ...and many other details. You are encouraged to read the source of the stylesheets (lyxtox-html.dsl, lyxtox-onehtml.dsl, lyxtox-print.dsl, lyxtox-print-pdf.dsl, lyxtox-print-ps.dsl, lyxtox-print-rtf.dsl, lyxtox-print-txt.dsl, lyxtox-print-howto.dsl)!

Important DocBook files

FYI, all changes presented here refer to variables that were originally defined in one of the following files: /usr/share/sgml/stylesheets/sgmltools/print.dsl /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/html/dbparam.dsl /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/print/dbparam.dsl /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/print/db31.dsl /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/print/dbchunk.dsl As said above, you should not change these files directly, because you will run into a lot of work when you upgrade them. For a list of all parameters, with references to the files that use them, see the /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/html/XREF file. If you are looking for a parameter and you can't find the file it's in, the XREF file is your friend.

7.1.6. Inline graphics

There is no way to include inline graphics with the method described in this document - here's why:

In theory, you could put something like

/^.*[^<]*<inlinegraphic/{
s/<inlinegraphic fileref="\([^"]*\)"[^>]*>/\
   <inlinemediaobject>\
      <\!\[ \%output\.print\.png; \[\
      <imageobject>\
         <imagedata fileref="\.\/images\/\1.png" format="PNG">\
      <\/imageobject>\
      \]\]>\
      <\!\[ \%output\.print\.pdf; \[\
      <imageobject>\
         <imagedata fileref="\1.pdf" format="PDF" scale="65">\
      <\/imageobject>\
      \]\]>\
      <\!\[ \%output\.print\.eps; \[\
      <imageobject>\
         <imagedata fileref="\1.eps" format="EPS">\
      <\/imageobject>\
       \]\]>\
      <\!\[ \%output\.print\.bmp; \[\
      <imageobject>\
         <imagedata fileref="\1.bmp" format="BMP">\
      <\/imageobject>\
       \]\]>\
      <textobject>\
         <phrase>Inline graphic<\/phrase>\
      <\/textobject>\
   <\/inlinemediaobject>/g
}

in sedscr and thus substitute the <inlinegraphic> element (which is produced by LyX whenever you choose Insert-->Include File, then “Verbatim” ) with an <inlinemediaobject> along the lines of Section 7.1.4.1. But LyX uses <inlinegraphic> also for verbatim inclusions of files. We make use of this feature in Section 5.14, where we see how to include potentially problematic SGML code in program listings. Unfortunately, there is no way to tell which purpose the <inlinegraphic> element serves in the SGML file that is exported from LyX, a file inclusion of program code, or an inline image. The code above would make the substitution in both cases, which would definitely mess things up.

Tip

Nevertheless, you can try it, if you are sure that your code does not include any other files, only images. There is a caveat though: you should create files with the same basename (i.e. without the ending) in the working directory, in addition to the ones you create in ./images. Example: if you want to include an icon named wink.png inline, then you have to create wink.png, wink.eps, wink.pdf and wink.bmp in ./images (as shown in Section 4.9) and a (possibly empty, it doesn't really matter) file named "wink" in ./. This is because when you will try to Insert-->Include File, LyX will not allow you to enter a fantasy name in the filename field and, on the other side, you must enter the filename without the ending and without the directory path, in order for the above code to work in sedscr.

7.1.7. Catalogs

A catalogue is a text file containing the translation rules of the public identifier to system's files.

The identifier systems used by SGML and by some tools are based on catalogues that perform the translation of these identifiers to files that hold the necessary definitions. For tools to be able to find the necessary catalogue(s), the environment variable SGML_CATALOG_FILES should be set, as explained in Section 7.1.3.

In my system, the sgmltools-lite package installed the /etc/sgml/catalog file. Its content can be used to set SGML_CATALOG_FILES as follows:

SGML_CATALOG_FILES="/usr/share/sgml/CATALOG.iso_ent" SGML_CATALOG_FILES="$SGML_CATALOG_FILES:
/usr/share/sgml/CATALOG.docbook-dsssl-stylesheets" SGML_CATALOG_FILES="$SGML_CATALOG_FILES:
/usr/share/sgml/CATALOG.docbook_3" SGML_CATALOG_FILES="$SGML_CATALOG_FILES:
/usr/share/sgml/CATALOG.docbook_4" SGML_CATALOG_FILES="$SGML_CATALOG_FILES:
/usr/share/sgml/openjade/catalog" SGML_CATALOG_FILES="$SGML_CATALOG_FILES:
/usr/share/sgml/stylesheets/sgmltools/sgmltools.cat" SGML_CATALOG_FILES="$SGML_CATALOG_FILES:
/usr/share/sgml/dtd/sgmltools/catalog" 
export SGML_CATALOG_FILES 

However, as recent versions of lyxtox do not use sgmltools, I use the relevant (and only those!) lines of my “master” catalog file in /etc/sgml/catalog to define SGML_CATALOG_FILES as:

SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/sgml/CATALOG.iso_ent"
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/sgml/CATALOG.docbook-dsssl-stylesheets"
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/sgml/CATALOG.mathml-2.0"
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/sgml/CATALOG.svg-1.1"
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/sgml/CATALOG.docbook_4"
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/sgml/openjade/catalog"
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/refdb/refdb.cat"
export SGML_CATALOG_FILES

Generally, you'll need to set the SGML_CATALOG_FILES environment variable to all the catalogs that you have under the directory you installed the DocBook stylesheets (probably something like /usr/share/sgml or /usr/local/sgml, see Section 3.2 and Section 3.3 for the packages that install stylesheets).

If you want to learn more on catalogues and the way they are constructed, see Creating and modifying catalogues.

7.1.8. CSS

See Section 4.14 and Chapter 8 for the details of using a CSS for the HTML output. The proposed ck-style.css is a CSS tailored to the HTML produced by DocBook. It also takes into account some modern approaches to accessibility (see Chapter 9, for more on accessibility of DocBook generated HTML pages).

For example, you can control the navigation header style with

DIV.NAVHEADER {
        color: #000000;
        background-color: #EFEFF8;
        padding: 5px;
        margin-bottom: 10px;
        width: 100%;
        border: thin solid #a0a0d0;
}

and the navigation footer style with

DIV.NAVFOOTER {
        color: #000000;
        background-color: #EFEFF8;
        padding: 5px;
        margin-top: 10px;
        width: 100%;
        border: thin solid #a0a0d0;
}

The concepts of margin, border and padding follow a page model that is described in W3C's working draft CSS3 Paged Media Module, version of Dec. 18th 2003. Figure 7-1, taken from this document (Copyright © 2003 W3C (MIT, ERCIM, Keio), All Rights Reserved) illustrates the various geometric notions of this page model. Note that the XSL area model is deliberately very similar to the CSS one.

If you output admonitions as tables, rather than graphics (see Section 4.7), then you can control their style with a code like the following (shown here for the "Important" admonition):

TABLE.IMPORTANT
{
        font-style:italic;
        border: solid 2px #ff0000;
        width: 70%;
        margin-left: 15%;
}

Screen output (code) is controlled by

PRE.SCREEN
{
        font-family:monospace;
        white-space: pre;
        width: 100%;
        background-color: #ffffcc;
        border:solid;
        color: #000000;
        border-color: #009999;
        border-left: solid #009999 2px;
        border-right: solid #009999 2px;
        border-top: solid #009999 2px;
        border-bottom: solid #009999 2px;
        padding-left: 15pt;
}

while examples and the Table of Contents by

DIV.EXAMPLE,DIV.TOC {
        border: thin dotted #70AAE5;
        padding-left: 10px;
        padding-right: 10px;
        color: #000000;
        background-color: #EFF8F8;
}
DIV.TOC {
        margin-left: 20px;
        margin-right: 20px;
        width: 95%;
}

An “external link” icon to absolute links (i.e. links starting with “http:”) is added through

/* Add an external-link icon to absolute links */
a[href^="http:"] {
        background: url(images/remote.gif) right center no-repeat;
        padding-right: 12px;
}
a[href^="http:"]:hover {
        background: url(images/remote_a.gif) right center no-repeat;
}

However, this alone would put the icon on every link with an absolute URL, including links pointing to the local domain. This is corrected by

/* ...but not to absolute links in this domain... */
a[href^="http://www.karakas-online.de"] {
        background: transparent;
        padding-right: 0px;
}
a[href^="http://www.karakas-online.de"]:hover {
        background: transparent;
}

“External link” icons tell you what a link will do before you click on it. There are icons specifically designed for this purpose, like QBullets. QBullets are a collection of elegant, animated icons that attach to hypertext links to indicate their function. You can download Qbullets for free from matterform media.

To use this idea for footnotes, the name attribute is used as a selector:

/* Add a note icon to footnote links */
a[href^="#FTN"] {
        background: url(images/qbullet-note.gif) right center no-repeat;
        padding-right: 12px;
}
a[href^="#FTN"]:hover {
        background: url(images/qbullet-note_a.gif) right center no-repeat;
}

This will select all links whose href attribute starts with "#FTN" and append a note icon to them, which will even show an animated page curl upon passing with the mouse over it (hover). The links whose href attribute starts with “#FTN” look like

<a name="AEN1175" href="#FTN.AEN1175">[1]</a>

and point to a footnote. The footnote itself also contains a link - which points back to the referring text. That link will not be affected by the above selection, since its href attribute does not start with “#FTN” :

<a name="FTN.AEN1175" href="explain-runsed-sed-sedscr.html#AEN1175">[1]</a>

To display a back icon besides those links, a selector on the name attribute is used:

/* ...and a back icon to the backlinks in the footnotes themselves */
a[name^="FTN"] {
        background: url(images/scrollup.gif) right center no-repeat;
        padding-right: 12px;
}
a[name^="FTN"]:hover {
        background: url(images/scrollup_a.gif) right center no-repeat;
}

	String matching on attributes is a CSS3 feature!
	To be able to use string matching on attributes, as we have done in the QBullets examples above, the user must view our document with a browser that supports this CSS3 feature. If you are wondering whether your browser belongs to this cutting edge category (Mozilla 1.5 does, tip, tip ), you can do this W3C browser test on CSS selectors and test for "Substring matching attribute selector".

To get an icon in place of the usual bullet in itemized lists, the list-style property is used for the UL tag:

UL {
        margin-bottom: 10px;
        list-style: url(images/tux-bullet.png) square;
    }

Last but not least, a cross-browser relative font setting can be achieved with

P {
        font-size: 12px;
}
/*/*/A{}
BODY P {
        font-size: x-small;
        voice-family: "\"}\"";
        voice-family: inherit;
        font-size: small;
}
HTML>BODY P {
        font-size: small;
}
/* */

which is indeed too complicated to explain here in all its depth. See Dive into Accessibility, day 26 for this.

7.1.9. Appendix

As already noted in Section 5.18, we can't include the Appendix in the main document, even if we mark it as an appendix with LyX' aproppriate check box in the Layout -> “Start Appendix here” menu item. We must include an extra LyX document of DocBook article type that is marked as an Appendix itself and contains our Appendix.

If such a file with the name appendix. lyx exists, lyxtox will take a series of actions to incorporate it into the final SGML document automatically:

• The appendix. lyx file is exported to SGML:

  # Export the Appendix to DocBook SGML. if test -e appendix.lyx; then $LYX -e docbook appendix.lyx fi

• A series of SGML code corrections take place through successive runs of 3 sed scripts:

  if test -e appendix.lyx; then $RUNSED $SEDSCRABI $1.sgml $RUNSED $SEDSCR appendix.sgml $RUNSED $SEDSCRAPP appendix.sgml fi

  1. With the sedscr_abi sed script, the ending tags </book> or </article> are substituted with SGML code that inserts the SGML entities of the Appendix, Bibliography and Index as defined in the Preample (see Section 4.6). For example, the following sed commands from sedscr_abi:

     /<\/book>/s/<\/book>/\ \&appendix;\ \&bibliography;\ \&index;\ <\/book>/

     will substitute

     &appendix; &bibliography; &index; </book> with &appendix; &bibliography; &index; &appendix; &bibliography; &index; </book>

     Note that the inserted lines before the closing </book> tag contain SGML entities that were defined as SYSTEM files with the names appendix.sgml, bibliography.sgml and index.sgml respectively in the Preample (see Section 4.6). Similar sed commands in sedscr_abi will do the same for the closing </article> tag.

  2. The sedscr sed script will correct the SGML code of appendix.sgml, as it will do for the main document. See Section 7.1.4.1 for an explanation of its inner workings.

  3. Finally, the sedscr_app sed script will replace the first line of appendix.sgml and its subsequent 3 lines with the correct SGML incantation for an Appendix:

     <appendix label="A"><title>Appendix</title>

     It also replaces the closing </article> tag (remember that we created the appendix. lyx file as a document of type "DocBook article (SGML)", see Section 5.18) with the right </appendix> one.

• If Mathematics processing is ON (with the variable $process_math set to 1 at the start of lyxtox), the appendix.sgml file is undergone the same transformations as the main document using the awkscr_math awk script (explained in Section 10.3):

  $AWK -f $AWKSCRMATH appendix.sgml > appendix.awk.sgml mv appendix.awk.sgml appendix.sgml

• Openjade (Section 3.4), called by the lyxtox script, will process both the main document and appendix.sgml and will insert the contents of the latter in place of the appendix SGML entity that was inserted by sedscr_abi above.

7.1.10. Bibliography

To create a bibliography section, LyX offers two possibilities: one using the citation keys of your free choice and one using keys of bibliographic entries in a BibTeX database. Neither of them produces SGML code when the document is exported to SGML, so we have to search for other methods. Before I explain the RefDB method, which suits our purposes perfectly, I will first decribe both standard methods to give you an idea of the classic bibliography creation process in a TeX/LaTeX system with LyX. You can read more about them in the LyX User's Guide and Extended Features Guide respective, both accessible from LyX' Help menu.

---

7.1.10.2. The RefDB method

The problem with both methods is that they don't “speak” SGML. Of course, you can use BibTeX to create a DVI document containing citations and bibliography and from there take the route to PS and PDF, or even to HTML through a tool like LaTeX2HTML, but this is not the route we want to take. We want to take the route through SGML - and that's where both methods fail to follow us.

The general principle of the RefDB method is straightforward: each citation that you want to be treated as a RefDB citation needs to have a role attribute with the value "REFDB". Each citation defines at least one xref element. The value of the linkend attribute encodes the ID of the required reference in the database (if you need references in several databases, this attribute can additionally specify the database). RefDB uses this information to generate a DocBook bibliography element. This contains an entry for each requested reference. These entries are labelled with ID attributes that match the xref linkend attributes in the text. Each RefDB-generated reference entry defines a xreflabel attribute which holds the text that is to be displayed at the position of the corresponding xref elements.

This is all it takes for single and unique citations, i.e. with one xref element per citation element and only one occurrence throughout the text. Both multiple occurrences of the same citation in the text and multiple citations (more than one xref elements per citation element) make things a bit more difficult.

Some output formats require a different formatting for the first citation of a publication in the text and all subsequent citations of the same publication. The first citation is identical with the above mentioned default case. All following citations of the same publication need an additional xref endterm attribute which points to an additional bibliomset element which in turn contains the text to be displayed for subsequent citations. The endterm attribute has the same value as the linkend attribute except that the letter "S" (as in subsequent) is appended to the attribute. See Processing expectations for the refdb DocBook bibliography output.

Compare the way you would use BibTeX with LaTeX (and LyX) to the way you use RefDB (10) to produce a Bibliography (see RefDB and BibTeX comparison):

With the BibTeX method, you proceed as follows:

• You enter your LaTeX references into a flat-file database in the BibTeX format.

• You use style files in the powerful but somewhat cryptic BibTeX format for your LaTeX documents.

• In a LaTeX document, you specify with the \bibliography command which external bibliography file to use. You specify with \cite commands which references you want to cite (and appear in your bibliography). LyX does this automatically for you.

• You run latex on your LaTeX document. This will create an .aux file which contains (among other stuff) a list of all citations.

• Then you run bibtex on your LaTeX document. This will use the bibliography style you specified in the document and will create a cooked bibliography in a .bbl file.

• Finally you run latex once or twice again to finalize your document.

With the RefDB method, you proceed as follows:

• You enter your references for a SGML or XML document into a SQL database. Input can be either RIS, DocBook, or BibTeX. As RefDB is Unix-style, you can write other import filters in any language that can send output to either stdout or to a file. Using a SQL database means better scalability for large collections and added benefit if you share your data with colleagues (think workgroups, departments, access control...)

• You specify the bibliography and citation styles for SGML and XML documents in XML files which are essentially templates for the sequence and appearance of bibliography and citation elements. These are also loaded into a database. This means they are pre-parsed, which speeds up the formatting of bibliographies.

• In an SGML or XML document, you specify an external entity with the name of the SMGL or XML file that will contain your bibliography. In DocBook documents you specify with <citation><xref..></citation> constructs which references you want to cite. Parenthetical and textual citations are supported.

• RefDB uses a DSSSL script to extract a list of all citations from SGML or XML documents into an XML document (which you can edit to add other, not cited references)

• Then you run a RefDB tool on your SGML or XML document. This will use the bibliography style you specified on the command line and will create a cooked bibliography in a SGML or XML file. It will also create a small stylesheet driver file specific for your bibliography style.

• Finally you run Jade or an XSLT processor on your document to transform it to the final output. This step uses the RefDB-created driver files to format the RefDB bibliographies (leaving alone potential other bibliographies) and the RefDB citations (leaving alone potential other citations). The stylesheet driver files essentially take care of character properties like font weight, posture etc. for various parts of the citation or bibliography. The citations are neatly hyperlinked with the references in the bibliography in all output formats that support this.

Your sources remain intact!

Please note that neither BibTeX nor RefDB do any "search-and-replace"-style mangling of your sources. The cooked bibliography is kept in an external file in both cases. This way it is easy to reformat your document for a different bibliography style without touching the document source. And the whole thing works for DocBook, TEI, and any other reasonable DTD (with a little stylesheet tweaking, that is).

Let's see how lyxtox handles all this complexity in the background for you:

When sedscr is run through runsed from lyxtox:

$RUNSED $SEDSCR $1.sgml

it makes a lot of changes to the SGML file $1.sgml that was previously exported by LyX (see Section 7.1.4.1 for an in-depth description of them). The following code in sedscr takes care of citations that were entered as described in Section 5.19.2:

s/<xref linkend="cit:\([^"]*\)">/\ <citation role="REFDB">\1<\/citation>\ /g

This sed code will substitute every cross-reference to a label of the form “cit:IDsome” with a citation of the form:

<citation role="REFDB">"IDsome"</citation>

in the exported SGML file. Then, lyxtox will call refdbxp:

$REFDBXP -t db31 < $1.sgml > $1.full.sgml mv $1.full.sgml $1.sgml

to transform all citations of the above form to one of the form:

<citation role="REFDB"><xref linkend="IDsome"></citation>

But how are the citations and references going to be formatted? We need special DSSSL instructions for those parts of our document! Fortunately, RefDB provides us with the aproppriate stylesheet. It is generated dynamically each time, using as input the style name we entered in lyxtox as the value of the REFDB_style variable (see Section 4.13), with a call to runbib from lyxtox:

$RUNBIB -d $RefDB_db -S $REFDB_style -t db31 $1.sgml

This will produce the stylesheet ${REFDB_style}dsl (notice the absence of a dot before the dsl ending). For example, if REFDB_style is “J.Biol.Chem.”, then the above call to runbib will create J.Biol.Chem.dsl.

J.Biol.Chem.dsl looks like this:

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [ <!ENTITY docbook-refdb-html.dsl PUBLIC "-//Markus Hoenicka//DOCUMENT RefDB DocBook html stylesheet//EN" CDATA DSSSL> <!ENTITY docbook-refdb-print.dsl PUBLIC "-//Markus Hoenicka//DOCUMENT RefDB DocBook print stylesheet//EN" CDATA DSSSL> ]> <style-sheet> <style-specification id="html" use="docbook-refdb-html"> <style-specification-body> (define ABSTJOURNALNAMESTYLE "ITALIC") (define ABSTVOLUMESTYLE "BOLD") (define CHAPBOOKTITLESTYLE "ITALIC") (define BOOKBOOKTITLESTYLE "ITALIC") (define INPRJOURNALNAMESTYLE "ITALIC") (define JOURJOURNALNAMESTYLE "ITALIC") (define JOURVOLUMESTYLE "BOLD") (define NEWSJOURNALNAMESTYLE "ITALIC") (define NEWSVOLUMESTYLE "BOLD") </style-specification-body> </style-specification> <style-specification id="print" use="docbook-refdb-print"> <style-specification-body> (define ABSTJOURNALNAMESTYLE "ITALIC") (define ABSTVOLUMESTYLE "BOLD") (define CHAPBOOKTITLESTYLE "ITALIC") (define BOOKBOOKTITLESTYLE "ITALIC") (define INPRJOURNALNAMESTYLE "ITALIC") (define JOURJOURNALNAMESTYLE "ITALIC") (define JOURVOLUMESTYLE "BOLD") (define NEWSJOURNALNAMESTYLE "ITALIC") (define NEWSVOLUMESTYLE "BOLD") </style-specification-body> </style-specification> <external-specification id="docbook-refdb-html" document="docbook-refdb-html.dsl"> <external-specification id="docbook-refdb-print" document="docbook-refdb-print.dsl"> </style-sheet>

This means the following:

For online output (id=”html”), take those define's into account and then proceed to use the part of the stylesheets with ID “docbook-refdb-html” (use=”docbook-refdb-html”). Openjade will look at the external specification with id “docbook-refdb-html” at the end:

<external-specification id="docbook-refdb-html" document="docbook-refdb-html.dsl">

and will see that is is the document whose name is the "docbook-refdb-html.dsl" SGML entity (document="docbook-refdb-html.dsl"). It will then consult the entity declarations at the start of the stylesheet:

<!ENTITY docbook-refdb-html.dsl PUBLIC "-//Markus Hoenicka//DOCUMENT RefDB DocBook html stylesheet//EN" CDATA DSSSL>

and find out that the docbook-refdb-html.dsl entity is the one with the public identifier "-//Markus Hoenicka//DOCUMENT RefDB DocBook html stylesheet//EN", it will search the catalog files (see Section 4.5) and, since the lyxtox script stores the RefDB catalog file in its SGML_CATALOG_FILES variable:

SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/refdb/refdb.cat"

openjade will finally be able to locate the document containing the rest of the DSSSL instructions necessary for processing the Bibliography. It turns out that, on my system, this is the /usr/share/refdb/dsssl/html/docbook-refdb.dsl, but this depends on how you compiled RefDB - on the value of the --prefix option precisely. The same procedure is followed for the print output (the id=”print” part).

But wait a minute! That /usr/share/refdb/dsssl/html/docbook-refdb.dsl, does it contain any special code for Mathematics, like the one in Section 10.3.2.1? No. Does it contain any of the other special DSSSL processing as described in Section 7.1.5? Again, no. It is a “driver” file containing only the RefDB-specific DSSSL instructions - for the rest, it jumps directly to the standard DocBook stylesheets of Norman Walsh, through the use=”docbook” attribute, just as our J.Biol.Chem.dsl jumps to /usr/share/refdb/dsssl/html/docbook-refdb.dsl through the use="docbook-refdb-html" attribute.

Of course, you can tweak the /usr/share/refdb/dsssl/html/docbook-refdb.dsl to include both the Mathematics (DBTeXMath) and all the other specific code, but this is not acceptable. Clearly, we need an automatic solution.

Fortnunately, there is one: use the ${REFDB_style}dsl stylesheet that RefDB created automatically for us, to create two new DSSSL driver files, one for HTML and one for print output. these stylesheets will take care to jump first to our other DSSSL files - the latter ones will then jump to the standard DocBook stylesheets.

To implement this solution, two new scripts are necessary, awkscr_refdb_html and awkscr_refdb_print. The lyxtox script calls them as follows:

$AWKSCR_REFDB_HTML ${REFDB_style}dsl > $HTML_DSL $AWKSCR_REFDB_PRINT ${REFDB_style}dsl > $PRINT_DSL

Both take as input the newly created ${REFDB_style}dsl stylesheet (J.Biol.Chem.dsl in our example) and produce a new HTML and print DSSSL stylesheet respectively. Here is the awkscr_refdb_html script :

#! /bin/sh AWK="/usr/bin/awk" cat <<-EOF <!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [ <!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL> <!ENTITY lyxtox-html.dsl SYSTEM "lyxtox-html.dsl" CDATA DSSSL> <!ENTITY lyxtox-onehtml.dsl SYSTEM "lyxtox-onehtml.dsl" CDATA DSSSL> ]> <style-sheet> EOF for id in "html" "onehtml"; do echo "<style-specification id=\"$id\" use=\"lyxtox-"$id"\">" echo "<style-specification-body>" $AWK '$1 ~ /<style-specification/ && $2 ~ "id=\"html\"",$1 ~ /<\/style-specification/ {if ($1 !~ /^</) {print}}' "id=$id" $1 echo "</style-specification-body>" echo "</style-specification>" done cat <<-EOF <external-specification id="lyxtox-html" document="lyxtox-html.dsl"> <external-specification id="lyxtox-onehtml" document="lyxtox-onehtml.dsl"> </style-sheet> EOF

This script

1. Prints the necessary entity declarations that have to come at the top of the new DSSSL stylesheet.

2. For every HTML id (there are currently two of them, “html” and “onehtml”), print as style specification containing all lines that do NOT start with “<” in the style specification for the “html” id in the given file, i.e. the newly created ${REFDB_style}dsl stylesheet. In our example, it prints every line not starting with “<” in the following part of J.Biol.Chem.dsl that comprises only the style specification for the id=”html” part:

   <style-specification id="html" use="docbook-refdb-html"> <style-specification-body> (define ABSTJOURNALNAMESTYLE "ITALIC") (define ABSTVOLUMESTYLE "BOLD") (define CHAPBOOKTITLESTYLE "ITALIC") (define BOOKBOOKTITLESTYLE "ITALIC") (define INPRJOURNALNAMESTYLE "ITALIC") (define JOURJOURNALNAMESTYLE "ITALIC") (define JOURVOLUMESTYLE "BOLD") (define NEWSJOURNALNAMESTYLE "ITALIC") (define NEWSVOLUMESTYLE "BOLD") </style-specification-body> </style-specification>

   Obviously, the lines that do NOT start with a “<” are those define's - and those are exactly the lines we are interested in, everything else will be replaced by our own code.

3. Prints aproppriate external specifications that point to our own stylesheets that contain the rest of our customization.

The output looks like this (see also refdb-html.dsl):

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [ <!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL> <!ENTITY lyxtox-html.dsl SYSTEM "lyxtox-html.dsl" CDATA DSSSL> <!ENTITY lyxtox-onehtml.dsl SYSTEM "lyxtox-onehtml.dsl" CDATA DSSSL> ]> <style-sheet> <style-specification id="html" use="lyxtox-html"> <style-specification-body> (define ABSTJOURNALNAMESTYLE "ITALIC") (define ABSTVOLUMESTYLE "BOLD") (define CHAPBOOKTITLESTYLE "ITALIC") (define BOOKBOOKTITLESTYLE "ITALIC") (define INPRJOURNALNAMESTYLE "ITALIC") (define JOURJOURNALNAMESTYLE "ITALIC") (define JOURVOLUMESTYLE "BOLD") (define NEWSJOURNALNAMESTYLE "ITALIC") (define NEWSVOLUMESTYLE "BOLD") </style-specification-body> </style-specification> <style-specification id="onehtml" use="lyxtox-onehtml"> <style-specification-body> (define ABSTJOURNALNAMESTYLE "ITALIC") (define ABSTVOLUMESTYLE "BOLD") (define CHAPBOOKTITLESTYLE "ITALIC") (define BOOKBOOKTITLESTYLE "ITALIC") (define INPRJOURNALNAMESTYLE "ITALIC") (define JOURJOURNALNAMESTYLE "ITALIC") (define JOURVOLUMESTYLE "BOLD") (define NEWSJOURNALNAMESTYLE "ITALIC") (define NEWSVOLUMESTYLE "BOLD") </style-specification-body> </style-specification> <external-specification id="lyxtox-html" document="lyxtox-html.dsl"> <external-specification id="lyxtox-onehtml" document="lyxtox-onehtml.dsl"> </style-sheet>

We then process our SGML file with this stylesheets for HTML output!

Let's examine for a moment what the new stylesheet does:

1. lyxtox calls openjade and tells it to use the “html” id of this stylesheet. This is because, in case RefDB processing is on, the stylesheet for HTML chunked output is defined by:

   HTML_DSL="refdb-html.dsl" HTML_CHUNKS_DSL="$HTML_DSL#html"

   and HTML_DSL is the name of the file created by awkscr_refdb_html above:

   $AWKSCR_REFDB_HTML ${REFDB_style}dsl > $HTML_DSL

   That “#html” is a special Jade/Openjade construct that tells it to start processing at id=”html” of the given stylesheet.

The new stylesheet (which will bear the name refdb-html.dsl, if HTML_DSL is left to its default value) jumps to id “lyxtox-html” which, by the same reasoning as we saw for the original J.Biol.Chem.dsl file previously, will be found in the lyxtox-html.dsl file that contains all our non-RefDB-specific customization. lyxtox-html.dsl, on the other hand, is constructed in such a way that it will call the standard DocBook stylesheets with a use=”docbook” attribute - and the processing chain is closed!

Processing for print output is done similarly: awkscr_refdb_print creates a new print stylesheet from ${REFDB_style}dsl, refdb-print.dsl, then this new stylesheet is called from lyxtox with an id of “print-pdf”, “print-ps”, “print-rtf” or “print-txt” respectively for each one of the print formats:

PRINT_DSL="refdb-print.dsl" PRINT_PDF_DSL="$PRINT_DSL#print-pdf" PRINT_PS_DSL="$PRINT_DSL#print-ps" PRINT_RTF_DSL="$PRINT_DSL#print-rtf" PRINT_TXT_DSL="$PRINT_DSL#print-txt"

Just as its HTML counterpart above, refdb-print.dsl is constructed in such a way that it will call our lyxtox-print-pdf.dsl, lyxtox-print-pdf.dsl etc. stylesheets with use attributes like use="lyxtox-print-pdf", use="lyxtox-print-ps" etc. respectively. Those stylesheets, in turn, will jump to the standard DocBook stylesheets with a use=”docbook” attribute.

How does a typical RefDB bibliography look like? lyxtox copies the $1.bib.sgml file (wher $1 is the argument passed to it) to the file with the fixed name bibliography.sgml:

mv $1.bib.sgml bibliography.sgml

The &bibliography; entity that sedscr_abi appends to our SGML file is mapped automatically to bibliography.sgml through the line

<!entity bibliography SYSTEM "bibliography.sgml">

in the preample of our document (see Section 4.6). Thus, you only have to look at bibliography.sgml - a typical entry there looks like:

<bibliomixed id="IDKARAKAS1992" role="BOOK"> <bibliomset role="intext" id="IDKARAKAS1992X"> (<abbrev>11</abbrev>) </bibliomset> <bibliomset role="intextsq" id="IDKARAKAS1992S"> (<abbrev>11</abbrev>) </bibliomset> <bibliomset role="authoronly" id="IDKARAKAS1992A"> <bibliomset relation="author"> <surname>Karakas</surname> </bibliomset> </bibliomset> <bibliomset role="authoronlysq" id="IDKARAKAS1992Q"> <bibliomset relation="author"> <surname>Karakas</surname> </bibliomset> </bibliomset> <bibliomset role="yearonly" id="IDKARAKAS1992Y"> (<abbrev>11</abbrev>) </bibliomset> <bibliomset role="bibliography" id="IDKARAKAS1992B"> <abbrev>11. </abbrev> <bibliomset relation="book"> <bibliomset relation="author"> <surname>Karakas</surname> <firstname>C.</firstname> </bibliomset> </bibliomset> <bibliomset relation="book"> (<pubdate role="primary">1999</pubdate>) </bibliomset> <bibliomset relation="book"> <publishername>BoD GmbH, Norderstedt</publishername> </bibliomset> </bibliomset> </bibliomixed>

As you can see, it is based on bibliomixed and bibliomset elements. The content of a bibliomixed element includes all necessary punctuation for formatting - we say that bibliomixed entries are “cooked”. The creator of RefDB, Markus Hoenicka, says the following about the role of bibliomixed elements in RefDB (see Formatting DocBook bibliographies):

RefDB does use bibliomixed on purpose. I think the choice between raw and cooked is a compromise between philosophy and ease of implementation, speed of execution etc. I see the main purpose of auto-generating bibliographies not in creating beautiful and philosophically correct *source* documents, but to help users create correct *formatted* output. The intermediate bibliography element is a means to achieve this. The DocBook DTD explicitly defines the bibliomixed element to create bibliographic output that would be too tedious or complicated to create on the stylesheet level alone.

7.1.11. Index

Before you can process your document, you must make sure that index.sgml exists. This is a chicken and egg problem, but it can be solved with the collateindex.pl command:

perl collateindex.pl -N -o index.sgml 

or, as in lyxtox:

$PERL $COLLATEINDEX -N -o index.sgml

The -N option creates a new index; -o indentifies the name of the output file. This name must be the same as the name you specified in the preample (see Section 4.6). The collateindex.pl script is part of the docbook-dsssl-stylesheets package (see Section 3.2). There are a multitude of options to collateindex.pl; see the reference page for more information.

Creating an index is a multi-step, two-pass process (see Automatic Indexing with the DocBook DSSSL Stylesheets):

• In order to create an index, you must first generate the raw index data. This is done with the HTML stylesheet (even if you want print output). That's why in lyxtox we use the same copy of HTML.index which was created with the “no-chunks” HTML stylesheet

  $PERL $COLLATEINDEX -p -g -o index.sgml HTML.index

• After you created the HTML.index file, you can generate your final document as usual using whichever stylesheet is appropriate. The generated document will contain the index:

  • Using sgmltools, as in older versions of lyxtox:

    • For one big HTML file:

      $SGMLTOOLS -b onehtml -s $HTML_NOCHUNKS_DSL -j "-i output.print.png" $1.sgml

      (notice the nochunks option we pass to openjade through sgmltools)

    • For many HTML files (one per chapter/section):

      $SGMLTOOLS -b html -s $HTML_DSL -j "-i output.print.png" $1.sgml

    • and for PDF:

      $SGMLTOOLS -b pdf -s sgmltools-pdf -j "-i output.print.pdf" $1.sgml

  • And using openjade and pdfjadetex as in newer versions:

    • For one big HTML file:

      ${OPENJADE} -t sgml -d $HTML_NOCHUNKS_DSL -i output.print.png -V nochunks $1.sgml > $1.html

    • For many HTML files (one per chapter/section):

      $OPENJADE -t sgml -d $HTML_CHUNKS_DSL -i output.print.png $1.sgml

    • and for PDF:

      ${PDFJADETEX} $1.tex

Tip

Whether an index has to be created or not, can be controlled by setting html-index to "#t" in the stylesheets (see Section 4.2 and Section 7.1.5) as follows (original code is in dbparam.dsl, but it is better not to touch it): (define html-index ;; REFENTRY html-index ;; PURP HTML indexing? ;; DESC ;; Turns on HTML indexing. If true, then index data will be written ;; to the file defined by 'html-index-filename'. This data can be ;; collated and turned into a DocBook index with bin/collateindex.pl. ;; /DESC ;; AUTHOR N/A ;; /REFENTRY #t) Default is false ("#f"). I preferred to let the default untouched and insert the external entity "index" at the end of the document using runsed and sedscr, see Section 7.1.4.1. If you decide to set html-index you will have to comment this in sedscr.

Tip

You can change the name of the file to which index data will be written by setting html-index-filename in the stylesheets (see Section 4.2 and Section 7.1.5) as follows (original code is in dbparam.dsl, but it is better not to touch it): (define html-index-filename ;; REFENTRY html-index-filename ;; PURP Name of HTML index file ;; DESC ;; The name of the file to which index data will be written if ;; 'html-index' is not '#f'. ;; /DESC ;; AUTHOR N/A ;; /REFENTRY "HTML.index") Default is HTML.index. I preferred to let the default untouched. If you decide to set html-index-filename, you will have to adapt lyxtox to reflect the name change.

7.2.1. From .lyx to .pdf

The classic way to transform a . lyx document to PDF format is to follow a three-pass procedure: first, the .lyx document is exported to DVI, then to PS through dvi2ps, then the PS version is tranformed to PDF through software like the commercial Acrobat® Distiller®[22], or the freely available Ghostscript. (via ps2pdf).

This classic three-pass procedure is not only complicated, it also loses some information through the intermediate DVI format. The results are often not acceptable: the most frequent problem is bad presentation of the character glyphs that make up the document (see Quality of PDF from PostScript):

• Wrong type of fonts used, which is the commonest cause of fuzzy text.

• ghostscript too old, which can also result in fuzzy text.

• Switching to font encoding T1, which is yet another possible cause of fuzzy text.

• Another problem - missing characters - arises from an aged version of Acrobat® Distiller®.

• Finally, there's the common confusion that arises from using the dvips configuration file -Ppdf, the weird characters.

It would be much better to produce the PDF version directly from the TeX (i.e. LyX) output. The pdftex package (see Section 3.5) was created with this objective in mind. pdftex (and pdfjadetex) creates the PDF document in one pass from the TeX format. A disadvantage of pdftex and pdfjadetex used to be the complexity of the preliminary steps (see Chapter 4, especially Section 4.9) needed to get a LaTeX document converted to PDF, escecially when it contained images. Not anymore: the method described here automates the format transormations for the images and hides the complexity of the commands involved in three files (sedscr, jadetex.cfg, lyxtox). See Section 7.2.2.

7.2.2. Figures

This is a serious problem most people fail in first place. LaTeX (and LyX) expects the images to be in encapsulated PostScript® (.eps) format (see Section 5.7). On the other hand, pdfjadetex (see Section 3.4) is not capable of dealing with eps (only with PDF, JPEG, PNG or MetaPost), we will have to convert the images to encapsulated PDF (.epdf) format, while still carrying the .pdf ending! This is best done by the addd script, which in turn uses convert (from the Image Magick package) and eps2pdf. The script works as follows (FIXME: The script has been simplified. I didn't test it extensively though. The following describes the old script):

Some variables are set first:

CONVERT="/usr/bin/convert" 
DENSITY=133 

• The script echoes some information about the file it processes and the calculated constants:

  echo "" echo "Processing file $1.png" echo "" echo "DENSITY=$DENSITY"

• We use ImageMagik to convert the PNG image to encapsulated PDF (EPDF, a format different from encapsulated PostScript®, EPS), adding density and antialiasing (so that texts are more readable). This is necessary in order for the bitmapped image to behave correctly in the PS document and is a point often and easily missed[23]:

  ${CONVERT} -antialias -density ${DENSITY} $1.png $1.epdf

• We then use ImageMagick again to convert the PNG image to encapsulated PostScript®[24] format, adding antialiasing again:

  ${CONVERT} -antialias -density ${DENSITY} $1.png $1.eps

• But we are still not done! pdfjadetex will accept encapsulated PDF images (.epdf), but only if they end in .pdf! We thus have to rename the EPDF image to a PDF one:

  # Rename the file so that it ends in pdf - pdftex wants this! mv $1.epdf $1.pdf

This procedure will create pdf and png files with the right resolution (density) information. Unfortunately the eps file that is also created as a by-product, will display somewhat smaller. FIXME: This may be the result of ghostview not using the right DPI when it displays the image, so it may be a problem of my system configuration.

You can automate the “add density” procedure using the adddscr script, which is included in the packages that you will find in Section 1.2:

#! /bin/sh
for x in `ls *.$1`; do
y=`basename $x .$1`
convert $y.$1 $y.png
addd $y
convert $y.png $y.bmp
done

The adddscr script accepts one parameter: the format from which you want to start the conversion. The idea is the following: suppose you have a set of GIFs, but no PNGs or any other format. Then you can change to the directory of the images, type

adddscr gif

and get your GIFs converted to PNGs, then get EPDF (renamed as PDF) and EPS version with added density. If you only have, say, BMP versions, just type

adddscr bmp

and the script will convert your BMPs to PNGs first, then to all other formats, adding density on the way.

For example, you can use the adddscr script the very first time you install the docbook-dsssl-stylesheets RPM. The RPM package offers GIF, EPS and PDF versions of admonitions (see Section 4.7) and callouts (see Section 4.8). The EPS and PDF versions surely come with the density of the system (read: monitor) they were created on, so it may not be wise to add density to them once again (if you do it, it may make the admonition and callout icons display smaller or larger than they should in PDF and PS documents)[25]. However, while you might want to leave the EPS and PDF versions untouched, you definitely need PNG and BMP versions of the images. Here's where the adddscr script comes in handy:

Comment the line that adds density in adddscr:

#! /bin/sh
for x in `ls *.$1`; do
y=`basename $x .$1`
convert $y.$1 $y.png
# addd $y
convert $y.png $y.bmp
done

change to the directory of the admonitions and callouts:

cd /usr/share/sgml/docbook/docbook-dsssl-stylesheets/images

then type

adddscr gif

Do the same for the callouts:

cd /usr/share/sgml/docbook/docbook-dsssl-stylesheets/images/callouts
adddscr gif

Now you have PNG and BMP versions of all your admonition and callout icons![26]

If you wondered why your images dont't get included in the PDF, although you meticulously prepared everything “right”, now you know why! But there's more to it - read on!

But what is this "density" anyway?

From problem downsampling: You should think of a digital image as a rectangular pixel grid. Suppose you have an image of 1500 by 2000 pixels. The image could be printed (on paper) or viewed (on screen). For that purpose, you have to tell the printer software or the "display" utility program how large an image pixel should be printed as. Suppose you want a single image pixel for a single printer dot, at 300 dots per inch (dpi). That means that the image will come out of the printer with a size of about 5 inch by 6.6 inch (or 127 mm by 169 mm). But the image file (normally) only knows about its pixel size (1500x2000), not its size at which it should be printed (since you could as well print it at double or half of the size; that's up to the printer software). However, some image formats (e.g. TIFF, EPS, EPDF) allow to store the "density", i.e., the real physical size of a pixel, as extra (header) information. This is what we have to do with our EPS and PDF images too.

Having converted the images to all possible formats and having used the right parameters for each format, still does not mean we are done! If we are not very careful about the way we will use them, we will end up in a real mess, even though all seems to be right according to the packages, the SGML specification, the Stylesheets etc.

The problem is that when you generate "print" output, the stylesheets don't have any means to know which print format you mean, EPS, PDF or RTF -- there's no way to provide them with that information yet. Given the choice of PNG, BMP or EPS they'll choose EPS every time. As we've said, pdfjadetex doesn't handle .eps files.

The solution is to use parameter entities (if that's an unfamiliar term, read the FreeBSD Documentation Project Primer for New Contributors: Entities, there's a section in there which explains them, and gives examples of using them to conditionally include certain parts of your document).

In a nutshell, start your document like this:

<!DOCTYPE book  PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
<!ENTITY % output.print.png "IGNORE">
<!ENTITY % output.print.pdf "IGNORE">
<!ENTITY % output.print.eps "IGNORE">
<!ENTITY % output.print.bmp "IGNORE">
]>
<!-- rest of the document as normal -->

Adjust that as necessary, depending on which version of the DTD you're using. The key bits are the ENTITY lines.

Then, when you want to include an image, do this (see the explanation of the sedscr file in Section 7.1.4.1):

<mediaobject>
      <![ %output.print.png; [
      <imageobject>
         <imagedata fileref="./images/imagename.png" format="PNG">
      </imageobject>
      ]]>
      <![ %output.print.pdf; [
      <imageobject>
         <imagedata fileref="imagename.pdf" format="PDF" scale="65">
      </imageobject>
      ]]>
      <![ %output.print.eps; [
      <imageobject>
         <imagedata fileref="imagename.eps" format="EPS">
      </imageobject>
       ]]>
      <![ %output.print.bmp; [
      <imageobject>
         <imagedata fileref="imagename.bmp" format="BMP">
      </imageobject>
       ]]>
</mediaobject>

Now, when you process your document with "openjade ...", the "%output.print.xxx;" is replaced by the word "IGNORE". This tells Jade to ignore that section of the document. The overall effect is that no image will be included, neither PNG, nor PDF, nor EPS, nor BMP.

In order to get one (and only one) image included, you have to tell Jade that one or other of the %output.print.xxx; entities must contain "INCLUDE" rather than "IGNORE". You can do this on the command line with the "-i" flag. So if you're producing a HTML file, you would do (see lyxtox and Section 7.1.4.6):

$SGMLTOOLS -b html -s $HTML_DSL -j "-i output.print.png" $1.sgml

If you're producing a PDF file, you would do (see lyxtox and Section 7.1.4.7):

$SGMLTOOLS -b pdf -s sgmltools-pdf -j "-i output.print.pdf" $1.sgml

and so on. With the -j option to sgmltools you can pass options to Jade - we thus pass the aproppriate "-i output.print.xxx" for each format.

Using openjade and pdfjadetex, these commands are equivalent to:

${OPENJADE} -t sgml -d $HTML_NOCHUNKS_DSL -i output.print.png -V nochunks $1.sgml > $1.html

and:

${OPENJADE} -t tex -d ${PRINT_PDF_DSL} -o $1.tex -i "output.print.pdf" $1.sgml
${PDFJADETEX} $1.tex

respectively.

Yes, it's a kludge. But once incorporated in a script (like sedscr, see Section 7.1.4.1), that doesn't have to bother us any more. I owe it to Nik Clayton, who posted it to the docbook-apps mailing list on June 8th, 2000 . It works great! Thanks Nik.

7.2.3. Using Type 1 Fonts

If you want a PDF document that not only excels when printed, but also when displayed on the screen, it is advisable to embed Type 1 fonts, even though the document may increase in size. The reason is is that by default TeX/LaTeX uses bitmapped fonts instead of Type1 or TrueType ones. The resolution of these bitmapped fonts matches that of the printer on the system you create the document. This is rarely the same resolution of the monitor or printer the reader will use. This change in resolution results in terrible quality when displaying these fonts on a screen. or printing it on a printer, whose resolution does not match the one of the bitmapped font.

The solution to the problem is to force TeX/LaTeX to use Type1 fonts which are scalable and thus resolution-independent. There are two ways to achieve this:

• Use of the standard PostScript® fonts

• Use of Type1 versions of Computer Modern (CM) fonts.

I chose the latter method. I like the look of the TeX documents that use Computer Modern fonts.

I am not alone with this predilection: most people use Computer Modern to start with, and even those relative sophisticates who use something as exotic as Sabon often find themselves using odd characters from CM without really intending to do so (see The wrong type of fonts in PDF).

Fortunately, rather good versions of the CM fonts are available from the AMS (who have them courtesy of Blue Sky Research and Y&Y, see Blue Sky Research and Computer Modern fonts for some historical background) and most modern systems have the fonts installed ready to use (if yours doesn't, go get them from the Comprehensive TeX Archive Network archives: Blue Sky CM Type 1 fonts, or any other CTAN mirror).

There are six DSSSL variables for defining parameters for changing fonts.

By default, these variables may take the following values:

• Helvetica

• Palatino

• Bookman

• Courier

• Wingdings

• Avant-Garde

• New-Century-Schoolbook

• Times-Roman

• Zapf-Dingbats

• Computer-Modern-Typewriter

• Computer-Moder-Sans

• Computer-Modern

• Computer-Modern-Caps-And-Small-Caps

Other font names may be used, but they correspond to one of the fonts in the list above. For example:

• Arial = iso-sanserif = Helvetica

• Courier-New = Courier

• Times-New-Roman = iso-serif = Times-Roman

• WingDings = Wingdings

To use other fonts, they must be T1 fonts, the coding used by TeX. These are listed in the file called t1***.fd, where *** is the font code. The first letter represents the font provider; the next two letters represent the font name. In addition, we must ensure that all required files are present in our installation, i.e. the .tfm, .afm, .vf, .pfm and .pfb files for each .fd file.

We must ensure that Jadetex can associate the font name, e.g. Utopia, with the code name of the font (for Utopia, "put"). This is done by adding lines such as the following to the jadetex.cfg file:

\def\Family@font_name(***)

where *** again represents the three-letter code and "font_name" is the... font name. For example, to use the Utopia font, the following line would be added to the jadetex.cfg file:

\def\Family@Utopia{put}.

Following Customizing Document Production, we can include these lines in the jadetex.cfg file (currently commented, since they make sense only if you have those fonts installed - uncomment accordingly):

\makeatletter
\def\Family@Utopia{put}
\def\Family@ZapfChancery{pzc}
\def\Family@Fibonacci{cmfib}
\def\Family@Funny{cmfr}
\def\Family@Dunhill{cmdh}
\def\Family@Concrete{ccr}
\def\Family@Charter{bch}
\def\Family@Fontpxr{pxr}
\def\Family@Fontaer{aer}
\def\Family@Fontaess{aess}
\def\Family@Fontaett{aett}
\def\Family@Fontlcmss{lcmss}
\def\Family@Fontlcmtt{lcmtt}
\def\Family@Fontcmvtt{cmvtt}
\def\Family@Fontcmbr{cmbr}
\def\Family@Fontcmtl{cmtl}
\def\Family@Fontpxss{pxss}
\def\Family@Fonttxss{txss}
\def\Family@Fonttxr{txr}
\makeatother

The font declarations are preceded by \makeatletter and followed by \makeatother to properly escape the "@" symbol.

Now, if we wish titles to be formatted using Fonttxr and body text with Concrete, all that is necessary is to add the following lines to lyxtox-print-pdf.dsl:

(define %title-font-family% "Fonttxr") (define
%body-font-family% "Concrete"

And in order to use Computer Modern fonts in the PDF document , we write the following in the print stylesheet, lyxtox-print-pdf.dsl (see Section 7.1.5):

    ;;  Gnuishly correct fonts...
    ;;
    (define %body-font-family% "Computer-Modern")
    (define %mono-font-family% "Computer-Modern-Typewriter")
    (define %title-font-family% "Computer-Modern")
    (define %admon-font-family% "Computer-Modern-Sans")
    (define %guilabel-font-family% "Computer-Modern-Sans")

Now, if the T1 font encoding is used, i.e. if the jadetex.cfg file contains the line

\usepackage[T1]{fontenc}

the EC fonts will be used instead of the CM ones. Since there are no Type1 EC fonts available, pdftex will use bitmapped ones, yielding poor quality PDF files. Fortunately, there is a workaround: the ae package provides virtual EC fonts based on the CM ones, so that the Type1 CM fonts can be used in the output file. However, not all EC characters are available in this way. The aecompl package defines the missing characters as bitmapped fonts. To use them you should have the following in jadetex.cfg:

\usepackage{ae} 
\usepackage{aecompl} 

or just

\usepackage{ae,aecompl} 

In this way the output file will use CM fonts for all except some rarely used characters. pdfjadetex will end saying something like:

<8r.enc><cmex10.pfb><cmti9.pfb><cmmi6.pfb><cmr7.pfb><cmmi7.pfb> </var/cache/f
onts/pk/ljfour/jknappen/tc/tcrm0700.600pk><cmr6.pfb><cmsy10.pfb><cmitt10.pfb><c
mssi9.pfb><cmmi9.pfb><cmr9.pfb><cmmi10.pfb><cmtt8.pfb><cmtt9.pfb><cmss9.pfb> </
var/cache/fonts/pk/ljfour/jknappen/tc/tcrm0800.600pk><cmti10.pfb><cmbx10.pfb> <
/var/cache/fonts/pk/ljfour/jknappen/tc/tcrm1000.600pk><cmr10.pfb><cmssbx10.pfb>

meaning that it has embedded all fonts shown in angle brackets into the PDF file. See High quality PDF output from LaTeX and TeX for more details.

	Tip:
	You can check the fonts used in the PDF file by choosing File-->Documet Info-->Fonts-->List all fonts in Acrobat® Reader. You will see that the fonts are embedded (not totally, but as a subset, which is the legally correct way) in the PDF document, see Figure 7-2.

However, today other solutions to the font quality problem exist as well: instead of using virtual Type 1 fonts (which is what you do when you use the ae, aecompl and aeguill packages), you may choose to use “true” Type 1[27] fonts by installing one of the new CM-super, CM-LGC or Latin Modern fonts. From Finding 8-bit Type 1 fonts:

7.2.4. Choosing the right font encoding

If you think of a font as being arranged in a table, then the font encoding is nothing else than the way the font's symbols (the “glyphs”) are arranged in the table. If you think of the table as being fixed, then different font encodings arrange the same or different glyphs in different ways in the table's cells. If you mentally number all table cells sequentially, then for each table cell you have a number and a glyph. The number is the font's internal representation (the “encoding”) of the glyph.

Fonts are always encoded in some encoding - that's the nature of a font, being just a table of glyphs. Thus, in order to use a font that contains the glyphs (letters, symbols,...) you need, you must tell pdfjadetex and jadetex which encoding to use. For example, to use the T1 font encoding, the jadetex.cfg file must contain the line

\usepackage[T1]{fontenc}

To use the OT1 encoding, you must have:

\usepackage[OT1]{fontenc}

There are some factors that affect the choice of font encoding:

• Your language. More precisely, the glyphs you want to present in your document (if you find the word “glyphs” confusing, just read “letters” or “symbols”). If your language is english, then you can use both the T1 and the OT1 font encoding. If your language is french, then you have to use the T1 encoding. The same is true for many european languages. FIXME: encodings for other languages.

• Mathematics. If you don't display any Mathematics, you can choose from a wider choice of fonts and font encodings. But if you use Mathematics, your document will look better if you choose a font family that contains mathematical symbols as well. A font family that contains excellent mathematical fonts is Computer Modern. Computer Codern came originally only in the OT1 encoding. This is fine, as long as you use only english. For european languages, you have to use the T1 encoding. Now, if you have Mathematics and write in some european language (e.g. french, where you need accented letters and the like), then your choice is becoming narrower: you need a good Mathematics font, say Computer Modern, but you also need T1 encoding. This leads to the use of virtual EC fonts with the ae and aecompl packages, as discussed in Section 7.2.3.

• The symbols you want to use. Some symbols are available in one encoding, but not in another. For example, is missing from the OT1 encoded Computer Modern fonts, but you can still get it in the PDF and PS if you enter math mode in Lyx and type the two there. However,if your purpose is to get the french quotes (“guillemets”), then you might just as well choose the T1 encoding and the aeguill package:

  \usepackage[T1]{fontenc} \usepackage{aeguill}

• Quality. You might not want to use the aeguill package, because the fonts it defines are not as perfect as the original Computer Modern fonts, leading to (maybe imperceptible, but nonetheless existent) inaccuracies and inconveniences in the resulting PDF. So you might decide to use the OT1 font encoding and the original Computer Modern fonts, entering your and always in math mode in LyX. Note that the HTML versions of your document will then contain small images in place of those symbols, since lyxtox will treat them as mathematical “ inline equations” (see Chapter 10).

Note that today other solutions to the font quality problem exist as well: instead of using virtual Type 1 fonts (which is what you do when you use the ae, aecompl and aeguill packages), you may choose to use “true” Type 1 fonts by installing one of the new CM-super, CM-LGC or Latin Modern fonts, see Section 7.2.3.

7.2.5. Using True Type fonts

FIXME: To be done.

For the moment, see Using TrueType fonts with TeX via Postscript Type1 format.

The idea is:

• Transform the TT font to Type1 (see Section 7.2.3) using ttf2pt1. Take care of naming conventions for the new font.

• Integrate the newly created Type 1 font in your TeX installation. If you observed naming conventions, then this step might be done automatically.

• In one of the last output lines of ttf2pt1, the font name was printed, for example:

  FontName VAGRoundedBT_Regular

  Use that name in the lyxtox-print-pdf.dsl file (see Section 7.1.5):

  (define %body-font-family% "VAGRoundedBT_Regular") (define %mono-font-family% "Computer-Modern-Typewriter") (define %title-font-family% "VAGRoundedBT_Regular") (define %admon-font-family% "Computer-Modern-Sans") (define %guilabel-font-family% "Computer-Modern-Sans")

  Of course, since this is a T1 font, the T1 font encoding has to be used, i.e. the jadetex.cfg file must contain the line

  \usepackage[T1]{fontenc}

7.2.6. The hyperref package

The hyperref package by Sebastian Rahtz und Heiko Oberdiek expands the cross-referencing capabilities of LaTeX introducing \special commands that can be interpreted by a driver (like pdfjadetex) to produce hypertext links to places in the same document (cross-references), other PDF documents, or even WWW pages.

We pass options to the hyperref package in the jadetex.cfg configuration file. Either the classic \usepackage, or the new \ hypersetup command can be used for this purpose. I use the latter. If you use the \ usepackage method, you should always specify the driver like in

\usepackage[pdftex]{hyperref}

In addition to the base URL, author, title, subject and keywords (which you have already set up correctly in Section 4.4), there are a lot of other options that can be set in jadetex.cfg (see Erstellung von pdf-Dokumenten mit LaTeX (in german) ):

• open settings:

  • pdfpagemode: Determines how the document will open in Acrobat®. If no mode is explicitly chosen, but the bookmarks option is set, UseOutlines is used.

    • None

    • UseThumbs: show thumbnails.

    • UseOutlines: show bookmarks.

    • FullScreen

  • pdfstartpage: Determines on which page the PDF document is opened.

  • pdfstartview: FitB or FitH: Set the startup page view.

• paper size settings: The keywords for paper size may directly appear in the hypersetup command, since they are boolean variables. (draft=true is equivalent to draft.) . An overview of the possible settings is presented in Table 7-1.

  Table 7-1. Paper sizes with hyperref

  Paper size option	Meaning
  draft	all hypertext options are turned off
  debug	extra diagnostic messages are printed in the log file
  a4paper	210mm x 297mm
  a5paper	148mm x 210mm
  b5paper	176mm x 250mm
  letterpaper	8.5in x 11in
  legalpaper	8.5in x 14in
  executivepaper	7.25in x 10.5in

The breaklinks option enables breaking of long hypertext links across lines, the linktopage option has the effect that only the page number (and not the chapter/section text) links to the relevant chapter or section. All possible link colour options are shown in Table 7-2. The frenchlinks option differentiates links from the rest of the text not through colours, but through small caps instead.

See Erstellung von pdf-Dokumenten mit LaTeX for more PDF options.

7.2.7. Hyphenation

If pdfjadetex encounters a word it does not know how to hyphenate, the word is skipped! In the following example from Customizing Document Production, the french words savoir or évolution were problematical.

The error log file contained the following lines:

Overfull \hbox (3.64668pt too wide) in paragraph at lines
249?256 \T1/ptm/m/n/11 plusiers resources liées á linux-mandrake. Si vous souhaitez en savoir

This message tells us that pdfjadetex does not know how to hyphenate savoir, consequently it is skipped. In order for pdfjadetex to correctly format lines, we must ensure that hyphenation is explicitly activated using the command \def\Hyphenate{1 } in jadetex.cfg and, in addition, that the text is justified (\def\Quadding{justify}). But, in addition, we must explicitly set the language in order to activate the correct hyphenation module (with \def\Language{UK}).

Internet addresses can become quite long, even longer than a single line. jadetex doesn't hyphenate them properly. Actually, no hyphenation rule prevents it from inserting a hyphen after the double slash. The url package was developed by Donald Arseneau to solve these problems. To use it, you must tell jadetex to load it. You do this by inserting the following in the jadetex.cfg file (see Section 4.4 and Section 7.2.12 for more on jadetex.cfg):

\usepackage{url}

We must also ensure that openjade properly transforms the <ulink> and <filename> elements into jadetex commands. See Section 7.2.10 for more on this.

7.2.8. Bookmarks

Bookmarks are a navigation aid for the Acrobat® Reader. They are a tree-like structure that reflects the chapter/section structure of the document. The nodes of the tree are the chapter/section texts, which link directly to the respective chapter/section. The behaviour of bookmarks can be customised with the following commands (since they are boolean variables, they can appear directly in the hypersetup command, e.g. to switch it explicitly off, use e.g. bookmarksopen=false):

• bookmarks: bookmarks are created even if the \ tableofcontents command is not present.

• bookmarksopen: Expand all bookmarks.

• bookmarksnumbered: Include section numbers in bookmarks.

• bookmarksopenlevel: The maximal tree depth of bookmarks to open

7.2.9. PDF view options

The most important options regarding PDF view options are shown in Table 7-3. They are set in jadetex.cfg with the hypersetup command.

See Erstellung von pdf-Dokumenten mit LaTeX for more PDF options.

7.2.10. Links to internet sites

The url package enables the use of URL links in the PDF document and takes care of their hyphenation. To use it, you must tell jadetex to load it. You do this by inserting the following in the jadetex.cfg file (see also Section 4.4):

\usepackage{url}

We must also ensure that openjade properly transforms the <ulink> and <filename> elements into jadetex commands. For the <ulink> element, we want openjade to copy the text found between the two tags and within parentheses, i.e. the address given in the id attribute.

In order to do this, we use the customization as described by Pascal Lo Ré in Customizing Document Production: we create a sosofo of type formatting-instruction. We added a new flow-object to those already defined in the DSSSL stylesheets:

;;  Inserted in order to be able to get URLs in PDF documents.
;;  Adapted from manual-print.dsl of <productname>Mandrake</productname>.
;; Include the flow object class "formatting-instruction" : ONLY for Jade
(declare-flow-object-class formatting-instruction
       "UNREGISTERED::James Clark//Flow Object Class::formatting-instruction")

This addition allows us to insert arbitrary, non-formatted text into the output file. Then we can insert suitable TeX instructions into the intermediate output. This new flow-object is called formatting-instruction. The usage syntax of formatting-instruction is as follows:

(make formatting-instruction data:
"text-to-be-output")

The value of the data variable is inserted into the output file. Note that the “\” character must be escaped with an addition '\'. For example, in order to insert the TeX function,\penalty, you would use the following:

(make formatting-instruction data:
"\\penalty")

Now, in order to get hypertext links in PDF, the ulink element is redefined in lyxtox-print.dsl with the help of formatting-instruction (see Using Jade for SGML transformations for the class "formatting-instruction" and Section 4.2 and Section 7.1.5 for the lyxtox-print.dsl file):

;; *** URLs ***
;; Original : dblink.dsl
(element ulink
 (sosofo-append
  ;; If you allow process-children here, you will get the text printed once more!
  ;; (process-children)             ;; Write the text with its format (anchor in HTML)
  (make formatting-instruction      ;; Write : " \href{" + theUrl + "}{" + theText + "}"
    data: (string-append " \\href{" (attribute-string (normalize "url")) "}{" (data-of (current-node)) "}")
  )
 )
)

The text to be edited is accessed by data-of (current-node). Because this text requires special formatting (italics?), we must call the (process-children) function. The address is returned by attribute-string (normalize “url”). To construct the string, we concatenate using the command string-append, and assign the result to data in the sosofo. This nicely produces hypertext links in PDF.

However, the <ulink> element is not only used for URLs, but also for the index generation (see Section 7.1.11). Since we redefined it above, it is going to be used for the index too (remember, the changes you do in the stylesheets, as discussed in Section 7.1.5, will take precedence over the defaults). We thus have to copy the code from dbindex.dsl for <ulink> elements that are children of <primaryie>, <secondaryie> or <tertiaryie>, which is the case for the index:

;; These three elements are from "dbindex.dsl".
;; Must be placed here because of the redifinition of "ulink".
;; Otherwise the Index entries will point to HTML files,
;; instead of page numbers.
(element (primaryie ulink)
  (indexentry-link (current-node)))
(element (secondaryie ulink)
  (indexentry-link (current-node)))
(element (tertiaryie ulink)
  (indexentry-link (current-node)))

7.2.11. Thumbnails

The thumbpdf package by Heiko Oberdiek installs the Perl program thumbpdf on your system. With the help of thumbpdf and Ghostscript (which should also be installed), you can create thumbnails for the PDF document (to be seen when you click on the “thumbnails” register card in Acrobat® Reader). Thumbnails are embedded images of the document's pages, drawn in small size and resolution. Their purpose is to facilitate navigation through the document (of course only if the PDF viewer supports them).

You need at least Ghostscript 5.50 in order to be able to use thumbpdf. You need to declare its use in the jadetex.cfg file (see Section 4.4 and Section 7.2.12) as follows:

\usepackage[pdftex]{thumbpdf}

The PDF document with thumbnails is created in a three-pass process:

1. The PDF file without thumbnails is created first.

2. thumbpdf is called and given as argument the basename of the PDF file. It creates the thumbnails in a file with the same basename and the ending .tpt.

3. The PDF file is created again. Through the \ usepackage instruction above, pdfjadetex searches for a .tpt file in the current directory and uses it to embed the thumbnails in the PDF file.

If the parameter use_coolthumbs is set to 1 in lyxtox (that's currently the default), the thumbnails will be generated using the coolthumbs script (see Section 4.15), which in turn will call The GIMP to create smooth, anti-aliased thumbnails. See the Linux LaTeX-PDF HOW-TO for the details of the inner workings of coolthumbs.

See also Section 7.1.4.7 for the PDF document creation process.

7.2.12. Configuring pdfjadetex

The file jadetex.cfg is used whenever you want to override jadetex's or pdfjadtex's default behavior. This file just goes in the current working directory (i.e. where jadetex is being run from). It seems that pretty much any TeX code can go in there, but here are some common things.

• The hyperref package expands the cross-referencing capabilities of LaTeX introducing \special commands that can be interpreted by a driver (like pdfjadetex) to produce hypertext links to places in the same document (cross-references), other PDF documents, or even WWW pages. You declare its use in jadetex.cfg with

  \hypersetup{

  inserting various options after the curly bracket. See Section 7.2.6.

• Two-Sided Pages: sometimes, you will want jadetex to start chapters on the recto side, and try to keep the total count of pages even. This is no longer the default behaviour, so if you want to revert to it, put the following in jadetex.cfg:

  \def\PageTwoSide{1} \def\TwoSideStartOnRight{1}

• PDF Outlines (bookmarks): PDF outlines are a nested, tree-like list of the hierarchy of chapters, sections, etc, each trre node being a link to the relevant chapter or section. These are displayed on the left side of Acrobat® Reader. To enable the listing of bookmarks, put this in jadetex.cfg:

  pdfpagemode=UseOutlines

• If you happen to have a "Citation Reference" or a "Cross Reference" inside of a "Section" (for example "5 The Proof [somebook]"), then you will need to give the linktocpage option to pdftex, otherwise you will get an error when generating the Table of Contents saying

  "pdfTeX error (ext4): link annotations can't be nested"

  Put the following in jadetex.cfg:

  \usepackage[pdftex,linktocpage]{hyperref}

• Computer Modern (CM) fonts: The ae package provides virtual EC fonts based on the CM ones, so that the Type1 CM fonts can be used in the output file. However, not all EC characters are available in this way. The aecompl package defines the missing characters as bitmapped fonts. To use them you should have the following in jadetex.cfg:

  \usepackage[T1]{fontenc} \usepackage{ae} \usepackage{aecompl}

  In this way the output will use CM fonts for all except some rarely used characters

7.2.13. Further enhancements

The PDF format offers some possibilities that further enhance its use:

• Optimization: The document can be optimized for browsing , so that it needs only be partially downloaded to be viewed.

• Passwords: Using programs like pdlin [28] you can set passwords and permissions regarding printing, changing, selecting and adding text.

These enhancements are not used in my scripts, but they certainly could be incorporated if needed.

For more information on the creation on powerful PDF documents see Erstellung von pdf-Dokumenten mit LaTeX.

The manual-print.dsl file, used for the print versions of the Mandrake Linux distribution, contains examples of customizations that are beyond the scope of this document, but may very well be useful in a heavy production environment. These include:

• Definition of language

• Foreign text or abbreviations

• Long titles

• Glossary entries

• Inline graphics

• Character fonts

and other goodies that make reading of this document strongly recommended for the interested reader.

7.3.1. Embedding Computer Modern fonts

The reason behind embedding the Type1 Computer Modern fonts in PostScript® (PS) documents is the same as for PDF ones (see Section 7.2.3): the resolution of the bitmapped fonts that are used by default by TeX/LaTeX matches that of the printer on the system you create the document. This is rarely the same resolution of the monitor or printer the reader will use. This change in resolution results in terrible quality when displaying these fonts on a screen. or printing it on a printer, whose resolution does not match the one of the bitmapped font.

	Tip:
	In recent TeX/LaTeX distributions, freely available Type1 versions of the CM fonts are provided. These appear under the collective name of bluesky. The bluesky fonts can be obtained from CTAN, if not already installed on your system.

You can embed the CM fonts in the PS document using an aproppriate printer with the -P option:

PRINTER="cmz"
export PRINTER

I use this comfortable method in the lyxtox script. This will make dvips (which is directly called in the current lyxtox script, or indirectly called by sgmltools, in older versions of lyxtox, see Section 7.1.4.9) to read the configuration file config.cmz (under /var/lib/texmf/dvips/config/config.cmz on my system). On my system, this file contains only one line:

p +psfonts.cmz

and looking at the psfonts. cmz file (located in /usr/share/texmf/dvips/bluesky/psfonts.cmz, notice the name “bluesky” in the directory path), I can see that all the necessary mappings from short names to full ones are there. Here are some lines of psfonts.cmz:

cmb10           CMB10           <cmb10.pfb
cmbsy10         CMBSY10         <cmbsy10.pfb
cmbx10          CMBX10          <cmbx10.pfb
cmbx12          CMBX12          <cmbx12.pfb
cmbx5           CMBX5           <cmbx5.pfb
cmbx6           CMBX6           <cmbx6.pfb
cmbx7           CMBX7           <cmbx7.pfb
cmbx8           CMBX8           <cmbx8.pfb
cmbx9           CMBX9           <cmbx9.pfb
cmbxsl10        CMBXSL10        <cmbxsl10.pfb

If no map file like the above can be found, you probably miss something from your distribution, unless you installed TeX/LaTex by hand, in which case you know what you are doing and might try the following (see LaTeX to PDF Guide):

Search for a file pdftex.map (see Section 4.3) in your TeX distribution (located in /var/lib/texmf/dvips/config/pdftex.map on my system). Run a Perl script as follows:

perl -ne '($font, @rest) = split(/ /);
                  $uc = $font;
                  $uc =~ tr/a-z/A-Z/;
                  print "$font $uc @rest";
                 ' PATH-TO-PDFTEX-MAP/pdftex.map
                 > cm.map

The created cm.map file instructs dvips to embed the Type1 outline fonts for the Computer Modern fonts into the resulting PostScript® file.

Add to your presonal .dvipsrc the following line

p +PATH-TO-CM-MAP/cm.map 

This tells dvips to use the font map you just created in addition to the system-wide configuration files.

The LyX User's Guide (available through the menu: Help-->User's Guide) contains a whole chapter devoted to the configuration of dvips and Ghostscript for LyX (Section 2.6, as of LyX 1.2.0), which is definitely recommended reading.

10.3.1. SGML math code correction

SGML math code as exported by LyX is, once again, not perfect and the first step consists in correcting it, just as we did in Section 7.1.4.1. We will change the SGML math code to fit our needs using again runsed and sedscr. But this time, we are going to need an awk script too, awkscr_math. We'll see in Section 10.3.1.2 why.

---

10.3.1.2. Solution

We will start with the second problem from Section 10.3.1.1 above, since it is the only one that needs both sed and awk to be solved. It is also a nice example of a problem that cannot be solved with only one of them[35]. In order to solve it, an observation was crucial: whenever a displayed equation occurs, LyX ends the preceding line with </para><para>. The idea is therefore to the <equation> tag that follows a line ending in </para><para> to something different than <equation>, so that we can safely say that the rest of remaining <equation> tags denotes actually inline equations and change them accordingly.

The following code in sedscr checks if the line ends in </para><para> and if so, gets the next line in the pattern space (N command). It then changes the <equation> to <informalequation>[36], prints the line and deletes the pattern space completely:

/<\/para><para>$/{ N s/[ \t\n\r]*<equation>/\ <informalequation>\ / p d }

The rest is accomplished in the awk script awkscr_math. We know by now that whatever <equation> tags may have remained, they denote the start of inline equations. We thus change <equation> to <inlineequation> and </equation> in </inlineequation>, but only between <equation>/</equation> tags. This is done by the following code in awkscr_math:

/<equation>/,/<\/equation>/{ gsub("<equation>","<inlineequation>") gsub("<\/equation>","<\/inlineequation>") }

Finally, we can transform whatever <informalequation> tags remain back to <equation>:

/<informalequation>/,/<\/equation>/{ gsub("<informalequation>","<equation id=\"eq" ++num_eq "\"> <title>(eq" num_eq ")<\/title>") }

By the way, we also did something that is impossible to do in sed: we added a dynamic id and title, both composed of the string “eq” and a dynamically increased counter. The id is the same as the “label” in LyX, the title is what will be displayed in the equation title. By letting the title be equal to the id, we are able to see what id an equation has in the SGML code (because it will be displayed in the title) and set the LyX label for that equation to be the same (see Section 10.2), thus making cross-refernces to equations possible[37].

The first problem, create the <graphic fileref=...> tags, requires a decision: which filename to take? A first idea, to use the label from the TeX codebetween the <alt> tags, as long as there is one, is not viable: what if the TeX code describes more than one equations (an eqnarray), each one labeled with its own label? I decided to use random filenames in all situations, rather than running into such problems. Due to the random part, such a substitution calls for awk, rather than sed.

The random numbers, which will be the filenames to use, are currently drawn between 10000 and 20000. If you want to change these limits, you can do it in the BEGIN part of awkscr_math:

BEGIN { num_min = 10000 num_max = 20000 num_ran = 0 num_dif = num_max - num_min num_eq = 0 srand() }

But sometimes, this randomness is not needed:

	How to get identical filenames for the equations from run to run
	If you want the same sequence of random numbers each time you run the script (thus producing the same filenames from run to run), you should comment the seed function srand().

The following code creates the <graphic fileref=...> tag with a random filename in the fileref attribute after the closing </alt> tag:

gsub("<\/alt>","<\/alt>\n <\!\[ \%output\.print\.png; \[\n <graphic fileref=\"images\/math\/" num_ran "\.png\">\n \]\]>\n <\!\[ \%output\.print\.pdf; \[\n <graphic fileref=\"images\/math\/" num_ran "\.png\">\n \]\]>\n <\!\[ \%output\.print\.eps; \[\n <graphic fileref=\"images\/math\/" num_ran "\.png\">\n \]\]>\n <\!\[ \%output\.print\.bmp; \[\n <graphic fileref=\"images\/math\/" num_ran "\.bmp\">\n \]\]>\n ")

More precisely, it substitutes </alt> with something like

</alt> <![ %output.print.png; [ <graphic fileref="images/math/10404.png"> ]]> <![ %output.print.pdf; [ <graphic fileref="images/math/10404.png"> ]]> <![ %output.print.eps; [ <graphic fileref="images/math/10404.png"> ]]> <![ %output.print.bmp; [ <graphic fileref="images/math/10404.bmp"> ]]>

Some remarks:

• The number used for the filename (10404) is randomly generated (num_ran, in the previous code example).

• The directory for the images of the equations is images/math. If you need to change it, you will have to do so everywhere in awkscr_math.

• We make again use of the output.print.xxx entities to denote code that has to be IGNOREd or INCLUDEd , depending on the format we are rendering, see Section 7.2.2 and Section 7.1.4.1.

• We specify a PNG file even for PDF and PS processing. That's not important. These formats will not take into account the <graphic> element when processed (the stylesheets will take care of this). Nevertheless, we must put a <graphic> tag with some filename there, otherwise openjade will complain.

• The important information is that the file 10404.png shall be used to display the equation when the output.print.png entity is included (i.e. only in HTML) and that 10404.bmp shall be used when the output.print.bmp entity is included (i.e. only in RTF).

The above substitution takes place in the following 4 situations (which cover all math situations in LyX' SGML) in awkscr_math:

• Between “<alt>\[” and “</alt>”.

• Between “<alt>$” and “</alt>”.

• Between “<alt>\begin{equation}” and “</alt>”.

• Between “<alt>\begin{eqnarray}” and “</alt>”.

This solves our first problem.

While we are at it, we substitute the “<” and “>” symbols (that appear in inequalities between the alt tags) with their SGML entities[38]:

if ( $1 != "<alt>\\\[" && $1 != "<\/alt>" ) { gsub("<"," \\&lt; ") gsub(">"," \\&gt; ") }

When texmath2pngbmp.pl is executed, it will see those entities and will substitute them with their numeric equivalents:

sub unescape { $eqn =~ s/&#38;/&/g; $eqn =~ s/&#62;/\>/g; $eqn =~ s/&#60;/\</g; }

This solves the fourth problem.

The third problem is easier solved: the following code in awkscr_math will substitute everything between <math> and </math> with the empty string (thus creating an empty line):

/<math>/,/<\/math>/{ gsub(".*","") }

That empty lines do not get printed, is easily seen from the last code block in awkscr_math:

!/^$/{ print }

which will print every line that is not empty.