6.2. Openjade errors

Jade does not support the DTDDECL catalog directive and it complains loudly if it encounters one. You may safely ignore this warning. See here for more details.

This seems to be a Jade/Docbook problem and not a LyX one. LyX is capable of inserting cross-references to arbitrary positions in a text. For this purpose, it creates an anchor with the id tag aproppriately set in the SGML file:

<anchor id="homepage-fig">

The cross-reference itself is placed with the xref element:

<xref linkend="homepage-fig">

The error means that this mechanism of cross-referencing is unsupported. This is why I change

<section><anchor id="homepage-fig">

to

<section id="homepage-fig">

with sed (see Section 4.10). This way, at least cross-references to sections created by LyX will work in SGML.

the label you used for a section contains spaces. Change spaces to, say, underscores or dashes.

you used a cross-reference to a label that contains spaces. Do not change the cross-reference. Change the label: change spaces to, say, underscores or dashes.

You probably have an empty subsubsection, e.g. you just outlined your documents and some subsubsections have a title but no content (yet). I consider this warning to be a bug. Or is it a feature???

this may be a bug of LyX' SGML generation. It happens when in an itemize environment you use a higher depth, possibly with nested item lists and subsequent paragraphs that you want to be on the same identation level as the outer item. Not critical.

Didn't track it down, but seems harmless.

Openjade tell us:

must be one of "BMP", "CGM-CHAR", "CGM-BINARY", "CGM-CLEAR", "DITROFF", "DVI", "EPS", "EQN", "FAX", "GIF", "GIF87A", "GIF89A", "JPG", "JPEG", "IGES", "PCX", "PIC", "PNG", "PS", "SGML", "TBL", "TEX", "TIFF", "WMF", "WPG", "LINESPECIFIC"

this means that the list of accepted formats does not contain “PDF”. Such a list appears in the following files:

• /usr/share/sgml/db3xml/dbnotnx.mod

• /usr/share/sgml/docbk30/docbook.dtd

• /usr/share/sgml/docbook_3/dbnotn.mod

• /usr/share/sgml/sdb/sdocbook.dtd

• /usr/share/sgml/db41xml/dbnotnx.mod

• /usr/share/sgml/docbook_4/dbnotn.mod

Given that LyX produces a SGML file containing

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"

as the first line, meaning that it uses DocBook V4.1 (1.1.x versions still used DocBook V3.0), we only need to insert "PDF" in the /usr/share/sgml/docbook_4/dbnotn.mod file:

<!ENTITY % notation.class "BMP| CGM-CHAR | CGM-BINARY | CGM-CLEAR | DITROFF | DVI | EPS | EQN | FAX | GIF | GIF87a | GIF89a | JPG | JPEG | IGES | PCX | PDF | PIC | PNG | PS | SGML | TBL | TEX | TIFF | WMF | WPG | linespecific %local.notation.class;"> 

If you still use LyX v.1.1.x, you should change /usr/share/sgml/docbook_3/dbnotn.mod to include “PDF” in the list of accepted file extensions:

<!ENTITY % notation.class                 "BMP| CGM-CHAR | CGM-BINARY | CGM-CLEAR | DITROFF | DVI                 | EPS | EQN | FAX | GIF | GIF87a | GIF89a                  | JPG | JPEG | IGES | PCX                 | PIC | PS | SGML | TBL | TEX | TIFF | WMF | WPG | PDF | PNG                 | linespecific                 %local.notation.class;"> 

Also, in the dbparam.dsl file for the print formats (located in /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/print/dbparam.dsl on my system), zou would need to add “pdf” to the list of allowed graphic extensions:

(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
  '("eps" "epsf" "gif" "tif" "tiff" "jpg" "jpeg" "png" "pdf" "tex"))

However, this is not necessary, since we use the technique of “ customization layers” (see Section 7.1.5) and define %graphic-extensions% in lyxtox-print.dsl as shown above. Due to the nature of the DSSSL language (which bears similarities to Scheme), our change takes precedence over the definition in the standard files and we don't need to change standard code.

Some cross-refernce you use is probably misspelled. But this is somewhat difficult to achieve with LyX, since LyX provides you with a list of all the labels currently available for cross-referencing. The other occasion where you will see this error is in the first (or even second?) invocation of LaTeX for a particular format. You need at least 3 LaTeX passes for the table of contents and the cross-references to be worked out and if you are currently on the first pass, you will see this error for every cross-reference.

If you installed the Computern Modern fonts, you probably don't need to worry about this error. If you check the fonts used in the PDF file (File-->Documet Info-->Fonts-->List all fonts), you will probably find out that only some seldomly used characters were not rendered with CM fonts. That's O.K. for me.

You will get dozens of this. It is a typical LaTeX warning informing you that a line got some points too wide (mostly because there was some word that LaTeX could not hyphenate). Read the LaTeX documentation for this (but only if you want to produce a really perfect PDF document).

This is probably caused because %graphic-default-extension% is set to “false” (“#f”), while in lyxtox-print.dsl we try to concatenate the %admon-graphics-path%, the name of the admonition and %graphic-default-extension% to a full name of the admonition graphic. It is harmless, due to the way we use the graphics (see Section 7.2.2).

thumbpdf complains even if the version is a newer one:

*** make `thumbpdf.pdf' / run pdfTeX ***
!!! Warning: Version of `thumbpdf.tex' does not match with perl script!
Current `thumbpdf.tex': 2002/05/26 v3.2
Please install version: 2001/01/12 v2.8

But if you have the newest version, as in the above case, there is no need to worry about this error.

You may see this openjade error also for “SECT2”, “SECT3” and so forth. This may come up if you have written just the title of the section, subsection or subsubsection respectively, but you did not enter any text there. Just enter something, even a single word like “FIXME” (author's note to himself: this is a literal FIXME, not a meta-FIXME!), to remind you of the missing text, and the error should go away.

This is a similar error to the previous one. You most probably created a subsection which is not contained in a section, but is dircetly contained in a chapter. Similar errors will occur if you ommit environment levels that are “in between” the current one and its parent.

You have an ID on the line where this error comes up - and this ID is too long, longer than NAMELEN, which is 44 in my case. Use a shorter ID. What in SGL comes as the ID of a chapter, section, figure or table, in LyX it is a label. Thus you should check your labels and make sure they are not longer than 44 characters.

Alternatively, change the value of NAMELEN in the file pointed to by the SGMDCL directive in your catalog files: The lyxtox script uses, among others, the following catalog: /usr/share/sgml/CATALOG.docbook-dsssl-stylesheets. You can see this in the line:

SGML_CATALOG_FILES="$SGML_CATALOG_FILES: /usr/share/sgml/CATALOG.docbook-dsssl-stylesheets" 

In this catalog, I have changed the SGMLDECL line from:

-- SGMLDECL "dtds/decls/docbook.dcl" --

to

SGMLDECL "/usr/share/sgml/docbook/docbook-dsssl-stylesheets/dtds/decls/docbook.dcl"

to reflect the correct path to the DocBook declaration file in my system. You must thus change the value of the NAMELEN variable in the file where the SGMLDECL points to, i.e.[1] docbook/docbook-dsssl-stylesheets/dtds/decls/docbook.dcl. There, change

        QUANTITY SGMLREF
                ATTCNT    256
                GRPCNT    253
                GRPGTCNT  253
                LITLEN   8092
                NAMELEN    44
                TAGLVL    100

to, for example:

        QUANTITY SGMLREF
                ATTCNT    256
                GRPCNT    253
                GRPGTCNT  253
                LITLEN   8092
                NAMELEN    64
                TAGLVL    100

See the error 'character "_" is_not allowed in the value of attribute "ID"' below for more changes you might need to make in the DocBook declaration file.

You have a LyX label that contains “:”. Delete the “:” , as the label of a chapter, section, figure, table etc. is going to be the ID of that element and “:” is not allowed in IDs. However, this only the short answer. For an in-depth explanation, see the next item.

You have a LyX label that contains “_”. Delete the “_” , as the label of a chapter, section, figure, table etc. is going to be the ID of that element and “_” is not allowed in IDs. However, as said in the previous item, this is only the tip of the iceberg. A tip of the hat to Tony Graham for the following detailed information in Allowed characters in element id's!

The characters allowed in an ID are those allowed in an SGML "NAME". The characters that are allowed to appear in “names” in SGML (the id attribute is defined in SGML as such a “NAME”) are set in what is known as the “ SGML declarationSGML declaration” of your document. By default, the first character must be a letter, and any other characters may be a letter or a digit.

You can add to this by specifying the additional characters in your SGML Declaration (and you can't take any characters away). The convention in widest use is that of the "Reference concrete syntax" included in the SGML standard itself that adds "." and "-" as "name" characters (but not as "name start" characters). This is what's used in the DocBook SGML Declaration, docbook.dcl.

The specific portion of the SGML Declaration of interest here is the "naming rules". Jade's default inferred SGML Declaration uses the same naming rules as SGML's "Reference Concrete Syntax". To allow underscores in entity names (and other SGML names), you need to supply an SGML Declaration that includes the underscore character. Using the DocBook SGML Declaration as an example, you need to add "_" to the LCNMSTRT and UCNMSTRT parameters:

        NAMING
                LCNMSTRT ""
                UCNMSTRT ""
                LCNMCHAR ".-"
                UCNMCHAR ".-"
                NAMECASE
                        GENERAL YES
                        ENTITY  NO

The NAMING portion specifies both uppercase and lowercase forms of the additional "name start" and "name" characters (since names are folded to uppercase when the "GENERAL" parameter has the value YES"). You need to add it in two places because you are declaring the uppercase and lowercase forms, which just happen to be the same.

You can reference your SGML Declaration by including it in the Jade command line before the filename for your SGML file (or before your DTD if also including the DTD filename in the command line). You can also reference an SGML Declaration to infer by using the "SGMLDECL" keyword in your catalog file. (See "charset.htm" from the nsgmls distribution for more information on the catalog format. FIXME: URL!)

Now, what does all that mean for our specific situation?

The lyxtox script uses, among others, the following catalog: /usr/share/sgml/CATALOG.docbook-dsssl-stylesheets. You can see this in the line:

SGML_CATALOG_FILES="$SGML_CATALOG_FILES: /usr/share/sgml/CATALOG.docbook-dsssl-stylesheets" 

In this catalog, change the SGMLDECL line from:

-- SGMLDECL "dtds/decls/docbook.dcl" --

to

SGMLDECL "/usr/share/sgml/docbook/docbook-dsssl-stylesheets/dtds/decls/docbook.dcl"

Note that we have taken away the comments and corrected the path to the declaration.

But that's NOT enough!

You must also change the file where the SGMLDECL points to, i.e.[2] docbook/docbook-dsssl-stylesheets/dtds/decls/docbook.dcl. There, change

        NAMING
                LCNMSTRT ""
                UCNMSTRT ""
                LCNMCHAR ".-"
                UCNMCHAR ".-"
                NAMECASE
                        GENERAL YES
                        ENTITY  NO

to:

        NAMING
                LCNMSTRT ""
                UCNMSTRT ""
                LCNMCHAR ".-_"
                UCNMCHAR ".-_"
                NAMECASE
                        GENERAL YES
                        ENTITY  NO

i.e. add the underscore to LCNMCHAR and UCNMCHAR.

This solves the problem at its root! See also character "_" not allowed in value of attribute ID.

When you enter an URL in LyX, you are asked to enter the URL and the Name of the link in a window that pops up. Whatever you enter in the URL field, will be automatically taken care by LyX: if it contains special characters, like ampersands, they are replaced with their SGML equivalent (see SGML entities). But whatever you enter in the Name field, it will passed “as is” to SGML. If you feel lazy and just copy the URL in the Name field, you must take care to replace special characters with their SGML entities yourself. Dynamic URLs are a classic example and are going to flood you with this error, if you do not do your homework. For example, if you feel you have to write something like

http://www.karakas-online.de/forum/viewtopic.php?t=14&f=3

instead of

Welcome to the <productname>Linux</productname> Forum of Chris

then you should write it as

http://www.karakas-online.de/forum/viewtopic.php?t=14&f=3

i.e. replace “&” with its SGML entity “&”.

BODY? Which body? You don't remember to have entered anything like this in you text? Well, check for “<body>” somewhere in the text (not the code environments, as those have been taken care already by LyX). You have to replace the “<” and “>” with their SGML entities “&lt;” and “&gt” respectively. When you correct it, the other two errors

end tag for "BODY" omitted, but OMITTAG NO was specified
start tag was here

will disappear too, since they are just follow-ups of the first one.

This simply means that you did not replace some special character with its SGML entity. Have a look at the tables in SGML entities, try to guess which character is meant in the error (the SGML lines produced by LyX can become longer than Proust's), and replace it.

But the reason for this error may also lie in the fact that you forgot to change the LyX environment (see Section 5.1) from SGML to Standard and the text contains some special characters, like dashes. In this case, the text is interpreted in the SGML context and the special characters give rise to misunderstandings and errors in th parser. Just change the environment from SGML back to Standard (or whatever else it should be) and the error will disappear.

This error happens because sed (more precisely, the sed commands in sedscr) did not manage to change the SGML that LyX produced for a figure. The reason sedscr failed lies probably in some strange arrangement of the starting SGML tags for the figure. The best cure is to enter a “forced new line” by pressing Strg+Enter at the end of the line that precedes the offending figure. This will force the whole SGML code to start on a new line and will make identification by sedscr easier. The next time you run lyxtox, the correct SGML commands for the figure will be generated and the error will disappear.

How on earth could this happen? Well, if you are like me and always try new possibilities with LyX and SGML, then you will encounter this error if you enter an URL while in the SGML environment. There, of course, you cannot just use LyX' menu Insert->URL - you have to write the SGML code for an URL &lt;ulink url=”http://www.somesite.com”&gt;. Now, if you forget to enclose the URL (the “ attribute value”, as the error says, of the “url” attribute in the ulink element) in double quotes, then you will get that error.

You shouldn't get this error when you use the scripts desribed here - simply because the sedscr_tidy2 script takes care that it does not occur. However, if you do get it, it is nice to know why:

Due to the way the SGML parser works, the following piece of code describing an informal table will produce a “ document type does not allow element <para>” error:

<informaltable>
<tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="col0" align="center">
<colspec colname="col1" align="center">
<tbody>
<row>
<entry align="center" valign="top">
<para>
EAN
</para>
</entry>
<entry align="center" valign="top">
<para>
9783898112338
</para>
</entry>
</row>

The reason is the so-called “Pernicious Mixed Content Problem”. From the Definitive Guide to DocBook on the <entry> element:

The content model of the Entry element exhibits a nasty peculiarity that we call pernicious mixed content.[18]

Every other element in DocBook contains either block elements or inline elements (including #PCDATA) unambiguously. In these cases, the meaning of line breaks and spaces are well understood; they are insignificant between block elements and significant (to the SGML parser, anyway) where inline markup can occur.

Table entries are different; they can contain either block or inline elements, but not both at the same time. In other words, one Entry in a table might contain a paragraph or a list while another contains simply #PCDATA or another inline markup, but no single Entry can contain both.

Because the content model of an Entry allows both kinds of markup, each time the SGML parser encounters an Entry, it has to decide what variety of markup it contains. SGML parsers are forbidden to use more than a single token of lookahead to reach this decision. In practical terms, what this means is that a line feed or space after an Entry start tag causes the parser to decide that the cell contains inline markup. Subsequent discovery of a paragraph or another block element causes a parsing error.

All of these are legal:

<entry>3.1415927</entry> <entry>General <emphasis>#PCDATA</emphasis></entry> <entry><para> A paragraph of text </para></entry>

However, each of these is an error:

<entry> Error, cannot have a line break before a block element <para> A paragraph of text. </para></entry> <entry><para> A paragraph of text. </para> Error, cannot have a line break between block elements <para> A paragraph of text. </para></entry> <entry><para> A paragraph of text. </para> Error, cannot have a line break after a block element </entry>

Thus, the informal table example above must be corrected to:

<informaltable>
<tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="col0" align="center">
<colspec colname="col1" align="center">
<tbody>
<row>
<entry align="center" valign="top"><para>
EAN
</para></entry>
<entry align="center" valign="top"><para>
9783898112338
</para></entry>
</row>

This is done in lyxtox with a call to runsed using sedscr_tidy2 as the sed script. See also Openjade error: <para> not allowed after <entry>.