\end_deeper
\layout Itemize
Add translation links for the current page.
But how does the header know the link to the current page? Here's where
the constants DOMAIN, DIRNAME and FILENAME come into play:
\begin_deeper
\layout Code
\layout Code
chinese
\layout Code
|
\layout Code
french
\layout Code
|
\layout Code
german
\layout Code
|
\layout Code
italian
\layout Code
|
\layout Code
japanese
\layout Code
|
\layout Code
korean
\layout Code
|
\layout Code
portuguese
\layout Code
|
\layout Code
spanish
\layout Code
\layout Standard
DOMAIN is set in the .start file (see
\begin_inset LatexCommand \ref{start-and-end-scripts}
\end_inset
), DIRNAME is replaced in lyxtox with the parameter you passed it:
\layout Code
${SED} -e "s/_DIRNAME_/$1/g" part2_1.tmp > part2_2.tmp
\layout Standard
Since the parameter you pass to lyxtox is supposed to be the basename of
your .lyx file, which will also become the name of the directory where everythin
g is going to be placed, you can see that DIRNAME will be replaced with
the right directory name (actually, what will be replaced is _DIRNAME_,
but the underscores are there only to make sure there is no other DIRNAME
variable by accident there).
Finally, FILENAME is determined in lyxtox as the basename of the HTML file:
\layout Code
${SED} -e "s/_FILENAME_/${BASENAME}/g" part2_2.tmp > part2_3.tmp
\end_deeper
\layout Itemize
Add some
\begin_inset Quotes eld
\end_inset
breadcrumbs
\begin_inset Quotes erd
\end_inset
, i.e.
navigation links separated by a
\begin_inset Quotes eld
\end_inset
|
\begin_inset Quotes erd
\end_inset
.
Here the links point to the various formats of the document, with a nice
example of how to mail the current page to a friend using a custom text
and the right page link:
\begin_deeper
\layout Code
\end_deeper
\layout Standard
For the footer:
\layout Itemize
Add a timestamp and a
\begin_inset Quotes eld
\end_inset
permalink
\begin_inset Quotes erd
\end_inset
(a permanent link, which people can use to link to the page):
\begin_deeper
\layout Code
\end_deeper
\layout Itemize
Add translation links to the current page.
These are the same as the ones for the header, only that they are centered
instead of being aligned to the right of the page:
\begin_deeper
\layout Code
\layout Code
chinese
\layout Code
|
\layout Code
french
\layout Code
|
\layout Code
german
\layout Code
|
\layout Code
italian
\layout Code
|
\layout Code
japanese
\layout Code
|
\layout Code
korean
\layout Code
|
\layout Code
portuguese
\layout Code
|
\layout Code
spanish
\layout Code
\layout Code
Once again, the DOMAIN, DIRNAME and FILENAME constants come into play.
\end_deeper
\layout Itemize
Finally, add some icons.
Some of them point to the validator services of the W3C (see
\begin_inset LatexCommand \ref{HTML-validation}
\end_inset
).
These are also nice examples of how to compute the right link that is to
be sent to the validator so that it will be able to validate the current
page: you have to use
\begin_inset Quotes eld
\end_inset
http%3A%2F%2F_DOMAIN_%2F_DIRNAME_%2F_FILENAME_
\begin_inset Quotes erd
\end_inset
for the CSS validator, but is is enough to use
\begin_inset Quotes eld
\end_inset
http://validator.w3.org/check/referer
\begin_inset Quotes erd
\end_inset
for the HTML validator.
And don't miss the special link to
\begin_inset Quotes eld
\end_inset
validate your browser
\begin_inset Quotes erd
\end_inset
! :-)
\begin_deeper
\layout Code
\end_deeper
\layout SGML
\layout SGML
How to set the constants in the part* files
\layout SGML
\layout SGML
Do not set the DOMAIN, DIRNAME and FILENAME constants in the part* files.
Set only TITLE, DOMAIN, FORMATSFILE, COPYRIGHT and HOMEFILE in the .start
file.
DIRNAME and FILENAME are computed automatically in lyxtox.
\layout SGML
\layout SGML
\layout Section
Set up your bibliographic database
\begin_inset LatexCommand \label{bibliographic-database}
\end_inset
\layout Standard
If you don't want to use
\begin_inset LatexCommand \url[RefDB]{http://refdb.sourceforge.net}
\end_inset
, there is nothing you have to do at this stage, so you can skip this section.
However, you will have more work in the long run, as you will need to enter
the bibliographic
\begin_inset LatexCommand \index{bibliographic}
\end_inset
references each time by hand in pure SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
in a separate file, see
\begin_inset LatexCommand \ref{LyX-Bibliography}
\end_inset
.
\layout Standard
If you want to use RefDB,
\begin_inset LatexCommand \index{RefDB}
\end_inset
to take advantage of all the automated processing
\begin_inset LatexCommand \index{processing}
\end_inset
offered to you by a bibliographic database,
\begin_inset LatexCommand \index{database}
\end_inset
RefDB
\begin_inset LatexCommand \index{RefDB}
\end_inset
and the
\begin_inset LatexCommand \url[lyxtox]{./lyxtox}
\end_inset
script, there is some prelimnary work to do: before you use your bibliographic
\begin_inset LatexCommand \index{bibliographic}
\end_inset
treasures in citations
\begin_inset LatexCommand \index{citations}
\end_inset
and the reference list, you have to import them into the RefDB
\begin_inset LatexCommand \index{RefDB}
\end_inset
database you created during installation of the RefDB
\begin_inset LatexCommand \index{RefDB}
\end_inset
package (see
\begin_inset LatexCommand \ref{Refdb}
\end_inset
).
Further, you must give the name of your database
\begin_inset LatexCommand \index{database}
\end_inset
as the value of the RefDB_db
\begin_inset LatexCommand \index{RefDB_db}
\end_inset
variable in
\begin_inset LatexCommand \url[lyxtox]{./lyxtox}
\end_inset
and also set process_RefDB to
\begin_inset Quotes eld
\end_inset
1
\begin_inset Quotes erd
\end_inset
, indicating you wish bibliographic
\begin_inset LatexCommand \index{bibliographic}
\end_inset
processing
\begin_inset LatexCommand \index{processing}
\end_inset
through RefDB.
\begin_inset LatexCommand \index{RefDB}
\end_inset
\layout Standard
Adding references boils down to running the
\begin_inset LatexCommand \url[addref]{http://refdb.sourceforge.net/manual-0.9.4/x4965.html#APP-C-COMMAND-ADDREF}
\end_inset
command with proper input files.
The input files have to be valid RIS
\begin_inset LatexCommand \index{RIS}
\end_inset
files.
They may contain one or more RIS
\begin_inset LatexCommand \index{RIS}
\end_inset
datasets.
\layout Standard
An example of a RIS
\begin_inset LatexCommand \index{RIS}
\end_inset
file is
\begin_inset LatexCommand \url[refdb.ris]{refdb.ris}
\end_inset
.
A typical bibliographic
\begin_inset LatexCommand \index{bibliographic}
\end_inset
entry in the RIS
\begin_inset LatexCommand \index{RIS}
\end_inset
format looks like:
\layout Code
TY - ELEC
\layout Code
ID - Walsh2002
\layout Code
AU - Walsh,Norman
\layout Code
AU - Muellner,Leonard
\layout Code
TI - DocBook: The definitive Guide - Apendix
\layout Code
KW - guide
\layout Code
KW - docbook
\layout Code
RP - NOT IN FILE
\layout Code
PB - O'Reilly & Associates, Inc.
\layout Code
UR - http://docbook.org/tdg/en/html/appa.html
\layout Code
N1 - Accessed 29.06.2003
\layout Code
PY - 2002/06/17/Version 2.0.8
\layout Code
SN - 156592-580-7
\layout Code
ER -
\layout Standard
Each line starts with a two-letter
\begin_inset LatexCommand \index{two-letter}
\end_inset
tag followed by the string
\begin_inset Quotes eld
\end_inset
-
\begin_inset Quotes eld
\end_inset
(two spaces, a dash, and another space).
Each RIS
\begin_inset LatexCommand \index{RIS}
\end_inset
dataset starts with the TY
\begin_inset LatexCommand \index{TY}
\end_inset
(type) tag and ends with the ER
\begin_inset LatexCommand \index{ER}
\end_inset
(End of Reference) tag.
In between, tag sequence is arbitrary.
The meaning of the tags is:
\layout Description
TY: Citation type.
Can attain many values, some of the most usual being:
\layout Itemize
ABST (abstract reference)
\layout Itemize
BOOK (whole book reference)
\layout Itemize
COMP (computer program)
\layout Itemize
DATA
\begin_inset LatexCommand \index{DATA}
\end_inset
(data file)
\layout Itemize
ELEC
\begin_inset LatexCommand \index{ELEC}
\end_inset
(electronic citation)
\layout Itemize
GEN (generic)
\layout Itemize
JOUR (journal/periodical reference)
\layout Description
ID: Unique citation
\begin_inset LatexCommand \index{citation}
\end_inset
ID
\begin_inset LatexCommand \index{ID}
\end_inset
string.
This can either be explicitly set by you, or automatically
\begin_inset LatexCommand \index{automatically}
\end_inset
set by the RefDB
\begin_inset LatexCommand \index{RefDB}
\end_inset
system.
It plays the same role as the citation
\begin_inset LatexCommand \index{citation}
\end_inset
key in the standard methods provided by LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
for citation
\begin_inset LatexCommand \index{citation}
\end_inset
purposes (see
\begin_inset LatexCommand \ref{explain-bibliography}
\end_inset
).
\layout Description
AU: Author.
Synonym: A1.
\begin_inset LatexCommand \index{A1}
\end_inset
\layout Description
TI: Title
\layout Description
KW: Keyword
\layout Description
RP: Reprint status.
Can be one of
\layout Itemize
IN FILE
\begin_inset LatexCommand \index{FILE}
\end_inset
\layout Itemize
NOT IN FILE
\begin_inset LatexCommand \index{FILE}
\end_inset
\layout Itemize
ON REQUEST MM/DD/YY
\layout Description
PB: Publisher
\layout Description
UR: URL
\begin_inset LatexCommand \index{URL}
\end_inset
(for electronic citations)
\layout Standard
Multiple AU
\begin_inset LatexCommand \index{AU}
\end_inset
and KW
\begin_inset LatexCommand \index{KW}
\end_inset
tags are possible.
For a complete list of the RIS
\begin_inset LatexCommand \index{RIS}
\end_inset
tags and their possible values see
\begin_inset LatexCommand \url[Writing RefDB data input]{http://refdb.sourceforge.net/manual-0.9.4/c2166.html}
\end_inset
- here is a more elaborate example of a bibliographic
\begin_inset LatexCommand \index{bibliographic}
\end_inset
entry in RIS
\begin_inset LatexCommand \index{RIS}
\end_inset
format, taken from this document:
\begin_inset LatexCommand \index{document}
\end_inset
\layout Code
TY - CHAP
\layout Code
T1 - Physiological studies of the natriuretic peptide family
\layout Code
A1 - Lewicki,J.A.
\layout Code
A1 - Protter,A.A.
\layout Code
Y1 - 1995///
\layout Code
N1 - Atrial Natriuretic Peptide Cardiac synthesis and secretion of /
\layout Code
ANP Regulation of ANP Gene Expression Regulation of ANP Release /
\layout Code
ANP Receptors Biologic Actions of ANP Brain Natriuretic Peptide (BNP)
/
\layout Code
BNP Structure Biosynthesis of BNP Biological Actions of BNP C-Type
/
\layout Code
Natriuretic Peptide (CNP) Biologic Actions of CNP Modulators of /
\layout Code
Natriuretic Peptide Clearance Effects of Clearance Receptor Blockers
/
\layout Code
Effects of Neutral Endopeptidase Inhibitors Role of the Natriuretic /
\layout Code
Peitedes in Physiology and Disease Hypertension Congestive Heart /
\layout Code
Failure Supraventricular Tachyarrhythmias Acute Renal Dysfunction
\layout Code
KW - natriuretic
\layout Code
KW - ANF
\layout Code
KW - ANP
\layout Code
KW - receptors
\layout Code
KW - BNP
\layout Code
KW - CNP
\layout Code
KW - hypertension
\layout Code
KW - congestive heart failure
\layout Code
KW - review
\layout Code
KW - cardiac
\layout Code
KW - regulation
\layout Code
KW - gene expression
\layout Code
KW - expression
\layout Code
KW - brain
\layout Code
KW - structure
\layout Code
KW - biosynthesis
\layout Code
KW - receptor
\layout Code
KW - inhibitor
\layout Code
KW - physiology
\layout Code
KW - renal
\layout Code
KW - study
\layout Code
KW - Peptides
\layout Code
KW - atrial natriuretic peptide
\layout Code
KW - MODULATOR
\layout Code
KW - secretion
\layout Code
KW - Gene Expression Regulation
\layout Code
RP - IN FILE
\layout Code
SP - 1029
\layout Code
EP - 1053
\layout Code
VL - 2
\layout Code
T2 - Hypertension: Pathophysiology, Diagnosis, and Management
\layout Code
A2 - Laragh,J.H.
\layout Code
A2 - Brenner,B.M.
\layout Code
IS - 61
\layout Code
CY - New York
\layout Code
PB - Raven Press, Ltd.
\layout Code
ER -
\layout Standard
To build your own bibliographic
\begin_inset LatexCommand \index{bibliographic}
\end_inset
database, you thus need all your references in the RIS
\begin_inset LatexCommand \index{RIS}
\end_inset
format.
If you found your reference in the web edition of some scientific
\begin_inset LatexCommand \index{scientific}
\end_inset
journal, or one of the specialized bibliographic
\begin_inset LatexCommand \index{bibliographic}
\end_inset
databases on the Internet, like
\begin_inset LatexCommand \url[PubMed]{http://www.pubmed.com}
\end_inset
, chances are that you will be able to copy the RIS
\begin_inset LatexCommand \index{RIS}
\end_inset
version of the bibliographic
\begin_inset LatexCommand \index{bibliographic}
\end_inset
entry with a mouse click on some link.
Otherwise, you will either have to import it with the use of one of the
input filters
\begin_inset LatexCommand \index{filters}
\end_inset
shipped with RefDB,
\begin_inset LatexCommand \index{RefDB}
\end_inset
use the Web
\begin_inset LatexCommand \index{Web}
\end_inset
interface
\begin_inset LatexCommand \index{interface}
\end_inset
(which you installed in
\begin_inset LatexCommand \ref{Refdb}
\end_inset
), or write all those tags and their values by hand.
\layout Standard
For automatic import, RefDB
\begin_inset LatexCommand \index{RefDB}
\end_inset
offers the following input filters:
\begin_inset LatexCommand \index{filters}
\end_inset
\layout Itemize
dos2unix: A simple shell script to convert
\begin_inset LatexCommand \index{convert}
\end_inset
text files like RIS
\begin_inset LatexCommand \index{RIS}
\end_inset
documents from DOS-style line endings
\begin_inset LatexCommand \index{endings}
\end_inset
to Unix-style line endings.
Most refdb
\begin_inset LatexCommand \index{refdb}
\end_inset
tools need their input files with Unix-style line endings.
\begin_inset LatexCommand \index{endings}
\end_inset
This is a valuable tool to import reference databases from Windows
\begin_inset LatexCommand \index{Windows}
\end_inset
reference managers.
\layout Itemize
med2ris.pl: A tool to convert
\begin_inset LatexCommand \index{convert}
\end_inset
Pubmed
\begin_inset LatexCommand \index{Pubmed}
\end_inset
data in both the tagged
\begin_inset LatexCommand \index{tagged}
\end_inset
and the XML format to RIS.
\begin_inset LatexCommand \index{RIS}
\end_inset
\layout Itemize
bib2ris: A tool to convert
\begin_inset LatexCommand \index{convert}
\end_inset
BibTeX data to RIS.
\begin_inset LatexCommand \index{RIS}
\end_inset
\layout Itemize
db2ris: A tool to convert
\begin_inset LatexCommand \index{convert}
\end_inset
reference data in DocBook
\begin_inset LatexCommand \index{DocBook}
\end_inset
SGML/XML documents to RIS.
\begin_inset LatexCommand \index{RIS}
\end_inset
\layout Itemize
marc2ris.pl: A tool to convert
\begin_inset LatexCommand \index{convert}
\end_inset
references in MARC format to RIS.
\begin_inset LatexCommand \index{RIS}
\end_inset
\layout Standard
To import all references from a RIS
\begin_inset LatexCommand \index{RIS}
\end_inset
file called, say, refdb.
\begin_inset LatexCommand \index{refdb}
\end_inset
ris, start refdbc and then type:
\layout Code
addref refdb.ris
\layout Standard
Once you have populated your own bibliographic
\begin_inset LatexCommand \index{bibliographic}
\end_inset
database with entries, you should export it to a file - it will serve you
as a backup and reference.
To export all entries in a file called refdb.
\begin_inset LatexCommand \index{refdb}
\end_inset
ris (this will overwrite any existing refdb.
\begin_inset LatexCommand \index{refdb}
\end_inset
ris file, so take care):
\layout Code
getref -t ris -o refdb.ris -s "ALL" :ID:>0
\layout Standard
Open the refdb.
\begin_inset LatexCommand \index{refdb}
\end_inset
ris file with a text editor and examine it.
Pay special attention to the values of the ID
\begin_inset LatexCommand \index{ID}
\end_inset
field - we will use this field in a somewhat tricky way to refer to the
bibliographic
\begin_inset LatexCommand \index{bibliographic}
\end_inset
entries from LyX.
\begin_inset LatexCommand \index{LyX}
\end_inset
How this is done, is explained in
\begin_inset LatexCommand \ref{LyX-Bibliography}
\end_inset
.
\layout Section
Use a CSS for DocBook
\begin_inset LatexCommand \label{CSS}
\end_inset
\layout Standard
The following two definitions in the HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
stylesheets (see
\begin_inset LatexCommand \ref{DSSSL-stylesheets}
\end_inset
) specify the CSS
\begin_inset LatexCommand \index{CSS}
\end_inset
that is to be used for HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
output:
\layout Code
(define %stylesheet%
\layout Code
;; Name of the stylesheet to use
\layout Code
;;#f)
\layout Code
"ck-style.css")
\layout Code
\layout Code
(define %stylesheet-type%
\layout Code
;; The type of the stylesheet to use
\layout Code
"text/css")
\layout Standard
Of course, you may decide that you don't need a CSS,
\begin_inset LatexCommand \index{CSS}
\end_inset
in which case you should define %stylesheet%
\begin_inset LatexCommand \index{%stylesheet%}
\end_inset
to
\begin_inset Quotes eld
\end_inset
#f
\begin_inset Quotes erd
\end_inset
.
But this is only part of the story! You may discover that your HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
documents still need the ck-style.css,
\begin_inset LatexCommand \index{ck-style.css}
\end_inset
even if you set %stylesheet%
\begin_inset LatexCommand \index{%stylesheet%}
\end_inset
to
\begin_inset Quotes eld
\end_inset
#f
\begin_inset Quotes erd
\end_inset
! This is because of the extra processing
\begin_inset LatexCommand \index{processing}
\end_inset
that the header, body
\begin_inset LatexCommand \index{body}
\end_inset
and footer are subject to, as described in
\begin_inset LatexCommand \ref{HTML-validation}
\end_inset
.
You will have to change
\begin_inset LatexCommand \url[part2]{part2}
\end_inset
too to reflect the right CSS.
\begin_inset LatexCommand \index{CSS}
\end_inset
\layout Standard
Talking about a
\begin_inset Quotes eld
\end_inset
right
\begin_inset Quotes erd
\end_inset
CSS
\begin_inset LatexCommand \index{CSS}
\end_inset
for DocBook,
\begin_inset LatexCommand \index{DocBook}
\end_inset
you may find out that there not so many out there available - see
\begin_inset LatexCommand \url[CSS for DocBook]{http://www.karakas-online.de/myLinuxTips/css-for-docbook.html}
\end_inset
for a rare example.
The problem is that the HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
produced by the tools
\begin_inset LatexCommand \index{tools}
\end_inset
presented here uses its own classes which don't seem to be widely used outside
DocBook.
\begin_inset LatexCommand \index{DocBook}
\end_inset
Instead of inventing the wheel
\begin_inset LatexCommand \index{wheel}
\end_inset
for the third time, just grab my
\begin_inset LatexCommand \url[ck-style.css]{ck-style.css}
\end_inset
and use it as is, or adapt it to your purposes.
As the scripts currently use it, it has to be installed in the working
directory, but you can certainly change that easily.
\layout Section
Use coolthumbs
\begin_inset LatexCommand \label{coolthumbs}
\end_inset
\layout Standard
coolthumbs is a small, fine script that will create antialiased thumbnails
\begin_inset LatexCommand \index{thumbnails}
\end_inset
for your PDF
\begin_inset LatexCommand \index{PDF}
\end_inset
document (those icons
\begin_inset LatexCommand \index{icons}
\end_inset
that look like miniature copies of your pages, in the left column of Acrobat
Reader, besides the bookmarks
\begin_inset LatexCommand \index{bookmarks}
\end_inset
tab).
Whithout it, the thumbnails
\begin_inset LatexCommand \index{thumbnails}
\end_inset
will look
\begin_inset Quotes eld
\end_inset
high contrast
\begin_inset Quotes erd
\end_inset
or
\begin_inset Quotes eld
\end_inset
edgy
\begin_inset Quotes erd
\end_inset
.
Using coolthumbs will produce hight quality thumbnails,
\begin_inset LatexCommand \index{thumbnails}
\end_inset
with the help of Ghostscript
\begin_inset LatexCommand \index{Ghostscript}
\end_inset
and The GIMP (which, of course, you must also have installed, if you decide
to use it).
You can get coolthumbs from the
\begin_inset LatexCommand \url[Linux LaTeX-PDF HOW-TO]{http://www.ringlord.com/publications/latex-pdf-howto}
\end_inset
(I would love to include it here, but unfortunately its copyright
\begin_inset LatexCommand \index{copyright}
\end_inset
notice does not allow it explicitly).
\layout Standard
Install coolthumbs in, say, /usr/local/bin.
Then enter its location in lyxtox
\begin_inset LatexCommand \index{lyxtox}
\end_inset
and set the use_coolthumbs parameter
\begin_inset LatexCommand \index{parameter}
\end_inset
to 1:
\layout Code
# Shall we use the coolthumbs script to create the PDF thumbnails?
\layout Code
# You can get coolthumbs from
\layout Code
# http://www.ringlord.com/publications/latex-pdf-howto/
\layout Code
# Note that you will also need to have GIMP installed
\layout Code
# and that you will have to edit some lines in coolthumbs too.
\layout Code
use_coolthumbs="1"
\layout Standard
These are the values I had to change in my copy of coolthumbs:
\layout Itemize
The location of The GIMP:
\begin_deeper
\layout Code
# Program locations
\layout Code
GIMP="/usr/bin/gimp"
\layout Code
My GIMP scripts directory:
\layout Code
# GIMPSCRIPTS: Your GIMP scripts directory.
the file named by
\layout Code
# SCALEALL will be CREATED there and then DELETED again:
\layout Code
GIMPSCRIPTS=${HOME}/.gimp-1.2/scripts
\end_deeper
\layout Itemize
Width and height of the thumbnails:
\begin_inset LatexCommand \index{thumbnails}
\end_inset
\begin_deeper
\layout Code
THUMBNAIL_W=74
\layout Code
THUMBNAIL_H=105
\end_deeper
\layout Itemize
Some explanation on the choice of those values is due here: the ISO/DIN
paper
\begin_inset LatexCommand \index{paper}
\end_inset
sizes (in mm) for the various DIN paper
\begin_inset LatexCommand \index{paper}
\end_inset
sizes are shown in
\begin_inset LatexCommand \ref{tab-ISO-DIN-paper-sizes}
\end_inset
(taken from
\begin_inset LatexCommand \url[Paper size]{http://en.wikipedia.org/wiki/Paper_size}
\end_inset
).
\begin_deeper
\layout Standard
\begin_inset Float table
placement htbp
wide false
collapsed false
\layout Caption
\begin_inset LatexCommand \label{tab-ISO-DIN-paper-sizes}
\end_inset
ISO/DIN paper sizes
\layout Standard
\begin_inset Tabular
\begin_inset Text
\layout Standard
\end_inset
\begin_inset Text
\layout Standard
A
\end_inset
\begin_inset Text
\layout Standard
B
\end_inset
\begin_inset Text
\layout Standard
C
\end_inset
\begin_inset Text
\layout Standard
0
\end_inset
\begin_inset Text
\layout Standard
841x1189
\end_inset
\begin_inset Text
\layout Standard
1000x1414
\end_inset
\begin_inset Text
\layout Standard
917x1297
\end_inset
\begin_inset Text
\layout Standard
1
\end_inset
\begin_inset Text
\layout Standard
594x841
\end_inset
\begin_inset Text
\layout Standard
707x1000
\end_inset
\begin_inset Text
\layout Standard
648x917
\end_inset
\begin_inset Text
\layout Standard
2
\end_inset
\begin_inset Text
\layout Standard
420x594
\end_inset
\begin_inset Text
\layout Standard
500x707
\end_inset
\begin_inset Text
\layout Standard
458x648
\end_inset
\begin_inset Text
\layout Standard
3
\end_inset
\begin_inset Text
\layout Standard
297x420
\end_inset
\begin_inset Text
\layout Standard
353x500
\end_inset
\begin_inset Text
\layout Standard
324x458
\end_inset
\begin_inset Text
\layout Standard
4
\end_inset
\begin_inset Text
\layout Standard
210x297
\end_inset
\begin_inset Text
\layout Standard
250x353
\end_inset
\begin_inset Text
\layout Standard
229x324
\end_inset
\begin_inset Text
\layout Standard
5
\end_inset
\begin_inset Text
\layout Standard
148x210
\end_inset
\begin_inset Text
\layout Standard
176x250
\end_inset
\begin_inset Text
\layout Standard
162x229
\end_inset
\begin_inset Text
\layout Standard
6
\end_inset
\begin_inset Text
\layout Standard
105x148
\end_inset
\begin_inset Text
\layout Standard
125x176
\end_inset
\begin_inset Text
\layout Standard
114x162
\end_inset
\begin_inset Text
\layout Standard
7
\end_inset
\begin_inset Text
\layout Standard
74x105
\end_inset
\begin_inset Text
\layout Standard
88x125
\end_inset
\begin_inset Text
\layout Standard
81x114
\end_inset
\begin_inset Text
\layout Standard
8
\end_inset
\begin_inset Text
\layout Standard
52x74
\end_inset
\begin_inset Text
\layout Standard
62x88
\end_inset
\begin_inset Text
\layout Standard
57x81
\end_inset
\begin_inset Text
\layout Standard
9
\end_inset
\begin_inset Text
\layout Standard
37x52
\end_inset
\begin_inset Text
\layout Standard
44x62
\end_inset
\begin_inset Text
\layout Standard
40x57
\end_inset
\begin_inset Text
\layout Standard
10
\end_inset
\begin_inset Text
\layout Standard
26x37
\end_inset
\begin_inset Text
\layout Standard
31x44
\end_inset
\begin_inset Text
\layout Standard
28x40
\end_inset
\end_inset
\end_inset
\layout Standard
From
\begin_inset LatexCommand \ref{tab-ISO-DIN-paper-sizes}
\end_inset
we see that if, as the author of coolthumb says, the values of 82/106 are
"pretty much dead-on" for US Letter paper,
\begin_inset LatexCommand \index{paper}
\end_inset
then the values 74/105 must be just as "dead on" for DIN paper
\begin_inset LatexCommand \index{paper}
\end_inset
(we try to match one paper
\begin_inset LatexCommand \index{paper}
\end_inset
side as good as possible - and in this case we see that 106-105 is pretty
much as good as can be).
More precisely, it's dead-on for for DIN A7 paper,
\begin_inset LatexCommand \index{paper}
\end_inset
but DIN papers have the same aspect ratio throughout the whole paper
\begin_inset LatexCommand \index{paper}
\end_inset
range (see
\begin_inset LatexCommand \ref{fig-ISO-DIN-paper-sizes}
\end_inset
), so the ratio 74/105 for DIN A7 is the same as the ratio 210/297 for DIN
A4 (which is mostly used outside the USA) and also the same as every other
DIN paper.
\begin_inset LatexCommand \index{paper}
\end_inset
\layout Standard
\begin_inset Float figure
placement htbp
wide false
collapsed false
\layout Caption
\begin_inset Graphics FormatVersion 1
filename paper-sizes.eps
display default
size_type 0
rotateOrigin center
lyxsize_type 0
\end_inset
\begin_inset LatexCommand \label{fig-ISO-DIN-paper-sizes}
\end_inset
ISO-DIN paper sizes.
\end_inset
\end_deeper
\layout Itemize
DPI (dots-per-inch) value for the thumbnails:
\begin_inset LatexCommand \index{thumbnails}
\end_inset
\begin_deeper
\layout Code
SNAPSHOT_DPI=133
\end_deeper
\layout Itemize
This is the DPI value of my monitor, as taken from the output of the graphic
card driver in /var/log/XFree86.0.log, where it says:
\begin_deeper
\layout Code
DPI set to (133, 133)
\layout Standard
Of course, YMMV (=Your Monitor May Vary ;-)).
\end_deeper
\layout Itemize
I use thumbpdf
\begin_inset LatexCommand \index{thumbpdf}
\end_inset
version 3.2, so I set
\begin_deeper
\layout Code
THUMBPDF_V2=0
\end_deeper
\layout Chapter
Writing in LyX, thinking in SGML
\begin_inset LatexCommand \label{writing-in-LyX}
\end_inset
\layout Standard
You have now installed the required software (see
\begin_inset LatexCommand \ref{required-software}
\end_inset
) and taken the required preliminary steps (see
\begin_inset LatexCommand \ref{required-preliminary-steps}
\end_inset
) to ensure that everything is in place and configured correctly.
In this chapter I will describe how write in LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
in order to achieve the desired results.
This may at first look trivial,
\begin_inset LatexCommand \index{trivial}
\end_inset
but is not:
\layout Standard
LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
is a frontend
\begin_inset LatexCommand \index{frontend}
\end_inset
for LaTeX.
\begin_inset LatexCommand \index{LaTeX}
\end_inset
It was designed with TeX/LaTeX in mind, not SGML.
\begin_inset LatexCommand \index{SGML}
\end_inset
The TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
language and the LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
macros describe a document
\begin_inset LatexCommand \index{document}
\end_inset
not only from the structural point of view (using markup
\begin_inset LatexCommand \index{markup}
\end_inset
that expresses facts like
\begin_inset Quotes eld
\end_inset
this is a paragraph
\begin_inset LatexCommand \index{paragraph}
\end_inset
\begin_inset Quotes erd
\end_inset
,
\begin_inset Quotes eld
\end_inset
this is an itemized
\begin_inset LatexCommand \index{itemized}
\end_inset
list
\begin_inset Quotes erd
\end_inset
), but also from the descriptive one (
\begin_inset Quotes eld
\end_inset
use 12pt
\begin_inset LatexCommand \index{12pt}
\end_inset
here
\begin_inset Quotes erd
\end_inset
,
\begin_inset Quotes eld
\end_inset
indent 5cm there
\begin_inset Quotes erd
\end_inset
).
SGML,
\begin_inset LatexCommand \index{SGML}
\end_inset
on the other side, separates structure from style.
It is clear that when you export a TeX/LaTeX document
\begin_inset LatexCommand \index{document}
\end_inset
not each and every TeX/LaTeX construct that is possible in LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
will find its equivalent in SGML.
\begin_inset LatexCommand \index{SGML}
\end_inset
Clearly, you will have to use only those constructs that are common to
both, or at least can be mapped to each other with some reasonable processing
\begin_inset LatexCommand \index{processing}
\end_inset
of LyX' SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
(done by
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
using
\begin_inset LatexCommand \url[runsed]{runsed}
\end_inset
and
\begin_inset LatexCommand \url[sedscr]{sedscr}
\end_inset
).
Remember this each time you try something in LyX,
\begin_inset LatexCommand \index{LyX}
\end_inset
only to find out that it does not work in SGML.
\begin_inset LatexCommand \index{SGML}
\end_inset
\layout SGML
\layout SGML
Use the .lyx version of this document as a template
\layout SGML
\layout SGML
Even if this chapter goes into a lot of details regarding writing in LyX
in a manner that is compatible with SGML processing, a real example is
still worth a thousand words.
You should thus study real LyX documents that use the constructs discussed
here and compare with the results in the other versions (HTML, PDF, PS,
RTF, TXT and of course SGML).
The best starting point is to use the .lyx version of this document (to
be found in the links of
\begin_inset LatexCommand \ref{formats}
\end_inset
).
\layout SGML
\layout SGML
\layout SGML
Load the
\begin_inset LatexCommand \url[LyX version]{http://www.karakas-online.de/mySGML/mySGML.lyx}
\end_inset
of this document in LyX and study the way various elements are used.
Use it as your template, your starting point for your own document! If
you look attentively, you will see that I am trying out quite a few non-trivial
tricks here, which you can copy for your own use.
]]>
]]> ]]>
]]> Inline graphic
\layout SGML
\layout SGML
\layout Section
LyX environments
\begin_inset LatexCommand \label{LyX-environments}
\end_inset
\layout Standard
Different parts of a document
\begin_inset LatexCommand \index{document}
\end_inset
have different purposes; we call these parts
\emph on
environments
\emph default
.
Most of a document
\begin_inset LatexCommand \index{document}
\end_inset
is made up of regular text.
Section (chapter, subsection,
\begin_inset LatexCommand \index{subsection}
\end_inset
etc.) titles let the reader know that a new topic or subtopic
\begin_inset LatexCommand \index{subtopic}
\end_inset
will be discussed.
Certain types of documents have special environments.
\begin_inset LatexCommand \index{environments}
\end_inset
A journal article will have an abstract,
\begin_inset LatexCommand \index{abstract}
\end_inset
and a title.
A letter will have neither of these, but will probably have an environment
\begin_inset LatexCommand \index{environment}
\end_inset
that gives the writer's address.
\layout Standard
Environments are a major part of the
\begin_inset Quotes eld
\end_inset
What You See Is What You Mean
\begin_inset Quotes erd
\end_inset
philosophy
\begin_inset LatexCommand \index{philosophy}
\end_inset
of LyX.
\begin_inset LatexCommand \index{LyX}
\end_inset
A given environment
\begin_inset LatexCommand \index{environment}
\end_inset
may require a certain font style, font size, indenting,
\begin_inset LatexCommand \index{indenting}
\end_inset
line spacing, and more.
This problem is aggravated, because the exact formatting
\begin_inset LatexCommand \index{formatting}
\end_inset
for a given environment may change: one journal may use boldface, 18 point,
centered type for section titles while another uses italicized, 15 point,
left justified type; different languages may have different standards
\begin_inset LatexCommand \index{standards}
\end_inset
for indenting;
\begin_inset LatexCommand \index{indenting}
\end_inset
and bibliography
\begin_inset LatexCommand \index{bibliography}
\end_inset
formats can vary widely.
LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
lets you avoid
\begin_inset LatexCommand \index{avoid}
\end_inset
learning all the different formatting
\begin_inset LatexCommand \index{formatting}
\end_inset
styles.
\layout Standard
The
\family sans
Environment
\family default
box is located on the left end of the toolbar (just under the
\family sans
\bar under
F
\bar default
ile
\family default
menu).
It indicates which environment
\begin_inset LatexCommand \index{environment}
\end_inset
you're currently writing in.
While you were writing your first document,
\begin_inset LatexCommand \index{document}
\end_inset
it said
\begin_inset Quotes eld
\end_inset
Standard,
\begin_inset Quotes erd
\end_inset
which is the default environment
\begin_inset LatexCommand \index{environment}
\end_inset
for text.
Now you will put a number of environments
\begin_inset LatexCommand \index{environments}
\end_inset
in your new document
\begin_inset LatexCommand \index{document}
\end_inset
so that you can see how they work.
You'll do so with the
\family sans
Environment
\family default
menu, which you open by clicking on the
\begin_inset Quotes eld
\end_inset
down arrow
\begin_inset Quotes erd
\end_inset
icon
\begin_inset LatexCommand \index{icon}
\end_inset
just to the right of the
\family sans
Environment
\family default
box.
\layout SGML
\layout SGML
Don't use the "Paragraph" environment!
\layout SGML
\layout SGML
Use "Standard" instead! Using "Paragraph" interferes with the changes that
\begin_inset LatexCommand \url[runsed]{runsed}
\end_inset
and
\begin_inset LatexCommand \url[sedscr]{sedscr}
\end_inset
try to effect in the SGML code as exported by LyX.
Writing paragraphs in LyX is treated in
\begin_inset LatexCommand \ref{LyX-paragraphs}
\end_inset
- although there is actually nothing more to say on this subject for the
moment.
Just choose "Standard" and write.
]]> ]]>
]]> ]]> Inline graphic
\layout SGML
\layout SGML
\layout Standard
An important thing to keep in mind is that whatever environment
\begin_inset LatexCommand \index{environment}
\end_inset
you set in LyX, it will NOT, per se, affect the formatting
\begin_inset LatexCommand \index{formatting}
\end_inset
of your document! LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
environments
\begin_inset LatexCommand \index{environments}
\end_inset
tell something about the
\emph on
structure
\emph default
of the document,
\begin_inset LatexCommand \index{document}
\end_inset
never about its formatting
\begin_inset LatexCommand \index{formatting}
\end_inset
(at least not in the context we will be using them here, i.e.
as equivalent to SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
tags).
Thus, an environment
\begin_inset LatexCommand \index{environment}
\end_inset
of
\begin_inset Quotes eld
\end_inset
Standard
\begin_inset Quotes erd
\end_inset
will induce the tag when exported to SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
from LyX.
\begin_inset LatexCommand \index{LyX}
\end_inset
The following quote from the sgml-tools
\begin_inset LatexCommand \index{sgml-tools}
\end_inset
mailing list deals with a common misconception
\begin_inset LatexCommand \index{misconception}
\end_inset
of (see
\begin_inset LatexCommand \url[Use of <Para> within <ListItem> mangles list items]{http://www.via.ecp.fr/via/ml/sgml-tools/199901/msg00153.html}
\end_inset
):
\layout Quotation
> I think the definition of means to start on a new line and break
on a new line.
\layout Quotation
At the risk of being pedantic,
\begin_inset LatexCommand \index{pedantic}
\end_inset
I think you're making a mistake of interpreting DocBook
\begin_inset LatexCommand \index{DocBook}
\end_inset
markup
\begin_inset LatexCommand \index{markup}
\end_inset
tags as having any bearing on format, which they do not.
This is unlike many HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
tags, so if that's the particular SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
DTD that you have more experience with, it may be coloring your intepretation.
\layout Quotation
DocBook
\begin_inset LatexCommand \index{DocBook}
\end_inset
tags (and to be honest,
\begin_inset LatexCommand \index{honest}
\end_inset
most SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
DTDs) are used to identify the type and purpose of information, but not
how that information might be portrayed in a formatted fashion.
That's part of the whole power of it - by separating formatting/display
from content, you are free to both ignore such issues when documenting,
and yet be totally flexible during formatting
\begin_inset LatexCommand \index{formatting}
\end_inset
on how you want to present marked up text.
\layout Quotation
In DocBook,
\begin_inset LatexCommand \index{DocBook}
\end_inset
the element
\begin_inset LatexCommand \index{element}
\end_inset
is just defined as a "paragraph"
\begin_inset LatexCommand \index{paragraph}
\end_inset
, a container
\begin_inset LatexCommand \index{container}
\end_inset
sort of element
\begin_inset LatexCommand \index{element}
\end_inset
for other inline,
\begin_inset LatexCommand \index{inline}
\end_inset
and some block, elements.
It says nothing about starting nor breaking on a newline,
\begin_inset LatexCommand \index{newline}
\end_inset
although of course such could be selected by a style sheet as an implementation.
\begin_inset LatexCommand \index{implementation}
\end_inset
In that respect the more tags you have in a document
\begin_inset LatexCommand \index{document}
\end_inset
(and the more granularity
\begin_inset LatexCommand \index{granularity}
\end_inset
of the information so tagged) the better - it gives the formatter
\begin_inset LatexCommand \index{formatter}
\end_inset
and style sheet the most flexibility in handling how the formatted output
should appear.
\layout Standard
We talk about stylesheets in
\begin_inset LatexCommand \ref{DSSSL-stylesheets}
\end_inset
,
\begin_inset LatexCommand \ref{CSS}
\end_inset
,
\begin_inset LatexCommand \ref{explain-DSSSL-stylesheets}
\end_inset
,
\begin_inset LatexCommand \ref{explain-CSS}
\end_inset
and
\begin_inset LatexCommand \ref{explain-math-processing-in-HTML-stylesheets}
\end_inset
.
\layout Section
Authors, Credits, Roles
\begin_inset LatexCommand \label{LyX-Authors-Credits-Roles}
\end_inset
\layout Standard
If you have a more complicated situation than just an author for your document,
\begin_inset LatexCommand \index{document}
\end_inset
like affiliations,
\begin_inset LatexCommand \index{affiliations}
\end_inset
translators, contributors etc., here's the right way to enter such information
in LyX,
\begin_inset LatexCommand \index{LyX}
\end_inset
so that it can be exported to SGML:
\begin_inset LatexCommand \index{SGML}
\end_inset
\layout Standard
Create an environment
\begin_inset LatexCommand \index{environment}
\end_inset
(
\begin_inset LatexCommand \ref{LyX-environments}
\end_inset
) of type
\begin_inset Quotes eld
\end_inset
SGML
\begin_inset Quotes erd
\end_inset
just after the title and before the abstract.
\begin_inset LatexCommand \index{abstract}
\end_inset
There, enter the information as in the following example:
\layout SGML
\layout SGML
\layout SGML
\layout SGML
ChrisKarakas
\layout SGML
\layout SGML
Webmaster
\layout SGML
www.karakas-online.de
\layout SGML
\layout SGML
\layout SGML
\layout SGML
Conversion from LyX to DocBook SGML, Index generation
\layout SGML
ChrisKarakas
\layout SGML
www.karakas-online.de
\layout SGML
\layout SGML
\layout SGML
Translation from italian
\layout SGML
ChrisKarakas
\layout SGML
www.karakas-online.de
\layout SGML
\layout SGML
\layout SGML
]]>
\layout SGML
\layout Section
Keywords
\begin_inset LatexCommand \label{LyX-keywords}
\end_inset
\layout Standard
The metainformation
\begin_inset LatexCommand \index{metainformation}
\end_inset
on keywords
\begin_inset LatexCommand \index{keywords}
\end_inset
is not as relevant today (in the context of search engine optimization)
as it was a few years ago.
Nevertheless it may be a good practice to incorporate some keywords
\begin_inset LatexCommand \index{keywords}
\end_inset
in the header as there are still some search engines around that use them
(
\begin_inset LatexCommand \url[Google]{http://www.google.com}
\end_inset
does not).
Here's how you enter keywords
\begin_inset LatexCommand \index{keywords}
\end_inset
in LyX:
\begin_inset LatexCommand \index{LyX}
\end_inset
\layout Standard
After the title and before the abstract,
\begin_inset LatexCommand \index{abstract}
\end_inset
create an environment
\begin_inset LatexCommand \index{environment}
\end_inset
(
\begin_inset LatexCommand \ref{LyX-environments}
\end_inset
) of type
\begin_inset Quotes eld
\end_inset
SGML
\begin_inset Quotes erd
\end_inset
.
There, enter the keywords
\begin_inset LatexCommand \index{keywords}
\end_inset
as in the following example:
\layout Code
\layout Code
LyX
\layout Code
SGML
\layout Code
DocBook
\layout Code
\layout Section
Revision history
\begin_inset LatexCommand \label{LyX-revision-history}
\end_inset
\layout Standard
You enter a revision history as follows:
\layout Standard
Create an environment
\begin_inset LatexCommand \index{environment}
\end_inset
(
\begin_inset LatexCommand \ref{LyX-environments}
\end_inset
) of type
\begin_inset Quotes eld
\end_inset
SGML
\begin_inset Quotes erd
\end_inset
that is located after the abstract
\begin_inset LatexCommand \index{abstract}
\end_inset
and before the first chapter/section.
In this environment,
\begin_inset LatexCommand \index{environment}
\end_inset
enter the revision history as in the following example:
\layout Code
\layout Code
\layout Code
1.2
\layout Code
\layout Code
29.05.2003
\layout Code
\layout Code
CK
\layout Code
\layout Code
Some remarks about this revision.
\layout Code
\layout Code
\layout Code
\layout Code
1.1
\layout Code
\layout Code
13.02.2003
\layout Code
\layout Code
CK
\layout Code
\layout Code
Some remarks about this revision.
\layout Code
\layout Code
\layout Standard
Revision numbers
\begin_inset LatexCommand \index{numbers}
\end_inset
should be entered in reverse order (i.e., the latest revision should appear
first on the list).
\layout Section
Paragraphs
\begin_inset LatexCommand \label{LyX-paragraphs}
\end_inset
\layout Standard
Do NOT use the
\begin_inset Quotes eld
\end_inset
Paragraph
\begin_inset Quotes erd
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
(
\begin_inset LatexCommand \ref{LyX-environments}
\end_inset
) when writing a paragraph.
\begin_inset LatexCommand \index{paragraph}
\end_inset
Use
\begin_inset Quotes eld
\end_inset
Standard
\begin_inset Quotes erd
\end_inset
instead.
Using
\begin_inset Quotes eld
\end_inset
Paragraph
\begin_inset Quotes erd
\end_inset
interferes with the changes that
\begin_inset LatexCommand \url[runsed]{runsed}
\end_inset
and
\begin_inset LatexCommand \url[sedscr]{sedscr}
\end_inset
try to effect in the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
code as exported by LyX.
\begin_inset LatexCommand \index{LyX}
\end_inset
\layout Section
Cross references
\begin_inset LatexCommand \label{LyX-cross-references}
\end_inset
\layout Standard
Cross-references work in exactly the same way as usually in LyX:
\begin_inset LatexCommand \index{LyX}
\end_inset
you first insert a label
\begin_inset LatexCommand \index{label}
\end_inset
(choosing Insert-->Label from the menu), then insert a cross-reference
\begin_inset LatexCommand \index{cross-reference}
\end_inset
at a point of your choice (choosing Insert-->Cross-reference from the menu).
BUT: You can't cross-reference
\begin_inset LatexCommand \index{cross-reference}
\end_inset
anything! Although it is certainly possible in LyX,
\begin_inset LatexCommand \index{LyX}
\end_inset
it will not work when exported to SGML:
\begin_inset LatexCommand \index{SGML}
\end_inset
you will get the error
\layout Code
xref to ANCHOR unsupported
\layout Standard
See
\begin_inset LatexCommand \ref{errors-and-warnings}
\end_inset
for a discussion of this error.
For the moment, just remember that the only cross-references that work
for our purposes are cross-references to
\layout Itemize
chapters, sections, subsections,
\begin_inset LatexCommand \index{subsections}
\end_inset
subsubsections
\layout Itemize
figures
\layout Itemize
tables
\layout Standard
but that's quite enough for cross-referencing.
\begin_inset LatexCommand \index{cross-referencing}
\end_inset
\layout SGML
\layout SGML
Always set labels!
\layout SGML
\layout SGML
Labels of chapters and sections will become the HTML filenames of the
files that contain them.
Choose them wisely and make it a habit to always create a label for your
new chapter and section as soon as you write down their titles! See
\begin_inset LatexCommand \ref{LyX-filenames}
\end_inset
for more tips on this important issue.
\layout SGML
\layout SGML
\layout Subsection
Mass insertion of cross-references in LyX
\begin_inset LatexCommand \label{LyX-cross-references-mass-insertion}
\end_inset
\layout Standard
If you have to add hundreds
\begin_inset LatexCommand \index{hundreds}
\end_inset
of cross-references in just one section (e.g.
more than 500, as in
\begin_inset LatexCommand \url[Credits for version 2.0 of the PHP-Nuke HOWTO]{http://www.karakas-online.de/EN-Book/credits-version-2.0.html}
\end_inset
), you will soon notice that, although a single cross-reference
\begin_inset LatexCommand \index{cross-reference}
\end_inset
is inserted very easily in LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
(just choose Insert->Cross-reference from the menu, then choose the label
\begin_inset LatexCommand \index{label}
\end_inset
of the reference you want), it becomes a real pain if you have to enter
hundreds
\begin_inset LatexCommand \index{hundreds}
\end_inset
of them.
\layout Standard
My solution to this was to write a script that reads a LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
file and outputs another LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
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
\begin_inset LatexCommand \url[Credits for version 2.0 of the PHP-Nuke HOWTO]{http://www.karakas-online.de/EN-Book/credits-version-2.0.html}
\end_inset
and then delete the unneeded ones, than try to insert all cross-references
by hand using the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
menu.
\layout Standard
The following script, call it
\begin_inset LatexCommand \url[lyxrefs]{lyxrefs}
\end_inset
, will print a LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
file in standard output, containing cross-references to each and every label
\begin_inset LatexCommand \index{label}
\end_inset
of the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
file whose name was passed on the command line as argument:
\layout Code
#!/bin/bash
\layout Code
#
\layout Code
\layout Code
AWK="/usr/bin/awk"
\layout Code
\layout Code
function preample() {
\layout Code
cat <<-EOF
\layout Code
#LyX 1.2 created this file.
For more info see http://www.lyx.org/
\layout Code
\backslash
lyxformat 220
\layout Code
\backslash
textclass article
\layout Code
\backslash
language english
\layout Code
\backslash
inputencoding auto
\layout Code
\backslash
fontscheme default
\layout Code
\backslash
graphics default
\layout Code
\backslash
paperfontsize default
\layout Code
\backslash
papersize Default
\layout Code
\backslash
paperpackage a4
\layout Code
\backslash
use_geometry 0
\layout Code
\backslash
use_amsmath 0
\layout Code
\backslash
use_natbib 0
\layout Code
\backslash
use_numerical_citations 0
\layout Code
\backslash
paperorientation portrait
\layout Code
\backslash
secnumdepth 3
\layout Code
\backslash
tocdepth 3
\layout Code
\backslash
paragraph_separation indent
\layout Code
\backslash
defskip medskip
\layout Code
\backslash
quotes_language english
\layout Code
\backslash
quotes_times 2
\layout Code
\backslash
papercolumns 1
\layout Code
\backslash
papersides 1
\layout Code
\backslash
paperpagestyle default
\layout Code
EOF
\layout Code
}
\layout Code
\layout Code
function label() {
\layout Code
n=$1
\layout Code
echo ""
\layout Code
echo "
\backslash
layout Standard"
\layout Code
echo ""
\layout Code
echo ""
\layout Code
echo "
\backslash
begin_inset LatexCommand
\backslash
label{cit:$n}"
\layout Code
echo ""
\layout Code
echo "
\backslash
end_inset"
\layout Code
}
\layout Code
\layout Code
preample
\layout Code
\layout Code
# Output LyX commands for Chapter "All references"
\layout Code
cat <<-EOF
\layout Code
\backslash
layout Section
\layout Code
\layout Code
All references
\layout Code
\layout Code
EOF
\layout Code
\layout Code
# Output all references.
\layout Code
$AWK 'BEGIN {FS=" "} /
\backslash
\backslash
begin_inset LatexCommand
\backslash
\backslash
label{/ {gsub("label","ref");
\layout Code
printf("
\backslash
n%s
\backslash
n
\backslash
n%s%s
\backslash
n
\backslash
n%s
\backslash
n","
\backslash
\backslash
layout Standard",
\layout Code
"
\backslash
\backslash
begin_inset LatexCommand",$3,"
\backslash
\backslash
end_inset")}' $1 > all-references.tmp
\layout Code
\layout Code
cat all-references.tmp
\layout Code
rm all-references.tmp
\layout Code
\layout Code
# Output LyX commands for Chapter "All references"
\layout Code
cat <<-EOF
\layout Code
\backslash
layout Section
\layout Code
\layout Code
All figure references
\layout Code
\layout Code
EOF
\layout Code
\layout Code
# Output only the figures.
\layout Code
$AWK 'BEGIN {FS=" "} /
\backslash
\backslash
begin_inset LatexCommand
\backslash
\backslash
label{fig-/ {gsub("label","ref");
\layout Code
printf("
\backslash
n%s
\backslash
n
\backslash
n%s%s
\backslash
n
\backslash
n%s
\backslash
n","
\backslash
\backslash
layout Standard",
\layout Code
"
\backslash
\backslash
begin_inset LatexCommand",$3,"
\backslash
\backslash
end_inset")}' $1 > fig-references.tmp
\layout Code
\layout Code
cat fig-references.tmp
\layout Code
rm fig-references.tmp
\layout Code
\layout Code
# Output LyX commands for Chapter "All references"
\layout Code
cat <<-EOF
\layout Code
\backslash
layout Section
\layout Code
\layout Code
All table references
\layout Code
\layout Code
EOF
\layout Code
\layout Code
# Output only the tables.
\layout Code
$AWK 'BEGIN {FS=" "} /
\backslash
\backslash
begin_inset LatexCommand
\backslash
\backslash
label{tab-/ {gsub("label","ref");
\layout Code
printf("
\backslash
n%s
\backslash
n
\backslash
n%s%s
\backslash
n
\backslash
n%s
\backslash
n","
\backslash
\backslash
layout Standard",
\layout Code
"
\backslash
\backslash
begin_inset LatexCommand",$3,"
\backslash
\backslash
end_inset")}' $1 > tab-references.tmp
\layout Code
\layout Code
cat tab-references.tmp
\layout Code
rm tab-references.tmp
\layout Code
\layout Code
echo "
\backslash
the_end"
\layout Standard
The script will even create three sections, with cross-references to all
labels, all figures
\begin_inset LatexCommand \index{figures}
\end_inset
and all tables respectively.
If you named it lyxrefs,
\begin_inset LatexCommand \index{lyxrefs}
\end_inset
you would call it as follows:
\layout Code
lyxrefs some-LyX-file.lyx > refs.lyx
\layout Standard
Then refs.lyx
\begin_inset LatexCommand \index{refs.lyx}
\end_inset
will contain cross-references to all labels of some-LyX-file.lyx.
\begin_inset LatexCommand \index{some-LyX-file.lyx}
\end_inset
You can open refs.lyx
\begin_inset LatexCommand \index{refs.lyx}
\end_inset
with LyX,
\begin_inset LatexCommand \index{LyX}
\end_inset
copy all or part of the cross-references there and paste them in some-LyX-file.l
yx.
The cross-references in
\begin_inset LatexCommand \url[Credits for version 2.0 of the PHP-Nuke HOWTO]{http://www.karakas-online.de/EN-Book/credits-version-2.0.html}
\end_inset
were entered this way.
\layout Section
Images
\begin_inset LatexCommand \label{LyX-images}
\end_inset
\layout Standard
You insert an image quite simply: from the menu, choose Insert-->Graphics.
Enter the basename
\begin_inset LatexCommand \index{basename}
\end_inset
of your image (this is the name without the ending), followed by the ending
\begin_inset Quotes eld
\end_inset
.eps
\begin_inset Quotes erd
\end_inset
.
Example: If your image is called myimage.png, enter
\begin_inset Quotes eld
\end_inset
myimage.eps
\begin_inset Quotes erd
\end_inset
in the file field.
Don't worry that LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
cannot find your image.
Don't worry that all your images are located in the images directory beneath
your working directory, but you didn't enter any paths.
\begin_inset LatexCommand \index{paths}
\end_inset
The scripts will take care of this (see
\begin_inset LatexCommand \ref{explain-document-processing}
\end_inset
for the gory details).
You just enter
\begin_inset Quotes eld
\end_inset
myimage.eps
\begin_inset Quotes erd
\end_inset
, that's all.
\layout Standard
If you want to see figure captions
\begin_inset LatexCommand \index{captions}
\end_inset
and titles (and the
\begin_inset Quotes eld
\end_inset
alternative text
\begin_inset Quotes erd
\end_inset
in HTML), or if you want to be able to reference a figure, or see your
figure in the
\begin_inset Quotes eld
\end_inset
List of Figures
\begin_inset Quotes erd
\end_inset
that is created automatically,
\begin_inset LatexCommand \index{automatically}
\end_inset
then you have to use floats.
\begin_inset LatexCommand \index{floats}
\end_inset
Follow the instructions exactly as given:
\layout Itemize
Be sure that your cursor
\begin_inset LatexCommand \index{cursor}
\end_inset
is in the
\begin_inset Quotes eld
\end_inset
Standard
\begin_inset Quotes erd
\end_inset
environment.
\begin_inset LatexCommand \index{environment}
\end_inset
\layout Itemize
From the menu, choose Insert-->Floats-->Figure.
\layout Itemize
In the float, insert an image as explained previously
\layout Itemize
While the cursor
\begin_inset LatexCommand \index{cursor}
\end_inset
is still besides the (empty) figure box and inside the float, change the
environment
\begin_inset LatexCommand \index{environment}
\end_inset
to
\begin_inset Quotes eld
\end_inset
Caption
\begin_inset Quotes erd
\end_inset
(
\begin_inset LatexCommand \ref{LyX-environments}
\end_inset
).
\layout Itemize
Now you see the text
\begin_inset Quotes eld
\end_inset
Figure#:
\begin_inset Quotes erd
\end_inset
to the left of the image box, followed by the image box .
Insert a label
\begin_inset LatexCommand \index{label}
\end_inset
(Insert-->Label) directly after (to the right of) the image box.
Through this label
\begin_inset LatexCommand \index{label}
\end_inset
you will be able to cross-reference
\begin_inset LatexCommand \index{cross-reference}
\end_inset
this figure in your document.
\begin_inset LatexCommand \index{document}
\end_inset
\layout Itemize
Type the figure caption
\begin_inset LatexCommand \index{caption}
\end_inset
text directly after the label.
\begin_inset LatexCommand \index{label}
\end_inset
It will become the figure title
\emph on
and
\emph default
caption
\begin_inset LatexCommand \index{caption}
\end_inset
text (there is currently no way to get different texts for figure title
and caption
\begin_inset LatexCommand \index{caption}
\end_inset
text from LyX,
\begin_inset LatexCommand \index{LyX}
\end_inset
although SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
would support this.
If you find an alternative, please send it to me).
\layout Subsection
Inline graphics
\begin_inset LatexCommand \label{LyX-inline-graphics}
\end_inset
\layout Standard
I will disappoint you: there is no way to include inline
\begin_inset LatexCommand \index{inline}
\end_inset
graphics with the method described in this document
\begin_inset LatexCommand \index{document}
\end_inset
- see
\begin_inset LatexCommand \ref{explain-inline-graphics}
\end_inset
for the reason.
\layout SGML
Well, almost...
]]> ]]> ]]> ]]> Inline graphic
\layout Standard
You have always the possibility to write SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
in LyX:
\begin_inset LatexCommand \index{LyX}
\end_inset
just create an environment
\begin_inset LatexCommand \index{environment}
\end_inset
(
\begin_inset LatexCommand \ref{LyX-environments}
\end_inset
) of type SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
and enter your text (in elements), followed by
\layout Code
\begin_inset Include \verbatiminput{inlinemediaobject}
\end_inset
\layout Standard
Substitute
\begin_inset Quotes eld
\end_inset
1
\begin_inset Quotes erd
\end_inset
with the basename
\begin_inset LatexCommand \index{basename}
\end_inset
of the inline
\begin_inset LatexCommand \index{inline}
\end_inset
graphic (i.e.
the name without path
\begin_inset LatexCommand \index{path}
\end_inset
information and without ending).
Of course all necessary formats (PNG, EPS,
\begin_inset LatexCommand \index{EPS}
\end_inset
PDF
\begin_inset LatexCommand \index{PDF}
\end_inset
and BMP) with the right density
\begin_inset LatexCommand \index{density}
\end_inset
settings must be available under the ./images directory, see
\begin_inset LatexCommand \ref{add-density}
\end_inset
.
\layout SGML
\layout SGML
Caution:
\layout SGML
\layout SGML
You must insert the above SGML code without introducing newline characters,
which in LyX will produce ]]> elements
when exported to SGML.
Thus, for the above sentence and inline icon, you would have to enter
\layout SGML
\layout SGML
\layout Section
Admonitions
\begin_inset LatexCommand \label{LyX-admonitions}
\end_inset
\layout Standard
There is no
\begin_inset Quotes eld
\end_inset
Admonition
\begin_inset Quotes erd
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
in LyX,
\begin_inset LatexCommand \index{LyX}
\end_inset
just as there are no
\begin_inset Quotes eld
\end_inset
Admonitions
\begin_inset Quotes erd
\end_inset
in TeX/LaTeX.
Admonitions
\begin_inset LatexCommand \index{Admonitions}
\end_inset
are a DocBook
\begin_inset LatexCommand \index{DocBook}
\end_inset
SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
element.
\begin_inset LatexCommand \index{element}
\end_inset
They are those text passages which alert the reader of some important fact
(see
\begin_inset LatexCommand \ref{conventions}
\end_inset
for examples).
They carry titles like
\begin_inset Quotes eld
\end_inset
Caution!
\begin_inset Quotes erd
\end_inset
,
\begin_inset Quotes eld
\end_inset
Important!
\begin_inset Quotes erd
\end_inset
,
\begin_inset Quotes eld
\end_inset
Note
\begin_inset Quotes erd
\end_inset
,
\begin_inset Quotes eld
\end_inset
Tip
\begin_inset Quotes erd
\end_inset
,
\begin_inset Quotes eld
\end_inset
Warning!
\begin_inset Quotes erd
\end_inset
.
There is no oher way to introduce admonitions
\begin_inset LatexCommand \index{admonitions}
\end_inset
in a LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
DocBook document,
\begin_inset LatexCommand \index{document}
\end_inset
than by creating an SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
and inserting the necessary SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
commands there.
Here is an example for
\begin_inset Quotes eld
\end_inset
Caution
\begin_inset Quotes erd
\end_inset
:
\layout Code
\layout Code
Caution
\layout Code
\layout Code
You will need to repeat the above steps for each and every image you produce!
\layout Code
If you omit it, or use your own .pdf and .eps versions, most probably they
\layout Code
will FAIL to be embedded in your PDF, resp.
PS document!
\layout Code
\layout Code
\layout Standard
which looks like this:
\layout SGML
\layout SGML
Caution
\layout SGML
\layout SGML
You will need to repeat the above steps for each and every image you produce!
If you omit it, or use your own .pdf and .eps versions, most probably they
will FAIL to be embedded in your PDF, resp.
PS document!
\layout SGML
\layout SGML
\layout Standard
Since the environment
\begin_inset LatexCommand \index{environment}
\end_inset
is SGML,
\begin_inset LatexCommand \index{SGML}
\end_inset
you can put any legal (from the DTD
\begin_inset LatexCommand \index{DTD}
\end_inset
point of view) SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
tag inside /, not only or .
Here is a more complicated example that uses an itemized
\begin_inset LatexCommand \index{itemized}
\end_inset
list (through the tag) , this time for the
\begin_inset Quotes eld
\end_inset
Tip
\begin_inset Quotes erd
\end_inset
admonition:
\begin_inset LatexCommand \index{admonition}
\end_inset
\layout Code
\layout Code
Tip
\layout Code
\layout Code
FYI, all changes presented here refer to variables that were
\layout Code
originally defined in one of the following files:
\layout Code
\layout Code
\layout Code
\layout Code
\layout Code
/usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/html/dbparam.dsl
\layout Code
\layout Code
\layout Code
\layout Code
\layout Code
/usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/print/dbparam.dsl
\layout Code
\layout Code
\layout Code
\layout Code
\layout Code
/usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/print/db31.dsl
\layout Code
\layout Code
\layout Code
\layout Code
As said above, you should not change these files directly, because
\layout Code
you will run into a lot of work when you upgrade them.
\layout Code
\layout Code
\layout Standard
It looks like this:
\layout SGML
\layout SGML
Tip
\layout SGML
\layout SGML
FYI, all changes presented here refer to variables that were originally
defined in one of the following files:
\layout SGML
\layout SGML
\layout SGML
\layout SGML
/usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/html/dbparam.dsl
\layout SGML
\layout SGML
\layout SGML
\layout SGML
\layout SGML
/usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/print/dbparam.dsl
\layout SGML
\layout SGML
\layout SGML
\layout SGML
\layout SGML
/usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/print/db31.dsl
\layout SGML
\layout SGML
\layout SGML
As said above, you should not change these files directly, because you will
run into a lot of work when you upgrade them.
\layout SGML
\layout SGML
\layout Standard
Another example (of a "Note" admonition) that makes use of a code example
(though the tag):
\layout Code
\layout Code
Please note:
\layout Code
\layout Code
A file containing
\emph on
graphical
\emph default
callouts (see
\begin_inset LatexCommand \ref{callouts}
\end_inset
and
\begin_inset LatexCommand \ref{LyX-callouts}
\end_inset
)
\layout Code
will NOT be validated! You will get an error saying
\layout Code
\layout Code
document type does not allow element "IMG" here
\layout Code
\layout Code
\layout Code
\layout Standard
It will look like this:
\layout SGML
\layout SGML
Please note:
\layout SGML
\layout SGML
A file containing
\emph on
graphical
\emph default
callouts (see
\begin_inset LatexCommand \ref{callouts}
\end_inset
and
\begin_inset LatexCommand \ref{LyX-callouts}
\end_inset
) will NOT be validated! You will get an error saying
\layout SGML
\layout SGML
document type does not allow element "IMG" here
\layout SGML
\layout SGML
\layout SGML
\layout Section
Callouts
\begin_inset LatexCommand \label{LyX-callouts}
\end_inset
\layout Standard
Callouts are those reverse-video
\begin_inset LatexCommand \index{reverse-video}
\end_inset
circled numbers
\begin_inset LatexCommand \index{numbers}
\end_inset
or "(1)", "(2)", etc.
that you see appended to selected lines in some code examples, like the
following:
\layout SGML
\layout SGML
baseurl={http://www.karakas-online.de/mySGML/},
\layout SGML
pdftitle={Document processing with LyX and SGML},
\layout SGML
pdfsubject={Linux,document formatting},
\layout SGML
pdfauthor={Copyright
\backslash
textcopyright 2004, Chris Karakas},
\layout SGML
pdfkeywords={Linux SGML LyX DSSSL DocBook}
\layout SGML
\layout SGML
\layout SGML
\layout SGML
\layout SGML
The baseurl will be added in front of any relative WWW link that you
have in your PDF document.
\layout SGML
\layout SGML
\layout SGML
\layout SGML
\layout SGML
The pdftitle will appear as the title of your PDF document in Acrobat®
Reader under File-->Document Info-->General.
\layout SGML
\layout SGML
\layout SGML
\layout SGML
\layout SGML
The pdfsubject will appear as the subject of your PDF document
in Acrobat® Reader under File-->Document Info-->General.
\layout SGML
\layout SGML
\layout SGML
\layout SGML
\layout SGML
The pdfauthor will appear as the author of your PDF document in
Acrobat® Reader under File-->Document Info-->General.
You may add copyright information as shown here.
\layout SGML
\layout SGML
\layout SGML
\layout SGML
\layout SGML
The pdfkeywords will appear as a list of keywords for your PDF
document in Acrobat® Reader under File-->Document Info-->General.
Keywords are separated by blanks.
\layout SGML
\layout SGML
\layout SGML
\layout Standard
Just as is the case with admonitions
\begin_inset LatexCommand \index{admonitions}
\end_inset
(see
\begin_inset LatexCommand \ref{LyX-admonitions}
\end_inset
), there is no LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
(
\begin_inset LatexCommand \ref{LyX-environments}
\end_inset
) for callouts
\begin_inset LatexCommand \index{callouts}
\end_inset
(there is no such environment
\begin_inset LatexCommand \index{environment}
\end_inset
for TeX/LaTeX either, which is the reason why it is absent from LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
too).
The only way to get callouts
\begin_inset LatexCommand \index{callouts}
\end_inset
to work with LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
ist to create an SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
and put the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
code there.
For the example above, here is what you would have to write in the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
environment:
\begin_inset LatexCommand \index{environment}
\end_inset
\layout Code
\layout Code
baseurl={http://www.karakas-online.de/mySGML/},
\layout Code
pdftitle={Document processing with LyX and SGML},
\layout Code
pdfsubject={Linux,document formatting},
\layout Code
pdfauthor={Copyright
\backslash
textcopyright 2003, Chris Karakas},
\layout Code
pdfkeywords={Linux SGML LyX DSSSL DocBook}
\layout Code
\layout Code
\layout Code
\layout Code
\layout Code
The baseurl will be added in front of any relative WWW link
\layout Code
that you have in your PDF document.
\layout Code
\layout Code
\layout Code
\layout Code
\layout Code
The pdftitle will appear as the title of your PDF document
\layout Code
in Acrobat® Reader under File-->Document Info-->General.
\layout Code
\layout Code
\layout Code
\layout Code
\layout Code
The pdfsubject will appear as the subject of your PDF document
\layout Code
in Acrobat® Reader under File-->Document Info-->General.
\layout Code
\layout Code
\layout Code
\layout Code
\layout Code
The pdfauthor will appear as the author of your PDF document
\layout Code
in Acrobat® Reader under File-->Document Info-->General.
You may add copyright information as shown here.
\layout Code
\layout Code
\layout Code
\layout Code
\layout Code
The pdfkeywords will appear as a list of keywords for your PDF
document
\layout Code
in Acrobat® Reader under File-->Document Info-->General.
Keywords are separated by blanks.
\layout Code
\layout Code
\layout Code
\layout Section
Tables
\begin_inset LatexCommand \label{LyX-tables}
\end_inset
\layout Standard
For table captions
\begin_inset LatexCommand \index{captions}
\end_inset
and titles to be output correctly, you have to insert tables in the following
way:
\layout Itemize
Be sure that your cursor
\begin_inset LatexCommand \index{cursor}
\end_inset
is in the
\begin_inset Quotes eld
\end_inset
Standard
\begin_inset Quotes erd
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
(see
\begin_inset LatexCommand \ref{LyX-environments}
\end_inset
).
\layout Itemize
Insert a table float (from the menu: Insert-->Floats-->Table)
\layout Itemize
You get a table float containing one line.
Change the environment
\begin_inset LatexCommand \index{environment}
\end_inset
on that line to
\begin_inset Quotes eld
\end_inset
Caption
\begin_inset Quotes erd
\end_inset
.
\layout Itemize
You see the text
\begin_inset Quotes eld
\end_inset
Table#:
\begin_inset Quotes erd
\end_inset
and the cursor
\begin_inset LatexCommand \index{cursor}
\end_inset
is positioned immediately to the right of it.
Insert a label
\begin_inset LatexCommand \index{label}
\end_inset
for the table (from the menu: Insert-->Label).
\layout Itemize
After the label,
\begin_inset LatexCommand \index{label}
\end_inset
on the same one line: type the table title and press .
This will produce a element
\begin_inset LatexCommand \index{element}
\end_inset
we will eliminate
\begin_inset LatexCommand \index{eliminate}
\end_inset
in
\begin_inset LatexCommand \url[sedscr]{sedscr}
\end_inset
(see
\begin_inset LatexCommand \ref{explain-runsed-sed-sedscr}
\end_inset
).
\layout Itemize
On the new line, insert your table as usual.
\layout Standard
A warning about an "end tag for element
\begin_inset LatexCommand \index{element}
\end_inset
"TABLE" which is not open", when processing
\begin_inset LatexCommand \index{processing}
\end_inset
the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
file with Jade,
\begin_inset LatexCommand \index{Jade}
\end_inset
is the less evil we can get (see
\begin_inset LatexCommand \ref{errors-and-warnings}
\end_inset
) and is harmless (probably caused by a LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
bug in version 1.2.0).
\layout Standard
A LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
related concern is that text within a cell will not wrap to fit the page,
so if a line of text in a table is too long, the table will extend beyond
the right margin of the page.
Similarly, LyX's table inset will not split itself at the bottom of a page,
and so might extend below the bottom margin.
You have these options to resolve this problem (taken from the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
User's Guide):
\layout Enumerate
Split it into two tables, to correctly handle pagebreaks
\begin_inset LatexCommand \index{pagebreaks}
\end_inset
and margins.
\layout Enumerate
Select the
\family sans
Longtable
\family default
button in the
\family sans
Table\SpecialChar ~
Layout
\family default
dialog.
This automatically
\begin_inset LatexCommand \index{automatically}
\end_inset
splits
\begin_inset LatexCommand \index{splits}
\end_inset
the table over more pages, if it is too high.
After doing this, the list of
\family sans
Longtable
\family default
buttons activate themselves and you may now define:
\begin_deeper
\layout Enumerate
\family sans
FirstHead
\family default
: The current row and all rows above that don't have any special options
defined, are defined to be the header-lines of the first page of the multipage-
table.
\layout Enumerate
\family sans
Head
\family default
: The current row and all rows above that don't have any special options
defined, are defined to be the header-lines of all pages of the multipage-table
\begin_inset LatexCommand \index{multipage-table}
\end_inset
except for the first page if
\family sans
FirstHead
\family default
is defined.
\layout Enumerate
\family sans
Foot
\family default
: The current row and all rows above that don't have any special options
defined, are defined to be the footer-lines of all pages of the multipage-table
\begin_inset LatexCommand \index{multipage-table}
\end_inset
except for the last page if
\family sans
LastFoot
\family default
is defined.
\layout Enumerate
\family sans
LastFoot
\family default
: The current row and all rows above that don't have any special options
defined, are defined to be the footer-lines of the last page of the multipage-t
able.
\layout Enumerate
\family sans
NewPage
\family default
: This forces a pagebreak after the row where this flag is defined.
\layout Standard
If you define more flags in the same table row, you should be aware of the
fact that only the first flag is used in the defined table rows.
The others will the be defined as
\emph on
empty
\emph default
.
In this context, first means first in this order:
\family sans
Foot, LastFoot,
\begin_inset LatexCommand \index{LastFoot}
\end_inset
\family default
\family sans
Head,
\family default
\family sans
FirstHead.
\family default
\emph on
\emph default
See the
\family typewriter
\begin_inset LatexCommand \index{typewriter}
\end_inset
TableExamples.lyx
\family default
example file to see how this works.
\emph on
\end_deeper
\layout Enumerate
Use the
\family sans
Width
\family default
entry in the
\family sans
Table\SpecialChar ~
Layout
\family default
dialog to restrict the width of the table till it fits horizontally.
\layout Enumerate
A table can also be placed in a float, as described below, which will allow
TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
to place it as well as it can within the page.
\layout Standard
One\SpecialChar ~
last\SpecialChar ~
remark:
\family sans
Longtable
\family default
and
\family sans
Rotate\SpecialChar ~
90°
\family default
use special LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
packages, so you should look into
\family sans
L
\bar under
a
\bar default
TeX\SpecialChar ~
configuration
\family default
in the
\family sans
\bar under
H
\bar default
elp
\family default
menu to see if your system supports these features.
\layout Section
Table of contents
\begin_inset LatexCommand \label{LyX-table-of-contents}
\end_inset
\layout Standard
LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
provides its own command for the creation of a Table of Contents (from the
menu: Insert-->Lists&TOC-->Table of Contents) -
\emph on
but you should not use it!
\emph default
Whether a table of contents will be created or not is entirely controlled
by the stylesheets (see
\begin_inset LatexCommand \ref{DSSSL-stylesheets}
\end_inset
and
\begin_inset LatexCommand \ref{explain-DSSSL-stylesheets}
\end_inset
).
For example, the following code in a stylesheet
\begin_inset LatexCommand \index{stylesheet}
\end_inset
specifies that a Table of Contents has to be created for document
\begin_inset LatexCommand \index{document}
\end_inset
type
\begin_inset Quotes eld
\end_inset
Article
\begin_inset Quotes erd
\end_inset
:
\layout Code
(define %generate-article-toc%
\layout Code
;; Should a Table of Contents be produced for Articles?
\layout Code
#t)
\layout Section
List of figures, tables and equations
\begin_inset LatexCommand \label{LyX-list-of-figures}
\end_inset
\layout Standard
A list of figures
\begin_inset LatexCommand \index{figures}
\end_inset
is created automatically
\begin_inset LatexCommand \index{automatically}
\end_inset
for the document
\begin_inset LatexCommand \index{document}
\end_inset
type
\begin_inset Quotes eld
\end_inset
DocBook
\begin_inset LatexCommand \index{DocBook}
\end_inset
book SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
\begin_inset Quotes erd
\end_inset
.
You don't need to undertake anything here.
The same is true for lists of tables and equations.
\begin_inset LatexCommand \index{equations}
\end_inset
This is true as long as you use the DSSSL
\begin_inset LatexCommand \index{DSSSL}
\end_inset
stylesheets (that form part of DocBook,
\begin_inset LatexCommand \index{DocBook}
\end_inset
see
\begin_inset LatexCommand \ref{DocBook}
\end_inset
) with their default settings.
In case you don't get a list, when you think you should, read in
\begin_inset LatexCommand \ref{explain-DSSSL-stylesheets}
\end_inset
about the generate-book-lot-list stylesheet
\begin_inset LatexCommand \index{stylesheet}
\end_inset
parameter.
\layout Section
Epigraphs
\begin_inset LatexCommand \label{epigraphs}
\end_inset
\layout Standard
An
\begin_inset LatexCommand \url[epigraph]{http://www.oreilly.com/catalog/docbook/chapter/book/epigraph.html}
\end_inset
is a short inscription at the beginning of a document
\begin_inset LatexCommand \index{document}
\end_inset
or component.
LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
only provides the
\begin_inset Quotes eld
\end_inset
Quotation
\begin_inset Quotes erd
\end_inset
environment,
\begin_inset LatexCommand \index{environment}
\end_inset
which is mapped onto the
\begin_inset LatexCommand \url[blockquote]{http://www.oreilly.com/catalog/docbook/chapter/book/blockquote.html}
\end_inset
SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
element,
\begin_inset LatexCommand \index{element}
\end_inset
when exported.
For an epigraph
\begin_inset LatexCommand \index{epigraph}
\end_inset
as such, there is no provision (as is the case with all SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
tags that do not have a clear correspondence to TeX/LaTeX environments
\begin_inset LatexCommand \index{environments}
\end_inset
- see
\begin_inset LatexCommand \ref{LyX-environments}
\end_inset
for the notion of an environment
\begin_inset LatexCommand \index{environment}
\end_inset
in LyX).
\layout SGML
However, you can always define an SGML environment and write the necessary
SGML tags there.
For an epigraph, you would then write for Norm's favourite quote: ]]>
]]> ]]> ]]> I
nline graphic
\layout Code
\layout Code
William Safire
\layout Code
\layout Code
Knowing how things work is the basis for appreciation, and is
\layout Code
thus a source of civilized delight.
\layout Code
\layout Code
\layout Standard
See
\begin_inset LatexCommand \ref{explain-magic}
\end_inset
for how the end result looks like.
\layout Section
SGML code in program listings
\begin_inset LatexCommand \label{LyX-SGML-code}
\end_inset
\layout Standard
If you want to write
\emph on
executable
\emph default
SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
code in LyX,
\begin_inset LatexCommand \index{LyX}
\end_inset
e.g.
to implement an admonition
\begin_inset LatexCommand \index{admonition}
\end_inset
(see
\begin_inset LatexCommand \ref{LyX-admonitions}
\end_inset
) or a callout (see
\begin_inset LatexCommand \ref{LyX-callouts}
\end_inset
), there is no problem: just create an environment
\begin_inset LatexCommand \index{environment}
\end_inset
of type
\begin_inset Quotes eld
\end_inset
SGML
\begin_inset Quotes erd
\end_inset
and enter your code there.
It will be part of the exported SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
file.
\layout Standard
But if you want to give some
\emph on
example
\emph default
SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
code, like in a program listing, then it might be a better idea to move
the code in a separate file and include that file per reference.
This is because if the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
code contains
\begin_inset Quotes eld
\end_inset
\begin_inset Quotes erd
\end_inset
, it is likely to interefere with the normal SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
processing,
\begin_inset LatexCommand \index{processing}
\end_inset
causing errors like the following:
\layout Code
/usr/bin/openjade:0:382:323:E: marked section end not in marked section
declaration
\layout Standard
To include a file, choose from the menu Insert-->Include file.
In the dialog box, choose
\begin_inset Quotes eld
\end_inset
Verbatim
\begin_inset Quotes erd
\end_inset
and enter the file name.
The file should best be located in the same directory as the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
file exported from LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
(but need not necessarily to).
\layout Standard
LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
will use the
\begin_inset Quotes eld
\end_inset
inlinegraphic
\begin_inset Quotes erd
\end_inset
SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
tag to include the file.
This will collide with inline
\begin_inset LatexCommand \index{inline}
\end_inset
graphics, if you want to include them using this method too (see
\begin_inset LatexCommand \ref{LyX-inline-graphics}
\end_inset
and
\begin_inset LatexCommand \ref{explain-inline-graphics}
\end_inset
).
\layout Section
Filenames
\begin_inset LatexCommand \label{LyX-filenames}
\end_inset
\layout Standard
It would be nice to have a
\begin_inset Quotes eld
\end_inset
Filename
\begin_inset Quotes erd
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
for DocBook
\begin_inset LatexCommand \index{DocBook}
\end_inset
SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
articles or books in LyX,
\begin_inset LatexCommand \index{LyX}
\end_inset
it would make computer documentation much nicer.
But I was unable to find one, or a workaround
\begin_inset LatexCommand \index{workaround}
\end_inset
to it.
If you find a way, please let me know.
Of course, a poor man's solution could be to mark
\begin_inset LatexCommand \index{mark}
\end_inset
a filename with the
\begin_inset Quotes eld
\end_inset
!
\begin_inset Quotes erd
\end_inset
button, making it part of an tag, which would then appear in
italics.
But this contradicts the very idea of SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
- separation
\begin_inset LatexCommand \index{separation}
\end_inset
of content from formatting.
\begin_inset LatexCommand \index{formatting}
\end_inset
\layout Subsection
Labels as filenames
\begin_inset LatexCommand \label{labels-as-filenames}
\end_inset
\layout Standard
You should always put a label
\begin_inset LatexCommand \index{label}
\end_inset
after the chapter/section/subsection/subsubsection title (from the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
menu: Insert-->Label).
The text you use for the label
\begin_inset LatexCommand \index{label}
\end_inset
will become the name of the HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
file that contains that chapter/section etc.
See
\begin_inset LatexCommand \ref{explain-DSSSL-stylesheets}
\end_inset
for the code that controls this setting in the stylesheets (it is the
\begin_inset LatexCommand \url[use-id-as-filename DSSSL parameter.]{http://docbook.sourceforge.net/release/dsssl/current/doc/html/use-id-as-filename.html}
\end_inset
that does this).
\layout SGML
\layout SGML
SEO (Search Engine Optimization) tips
\layout SGML
\layout SGML
There is circumstancial evidence that the search engines (especially
\begin_inset LatexCommand \url[Google]{http://www.google.com}
\end_inset
) 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...filena
mes ]]>
]]> ]]>
]]> Inline graphic):
\layout SGML
\layout SGML
\layout SGML
\layout SGML
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.
\layout SGML
\layout SGML
\layout SGML
\layout SGML
\layout SGML
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!
\layout SGML
\layout SGML
\layout SGML
\layout SGML
\layout SGML
Dont'use blanks.
Use hyphen
\begin_inset Quotes eld
\end_inset
-
\begin_inset Quotes erd
\end_inset
instead.
This makes use of the fact that for most search engines
\begin_inset Quotes eld
\end_inset
-
\begin_inset Quotes erd
\end_inset
is equivalent to a blank.
This is not the case for underscore
\begin_inset Quotes eld
\end_inset
_
\begin_inset Quotes erd
\end_inset
.
\layout SGML
\layout SGML
\layout SGML
\layout SGML
\layout SGML
Don't use illegal characters, i.e.
characters that are not allowed in HTML filenames.
\layout SGML
\layout SGML
\layout SGML
\layout SGML
\layout SGML
\layout Subsection
Cool labels don't change!
\begin_inset LatexCommand \label{cool-labels-dont-change}
\end_inset
\layout Standard
There is one thing to keep in mind when regrouping:
\begin_inset LatexCommand \index{regrouping}
\end_inset
chapter and section labels - DON'T change existing ones! You may change
their position, but please not the label.
\begin_inset LatexCommand \index{label}
\end_inset
Subsection
\begin_inset LatexCommand \index{Subsection}
\end_inset
and subsubsection
\begin_inset LatexCommand \index{subsubsection}
\end_inset
labels can be changed without problem.
\layout Standard
Why? Because chapters and sections will become separate HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
documents.
There is a DSSSL
\begin_inset LatexCommand \index{DSSSL}
\end_inset
stylesheet setting which controls how deep a level will still produce a
separate HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
document (see the decription of chunk-section-depth in
\begin_inset LatexCommand \ref{explain-DSSSL-stylesheets}
\end_inset
).
The name of the documents will be the label
\begin_inset LatexCommand \index{label}
\end_inset
of the chapter and section respectively.
This is a behaviour
\begin_inset LatexCommand \index{behaviour}
\end_inset
we explicitly set in the DSSSL
\begin_inset LatexCommand \index{DSSSL}
\end_inset
stylesheets (see
\begin_inset LatexCommand \ref{explain-DSSSL-stylesheets}
\end_inset
) through the
\begin_inset LatexCommand \url[use-id-as-filename DSSSL parameter.]{http://docbook.sourceforge.net/release/dsssl/current/doc/html/use-id-as-filename.html}
\end_inset
.
\layout Standard
Obviously, you can move a section around, without affecting the HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
name of the resulting file, if you don't change its label.
\begin_inset LatexCommand \index{label}
\end_inset
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
\begin_inset LatexCommand \index{label}
\end_inset
untouched.
\layout Standard
The problem is that, if the document
\begin_inset LatexCommand \index{document}
\end_inset
is already on the Web
\begin_inset LatexCommand \index{Web}
\end_inset
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,
\begin_inset LatexCommand \index{label}
\end_inset
the HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
name changes.
Consequently, the link from the search engines is no longer valid.
The same is true for private bookmarks,
\begin_inset LatexCommand \index{bookmarks}
\end_inset
or public bookmark lists.
\layout SGML
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.
]]>
]]> ]]> ]]> Inline graphic
\layout SGML
\layout SGML
It's not a question of sacrificing quality!
\layout SGML
\layout SGML
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.
\layout SGML
\layout SGML
\layout SGML
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!
\layout SGML
\layout SGML
\layout Standard
For example, suppose a chapter with the title
\begin_inset Quotes eld
\end_inset
Blue widgets
\begin_inset LatexCommand \index{widgets}
\end_inset
\begin_inset Quotes erd
\end_inset
is at around place 6 out of 2,5 million (!) for "blue widgets" on Google.
\begin_inset LatexCommand \index{Google}
\end_inset
If you change the label
\begin_inset LatexCommand \index{label}
\end_inset
of the chapter from "blue-widgets"
\begin_inset LatexCommand \index{blue-widgets}
\end_inset
to something else, then the original URI
\begin_inset LatexCommand \index{URI}
\end_inset
will disappear and you loose readers.
Of course, changing the title also affects the SERPS
\begin_inset LatexCommand \index{SERPS}
\end_inset
(Search Engine Result Pages), but not as drastically as to eliminate
\begin_inset LatexCommand \index{eliminate}
\end_inset
the document
\begin_inset LatexCommand \index{document}
\end_inset
altogether.
However, Google
\begin_inset LatexCommand \index{Google}
\end_inset
likes a title that is correlated
\begin_inset LatexCommand \index{correlated}
\end_inset
to the file name, so a title "Blue widgets" and a label
\begin_inset LatexCommand \index{label}
\end_inset
"blue-widgets" are optimal from the SEO
\begin_inset LatexCommand \index{SEO}
\end_inset
(Search Engine Optimization) point of view (see
\begin_inset LatexCommand \ref{labels-as-filenames}
\end_inset
).
\layout Standard
\begin_inset Quotes eld
\end_inset
But you are talking me into subjecting my writing to the whims of a search
engine!
\begin_inset Quotes erd
\end_inset
, 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
\begin_inset LatexCommand \index{rules}
\end_inset
for good writing that you might choose to observe, or not.
There are also rules
\begin_inset LatexCommand \index{rules}
\end_inset
for good
\begin_inset Quotes eld
\end_inset
copy
\begin_inset Quotes erd
\end_inset
, from the point of view of keywords,
\begin_inset LatexCommand \index{keywords}
\end_inset
search engines and ranking
\begin_inset LatexCommand \index{ranking}
\end_inset
- which you are also free to observe or defy.
\layout Standard
Then, at some point, you decide to put the document
\begin_inset LatexCommand \index{document}
\end_inset
on the web.
People will come, read it and, hopefully, find it good.
Those people may like your document
\begin_inset LatexCommand \index{document}
\end_inset
so much, as to go into the trouble to say something like "there's a cool
document
\begin_inset LatexCommand \index{document}
\end_inset
on blue widgets
\begin_inset LatexCommand \index{widgets}
\end_inset
in this link here" - and link to it.
Hundreds of people may do this perhaps - even thousands.
Imagine the effort!
\layout Standard
Now you come up with a new restructuring of you document
\begin_inset LatexCommand \index{document}
\end_inset
- fine! You change the content - also fine! Then you change the label
\begin_inset LatexCommand \index{label}
\end_inset
from:
\layout Code
Blue widgets
\layout Standard
to:
\layout Code
Blue widgets revisited
\layout Standard
In LyX,
\begin_inset LatexCommand \index{LyX}
\end_inset
this is equivalent to changing the title from
\begin_inset Quotes eld
\end_inset
Blue widgets
\begin_inset LatexCommand \index{widgets}
\end_inset
\begin_inset Quotes erd
\end_inset
to
\begin_inset Quotes eld
\end_inset
Blue widgets
\begin_inset LatexCommand \index{widgets}
\end_inset
revisited
\begin_inset Quotes erd
\end_inset
and the label
\begin_inset LatexCommand \index{label}
\end_inset
from
\begin_inset Quotes eld
\end_inset
blue-widgets
\begin_inset Quotes erd
\end_inset
to
\begin_inset Quotes eld
\end_inset
blue-widgets-2
\begin_inset Quotes erd
\end_inset
.
Perhaps you thought it would be a nice idea to change the title to reflect
the reorganization.
\begin_inset LatexCommand \index{reorganization}
\end_inset
This will affect your ranking
\begin_inset LatexCommand \index{ranking}
\end_inset
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.).
\layout Standard
But by changing that label
\begin_inset LatexCommand \index{label}
\end_inset
from
\begin_inset Quotes eld
\end_inset
blue-widgets
\begin_inset Quotes erd
\end_inset
to
\begin_inset Quotes eld
\end_inset
blue-widgets-2
\begin_inset Quotes erd
\end_inset
you just managed to throw your document
\begin_inset LatexCommand \index{document}
\end_inset
from place 6 to place 600 (or 6000, or...) in the SERPS.
\begin_inset LatexCommand \index{SERPS}
\end_inset
You just killed all the efforts of thousands of people that linked to your
document!
\layout Standard
Why?
\layout Standard
Because labels become filenames in the document
\begin_inset LatexCommand \index{document}
\end_inset
process from SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
to HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
(see
\begin_inset LatexCommand \ref{explain-magic}
\end_inset
for a detailed explanation of this process).
The document
\begin_inset LatexCommand \index{document}
\end_inset
that would be blue-widgets.
\begin_inset LatexCommand \index{blue-widgets}
\end_inset
html now is blue-widgets-2.html.
The original blue-widgets.
\begin_inset LatexCommand \index{blue-widgets}
\end_inset
html is nowhere to be found in your domain - hundreds,
\begin_inset LatexCommand \index{hundreds}
\end_inset
or even thousands of links on the Web
\begin_inset LatexCommand \index{Web}
\end_inset
now point to vacuum!
\layout Standard
Google
\begin_inset LatexCommand \index{Google}
\end_inset
- and every other search engine - sees this and takes the old URL
\begin_inset LatexCommand \index{URL}
\end_inset
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
\begin_inset LatexCommand \index{label}
\end_inset
(and the resulting HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
filename) at your whim.
Thus, noone points to the new "reorganized"
\begin_inset LatexCommand \index{reorganized}
\end_inset
document.
\begin_inset LatexCommand \index{document}
\end_inset
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
\begin_inset LatexCommand \index{document}
\end_inset
ranked at place 6 out of 2,5 million!
\layout Standard
You might think that, since the label-to-filename
\begin_inset LatexCommand \index{label-to-filename}
\end_inset
connection exists only for the
\begin_inset Quotes eld
\end_inset
chunked
\begin_inset Quotes erd
\end_inset
version (the version where openjade
\begin_inset LatexCommand \index{openjade}
\end_inset
is instructed to split the document
\begin_inset LatexCommand \index{document}
\end_inset
into separate HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
files, one per chapter or section, the so-called
\begin_inset Quotes eld
\end_inset
chunks
\begin_inset Quotes erd
\end_inset
, as explained in
\begin_inset LatexCommand \ref{explain-document-creation-HTML}
\end_inset
), the
\begin_inset Quotes eld
\end_inset
unchunked
\begin_inset Quotes erd
\end_inset
document
\begin_inset LatexCommand \index{document}
\end_inset
will save you from this disaster.
You are correct, the "single chunk
\begin_inset LatexCommand \index{chunk}
\end_inset
documents" (single, big HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
file, TXT,
\begin_inset LatexCommand \index{TXT}
\end_inset
PDF
\begin_inset LatexCommand \index{PDF}
\end_inset
or PS
\begin_inset LatexCommand \index{PS}
\end_inset
versions) will not be affected .
\layout Standard
If you only make the big HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
file, or the TXT,
\begin_inset LatexCommand \index{TXT}
\end_inset
PDF
\begin_inset LatexCommand \index{PDF}
\end_inset
and PS
\begin_inset LatexCommand \index{PS}
\end_inset
versions of your document
\begin_inset LatexCommand \index{document}
\end_inset
available on the web, then you are not affected.
But if you also made the chunked
\begin_inset LatexCommand \index{chunked}
\end_inset
HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
version available at some point, the search engines will prefer to return
results from this version, than from the others.
\layout Standard
There are various reasons for this, one of them being that search engines
don't read a document
\begin_inset LatexCommand \index{document}
\end_inset
that is too long till the end and will thus index small chunks
\begin_inset LatexCommand \index{chunks}
\end_inset
much better than huge textst.
Another reason is that you need more links to a PDF
\begin_inset LatexCommand \index{PDF}
\end_inset
document, to force a search engine to consider it important for indexing.
\begin_inset LatexCommand \index{indexing}
\end_inset
\layout Standard
So forget about the huge, one-chunk
\begin_inset LatexCommand \index{one-chunk}
\end_inset
docs as a search engine strategy.
\begin_inset LatexCommand \index{strategy}
\end_inset
If you want to be found by the SEs, you must rely on the chunked
\begin_inset LatexCommand \index{chunked}
\end_inset
versions - and perhaps a little on PDF,
\begin_inset LatexCommand \index{PDF}
\end_inset
but only a little.
\layout Standard
However, my point goes even further: we are not talking about a user who
is searching for a unique, multiple keyword
\begin_inset LatexCommand \index{keyword}
\end_inset
phrase that identifies the content of your reorganized
\begin_inset LatexCommand \index{reorganized}
\end_inset
document.
We are talking about a user who just searches for, two keywords:
\begin_inset LatexCommand \index{keywords}
\end_inset
\begin_inset Quotes eld
\end_inset
blue widgets
\begin_inset LatexCommand \index{widgets}
\end_inset
\begin_inset Quotes erd
\end_inset
.
If you change the label,
\begin_inset LatexCommand \index{label}
\end_inset
you change the filename of the chunked
\begin_inset LatexCommand \index{chunked}
\end_inset
version.
If you do so, the search engine will NOT think "Ahh...the file blue-widgets.
\begin_inset LatexCommand \index{blue-widgets}
\end_inset
html is not there, let's present the huge document
\begin_inset LatexCommand \index{document}
\end_inset
that contains all chapters, including the one on blue widgets
\begin_inset LatexCommand \index{widgets}
\end_inset
- at the same ranking
\begin_inset LatexCommand \index{ranking}
\end_inset
place"! There are three resons that this will not happen - and you should
not rely on it:
\layout Enumerate
First, the search engine does not know that blue-widgets.
\begin_inset LatexCommand \index{blue-widgets}
\end_inset
html is just a chunk
\begin_inset LatexCommand \index{chunk}
\end_inset
of some "whole" document,
\begin_inset LatexCommand \index{document}
\end_inset
book1.html.
There is nothing that a search engine does to find this out - not with
today's technology.
\begin_inset LatexCommand \index{technology}
\end_inset
The two documents are different from the search engine point of view.
\layout Enumerate
Second, the big one, book1.html, contains much more text, therefore the importanc
e of the "blue widgets" chapter is "diluted" from the surrounding, irrelevant
text (irrelevant to what the user is searching with those keywords,
\begin_inset LatexCommand \index{keywords}
\end_inset
namely "blue widgets").
This has to do with
\begin_inset Quotes eld
\end_inset
keyword
\begin_inset LatexCommand \index{keyword}
\end_inset
density
\begin_inset LatexCommand \index{density}
\end_inset
\begin_inset Quotes erd
\end_inset
, titles, structure and other
\begin_inset Quotes eld
\end_inset
on-page
\begin_inset Quotes erd
\end_inset
factors that the search engine calculates and takes into account for each
page.
Therefore, the document
\begin_inset LatexCommand \index{document}
\end_inset
will rank at a place that is way back - invisible to all but the most determined
searchers, practically dead.
\layout Enumerate
Third, if you are a HOWTO author, you may put your document
\begin_inset LatexCommand \index{document}
\end_inset
on
\begin_inset LatexCommand \url[The Linux Documentation Project]{http://www.tldp.org}
\end_inset
, which is a great place with good exposure
\begin_inset LatexCommand \index{exposure}
\end_inset
to the Web,
\begin_inset LatexCommand \index{Web}
\end_inset
but that alone does not guarantee good ranking.
\begin_inset LatexCommand \index{ranking}
\end_inset
What is also important, is that people
\emph on
link
\emph default
to it.
But if you change an existing label,
\begin_inset LatexCommand \index{label}
\end_inset
thus changing the filename of the chunked
\begin_inset LatexCommand \index{chunked}
\end_inset
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.
\begin_inset LatexCommand \index{URL}
\end_inset
You destroy what you were able to gather up to that point in terms
\begin_inset LatexCommand \index{terms}
\end_inset
of search engine visibility.
\begin_inset LatexCommand \index{visibility}
\end_inset
You start anew.
\layout SGML
\layout SGML
Use permanent redirects, if you do choose to change the label!
\layout SGML
\layout SGML
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?
\layout SGML
\layout SGML
\layout SGML
Certainly not.
\layout SGML
\layout SGML
\layout SGML
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
\begin_inset Quotes eld
\end_inset
permanent redirect
\begin_inset Quotes erd
\end_inset
instead.
See
\begin_inset LatexCommand \url[Managing URIs]{http://www.w3.org/QA/Tips/uri-manage}
\end_inset
and the links therein, for the preferred ways to handle this situation.
\layout SGML
\layout SGML
\layout SGML
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 (theoreti
cally, 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?
\layout SGML
\layout SGML
\layout SGML
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.
\layout SGML
\layout SGML
\layout Standard
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
\begin_inset LatexCommand \index{label}
\end_inset
wisely (for the same reasons that you would
\begin_inset LatexCommand \url[Choose URIs wisely]{http://www.w3.org/QA/Tips/uri-choose}
\end_inset
), 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.
\layout SGML
\begin_inset LatexCommand \url[Cool URIs don't change]{http://www.w3.org/Provider/Style/URI.html}
\end_inset
.
Cool labels don't change either.
]]>
]]> ]]>
]]> Inline graphic
\layout Section
Examples
\begin_inset LatexCommand \label{LyX-examples}
\end_inset
\layout Standard
There is no
\begin_inset Quotes eld
\end_inset
Example
\begin_inset Quotes erd
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
in LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
for document
\begin_inset LatexCommand \index{document}
\end_inset
types of DocBook
\begin_inset LatexCommand \index{DocBook}
\end_inset
SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
book/article.
You could certainly
\begin_inset Quotes eld
\end_inset
simulate
\begin_inset Quotes erd
\end_inset
it with a pure SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
environment,
\begin_inset LatexCommand \index{environment}
\end_inset
just as we did it for admonitions
\begin_inset LatexCommand \index{admonitions}
\end_inset
(
\begin_inset LatexCommand \ref{LyX-admonitions}
\end_inset
) and callouts
\begin_inset LatexCommand \index{callouts}
\end_inset
(
\begin_inset LatexCommand \ref{LyX-callouts}
\end_inset
), but I will not pursue this further here.
\layout Section
Mathematics
\begin_inset LatexCommand \label{LyX-Mathematics}
\end_inset
\layout Standard
You write Mathematics
\begin_inset LatexCommand \index{Mathematics}
\end_inset
in LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
the usual way (see, for example, the Tutorial and the User's Guide that
come with LyX).
There is absolutely nothing special you have to take care of.
Here is an example:
\layout Standard
\begin_inset Formula \[
\sum _{n=1}^{\infty }\frac{x^{n}}{n}=\ln \left(\frac{1}{1-x}\right)\]
\end_inset
\layout Standard
Whatever you type in math,
\begin_inset LatexCommand \index{math}
\end_inset
it will be typeset by TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
and be available in all formats - HTML,
\begin_inset LatexCommand \index{HTML}
\end_inset
PDF,
\begin_inset LatexCommand \index{PDF}
\end_inset
PS
\begin_inset LatexCommand \index{PS}
\end_inset
\emph on
and
\emph default
RTF! Isn't it great?
\layout Standard
You should nevertheless read
\begin_inset LatexCommand \ref{DBTeXMath}
\end_inset
to ensure that you installed the necessary software for math
\begin_inset LatexCommand \index{math}
\end_inset
processing
\begin_inset LatexCommand \index{processing}
\end_inset
and
\begin_inset LatexCommand \ref{mathematics}
\end_inset
to get an idea of what is going on in the background.
\begin_inset LatexCommand \index{background}
\end_inset
There are more Mathematics
\begin_inset LatexCommand \index{Mathematics}
\end_inset
examples for LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
in
\begin_inset LatexCommand \ref{LyX-writing-Mathematics}
\end_inset
, where the subject is discussed in more details.
\layout Section
Appendix
\begin_inset LatexCommand \label{LyX-Appendix}
\end_inset
\layout Standard
LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
offers the possibility to mark
\begin_inset LatexCommand \index{mark}
\end_inset
a part of the document
\begin_inset LatexCommand \index{document}
\end_inset
as being the Appendix: from the top menu, choose Layout -> Start Appendix
here.
Unfortunately, this will not work when the document
\begin_inset LatexCommand \index{document}
\end_inset
is exported to SGML.
\begin_inset LatexCommand \index{SGML}
\end_inset
We are thus left alone and have to implement a workaround.
\begin_inset LatexCommand \index{workaround}
\end_inset
I have implemented the following solution:
\layout Itemize
The writer provides an extra LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
file, with the fixed name
\begin_inset Quotes eld
\end_inset
appendix.lyx
\begin_inset Quotes erd
\end_inset
, in the same directory as the main document.
\begin_inset LatexCommand \index{document}
\end_inset
\layout Itemize
The appendix.
\begin_inset LatexCommand \index{appendix}
\end_inset
lyx
\begin_inset LatexCommand \index{lyx}
\end_inset
file must be of type
\begin_inset Quotes eld
\end_inset
DocBook
\begin_inset LatexCommand \index{DocBook}
\end_inset
article (SGML)
\begin_inset Quotes erd
\end_inset
, to be chosen from the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
menu: Layout -> Document.
A document
\begin_inset LatexCommand \index{document}
\end_inset
type of
\begin_inset Quotes eld
\end_inset
DocBook
\begin_inset LatexCommand \index{DocBook}
\end_inset
book (SGML)
\begin_inset Quotes erd
\end_inset
will NOT work, even if the main document
\begin_inset LatexCommand \index{document}
\end_inset
is of book type! This is because if you set the document
\begin_inset LatexCommand \index{document}
\end_inset
type to book, you will have to start with Chapters (instead of Sections)
and then you will get parsing errors from openjade
\begin_inset LatexCommand \index{openjade}
\end_inset
saying that CHAPTER is not allowed by the DTD
\begin_inset LatexCommand \index{DTD}
\end_inset
at that place.
\layout Itemize
The appendix
\begin_inset LatexCommand \index{appendix}
\end_inset
is marked as such, using LyX' menu: Layout -> Start Appendix here, with
the cursor
\begin_inset LatexCommand \index{cursor}
\end_inset
at the very start of the Appendix.
\layout Standard
That's all! The
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
script will check if a file called appendix.
\begin_inset LatexCommand \index{appendix}
\end_inset
lyx
\begin_inset LatexCommand \index{lyx}
\end_inset
is there and will take the aproppriate steps to incorporate it into the
document
\begin_inset LatexCommand \index{document}
\end_inset
(see
\begin_inset LatexCommand \ref{explain-appendix}
\end_inset
).
\layout SGML
\layout SGML
How to insert cross-references to the Appendix
\layout SGML
\layout SGML
To insert a cross-reference to the Appendix (more precisely to a section,
subsection, subsubsection, table, figure or equation in the Appendix),
you use the same mechanism in LyX, as you would do for cross-references
to labels that exist in a separate file: from the Insert menu, choose "Label",
then, from the drop-down list for "Buffer", choose the appendix.lyx file
(which you should have already opened in LyX).
LyX will then present you with all available labels from the appendix.lyx
file to choose for your cross-reference.
\layout SGML
\layout SGML
\layout Section
Bibliography
\begin_inset LatexCommand \label{LyX-Bibliography}
\end_inset
\layout SGML
So you want to use LyX to process citations and include a reference
list at the end of your document? And all this in SGML? You are at the
right place! ]]> ]]> ]]>
]]> Inline graphic
\layout Standard
To begin with, here is just a test citation:
\begin_inset LatexCommand \index{citation}
\end_inset
\begin_inset LatexCommand \index{citation:}
\end_inset
\begin_inset LatexCommand \ref{cit:KARAKAS1991}
\end_inset
.
And another one:
\begin_inset LatexCommand \ref{cit:KARAKAS1992}
\end_inset
.
Take the time to examine them and their formatting
\begin_inset LatexCommand \index{formatting}
\end_inset
in the version (HTML, PDF,
\begin_inset LatexCommand \index{PDF}
\end_inset
PS,
\begin_inset LatexCommand \index{PS}
\end_inset
RDF or TXT) you are currently reading.
\layout Subsection
Bibliography without RefDB
\begin_inset LatexCommand \label{LyX-Bibliography-without-RefDB}
\end_inset
\layout Standard
As stated in
\begin_inset LatexCommand \ref{Refdb}
\end_inset
, you are not confined to using
\begin_inset LatexCommand \url[RefDB]{http://refdb.sourceforge.net}
\end_inset
whith my
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
script.
If you don't feel like building your own bibliographic
\begin_inset LatexCommand \index{bibliographic}
\end_inset
database, you can just supply a bibliography.
\begin_inset LatexCommand \index{bibliography}
\end_inset
lyx
\begin_inset LatexCommand \index{lyx}
\end_inset
file together with your LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
document.
Set the process_RefDB variable in
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
to "0" and it will use your own bibliography.
\begin_inset LatexCommand \index{bibliography}
\end_inset
lyx
\begin_inset LatexCommand \index{lyx}
\end_inset
to produce a bibliography.
\begin_inset LatexCommand \index{bibliography}
\end_inset
sgml file, instead of trying to create one automatically
\begin_inset LatexCommand \index{automatically}
\end_inset
through RefDB.
\begin_inset LatexCommand \index{RefDB}
\end_inset
The bibliography.
\begin_inset LatexCommand \index{bibliography}
\end_inset
lyx
\begin_inset LatexCommand \index{lyx}
\end_inset
file should then contain the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
code for the references list, in the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
of LyX.
\begin_inset LatexCommand \index{LyX}
\end_inset
The
\begin_inset LatexCommand \url[GNU/Linux Command-Line Tools Summary HOWTO]{http://www.karakas-online.de/gnu-linux-tools-summary/}
\end_inset
uses this approach,
\begin_inset LatexCommand \index{approach}
\end_inset
for example.
\layout Standard
This means that if you don't want to use RefDB,
\begin_inset LatexCommand \index{RefDB}
\end_inset
but still want to have a bibliography, your bibliography.
\begin_inset LatexCommand \index{bibliography}
\end_inset
lyx
\begin_inset LatexCommand \index{lyx}
\end_inset
file should look like:
\layout Code
\layout Code
\layout Code
\layout Code
\layout Code
\layout Code
Karakas
\layout Code
Chris
\layout Code
\layout Code
\begin_inset LatexCommand \url[Neuronale Lernregeln und andere Methoden für lineare Assoziation und Trennung]{http://www.amazon.de/exec/obidos/ASIN/3898112330}
\end_inset
\layout Code
\layout Code
BoD GmbH, Norderstedt
\layout Code
\layout Code
\layout Code
\layout Code
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 associati
on problem and some so-called "learning rules" for its solution are considered:
\layout Code
...more Abstract text here.
\layout Code
\layout Code
\layout Code
\layout Code
\layout Code
...
\layout Code
more elements here
\layout Code
...
\layout Code
\layout Code
\layout Standard
The whole code should be in the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
(see
\begin_inset LatexCommand \ref{LyX-environments}
\end_inset
for an explanation of LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
environments).
You can even insert URLs and cross-references the usual LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
way (from the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
Insert menu) and they will be correctly exported to SGML.
\begin_inset LatexCommand \index{SGML}
\end_inset
The layout
\begin_inset LatexCommand \index{layout}
\end_inset
of bibliography.
\begin_inset LatexCommand \index{bibliography}
\end_inset
lyx
\begin_inset LatexCommand \index{lyx}
\end_inset
should be
\begin_inset Quotes eld
\end_inset
DocBook
\begin_inset LatexCommand \index{DocBook}
\end_inset
Chapter
\begin_inset LatexCommand \index{Chapter}
\end_inset
(SGML)
\begin_inset Quotes erd
\end_inset
(to be set from the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
Layout menu).
You don't need anything in the preample
\begin_inset LatexCommand \index{preample}
\end_inset
or elsewhere.
See the
\begin_inset LatexCommand \url[bibliography.lyx]{http://www.karakas-online.de/gnu-linux-tools-summary/bibliography.lyx}
\end_inset
file in the
\begin_inset LatexCommand \url[Formats section of GNU/Linux Command-Line Tools Summary HOWTO]{http://www.karakas-online.de/gnu-linux-tools-summary/introduction.html#FORMATS}
\end_inset
for an example.
\layout Standard
To cite
\begin_inset LatexCommand \index{cite}
\end_inset
a reference from a reference list created this way, you have to switch to
the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
for the whole paragraph
\begin_inset LatexCommand \index{paragraph}
\end_inset
containing the citation,
\begin_inset LatexCommand \index{citation}
\end_inset
then write as in the following example:
\layout Code
\layout Code
Consult KARAKAS1992 for more details on
\layout Code
neural learning rules.
\layout Code
\layout Standard
Note that we use the value of the xreflabel
\begin_inset LatexCommand \index{xreflabel}
\end_inset
attribute
\begin_inset LatexCommand \index{attribute}
\end_inset
to refer to the reference entry.
\layout SGML
\layout SGML
\layout SGML
Formatting your Reference List.
\layout SGML
\layout SGML
\layout SGML
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
\begin_inset LatexCommand \ref{cit:HOENICKA0}
\end_inset
(
\begin_inset LatexCommand \ref{LyX-Bibliography-with-RefDB}
\end_inset
) takes this burden out of your work for the slight overhead of setting
up a database and installing the RefDB package (
\begin_inset LatexCommand \ref{Refdb}
\end_inset
).
\layout SGML
\layout SGML
\layout Subsection
Bibliography with RefDB
\begin_inset LatexCommand \label{LyX-Bibliography-with-RefDB}
\end_inset
\layout Standard
You don't need to care about a bibliography.
\begin_inset LatexCommand \index{bibliography}
\end_inset
sgml file if you use RefDB
\begin_inset LatexCommand \index{RefDB}
\end_inset
- the
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
file will create it automatically
\begin_inset LatexCommand \index{automatically}
\end_inset
with the help of RefDB,
\begin_inset LatexCommand \index{RefDB}
\end_inset
totally transparently
\begin_inset LatexCommand \index{transparently}
\end_inset
to you.
All you need is install and set up RefDB
\begin_inset LatexCommand \index{RefDB}
\end_inset
(see
\begin_inset LatexCommand \ref{Refdb}
\end_inset
and
\begin_inset LatexCommand \ref{bibliographic-database}
\end_inset
respectively), and set the following variables in
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
:
\layout Itemize
Process_RefDB
\begin_inset LatexCommand \index{Process_RefDB}
\end_inset
to
\begin_inset Quotes eld
\end_inset
1
\begin_inset Quotes erd
\end_inset
.
\layout Itemize
RefDB_db
\begin_inset LatexCommand \index{RefDB_db}
\end_inset
to the name of the RefDB
\begin_inset LatexCommand \index{RefDB}
\end_inset
database containing the bibliographic
\begin_inset LatexCommand \index{bibliographic}
\end_inset
entries you plan to cite
\begin_inset LatexCommand \index{cite}
\end_inset
(you created this database
\begin_inset LatexCommand \index{database}
\end_inset
in
\begin_inset LatexCommand \ref{Refdb}
\end_inset
, the name in the example was
\begin_inset Quotes eld
\end_inset
ck_refdb
\begin_inset Quotes erd
\end_inset
and is the default one in
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
- you should of course change this).
\layout Itemize
REFDB_style
\begin_inset LatexCommand \index{REFDB_style}
\end_inset
to the style of the journal you want your Bibliography to conform to.
\layout Standard
Note that this name must contain a dot at the end, because
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
will create, the file ${REFDB_style}dsl.
\layout Standard
Example: for REFDB_style="J.Biol.Chem.",
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
will automatically
\begin_inset LatexCommand \index{automatically}
\end_inset
create (through RefDB) the file J.Biol.Chem.dsl,
\begin_inset LatexCommand \index{J.Biol.Chem.dsl}
\end_inset
i.e.
the
\begin_inset Quotes eld
\end_inset
dsl
\begin_inset Quotes erd
\end_inset
ending is appended without any extra dot.
The default value is
\begin_inset Quotes eld
\end_inset
J.Biol.Chem.
\begin_inset Quotes erd
\end_inset
, one of the two standard styles shipped with RefDB,
\begin_inset LatexCommand \index{RefDB}
\end_inset
and should get you starting.
See
\begin_inset LatexCommand \url[How to manage bibliography styles]{http://refdb.sourceforge.net/manual-0.9.4/x3098.html}
\end_inset
for more details on bibliography
\begin_inset LatexCommand \index{bibliography}
\end_inset
styles in RefDB.
\begin_inset LatexCommand \index{RefDB}
\end_inset
\layout Standard
The only thing that remains is...
cite
\begin_inset LatexCommand \index{cite}
\end_inset
of course!
\layout Standard
Citing with RefDB
\begin_inset LatexCommand \index{RefDB}
\end_inset
in LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
is a bit tricky, since LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
does not allow citing the way RefDB
\begin_inset LatexCommand \index{RefDB}
\end_inset
is expecting it: with a role attribute
\begin_inset LatexCommand \index{attribute}
\end_inset
with the value
\begin_inset Quotes eld
\end_inset
REFDB
\begin_inset Quotes erd
\end_inset
in the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
citation code.
Of course, we could use a pure SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
as in
\begin_inset LatexCommand \ref{LyX-Bibliography-without-RefDB}
\end_inset
and write:
\layout Code
\layout Code
Consult
\layout Code
for more details on neural learning rules.
\layout Code
\layout Standard
each time we want to cite
\begin_inset LatexCommand \index{cite}
\end_inset
something.
But there is a better way: RefDB
\begin_inset LatexCommand \index{RefDB}
\end_inset
can create that SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
code automatically,
\begin_inset LatexCommand \index{automatically}
\end_inset
if it finds something like:
\layout Code
\layout Code
Consult "KARAKAS1992"
\layout Code
for more details on neural learning rules.
\layout Code
\layout Standard
in the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
file.
But how can we convince LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
to output something like the above for each citation
\begin_inset LatexCommand \index{citation}
\end_inset
when it exports our file to SGML?
\begin_inset LatexCommand \index{SGML}
\end_inset
\layout Standard
The solution I found to this is:
\layout Enumerate
Export all the bibliographic
\begin_inset LatexCommand \index{bibliographic}
\end_inset
entries you plan to use in a file, say refdb.
\begin_inset LatexCommand \index{refdb}
\end_inset
ris (see
\begin_inset LatexCommand \ref{bibliographic-database}
\end_inset
on how to do this).
\layout Enumerate
Use the
\begin_inset LatexCommand \url[awkscr_cit]{awkscr_cit}
\end_inset
AWK
\begin_inset LatexCommand \index{AWK}
\end_inset
script to create a new LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
file from refdb.
\begin_inset LatexCommand \index{refdb}
\end_inset
ris:
\begin_deeper
\layout Code
awkscr_cit refdb.ris > citlabels.lyx
\layout Standard
The citlabels.lyx
\begin_inset LatexCommand \index{citlabels.lyx}
\end_inset
file is a LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
file containing only labels, one for each bibliographic
\begin_inset LatexCommand \index{bibliographic}
\end_inset
entry in refdb.
\begin_inset LatexCommand \index{refdb}
\end_inset
ris.
The labels have the prefix "cit:" to distinguish them from true labels.
To stay with the above example, the bibliographic
\begin_inset LatexCommand \index{bibliographic}
\end_inset
entry with ID
\begin_inset LatexCommand \index{ID}
\end_inset
\begin_inset Quotes eld
\end_inset
KARAKAS1992
\begin_inset Quotes erd
\end_inset
will produce a label
\begin_inset LatexCommand \index{label}
\end_inset
\begin_inset Quotes eld
\end_inset
cit:KARAKAS1992
\begin_inset Quotes erd
\end_inset
in the citlabels.lyx
\begin_inset LatexCommand \index{citlabels.lyx}
\end_inset
file created by awkscr_cit.
\begin_inset LatexCommand \index{awkscr_cit}
\end_inset
\end_deeper
\layout Enumerate
Open the citlabels.lyx
\begin_inset LatexCommand \index{citlabels.lyx}
\end_inset
file in LyX,
\begin_inset LatexCommand \index{LyX}
\end_inset
together with your document.
\begin_inset LatexCommand \index{document}
\end_inset
\layout Enumerate
To cite
\begin_inset LatexCommand \index{cite}
\end_inset
an entry, you (mis)use the
\begin_inset Quotes eld
\end_inset
Insert Cross-Reference
\begin_inset LatexCommand \index{Cross-Reference}
\end_inset
\begin_inset Quotes erd
\end_inset
feature of LyX:
\begin_inset LatexCommand \index{LyX}
\end_inset
from the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
menu, choose
\begin_inset Quotes eld
\end_inset
Insert -> Cross Reference
\begin_inset Quotes erd
\end_inset
.
In the upcoming
\begin_inset LatexCommand \index{upcoming}
\end_inset
dialog box there is a drop-down
\begin_inset LatexCommand \index{drop-down}
\end_inset
list field called
\begin_inset Quotes eld
\end_inset
Buffer
\begin_inset Quotes erd
\end_inset
.
The Buffer
\begin_inset LatexCommand \index{Buffer}
\end_inset
serves as the source of the labels you want to reference.
Usually,
\begin_inset Quotes eld
\end_inset
Buffer
\begin_inset Quotes erd
\end_inset
is set to the current file.
You change this to
\begin_inset Quotes eld
\end_inset
citlabels.lyx
\begin_inset Quotes erd
\end_inset
by clicking on the dropdown field and choosing the citlabels.lyx
\begin_inset LatexCommand \index{citlabels.lyx}
\end_inset
file.
Now you are presented with all labels of citlabels.lyx.
\begin_inset LatexCommand \index{citlabels.lyx}
\end_inset
Choose the label
\begin_inset LatexCommand \index{label}
\end_inset
containing the ID
\begin_inset LatexCommand \index{ID}
\end_inset
of the RefDB
\begin_inset LatexCommand \index{RefDB}
\end_inset
bibliographic
\begin_inset LatexCommand \index{bibliographic}
\end_inset
entry you want to cite.
\begin_inset LatexCommand \index{cite}
\end_inset
In our example, you choose
\begin_inset Quotes eld
\end_inset
cit:KARAKAS1992
\begin_inset Quotes erd
\end_inset
, if you want to cite
\begin_inset LatexCommand \index{cite}
\end_inset
the entry with ID
\begin_inset LatexCommand \index{ID}
\end_inset
\begin_inset Quotes eld
\end_inset
KARAKAS1992
\begin_inset Quotes erd
\end_inset
.
\layout Standard
That's all! Don't worry about that
\begin_inset Quotes eld
\end_inset
cit:
\begin_inset Quotes erd
\end_inset
prefix,
\begin_inset LatexCommand \url[sedscr]{sedscr}
\end_inset
takes care about it.
For every
\emph on
cross-reference
\emph default
to a label
\begin_inset LatexCommand \index{label}
\end_inset
of the form
\begin_inset Quotes eld
\end_inset
cit:IDsome
\begin_inset Quotes erd
\end_inset
, sedscr
\begin_inset LatexCommand \index{sedscr}
\end_inset
will create a
\emph on
citation
\emph default
of the form:
\layout Code
\begin_inset Include \verbatiminput{citation-short}
\end_inset
\layout Standard
in the exported SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
file.
Then,
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
will call the aproppriate RefDB
\begin_inset LatexCommand \index{RefDB}
\end_inset
tools to transform this citation
\begin_inset LatexCommand \index{citation}
\end_inset
to
\layout Code
\begin_inset Include \verbatiminput{citation-full}
\end_inset
\layout Standard
or some more complex form according to the bibliographic
\begin_inset LatexCommand \index{bibliographic}
\end_inset
style in use.
Again, you don't have to worry about this procedure.
\begin_inset LatexCommand \index{procedure}
\end_inset
Just create the citlabels.lyx
\begin_inset LatexCommand \index{citlabels.lyx}
\end_inset
file as shown above and insert cross-references to its labels in place of
your citations.
\begin_inset LatexCommand \index{citations}
\end_inset
You don't have to bother about SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
code and you can't get the ID's wrong since you get a list of all available
labels in citlabels.lyx
\begin_inset LatexCommand \index{citlabels.lyx}
\end_inset
to choose from.
On the other hand, you can't get anything but
\begin_inset Quotes eld
\end_inset
simple
\begin_inset Quotes erd
\end_inset
citations
\begin_inset LatexCommand \index{citations}
\end_inset
this way, but at the moment I can live with that.
See
\begin_inset LatexCommand \ref{explain-bibliography}
\end_inset
for a detailed explanation of what
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
and RefDB
\begin_inset LatexCommand \index{RefDB}
\end_inset
do for you in the background
\begin_inset LatexCommand \index{background}
\end_inset
to produce correctly formatted citations
\begin_inset LatexCommand \index{citations}
\end_inset
and a correctly formatted Reference List.
\layout SGML
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. ]]>
]]> ]]> ]]> I
nline graphic
\layout Section
Index
\begin_inset LatexCommand \label{LyX-Index}
\end_inset
\layout Standard
The index will be generated automatically
\begin_inset LatexCommand \index{automatically}
\end_inset
by the
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
script (which will call the collateindex.
\begin_inset LatexCommand \index{collateindex}
\end_inset
pl Perl script that came with the docbook-dsssl-stylesheets
\begin_inset LatexCommand \index{docbook-dsssl-stylesheets}
\end_inset
package you installed in
\begin_inset LatexCommand \ref{DocBook}
\end_inset
) as a separate file.
You must arrange to have this file incorporated into your document.
\begin_inset LatexCommand \index{document}
\end_inset
The easiest way to do this is by file entity
\begin_inset LatexCommand \index{entity}
\end_inset
reference.
In the preample
\begin_inset LatexCommand \index{preample}
\end_inset
of your document,
\begin_inset LatexCommand \index{document}
\end_inset
add an internal subset that defines the index file entity:
\begin_inset LatexCommand \index{entity}
\end_inset
\layout Code
\layout Standard
We have done this already in
\begin_inset LatexCommand \ref{preample}
\end_inset
.
See
\begin_inset LatexCommand \ref{explain-appendix}
\end_inset
for the sed scripts that insert the appendix
\begin_inset LatexCommand \index{appendix}
\end_inset
SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
entity at the end of the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
file and
\begin_inset LatexCommand \ref{explain-index}
\end_inset
for the explanation of the subsequent index generation.
\layout Standard
From the user perspective, all it remains is to enter the words that shall
be included in the index.
This is done as usual in LyX:
\begin_inset LatexCommand \index{LyX}
\end_inset
from the menu, choose either Insert-->
\begin_inset Quotes erd
\end_inset
Index entry of preceding word
\begin_inset Quotes erd
\end_inset
(which I personally find easier), or Insert-->
\begin_inset Quotes erd
\end_inset
Index entry
\begin_inset Quotes erd
\end_inset
, then enter the required word.
\layout SGML
\layout SGML
Don't underestimate the importance of an Index!
\layout SGML
\layout SGML
It is easy to neglect index generation.
It is so boring, having to read the whole document again, word for word,
and hour for hour use the menu to "insert index entry of preceding word"!
But don't underestimate the importance of a good, complete index for your
document, especially if it is of the order of a book! A knowledgeable reader
will allways appreciate the possibility to use the Index to arrive at the
information he is searching, rather than the usual time-consuming physical,
or, even worse, virtual page browsing.
Plan a whole working day for index generation of every 100 pages of text.
\layout SGML
\layout SGML
\layout Subsection
Automatic Index generation
\begin_inset LatexCommand \label{LyX-automatic-Index-generation}
\end_inset
\layout Standard
LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
provides an easy way to insert an Index entry (see
\begin_inset LatexCommand \ref{LyX-Index}
\end_inset
): from the menu, choose either Insert-->
\begin_inset Quotes erd
\end_inset
Index entry of preceding word
\begin_inset Quotes erd
\end_inset
(which I personally find easier), or Insert-->
\begin_inset Quotes erd
\end_inset
Index entry
\begin_inset Quotes erd
\end_inset
, then enter the required word.
This method works fine - if you have a small document,
\begin_inset LatexCommand \index{document}
\end_inset
with only a few keywords
\begin_inset LatexCommand \index{keywords}
\end_inset
to insert.
But what if your document
\begin_inset LatexCommand \index{document}
\end_inset
has grown to hundreds
\begin_inset LatexCommand \index{hundreds}
\end_inset
of pages, with hundreds (or even thousands) of index entries to insert?
See the Index of the
\begin_inset LatexCommand \url[PHP-Nuke HOWTO]{http://www.karakas-online.de/EN-Book/}
\end_inset
for an example of an Index that cannot be generated manually - unless you
want to drive yourself crazy!
\layout Standard
Clearly, for a comprehensive Index of large documents, an automatic procedure
\begin_inset LatexCommand \index{procedure}
\end_inset
is necessary.
However, the general problem of automatic Index generation is subject of
extensive (and still not conclusive) research
\begin_inset LatexCommand \index{research}
\end_inset
and I am not going to address it in its full generality
\begin_inset LatexCommand \index{generality}
\end_inset
here.
For our purposes, even a semi-automatic
\begin_inset LatexCommand \index{semi-automatic}
\end_inset
procedure
\begin_inset LatexCommand \index{procedure}
\end_inset
would be very helpful.
To this end, I have created the following 4 scripts:
\layout Itemize
\begin_inset LatexCommand \htmlurl[sedscr_list_index_items]{sedscr_list_index_items}
\end_inset
: lists all index entries contained in a LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
document.
\layout Itemize
\begin_inset LatexCommand \htmlurl[sedscr_delete_index_items]{sedscr_delete_index_items}
\end_inset
: deletes all index entries from a LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
document.
\layout Itemize
\begin_inset LatexCommand \htmlurl[awkscr_create_index_items]{awkscr_create_index_items}
\end_inset
: creates a list of words used in a LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
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
\begin_inset LatexCommand \index{document}
\end_inset
and are interesting enough to be part of its Index.
\layout Itemize
\begin_inset LatexCommand \htmlurl[awkscr_insert_index_items]{awkscr_insert_index_items}
\end_inset
: uses an externally supplied document
\begin_inset LatexCommand \index{document}
\end_inset
containing a list of index entries to insert an index entry in a LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
document for every word appearing in that list.
\layout Standard
They can be used in the following semi-automatic
\begin_inset LatexCommand \index{semi-automatic}
\end_inset
Index generation procedure:
\begin_inset LatexCommand \index{procedure}
\end_inset
\layout Enumerate
Optional: create a list of all existing index entries in your document.
\begin_inset LatexCommand \index{document}
\end_inset
This is useful not only because you are going to eliminate
\begin_inset LatexCommand \index{eliminate}
\end_inset
all index entries from the document
\begin_inset LatexCommand \index{document}
\end_inset
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.
\begin_deeper
\layout Standard
To create a list of all existing index entries in your document,
\begin_inset LatexCommand \index{document}
\end_inset
type:
\layout Code
sedscr_list_index_items document.lyx > indexitems
\layout Standard
The generated indexitems
\begin_inset LatexCommand \index{indexitems}
\end_inset
file will contain a list of all index entries in document.
\begin_inset LatexCommand \index{document}
\end_inset
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
\begin_inset LatexCommand \index{awk}
\end_inset
scripts that follow, so don't let it irritate you.
\layout Standard
To get an alphabetically sorted list of index items, without duplicate entries
and with all symbols
\begin_inset LatexCommand \index{symbols}
\end_inset
at the beginning of the list, use the sort and uniq utilities as follows:
\layout Code
cat indexitems | sort | uniq > indexitems.sorted
\layout Code
mv indexitems.sorted indexitems
\end_deeper
\layout Enumerate
Remove all previous index entries from the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
document.
You need this preliminary step because, if you forget to remove already
existing index entries, a subsequent run of the
\begin_inset LatexCommand \htmlurl[awkscr_insert_index_items]{awkscr_insert_index_items}
\end_inset
script may substitute even the existing index terms
\begin_inset LatexCommand \index{terms}
\end_inset
(those already inside the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
\backslash
index commands) with LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
\backslash
index commands.
This may or may not happen, depending on the regular expressions
\begin_inset LatexCommand \index{expressions}
\end_inset
used in the current implementation
\begin_inset LatexCommand \index{implementation}
\end_inset
of
\begin_inset LatexCommand \htmlurl[awkscr_insert_index_items]{awkscr_insert_index_items}
\end_inset
, but it is better to err on the side of caution.
What
\emph on
will
\emph default
happen, however, is that repeated invocations
\begin_inset LatexCommand \index{invocations}
\end_inset
of
\begin_inset LatexCommand \htmlurl[awkscr_insert_index_items]{awkscr_insert_index_items}
\end_inset
will add index entries besides already existing ones.
You will thus end up with a document
\begin_inset LatexCommand \index{document}
\end_inset
that contains double index entries for each index term in your indexitems
\begin_inset LatexCommand \index{indexitems}
\end_inset
file.
\begin_deeper
\layout Standard
Besides, there is another reason why you might want to remove all index
entries from your LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
document: a LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
text cluttered
\begin_inset LatexCommand \index{cluttered}
\end_inset
with index entries may still be a breeze to read for a computer, but quite
a headache
\begin_inset LatexCommand \index{headache}
\end_inset
to read for humans.
\layout Standard
To remove all index entries from a LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
document, type:
\layout Code
sedscr_delete_index_items document.lyx > document-noindexitems.lyx
\layout Standard
The generated document-noindexitems.
lyx
\begin_inset LatexCommand \index{lyx}
\end_inset
will contain everything from document.
\begin_inset LatexCommand \index{document}
\end_inset
lyx - except the index entries.
\end_deeper
\layout Enumerate
Create a list of all index entries to be used in the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
document.
This is the most difficult part: as said above, this problem is not trivial.
\begin_inset LatexCommand \index{trivial}
\end_inset
We will thus content ourselves with a list of all
\emph on
words
\emph default
used in the document.
\begin_inset LatexCommand \index{document}
\end_inset
Once we have all words, we can still edit the list manually and delete
all unwanted entries.
This is what makes this procedure
\begin_inset LatexCommand \index{procedure}
\end_inset
\emph on
semi-automatic
\emph default
and not automatic.
The idea is that it is still better having to delete 10000 lines from a
12000 line document,
\begin_inset LatexCommand \index{document}
\end_inset
than having to insert 2000 index entries from the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
Insert menu.
\begin_deeper
\layout Standard
To create a list of all words used in a LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
document, type:
\layout Code
awkscr_create_index_items document.lyx > words
\layout Standard
There is even some code in
\begin_inset LatexCommand \htmlurl[awkscr_create_index_items]{awkscr_create_index_items}
\end_inset
that checks whether the current word is in some
\begin_inset Quotes eld
\end_inset
trivia
\begin_inset Quotes erd
\end_inset
list of trivial
\begin_inset LatexCommand \index{trivial}
\end_inset
words and discards it.
In such a case, you would call the script with two arguments, as follows:
\layout Code
awkscr_create_index_items trivia document.lyx > words
\layout Standard
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).
\layout Standard
It is a good idea to sort your words alphabetically and delete double entries,
so do:
\layout Code
cat words | sort | uniq > words-unique
\layout Code
mv words-unique words
\layout Standard
Once the list of all words of your document
\begin_inset LatexCommand \index{document}
\end_inset
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
\begin_inset LatexCommand \index{punctuation}
\end_inset
at the end and so on.
This is still hard if your document
\begin_inset LatexCommand \index{document}
\end_inset
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,
\begin_inset LatexCommand \index{document}
\end_inset
which gives me an estimate
\begin_inset LatexCommand \index{estimate}
\end_inset
of 8000 menu selections with the mouse - unfortunately no keyboard bindings
\begin_inset LatexCommand \index{bindings}
\end_inset
were found to work on my system).
\layout Standard
You should delete all lines containing characters that could be interpreted
\begin_inset LatexCommand \index{interpreted}
\end_inset
as metacharacters of regular expressions:
\begin_inset LatexCommand \index{expressions}
\end_inset
*, +, ?, $, &, ^,
\backslash
- and probably many others.
Don't try to escape them, it will not work:
\begin_inset LatexCommand \htmlurl[awkscr_create_index_items]{awkscr_create_index_items}
\end_inset
will replace the correct, string with the
\emph on
escaped
\emph default
string, adding an index entry for the escaped
\begin_inset LatexCommand \index{escaped}
\end_inset
string too! This is not what you will want.
What is rather needed here is a mechanism to search for the escaped
\begin_inset LatexCommand \index{escaped}
\end_inset
string, but replaced it with the verbatim one (i.e.
the string without the escaping backslashes).
This is still work to be done (FIXME).
\layout Standard
Practically, this restriction means that you will have to add your index
entries for symbols
\begin_inset LatexCommand \index{symbols}
\end_inset
like *, +, ?, $, &, ^,
\backslash
manually, each time after you run
\begin_inset LatexCommand \htmlurl[awkscr_create_index_items]{awkscr_create_index_items}
\end_inset
.
\end_deeper
\layout Enumerate
Once you have a file, say indexitems,
\begin_inset LatexCommand \index{indexitems}
\end_inset
with all words that should appear in the Index of a LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
file, type:
\begin_deeper
\layout Code
awkscr_insert_index_items indexitems - < document-noindexitems.lyx > document-ind
exitems.lyx
\layout Standard
to create from document-noindexitems.
lyx
\begin_inset LatexCommand \index{lyx}
\end_inset
a document
\begin_inset LatexCommand \index{document}
\end_inset
with index entries (document-indexitems.lyx) for all words in indexitems.
\begin_inset LatexCommand \index{indexitems}
\end_inset
\end_deeper
\layout SGML
\layout SGML
\layout SGML
Long execution time!
\layout SGML
\layout SGML
\layout SGML
The current implementation of
\begin_inset LatexCommand \htmlurl[awkscr_insert_index_items]{awkscr_insert_index_items}
\end_inset
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!
]]> ]]>
]]> ]]> Inline graphic
\layout SGML
\layout SGML
\layout Standard
Some notes on
\begin_inset LatexCommand \htmlurl[awkscr_insert_index_items]{awkscr_insert_index_items}
\end_inset
's mode of operation:
\layout Itemize
The
\begin_inset Quotes eld
\end_inset
-
\begin_inset Quotes erd
\end_inset
in the above invocation
\begin_inset LatexCommand \index{invocation}
\end_inset
is important: it forces the awk
\begin_inset LatexCommand \index{awk}
\end_inset
script to continue reading from standard input, after it has read indexitems.
\begin_inset LatexCommand \index{indexitems}
\end_inset
This, together with the code
\begin_deeper
\layout Code
FILENAME == "indexitems" {
\layout Code
n++
\layout Code
indexentry[$1] = $1
\layout Code
next
\layout Code
}
\layout Standard
in
\begin_inset LatexCommand \htmlurl[awkscr_insert_index_items]{awkscr_insert_index_items}
\end_inset
, causes the words in indexitems
\begin_inset LatexCommand \index{indexitems}
\end_inset
to be imported into the indexentry[] associative array.
\end_deeper
\layout Itemize
The file separator in
\begin_inset LatexCommand \htmlurl[awkscr_insert_index_items]{awkscr_insert_index_items}
\end_inset
is set to the semicolon
\begin_inset Quotes eld
\end_inset
;
\begin_inset Quotes erd
\end_inset
, instead of the default, which is space.
This makes it possible to enter index entries with more than one words.
Accordingly, the
\begin_inset LatexCommand \htmlurl[awkscr_create_index_items]{awkscr_create_index_items}
\end_inset
script appends a semicolon at the end of each word it prints - you should
leave these untouched!
\layout Itemize
\begin_inset LatexCommand \htmlurl[awkscr_insert_index_items]{awkscr_insert_index_items}
\end_inset
follows a simple algorithm
\begin_inset LatexCommand \index{algorithm}
\end_inset
to insert the index entries at the right places in the document:
\begin_inset LatexCommand \index{document}
\end_inset
to insert an index entry, we have to know what LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
(
\begin_inset LatexCommand \ref{LyX-environments}
\end_inset
) we are in.
In essence, this means we have to parse the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
document.
Since the
\backslash
layout
\begin_inset LatexCommand \index{layout}
\end_inset
commands in the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
file do NOT have what we would call
\begin_inset Quotes eld
\end_inset
closing tags
\begin_inset Quotes erd
\end_inset
in other markup
\begin_inset LatexCommand \index{markup}
\end_inset
languages, we cannot tell awk
\begin_inset LatexCommand \index{awk}
\end_inset
\begin_inset Quotes eld
\end_inset
if you are between the start and the end of the Paragraph environment,
\begin_inset LatexCommand \index{environment}
\end_inset
do the following
\begin_inset Quotes erd
\end_inset
, or anything like that - there is no easy way to find the
\begin_inset Quotes eld
\end_inset
end
\begin_inset Quotes eld
\end_inset
of an environment,
\begin_inset LatexCommand \index{environment}
\end_inset
given all the environment
\begin_inset LatexCommand \index{environment}
\end_inset
nestings that are possible.
Luckily, another easy way exists: whenever a
\backslash
layout
\begin_inset LatexCommand \index{layout}
\end_inset
command is encountered, we are in the environment
\begin_inset LatexCommand \index{environment}
\end_inset
specified by that
\backslash
layout
\begin_inset LatexCommand \index{layout}
\end_inset
command, so we only need to set a variable, call it layout, accordingly:
\begin_deeper
\layout Code
/
\backslash
\backslash
layout SGML/ { layout = "SGML"; print; next }
\layout Code
/
\backslash
\backslash
layout Chapter/ { layout = "Chapter"; print; next }
\layout Code
/
\backslash
\backslash
layout Section/ { layout = "Section"; print; next }
\layout Code
/
\backslash
\backslash
layout Subsection/ { layout = "Subsection"; print; next }
\layout Code
/
\backslash
\backslash
layout Subsubsection/ { layout = "Subsubsection"; print; next }
\layout Code
/
\backslash
\backslash
layout Standard/ { layout = "Standard"; print; next }
\layout Code
\layout Standard
...and so on
\end_deeper
\layout Itemize
Clearly, we should not insert index entries everywhere, e.g.
in the
\begin_inset Quotes eld
\end_inset
Code
\begin_inset Quotes erd
\end_inset
environment.
\begin_inset LatexCommand \index{environment}
\end_inset
That's why we check if we are in the "Standard", "Itemize",
\begin_inset Quotes eld
\end_inset
Enumerate
\begin_inset Quotes erd
\end_inset
, "Quotation"
\begin_inset LatexCommand \index{Quotation}
\end_inset
, "Description" environment
\begin_inset LatexCommand \index{environment}
\end_inset
(warning: the way
\begin_inset LatexCommand \url[sedscr]{sedscr}
\end_inset
works currently, you should not insert index entries in the
\begin_inset Quotes eld
\end_inset
Caption
\begin_inset Quotes erd
\end_inset
environment) and, if we are (and only then), we substiture every word in
the indexentry[] array with the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
\begin_inset Quotes eld
\end_inset
insert index entry
\begin_inset Quotes erd
\end_inset
command:
\begin_deeper
\layout Code
{
\layout Code
if ( ( layout == "Standard" ||
\layout Code
layout == "Itemize" ||
\layout Code
layout == "Enumerate" ||
\layout Code
layout == "Quotation" ||
\layout Code
layout == "Description" ) && ( inset == 0 ) ) {
\layout Code
for (item in indexentry) {
\layout Code
if (gsub(" " item " "," " item "
\backslash
n
\backslash
\backslash
begin_inset LatexCommand
\backslash
\backslash
index{" indexentry[item] "}
\backslash
n
\backslash
n
\backslash
\backslash
end_inset
\backslash
n")) { continue }
\layout Code
else if (gsub("^" item " "," " item "
\backslash
n
\backslash
\backslash
begin_inset LatexCommand
\backslash
\backslash
index{" indexentry[item] "}
\backslash
n
\backslash
n
\backslash
\backslash
end_inset
\backslash
n")) { continue }
\layout Code
else if (gsub(" " item "$"," " item "
\backslash
n
\backslash
\backslash
begin_inset LatexCommand
\backslash
\backslash
index{" indexentry[item] "}
\backslash
n
\backslash
n
\backslash
\backslash
end_inset
\backslash
n")) { continue }
\layout Code
else if (gsub(" " item ":"," " item ":
\backslash
n
\backslash
\backslash
begin_inset LatexCommand
\backslash
\backslash
index{" indexentry[item] "}
\backslash
n
\backslash
n
\backslash
\backslash
end_inset
\backslash
n")) { continue }
\layout Code
else if (gsub(" " item "
\backslash
\backslash
."," " item ".
\backslash
n
\backslash
\backslash
begin_inset LatexCommand
\backslash
\backslash
index{" indexentry[item] "}
\backslash
n
\backslash
n
\backslash
\backslash
end_inset
\backslash
n")) { continue }
\layout Code
else if (gsub(" " item ","," " item ",
\backslash
n
\backslash
\backslash
begin_inset LatexCommand
\backslash
\backslash
index{" indexentry[item] "}
\backslash
n
\backslash
n
\backslash
\backslash
end_inset
\backslash
n")) { continue }
\layout Code
else if (gsub(" " item "
\backslash
\backslash
?"," " item "?
\backslash
n
\backslash
\backslash
begin_inset LatexCommand
\backslash
\backslash
index{" indexentry[item] "}
\backslash
n
\backslash
n
\backslash
\backslash
end_inset
\backslash
n")) { continue }
\layout Code
else if (gsub(" " item ";"," " item ";
\backslash
n
\backslash
\backslash
begin_inset LatexCommand
\backslash
\backslash
index{" indexentry[item] "}
\backslash
n
\backslash
n
\backslash
\backslash
end_inset
\backslash
n")) { continue }
\layout Code
else if (gsub(" " item "
\backslash
n"," " item "
\backslash
n
\backslash
n
\backslash
\backslash
begin_inset LatexCommand
\backslash
\backslash
index{" indexentry[item] "}
\backslash
n
\backslash
n
\backslash
\backslash
end_inset
\backslash
n")) { continue }
\layout Code
else if (gsub(" " "
\backslash
"" item "
\backslash
""," " "
\backslash
"" item "
\backslash
"
\backslash
n
\backslash
\backslash
begin_inset LatexCommand
\backslash
\backslash
index{" indexentry[item] "}
\backslash
n
\backslash
n
\backslash
\backslash
end_inset
\backslash
n")) { continue }
\layout Code
}
\layout Code
{ print; next }
\layout Code
}
\layout Code
}
\end_deeper
\layout Standard
Some tips regarding the (necessary) manual
\begin_inset LatexCommand \index{manual}
\end_inset
editing of the words file, the file output by
\begin_inset LatexCommand \htmlurl[awkscr_create_index_items]{awkscr_create_index_items}
\end_inset
above:
\layout Itemize
Leave the semicolons at the end of each line untouched! They are needed
as record separators in the awk
\begin_inset LatexCommand \index{awk}
\end_inset
scripts.
\layout Itemize
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.
\layout Itemize
You may need to supply some extra terms
\begin_inset LatexCommand \index{terms}
\end_inset
you feel are missing from that file.
Feel free to do this,
\begin_inset LatexCommand \htmlurl[awkscr_insert_index_items]{awkscr_insert_index_items}
\end_inset
does not know how you created the indexitems
\begin_inset LatexCommand \index{indexitems}
\end_inset
file you give it.
\layout Itemize
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
\begin_inset LatexCommand \index{terms}
\end_inset
that really appear somewhere, will make it to the Index, so don't worry
if your list is too long - given enough computing
\begin_inset LatexCommand \index{computing}
\end_inset
time, that is.
\layout Itemize
Take care to delete everything in your word list that looks like a regular
expression with metacharacters - because it will be interpreted
\begin_inset LatexCommand \index{interpreted}
\end_inset
as such, with unpredictable results (unless you really know what you are
doing).
I once had
\begin_inset Quotes eld
\end_inset
.*
\begin_inset Quotes erd
\end_inset
on one line and I forgot to delete it.
I then wondered how come that my document
\begin_inset LatexCommand \index{document}
\end_inset
was full of index entries to
\begin_inset Quotes eld
\end_inset
.*
\begin_inset Quotes erd
\end_inset
while the text was almost gone! See
\begin_inset LatexCommand \url[regular expressions]{http://www.karakas-online.de/EN-Book/regular-expressions.html}
\end_inset
, for a brief introduction to regular expressions.
\begin_inset LatexCommand \index{expressions}
\end_inset
\layout Itemize
Take out any
\begin_inset Quotes eld
\end_inset
:
\begin_inset Quotes erd
\end_inset
,
\begin_inset Quotes eld
\end_inset
;
\begin_inset Quotes erd
\end_inset
,
\begin_inset Quotes eld
\end_inset
?
\begin_inset Quotes erd
\end_inset
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
\begin_inset Quotes eld
\end_inset
pure
\begin_inset Quotes erd
\end_inset
words, without any punctuation
\begin_inset LatexCommand \index{punctuation}
\end_inset
signs.
\layout Itemize
Don't leave in
\begin_inset Quotes eld
\end_inset
config
\begin_inset Quotes erd
\end_inset
if your LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
file contains
\begin_inset Quotes eld
\end_inset
config.php
\begin_inset Quotes erd
\end_inset
.
If you do, the latter will look ugly in the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
editor, as it will contain an index entry for
\begin_inset Quotes eld
\end_inset
config
\begin_inset Quotes erd
\end_inset
just in the middle of it.
This will not affect the rendered formats, however.
\layout Itemize
Don't leave in words that might form parts of a LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
command.
I once left
\begin_inset Quotes eld
\end_inset
Enumerate
\begin_inset Quotes erd
\end_inset
in my word list.
The resulting LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
file contained an index entry for
\begin_inset Quotes eld
\end_inset
Enumerate
\begin_inset Quotes erd
\end_inset
in front of every item in every enumeration list! Clearly, the awk
\begin_inset LatexCommand \index{awk}
\end_inset
script
\begin_inset LatexCommand \htmlurl[awkscr_insert_index_items]{awkscr_insert_index_items}
\end_inset
\begin_inset Quotes eld
\end_inset
sees
\begin_inset Quotes erd
\end_inset
the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
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.
\layout Standard
Finally, there are a few known limitations of the collateindex
\begin_inset LatexCommand \index{collateindex}
\end_inset
script that creates the index (see
\begin_inset LatexCommand \url[Automatic Indexing with the DocBook DSSSL Stylesheets]{http://docbook.sourceforge.net/release/dsssl/current/doc/indexing.html}
\end_inset
:
\layout Itemize
Duplicate page numbers
\begin_inset LatexCommand \index{numbers}
\end_inset
are not suppressed in the index.
If the document
\begin_inset LatexCommand \index{document}
\end_inset
contains three indexing
\begin_inset LatexCommand \index{indexing}
\end_inset
hits on page 4, the generated index will contain 4, 4, 4.
\layout Itemize
Ranges are not automatically
\begin_inset LatexCommand \index{automatically}
\end_inset
constructed.
If the document
\begin_inset LatexCommand \index{document}
\end_inset
contains indexing
\begin_inset LatexCommand \index{indexing}
\end_inset
hits on pages 4, 5, 6, and 7, the generated index will contain 4, 5, 6,
7 instead of 4-7.
\layout Section
The final step: invoking lyxtox
\begin_inset LatexCommand \label{lyxtox}
\end_inset
\layout Standard
If you have followed all the above, your working directory should now contain:
\layout Code
awkscr_create_index_items
\layout Code
awkscr_insert_index_items
\layout Code
awkscr_math
\layout Code
awkscr_refdb_html
\layout Code
awkscr_refdb_print
\layout Code
ck-style.css
\layout Code
images
\layout Code
jadetex.cfg
\layout Code
lyxtox
\layout Code
lyxtox-html.dsl
\layout Code
lyxtox-onehtml.dsl
\layout Code
lyxtox-print.dsl
\layout Code
lyxtox-print-howto.dsl
\layout Code
lyxtox-print-pdf.dsl
\layout Code
lyxtox-print-ps.dsl
\layout Code
lyxtox-print-rtf.dsl
\layout Code
lyxtox-print-txt.dsl
\layout Code
sedscr
\layout Code
sedscr_abi
\layout Code
sedscr_app
\layout Code
sedscr_bib
\layout Code
sedscr_delete_index_items
\layout Code
sedscr_list_index_items
\layout Code
sedscr_math
\layout Code
sedscr_ris
\layout Code
sedscr_top
\layout Code
sedscr_val
\layout Standard
Now, to create all the other formats from your LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
source, you just call
\begin_inset LatexCommand \url[lyxtox]{./lyxtox}
\end_inset
with one argument: the name of your \SpecialChar \@.
lyx
\begin_inset LatexCommand \index{lyx}
\end_inset
file
\emph on
without
\emph default
the \SpecialChar \@.
lyx
\begin_inset LatexCommand \index{lyx}
\end_inset
ending:
\layout Code
lyxtox myTemplate
\layout SGML
It's time for a cup of coffee now.
Relax while your computer is busy creating a whole bunch of nice formatted
documents.
]]>
]]> ]]>
]]> Inline graphic
\layout Standard
For a detailed explanation of what is going behind the scenes, see
\begin_inset LatexCommand \ref{explain-magic}
\end_inset
.
\layout Standard
Now, let's see a more realistic example: the creation of the
\begin_inset LatexCommand \url[GNU/Linux Command-Line Tools Summary HowTo]{http://www.karakas-online.de/gnu-linux-tools-summary/}
\end_inset
.
This HowTo is an attempt to provide a comprehensive summary of useful command-l
ine tools
\begin_inset LatexCommand \index{tools}
\end_inset
available to a GNU/Linux based operating
\begin_inset LatexCommand \index{operating}
\end_inset
system, i.e.
commands needed by the majority of users.
The document
\begin_inset LatexCommand \index{document}
\end_inset
is authored by Gareth Anderson and I assist him in the document conversion
process.
So, how do I go about such a project?
\layout Standard
Here's how
\begin_inset Foot
collapsed false
\layout Standard
See also
\begin_inset LatexCommand \url[How to correctly invoke the lyxtox script]{http://www.karakas-online.de/forum/viewtopic.php?t=3846}
\end_inset
.
\end_inset
:
\layout Standard
My home directory is /home/chris.
This is not my working directory for a lyxtox
\begin_inset LatexCommand \index{lyxtox}
\end_inset
project.
A working directory is, say, myLinuxCommands, beneath my home directory.
That is, I create a working directory specific to a project.
In our case, let's say this is /home/chris/myLinuxCommands.
\layout Standard
Now, I change to the working directory and make sure I have all files mentioned
above.
These are at least
\layout Code
awkscr_create_index_items
\layout Code
awkscr_insert_index_items
\layout Code
awkscr_math
\layout Code
awkscr_refdb_html
\layout Code
awkscr_refdb_print
\layout Code
ck-style.css
\layout Code
images
\layout Code
jadetex.cfg
\layout Code
lyxtox
\layout Code
lyxtox-html.dsl
\layout Code
lyxtox-onehtml.dsl
\layout Code
lyxtox-print.dsl
\layout Code
lyxtox-print-howto.dsl
\layout Code
lyxtox-print-pdf.dsl
\layout Code
lyxtox-print-ps.dsl
\layout Code
lyxtox-print-rtf.dsl
\layout Code
lyxtox-print-txt.dsl
\layout Code
sedscr
\layout Code
sedscr_abi
\layout Code
sedscr_app
\layout Code
sedscr_bib
\layout Code
sedscr_delete_index_items
\layout Code
sedscr_list_index_items
\layout Code
sedscr_math
\layout Code
sedscr_ris
\layout Code
sedscr_top
\layout Code
sedscr_val
\layout Code
sedscr_ima
\layout Code
sedscr_apa
\layout Standard
and may well have forgotten others (please tell me if I have).
I copy these files from yet another directory in my home, where I have
extracted a pristine copy of mySGML.tar.gz.
\layout Standard
So now I have created the files
\layout Code
/home/chris/myLinuxCommands/awkscr_create_index_items
\layout Code
/home/chris/myLinuxCommands/awkscr_insert_index_items
\layout Code
/home/chris/myLinuxCommands/awkscr_math
\layout Code
/home/chris/myLinuxCommands/awkscr_refdb_html
\layout Code
/home/chris/myLinuxCommands/awkscr_refdb_print
\layout Code
/home/chris/myLinuxCommands/ck-style.css
\layout Code
/home/chris/myLinuxCommands/images
\layout Code
/home/chris/myLinuxCommands/jadetex.cfg
\layout Code
/home/chris/myLinuxCommands/lyxtox
\layout Code
/home/chris/myLinuxCommands/lyxtox-html.dsl
\layout Code
/home/chris/myLinuxCommands/lyxtox-onehtml.dsl
\layout Code
/home/chris/myLinuxCommands/lyxtox-print.dsl
\layout Code
/home/chris/myLinuxCommands/lyxtox-print-howto.dsl
\layout Code
/home/chris/myLinuxCommands/lyxtox-print-pdf.dsl
\layout Code
/home/chris/myLinuxCommands/lyxtox-print-ps.dsl
\layout Code
/home/chris/myLinuxCommands/lyxtox-print-rtf.dsl
\layout Code
/home/chris/myLinuxCommands/lyxtox-print-txt.dsl
\layout Code
/home/chris/myLinuxCommands/sedscr
\layout Code
/home/chris/myLinuxCommands/sedscr_abi
\layout Code
/home/chris/myLinuxCommands/sedscr_app
\layout Code
/home/chris/myLinuxCommands/sedscr_bib
\layout Code
/home/chris/myLinuxCommands/sedscr_delete_index_items
\layout Code
/home/chris/myLinuxCommands/sedscr_list_index_items
\layout Code
/home/chris/myLinuxCommands/sedscr_math
\layout Code
/home/chris/myLinuxCommands/sedscr_ris
\layout Code
/home/chris/myLinuxCommands/sedscr_top
\layout Code
/home/chris/myLinuxCommands/sedscr_val
\layout Code
/home/chris/myLinuxCommands/sedscr_ima
\layout Code
/home/chris/myLinuxCommands/sedscr_apa
\layout Standard
as exact copies of the original ones (which are, as I said, in some other
directory).
\layout Standard
Now, in the /home/chris/myLinuxCommands directory, I create (or copy) the
LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
file that I want to process.
In our case, this is the gnu-linux-tools-summary.lyx file, together with
bibliography.
\begin_inset LatexCommand \index{bibliography}
\end_inset
lyx
\begin_inset LatexCommand \index{bibliography.lyx}
\end_inset
and appendix.
\begin_inset LatexCommand \index{appendix}
\end_inset
lyx.
In other cases, the bibliography.
\begin_inset LatexCommand \index{bibliography}
\end_inset
lyx
\begin_inset LatexCommand \index{bibliography.lyx}
\end_inset
and appendix.
\begin_inset LatexCommand \index{appendix}
\end_inset
lyx are not needed, so they are not there.
\layout Standard
I change to the /home/chris/myLinuxCommands directory, which, as I said,
is the working directory for the specific project in our example.
Since my LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
file is gnu-linux-tools-summary.lyx, I call lyxtox
\begin_inset LatexCommand \index{lyxtox}
\end_inset
with the basename
\begin_inset LatexCommand \index{basename}
\end_inset
of gnu-linux-tools-summary.lyx, i.e.
with "gnu-linux-tools-summary", as its first and only parameter:
\begin_inset LatexCommand \index{parameter}
\end_inset
\layout Code
lyxtox gnu-linux-tools-summary
\layout Standard
The name of the parameter
\begin_inset LatexCommand \index{parameter}
\end_inset
is $1 in the lyxtox
\begin_inset LatexCommand \index{lyxtox}
\end_inset
script.
\layout Standard
(Of cource, I have taken care to adjust all parameters at the start of lyxtox
\begin_inset LatexCommand \index{lyxtox}
\end_inset
to my situation, as described in
\begin_inset LatexCommand \ref{required-preliminary-steps}
\end_inset
).
\layout Standard
If all goes well, I get another directory inside my working directory, named
exactly as the parameter
\begin_inset LatexCommand \index{parameter}
\end_inset
of the script, in our case gnu-linux-tools-summary.
Everything I need is there: the one, big HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
file, the many HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
files ("chunks"), the PDF,
\begin_inset LatexCommand \index{PDF}
\end_inset
PS.
\begin_inset LatexCommand \index{PS}
\end_inset
GZ, TXT
\begin_inset LatexCommand \index{TXT}
\end_inset
files, the images directory, the math
\begin_inset LatexCommand \index{math}
\end_inset
directory...simply everything.
I can just tar the whole directory, upload it to my web site, extract it
and I will have the whole project there!
\layout SGML
Indeed, it is here:
\begin_inset LatexCommand \url[http://www.karakas-online.de/gnu-linux-tools-summary/]{http://www.karakas-online.de/gnu-linux-tools-summary/}
\end_inset
.
]]>
]]> ]]> ]]> Inline graphic
\layout Standard
Thus http://www.karakas-online.de/gnu-linux-tools-summary is an exact copy
of my local /home/chris/myLinuxCommands/gnu-linux-tools-summary, as created
by the lyxtox
\begin_inset LatexCommand \index{lyxtox}
\end_inset
invocation
\begin_inset LatexCommand \index{invocation}
\end_inset
\layout Code
lyxtox gnu-linux-tools-summary
\layout SGML
\layout SGML
\layout SGML
Notice that you are supposed to have an "images" directory inside your working
directory.
Mine is /home/chris/myLinuxCommands/images.
\layout SGML
When you run lyxtox with "gnu-linux-tools-summary" as parameter, you get
another one: /home/chris/myLinuxCommands/gnu-linux-tools-summary/images.
This is perfectly OK: it is a copy of the original images directory.
It is done this way, so that you only need to copy the gnu-linux-tools-summary
to your website and be up and running without needing anything else.
\layout SGML
\layout SGML
\layout Chapter
Errors and warnings
\begin_inset LatexCommand \label{errors-and-warnings}
\end_inset
\layout Standard
There will be some errors and warnings.
However, many of them are not crucial (or even avoidable) and can be safely
ignored.
Some day, in a perfect world, where all involved programs and languages
will work perfectly with each other, these errors will disappear.
Until then, you must learn to live with them.
\layout Standard
Here are some examples of possible errors:
\layout Section
LyX errors
\begin_inset LatexCommand \label{lyx-errors}
\end_inset
\layout Description
text\SpecialChar ~
class\SpecialChar ~
not\SpecialChar ~
available: If you get:
\begin_deeper
\layout Code
The document uses an unknown textclass "docbook-book".
LyX wil not be able to format output correctly
\layout Standard
do "Layout-->Document" on any LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
document you have and then, in the window that will appear, check the classes
available under "Class".
You should see all the above classes you listed, especially the "DocBook
book (SGML)" class
\begin_inset LatexCommand \index{class}
\end_inset
I use.
You should see something like:
\layout Code
+checking for docbook class docbook-algo...
yes
\layout Code
+checking for docbook class docbook-book...
yes
\layout Code
+checking for docbook class docbook-chapter...
yes
\layout Code
+checking for docbook class docbook...
yes
\layout Code
+checking for docbook class docbook-section...
yes
\layout Standard
If not, then somehow the reconfigure
\begin_inset LatexCommand \index{reconfigure}
\end_inset
command above (see
\begin_inset LatexCommand \ref{reconfigure-LyX}
\end_inset
) did not find all your classes.
\end_deeper
\layout Section
Openjade errors
\begin_inset LatexCommand \label{openjade-errors}
\end_inset
\layout Description
DTDDECL\SpecialChar ~
catalog\SpecialChar ~
entries\SpecialChar ~
are\SpecialChar ~
not\SpecialChar ~
supported: Jade
\begin_inset LatexCommand \index{Jade}
\end_inset
does not support the
\begin_inset LatexCommand \url[DTDDECL]{http://docbook.org/tdg/en/html/ch02.html#s-catalog-files}
\end_inset
catalog
\begin_inset LatexCommand \index{catalog}
\end_inset
directive
\begin_inset LatexCommand \index{directive}
\end_inset
and it complains loudly if it encounters one.
You may safely ignore this warning.
See
\begin_inset LatexCommand \url[here]{http://docbook.org/tdg/en/html/appa.html#d0e279037}
\end_inset
for more details.
\layout Description
xref\SpecialChar ~
to\SpecialChar ~
ANCHOR\SpecialChar ~
unsupported: This seems to be a Jade/Docbook problem and not
a LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
one.
LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
is capable of inserting cross-references to arbitrary positions in a text.
For this purpose, it creates an anchor
\begin_inset LatexCommand \index{anchor}
\end_inset
with the id tag aproppriately set in the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
file:
\begin_deeper
\layout Code
\layout Standard
The cross-reference
\begin_inset LatexCommand \index{cross-reference}
\end_inset
itself is placed with the xref
\begin_inset LatexCommand \index{xref}
\end_inset
element:
\begin_inset LatexCommand \index{element}
\end_inset
\layout Code
\layout Standard
The error means that this mechanism of cross-referencing
\begin_inset LatexCommand \index{cross-referencing}
\end_inset
is unsupported.
This is why I change
\layout Code
\layout Standard
to
\layout Code
\layout Standard
with sed (see
\begin_inset LatexCommand \ref{run-sed-awk-scripts}
\end_inset
).
This way, at least cross-references to sections created by LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
will work in SGML.
\begin_inset LatexCommand \index{SGML}
\end_inset
\end_deeper
\layout Description
value\SpecialChar ~
of\SpecialChar ~
attribute\SpecialChar ~
"LINKEND"\SpecialChar ~
must\SpecialChar ~
be\SpecialChar ~
a\SpecialChar ~
single\SpecialChar ~
token: the label
\begin_inset LatexCommand \index{label}
\end_inset
you used for a section contains spaces.
Change spaces to, say, underscores or dashes.
\layout Description
value\SpecialChar ~
of\SpecialChar ~
attribute\SpecialChar ~
"ID"\SpecialChar ~
must\SpecialChar ~
be\SpecialChar ~
a\SpecialChar ~
single\SpecialChar ~
token: you used a cross-reference
\begin_inset LatexCommand \index{cross-reference}
\end_inset
to a label
\begin_inset LatexCommand \index{label}
\end_inset
that contains spaces.
Do not change the cross-reference.
\begin_inset LatexCommand \index{cross-reference}
\end_inset
Change the label:
\begin_inset LatexCommand \index{label}
\end_inset
change spaces to, say, underscores or dashes.
\layout Description
end\SpecialChar ~
tag\SpecialChar ~
for\SpecialChar ~
"SECT3"\SpecialChar ~
which\SpecialChar ~
is\SpecialChar ~
not\SpecialChar ~
finished: You probably have an empty subsubsection,
\begin_inset LatexCommand \index{subsubsection}
\end_inset
e\SpecialChar \@.
g\SpecialChar \@.
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???
\layout Description
end\SpecialChar ~
tag\SpecialChar ~
for\SpecialChar ~
element\SpecialChar ~
"LISTITEM"\SpecialChar ~
which\SpecialChar ~
is\SpecialChar ~
not\SpecialChar ~
open: this may be a bug of LyX' SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
generation.
It happens when in an itemize
\begin_inset LatexCommand \index{itemize}
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
you use a higher depth, possibly with nested
\begin_inset LatexCommand \index{nested}
\end_inset
item lists and subsequent paragraphs that you want to be on the same identation
\begin_inset LatexCommand \index{identation}
\end_inset
level as the outer item.
Not critical.
\layout Description
"keep-with-next:"\SpecialChar ~
is\SpecialChar ~
not\SpecialChar ~
a\SpecialChar ~
valid\SpecialChar ~
keyword\SpecialChar ~
in\SpecialChar ~
a\SpecialChar ~
make\SpecialChar ~
expression\SpecialChar ~
for\SpecialChar ~
flow\SpecialChar ~
object\SpecialChar ~
class\SpecialChar ~
"paragraph
": Didn't track
\begin_inset LatexCommand \index{track}
\end_inset
it down, but seems harmless.
\layout Description
value\SpecialChar ~
of\SpecialChar ~
attribute\SpecialChar ~
"FORMAT"\SpecialChar ~
cannot\SpecialChar ~
be\SpecialChar ~
"PDF": Openjade
\begin_inset LatexCommand \index{Openjade}
\end_inset
tell us:
\begin_deeper
\layout Quotation
must be one of "BMP"
\begin_inset LatexCommand \index{BMP}
\end_inset
, "CGM-CHAR"
\begin_inset LatexCommand \index{CGM-CHAR}
\end_inset
, "CGM-BINARY", "CGM-CLEAR", "DITROFF"
\begin_inset LatexCommand \index{DITROFF}
\end_inset
, "DVI"
\begin_inset LatexCommand \index{DVI}
\end_inset
, "EPS"
\begin_inset LatexCommand \index{EPS}
\end_inset
, "EQN"
\begin_inset LatexCommand \index{EQN}
\end_inset
, "FAX"
\begin_inset LatexCommand \index{FAX}
\end_inset
, "GIF"
\begin_inset LatexCommand \index{GIF}
\end_inset
, "GIF87A", "GIF89A", "JPG"
\begin_inset LatexCommand \index{JPG}
\end_inset
, "JPEG"
\begin_inset LatexCommand \index{JPEG}
\end_inset
, "IGES", "PCX"
\begin_inset LatexCommand \index{PCX}
\end_inset
, "PIC", "PNG"
\begin_inset LatexCommand \index{PNG}
\end_inset
, "PS"
\begin_inset LatexCommand \index{PS}
\end_inset
, "SGML"
\begin_inset LatexCommand \index{SGML}
\end_inset
, "TBL", "TEX", "TIFF"
\begin_inset LatexCommand \index{TIFF}
\end_inset
, "WMF", "WPG"
\begin_inset LatexCommand \index{WPG}
\end_inset
, "LINESPECIFIC"
\layout Standard
this means that the list of accepted formats does not contain
\begin_inset Quotes eld
\end_inset
PDF
\begin_inset Quotes erd
\end_inset
.
Such a list appears in the following files:
\layout Itemize
/usr/share/sgml/db3xml/dbnotnx.mod
\layout Itemize
/usr/share/sgml/docbk30/docbook.dtd
\layout Itemize
/usr/share/sgml/docbook_3/dbnotn.mod
\layout Itemize
/usr/share/sgml/sdb/sdocbook.dtd
\layout Itemize
/usr/share/sgml/db41xml/dbnotnx.mod
\layout Itemize
/usr/share/sgml/docbook_4/dbnotn.mod
\layout Standard
Given that LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
produces a SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
file containing
\layout Code
\layout Standard
If you still use LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
v.1.1.x, you should change /usr/share/sgml/docbook_3/dbnotn.mod to include
\begin_inset Quotes eld
\end_inset
PDF
\begin_inset Quotes erd
\end_inset
in the list of accepted file extensions:
\begin_inset LatexCommand \index{extensions}
\end_inset
\layout Code
\layout Standard
Also, in the dbparam.dsl
\begin_inset LatexCommand \index{dbparam.dsl}
\end_inset
file for the print formats (located in /usr/share/sgml/docbook/docbook-dsssl-sty
lesheets-1.72/print/dbparam.dsl on my system), zou would need to add
\begin_inset Quotes eld
\end_inset
pdf
\begin_inset Quotes erd
\end_inset
to the list of allowed graphic extensions:
\begin_inset LatexCommand \index{extensions}
\end_inset
\layout Code
(define %graphic-extensions%
\layout Code
;; REFENTRY graphic-extensions
\layout Code
;; PURP List of graphic filename extensions
\layout Code
;; DESC
\layout Code
;; The list of extensions which may appear on a 'fileref'
\layout Code
;; on a 'Graphic' which are indicative of graphic formats.
\layout Code
;;
\layout Code
;; Filenames that end in one of these extensions will not have
\layout Code
;; the '%graphic-default-extension%' added to them.
\layout Code
;; /DESC
\layout Code
;; AUTHOR N/A
\layout Code
;; /REFENTRY
\layout Code
'("eps" "epsf" "gif" "tif" "tiff" "jpg" "jpeg" "png" "pdf" "tex"))
\layout Code
\layout Standard
However, this is not necessary, since we use the technique of
\begin_inset Quotes eld
\end_inset
customization
\begin_inset LatexCommand \index{customization}
\end_inset
layers
\begin_inset Quotes erd
\end_inset
(see
\begin_inset LatexCommand \ref{explain-DSSSL-stylesheets}
\end_inset
) and define %graphic-extensions%
\begin_inset LatexCommand \index{%graphic-extensions%}
\end_inset
in
\begin_inset LatexCommand \url[lyxtox-print.dsl]{lyxtox-print.dsl}
\end_inset
as shown above.
Due to the nature of the DSSSL
\begin_inset LatexCommand \index{DSSSL}
\end_inset
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.
\end_deeper
\layout Description
Reference\SpecialChar ~
`4'\SpecialChar ~
on\SpecialChar ~
page\SpecialChar ~
1\SpecialChar ~
undefined\SpecialChar ~
on\SpecialChar ~
input\SpecialChar ~
line\SpecialChar ~
180: Some cross-refernce
\begin_inset LatexCommand \index{cross-refernce}
\end_inset
you use is probably misspelled.
\begin_inset LatexCommand \index{misspelled}
\end_inset
But this is somewhat difficult to achieve with LyX,
\begin_inset LatexCommand \index{LyX}
\end_inset
since LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
provides you with a list of all the labels currently available for cross-referen
cing.
\begin_inset LatexCommand \index{cross-referencing}
\end_inset
The other occasion where you will see this error is in the first (or even
second?) invocation
\begin_inset LatexCommand \index{invocation}
\end_inset
of LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
for a particular format.
You need at least 3 LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
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.
\begin_inset LatexCommand \index{cross-reference}
\end_inset
\layout Description
LaTeX_Font_Warning:\SpecialChar ~
Some\SpecialChar ~
font\SpecialChar ~
shapes\SpecialChar ~
were\SpecialChar ~
not\SpecialChar ~
available,\SpecialChar ~
defaults\SpecialChar ~
substituted: If
you installed the Computern Modern fonts,
\begin_inset LatexCommand \index{fonts}
\end_inset
you probably don't need to worry about this error.
If you check the fonts
\begin_inset LatexCommand \index{fonts}
\end_inset
used in the PDF
\begin_inset LatexCommand \index{PDF}
\end_inset
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.
\begin_inset LatexCommand \index{fonts}
\end_inset
That's O.K.
for me.
\layout Description
Overfull\SpecialChar ~
\backslash
hbox\SpecialChar ~
(30.17416pt\SpecialChar ~
too\SpecialChar ~
wide)\SpecialChar ~
in\SpecialChar ~
paragraph\SpecialChar ~
at\SpecialChar ~
lines\SpecialChar ~
5425--5425: You will get dozens
of this.
It is a typical LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
warning informing you that a line got some points too wide (mostly because
there was some word that LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
could not hyphenate).
Read the LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
documentation for this (but only if you want to produce a really perfect
PDF
\begin_inset LatexCommand \index{PDF}
\end_inset
document).
\layout Description
/usr/share/sgml/stylesheets/sgmltools/print.dsl:53:6:E:\SpecialChar ~
3rd\SpecialChar ~
argument\SpecialChar ~
for\SpecialChar ~
primitive\SpecialChar ~
"st
ring-append"\SpecialChar ~
of\SpecialChar ~
wrong\SpecialChar ~
type:\SpecialChar ~
"#f"\SpecialChar ~
not\SpecialChar ~
a\SpecialChar ~
string: This is probably caused because
%graphic-default-extension%
\begin_inset LatexCommand \index{%graphic-default-extension%}
\end_inset
is set to
\begin_inset Quotes eld
\end_inset
false
\begin_inset Quotes erd
\end_inset
(
\begin_inset Quotes eld
\end_inset
#f
\begin_inset Quotes erd
\end_inset
), while in
\begin_inset LatexCommand \url[lyxtox-print.dsl]{lyxtox-print.dsl}
\end_inset
we try to concatenate the %admon-graphics-path%,
\begin_inset LatexCommand \index{%admon-graphics-path%}
\end_inset
the name of the admonition
\begin_inset LatexCommand \index{admonition}
\end_inset
and %graphic-default-extension%
\begin_inset LatexCommand \index{%graphic-default-extension%}
\end_inset
to a full name of the admonition
\begin_inset LatexCommand \index{admonition}
\end_inset
graphic.
It is harmless, due to the way we use the graphics (see
\begin_inset LatexCommand \ref{explain-figures}
\end_inset
).
\layout Description
Warning:\SpecialChar ~
Version\SpecialChar ~
of\SpecialChar ~
thumbpdf.tex'\SpecialChar ~
does\SpecialChar ~
not\SpecialChar ~
match\SpecialChar ~
with\SpecialChar ~
perl\SpecialChar ~
script!: thumbpdf
\begin_inset LatexCommand \index{thumbpdf}
\end_inset
complains even if the version is a newer one:
\begin_deeper
\layout Code
*** make `thumbpdf.pdf' / run pdfTeX ***
\layout Code
!!! Warning: Version of `thumbpdf.tex' does not match with perl script!
\layout Code
Current `thumbpdf.tex': 2002/05/26 v3.2
\layout Code
Please install version: 2001/01/12 v2.8
\layout Standard
But if you have the newest version, as in the above case, there is no need
to worry about this error.
\end_deeper
\layout Description
end\SpecialChar ~
tag\SpecialChar ~
for\SpecialChar ~
"SECT1"\SpecialChar ~
which\SpecialChar ~
is\SpecialChar ~
not\SpecialChar ~
finished: You may see this openjade
\begin_inset LatexCommand \index{openjade}
\end_inset
error also for
\begin_inset Quotes eld
\end_inset
SECT2
\begin_inset Quotes erd
\end_inset
,
\begin_inset Quotes eld
\end_inset
SECT3
\begin_inset Quotes erd
\end_inset
and so forth.
This may come up if you have written just the title of the section, subsection
\begin_inset LatexCommand \index{subsection}
\end_inset
or subsubsection
\begin_inset LatexCommand \index{subsubsection}
\end_inset
respectively, but you did not enter any text there.
Just enter something, even a single word like
\begin_inset Quotes eld
\end_inset
FIXME
\begin_inset Quotes erd
\end_inset
(author's note to himself: this is a literal FIXME,
\begin_inset LatexCommand \index{FIXME}
\end_inset
not a meta-FIXME!), to remind you of the missing text, and the error should
go away.
\layout Description
document\SpecialChar ~
type\SpecialChar ~
does\SpecialChar ~
not\SpecialChar ~
allow\SpecialChar ~
element\SpecialChar ~
"SECT2"\SpecialChar ~
here: This is a similar error to the
previous one.
You most probably created a subsection
\begin_inset LatexCommand \index{subsection}
\end_inset
which is not contained in a section, but is dircetly contained in a chapter.
Similar errors will occur if you ommit environment
\begin_inset LatexCommand \index{environment}
\end_inset
levels that are
\begin_inset Quotes eld
\end_inset
in between
\begin_inset Quotes erd
\end_inset
the current one and its parent.
\layout Description
length\SpecialChar ~
of\SpecialChar ~
name\SpecialChar ~
token\SpecialChar ~
must\SpecialChar ~
not\SpecialChar ~
exceed\SpecialChar ~
NAMELEN\SpecialChar ~
(44): You have an ID
\begin_inset LatexCommand \index{ID}
\end_inset
on the line where this error comes up - and this ID
\begin_inset LatexCommand \index{ID}
\end_inset
is too long, longer than NAMELEN, which is 44 in my case.
Use a shorter ID.
\begin_inset LatexCommand \index{ID}
\end_inset
What in SGL comes as the ID
\begin_inset LatexCommand \index{ID}
\end_inset
of a chapter, section, figure or table, in LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
it is a label.
\begin_inset LatexCommand \index{label}
\end_inset
Thus you should check your labels and make sure they are not longer than
44 characters.
\begin_deeper
\layout Standard
Alternatively, change the value of NAMELEN in the file pointed to by the
SGMDCL directive
\begin_inset LatexCommand \index{directive}
\end_inset
in your catalog
\begin_inset LatexCommand \index{catalog}
\end_inset
files: The
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
script uses, among others, the following catalog:
\begin_inset LatexCommand \index{catalog}
\end_inset
/usr/share/sgml/CATALOG.docbook-dsssl-stylesheets.
You can see this in the line:
\layout Code
SGML_CATALOG_FILES="$SGML_CATALOG_FILES: /usr/share/sgml/CATALOG.docbook-dsssl-st
ylesheets"
\layout Standard
In this catalog,
\begin_inset LatexCommand \index{catalog}
\end_inset
I have changed the SGMLDECL line from:
\layout Code
-- SGMLDECL "dtds/decls/docbook.dcl" --
\layout Standard
to
\layout Code
SGMLDECL "/usr/share/sgml/docbook/docbook-dsssl-stylesheets/dtds/decls/docbook.dc
l"
\layout Standard
to reflect the correct path
\begin_inset LatexCommand \index{path}
\end_inset
to the DocBook
\begin_inset LatexCommand \index{DocBook}
\end_inset
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.
\begin_inset Foot
collapsed false
\layout Standard
Note that this may be specific to SuSE 9.0.
Other distributions may have corrected it.
\end_inset
docbook/docbook-dsssl-stylesheets/dtds/decls/docbook.dcl.
There, change
\layout Code
QUANTITY SGMLREF
\layout Code
ATTCNT 256
\layout Code
GRPCNT 253
\layout Code
GRPGTCNT 253
\layout Code
LITLEN 8092
\layout Code
NAMELEN 44
\layout Code
TAGLVL 100
\layout Standard
to, for example:
\layout Code
QUANTITY SGMLREF
\layout Code
ATTCNT 256
\layout Code
GRPCNT 253
\layout Code
GRPGTCNT 253
\layout Code
LITLEN 8092
\layout Code
NAMELEN 64
\layout Code
TAGLVL 100
\layout Code
\layout Standard
See the error 'character\SpecialChar ~
"_"\SpecialChar ~
is_not\SpecialChar ~
allowed\SpecialChar ~
in\SpecialChar ~
the\SpecialChar ~
value\SpecialChar ~
of\SpecialChar ~
attribute\SpecialChar ~
"ID"' below
for more changes you might need to make in the DocBook
\begin_inset LatexCommand \index{DocBook}
\end_inset
declaration file.
\end_deeper
\layout Description
character\SpecialChar ~
":"\SpecialChar ~
is_not\SpecialChar ~
allowed\SpecialChar ~
in\SpecialChar ~
the\SpecialChar ~
value\SpecialChar ~
of\SpecialChar ~
attribute\SpecialChar ~
"ID": You have a LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
label
\begin_inset LatexCommand \index{label}
\end_inset
that contains
\begin_inset Quotes eld
\end_inset
:
\begin_inset Quotes erd
\end_inset
.
Delete the
\begin_inset Quotes eld
\end_inset
:
\begin_inset Quotes erd
\end_inset
, as the label
\begin_inset LatexCommand \index{label}
\end_inset
of a chapter, section, figure, table etc.
is going to be the ID
\begin_inset LatexCommand \index{ID}
\end_inset
of that element
\begin_inset LatexCommand \index{element}
\end_inset
and
\begin_inset Quotes eld
\end_inset
:
\begin_inset Quotes erd
\end_inset
is not allowed in IDs.
However, this only the short answer.
For an in-depth explanation, see the next item.
\layout Description
character\SpecialChar ~
"_"\SpecialChar ~
is_not\SpecialChar ~
allowed\SpecialChar ~
in\SpecialChar ~
the\SpecialChar ~
value\SpecialChar ~
of\SpecialChar ~
attribute\SpecialChar ~
"ID": You have a LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
label
\begin_inset LatexCommand \index{label}
\end_inset
that contains
\begin_inset Quotes eld
\end_inset
_
\begin_inset Quotes erd
\end_inset
.
Delete the
\begin_inset Quotes eld
\end_inset
_
\begin_inset Quotes erd
\end_inset
, as the label
\begin_inset LatexCommand \index{label}
\end_inset
of a chapter, section, figure, table etc.
is going to be the ID
\begin_inset LatexCommand \index{ID}
\end_inset
of that element
\begin_inset LatexCommand \index{element}
\end_inset
and
\begin_inset Quotes eld
\end_inset
_
\begin_inset Quotes erd
\end_inset
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
\begin_inset LatexCommand \url[Allowed characters in element id's]{http://www.biglist.com/lists/dssslist/archives/199804/msg00175.html}
\end_inset
!
\begin_deeper
\layout Standard
The characters allowed in an ID
\begin_inset LatexCommand \index{ID}
\end_inset
are those allowed in an SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
"NAME".
The characters that are allowed to appear in
\begin_inset Quotes eld
\end_inset
names
\begin_inset Quotes erd
\end_inset
in SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
(the id attribute
\begin_inset LatexCommand \index{attribute}
\end_inset
is defined in SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
as such a
\begin_inset Quotes eld
\end_inset
NAME
\begin_inset Quotes erd
\end_inset
) are set in what is known as the
\begin_inset Quotes eld
\end_inset
SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
declaration
\begin_inset LatexCommand \url[SGML declaration]{http://home.chello.no/~mgrsby/sgmlintr/sgmldec.htm}
\end_inset
\begin_inset Quotes erd
\end_inset
of your document.
\begin_inset LatexCommand \index{document}
\end_inset
By default, the first character must be a letter, and any other characters
may be a letter or a digit.
\layout Standard
You can add to this by specifying the additional characters in your SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
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
\begin_inset LatexCommand \index{SGML}
\end_inset
standard itself that adds "." and "-" as "name" characters (but not as "name
start" characters).
This is what's used in the DocBook
\begin_inset LatexCommand \index{DocBook}
\end_inset
SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
Declaration, docbook.dcl.
\layout Standard
The specific portion of the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
Declaration of interest here is the "naming rules".
Jade's default inferred SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
Declaration uses the same naming rules
\begin_inset LatexCommand \index{rules}
\end_inset
as SGML's "Reference Concrete Syntax".
To allow underscores in entity
\begin_inset LatexCommand \index{entity}
\end_inset
names (and other SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
names), you need to supply an SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
Declaration that includes the underscore character.
Using the DocBook
\begin_inset LatexCommand \index{DocBook}
\end_inset
SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
Declaration as an example, you need to add "_" to the LCNMSTRT and UCNMSTRT
parameters:
\layout Code
NAMING
\layout Code
LCNMSTRT ""
\layout Code
UCNMSTRT ""
\layout Code
LCNMCHAR ".-"
\layout Code
UCNMCHAR ".-"
\layout Code
NAMECASE
\layout Code
GENERAL YES
\layout Code
ENTITY NO
\layout Standard
The NAMING portion specifies both uppercase and lowercase forms of the additiona
l "name start" and "name" characters (since names are folded to uppercase
when the "GENERAL" parameter
\begin_inset LatexCommand \index{parameter}
\end_inset
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.
\layout Standard
You can reference your SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
Declaration by including it in the Jade
\begin_inset LatexCommand \index{Jade}
\end_inset
command line before the filename for your SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
file (or before your DTD
\begin_inset LatexCommand \index{DTD}
\end_inset
if also including the DTD
\begin_inset LatexCommand \index{DTD}
\end_inset
filename in the command line).
You can also reference an SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
Declaration to infer by using the "SGMLDECL" keyword
\begin_inset LatexCommand \index{keyword}
\end_inset
in your catalog
\begin_inset LatexCommand \index{catalog}
\end_inset
file.
(See "charset.htm" from the nsgmls distribution
\begin_inset LatexCommand \index{distribution}
\end_inset
for more information on the catalog
\begin_inset LatexCommand \index{catalog}
\end_inset
format.
FIXME:
\begin_inset LatexCommand \index{FIXME}
\end_inset
URL!)
\layout Standard
Now, what does all that mean for our specific situation?
\layout Standard
The
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
script uses, among others, the following catalog:
\begin_inset LatexCommand \index{catalog}
\end_inset
/usr/share/sgml/CATALOG.docbook-dsssl-stylesheets.
You can see this in the line:
\layout Code
SGML_CATALOG_FILES="$SGML_CATALOG_FILES: /usr/share/sgml/CATALOG.docbook-dsssl-st
ylesheets"
\layout Standard
In this catalog,
\begin_inset LatexCommand \index{catalog}
\end_inset
change the SGMLDECL line from:
\layout Code
-- SGMLDECL "dtds/decls/docbook.dcl" --
\layout Standard
to
\layout Code
SGMLDECL "/usr/share/sgml/docbook/docbook-dsssl-stylesheets/dtds/decls/docbook.dc
l"
\layout Standard
Note that we have taken away the comments and corrected the path
\begin_inset LatexCommand \index{path}
\end_inset
to the declaration.
\layout Standard
But that's NOT enough!
\layout Standard
You must also change the file where the SGMLDECL points to, i.e.
\begin_inset Foot
collapsed false
\layout Standard
Note that this may be specific to SuSE 9.0.
Other distributions may have corrected it.
\end_inset
docbook/docbook-dsssl-stylesheets/dtds/decls/docbook.dcl.
There, change
\layout Code
NAMING
\layout Code
LCNMSTRT ""
\layout Code
UCNMSTRT ""
\layout Code
LCNMCHAR ".-"
\layout Code
UCNMCHAR ".-"
\layout Code
NAMECASE
\layout Code
GENERAL YES
\layout Code
ENTITY NO
\layout Standard
to:
\layout Code
NAMING
\layout Code
LCNMSTRT ""
\layout Code
UCNMSTRT ""
\layout Code
LCNMCHAR ".-_"
\layout Code
UCNMCHAR ".-_"
\layout Code
NAMECASE
\layout Code
GENERAL YES
\layout Code
ENTITY NO
\layout Standard
i.e.
add the underscore to LCNMCHAR and UCNMCHAR.
\layout Standard
This solves the problem at its root! See also
\begin_inset LatexCommand \url[character "_" not allowed in value of attribute ID]{http://www.karakas-online.de/forum/viewtopic.php?t=872}
\end_inset
.
\end_deeper
\layout Description
general_entity_"d_op"_not_defined_and_no_default_entity: When you enter
an URL
\begin_inset LatexCommand \index{URL}
\end_inset
in LyX,
\begin_inset LatexCommand \index{LyX}
\end_inset
you are asked to enter the URL
\begin_inset LatexCommand \index{URL}
\end_inset
and the Name of the link in a window that pops up.
Whatever you enter in the URL
\begin_inset LatexCommand \index{URL}
\end_inset
field, will be automatically
\begin_inset LatexCommand \index{automatically}
\end_inset
taken care by LyX:
\begin_inset LatexCommand \index{LyX}
\end_inset
if it contains special characters, like ampersands,
\begin_inset LatexCommand \index{ampersands}
\end_inset
they are replaced with their SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
equivalent (see
\begin_inset LatexCommand \url[SGML entities]{http://www.ncbi.nlm.nih.gov/entrez/query/static/entities.html}
\end_inset
).
But whatever you enter in the Name field, it will passed
\begin_inset Quotes eld
\end_inset
as is
\begin_inset Quotes erd
\end_inset
to SGML.
\begin_inset LatexCommand \index{SGML}
\end_inset
If you feel lazy and just copy the URL
\begin_inset LatexCommand \index{URL}
\end_inset
in the Name field, you must take care to replace special characters with
their SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
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
\begin_deeper
\layout Code
http://www.karakas-online.de/forum/viewtopic.php?t=14&f=3
\layout Standard
instead of
\layout Code
Welcome to the Linux Forum of Chris
\layout Standard
then you should write it as
\layout Code
http://www.karakas-online.de/forum/viewtopic.php?t=14&f=3
\layout Standard
i.e.
replace
\begin_inset Quotes eld
\end_inset
&
\begin_inset Quotes erd
\end_inset
with its SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
entity
\begin_inset Quotes eld
\end_inset
&
\begin_inset Quotes erd
\end_inset
.
\end_deeper
\layout Description
element\SpecialChar ~
"BODY"\SpecialChar ~
undefined: BODY? Which body?
\begin_inset LatexCommand \index{body}
\end_inset
You don't remember to have entered anything like this in you text? Well,
check for
\begin_inset Quotes eld
\end_inset
\begin_inset Quotes erd
\end_inset
somewhere in the text (not the code environments,
\begin_inset LatexCommand \index{environments}
\end_inset
as those have been taken care already by LyX).
You have to replace the
\begin_inset Quotes eld
\end_inset
<
\begin_inset Quotes erd
\end_inset
and
\begin_inset Quotes eld
\end_inset
>
\begin_inset Quotes erd
\end_inset
with their SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
entities
\begin_inset Quotes eld
\end_inset
<
\begin_inset Quotes erd
\end_inset
and
\begin_inset Quotes eld
\end_inset
>
\begin_inset Quotes erd
\end_inset
respectively.
When you correct it, the other two errors
\begin_deeper
\layout Code
end tag for "BODY" omitted, but OMITTAG NO was specified
\layout Code
start tag was here
\layout Standard
will disappear too, since they are just follow-ups of the first one.
\end_deeper
\layout Description
character\SpecialChar ~
data\SpecialChar ~
is\SpecialChar ~
not\SpecialChar ~
allowed\SpecialChar ~
here: This simply means that you did not replace
some special character with its SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
entity.
Have a look at the tables in
\begin_inset LatexCommand \url[SGML entities]{http://www.ncbi.nlm.nih.gov/entrez/query/static/entities.html}
\end_inset
, try to guess which character is meant in the error (the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
lines produced by LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
can become longer than Proust's), and replace it.
\begin_deeper
\layout Standard
But the reason for this error may also lie in the fact that you forgot to
change the LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
(see
\begin_inset LatexCommand \ref{LyX-environments}
\end_inset
) from SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
to Standard and the text contains some special characters, like dashes.
In this case, the text is interpreted
\begin_inset LatexCommand \index{interpreted}
\end_inset
in the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
context and the special characters give rise to misunderstandings and errors
in th parser.
\begin_inset LatexCommand \index{parser}
\end_inset
Just change the environment
\begin_inset LatexCommand \index{environment}
\end_inset
from SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
back to Standard (or whatever else it should be) and the error will disappear.
\end_deeper
\layout Description
document\SpecialChar ~
type\SpecialChar ~
does\SpecialChar ~
not\SpecialChar ~
allow\SpecialChar ~
element\SpecialChar ~
"MEDIAOBJECT"\SpecialChar ~
here: This error happens because
sed (more precisely, the sed commands in
\begin_inset LatexCommand \url[sedscr]{sedscr}
\end_inset
) did not manage to change the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
that LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
produced for a figure.
The reason
\begin_inset LatexCommand \url[sedscr]{sedscr}
\end_inset
failed lies probably in some strange arrangement of the starting SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
tags for the figure.
The best cure is to enter a
\begin_inset Quotes eld
\end_inset
forced new line
\begin_inset Quotes erd
\end_inset
by pressing Strg+Enter at the end of the line that precedes the offending
figure.
This will force the whole SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
code to start on a new line and will make identification
\begin_inset LatexCommand \index{identification}
\end_inset
by
\begin_inset LatexCommand \url[sedscr]{sedscr}
\end_inset
easier.
The next time you run
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
, the correct SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
commands for the figure will be generated and the error will disappear.
\layout Description
an\SpecialChar ~
attribute\SpecialChar ~
value\SpecialChar ~
must\SpecialChar ~
be\SpecialChar ~
a\SpecialChar ~
literal\SpecialChar ~
unless\SpecialChar ~
it\SpecialChar ~
contains\SpecialChar ~
only\SpecialChar ~
name\SpecialChar ~
characters: How on
earth could this happen? Well, if you are like me and always try new possibilit
ies with LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
and SGML,
\begin_inset LatexCommand \index{SGML}
\end_inset
then you will encounter this error if you enter an URL
\begin_inset LatexCommand \index{URL}
\end_inset
while in the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
environment.
\begin_inset LatexCommand \index{environment}
\end_inset
There, of course, you cannot just use LyX' menu Insert->URL - you have
to write the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
code for an URL
\begin_inset LatexCommand \index{URL}
\end_inset
<ulink url=
\begin_inset Quotes erd
\end_inset
http://www.somesite.com
\begin_inset Quotes erd
\end_inset
>.
Now, if you forget to enclose the URL
\begin_inset LatexCommand \index{URL}
\end_inset
(the
\begin_inset Quotes eld
\end_inset
attribute
\begin_inset LatexCommand \index{attribute}
\end_inset
value
\begin_inset Quotes erd
\end_inset
, as the error says, of the
\begin_inset Quotes eld
\end_inset
url
\begin_inset Quotes erd
\end_inset
attribute
\begin_inset LatexCommand \index{attribute}
\end_inset
in the ulink element) in double quotes, then you will get that error.
\layout Description
document\SpecialChar ~
type\SpecialChar ~
does\SpecialChar ~
not\SpecialChar ~
allow\SpecialChar ~
element\SpecialChar ~
\SpecialChar ~
(after\SpecialChar ~
\SpecialChar ~
in\SpecialChar ~
a\SpecialChar ~
table): You shouldn't
get this error when you use the scripts desribed here - simply because
the
\begin_inset LatexCommand \url[sedscr_tidy2]{sedscr_tidy2}
\end_inset
script takes care that it does not occur.
However, if you do get it, it is nice to know why:
\begin_deeper
\layout Standard
Due to the way the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
parser works, the following piece of code describing an informal table will
produce a
\begin_inset Quotes eld
\end_inset
document
\begin_inset LatexCommand \index{document}
\end_inset
type does not allow element
\begin_inset LatexCommand \index{element}
\end_inset
\begin_inset Quotes erd
\end_inset
error:
\layout Code
\begin_inset Include \verbatiminput{informaltable-wrong}
\end_inset
\layout Standard
The reason is the so-called
\begin_inset Quotes eld
\end_inset
Pernicious Mixed Content Problem
\begin_inset Quotes erd
\end_inset
.
From the
\begin_inset LatexCommand \url[Definitive Guide to DocBook on the <entry> element]{http://www.docbook.org/tdg/en/html/entry.html}
\end_inset
:
\layout Quotation
The content model of the Entry element
\begin_inset LatexCommand \index{element}
\end_inset
exhibits a nasty peculiarity that we call pernicious mixed content.[18]
\layout Quotation
Every other element
\begin_inset LatexCommand \index{element}
\end_inset
in DocBook
\begin_inset LatexCommand \index{DocBook}
\end_inset
contains either block elements or inline
\begin_inset LatexCommand \index{inline}
\end_inset
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
\begin_inset LatexCommand \index{SGML}
\end_inset
parser, anyway) where inline
\begin_inset LatexCommand \index{inline}
\end_inset
markup
\begin_inset LatexCommand \index{markup}
\end_inset
can occur.
\layout Quotation
Table entries are different; they can contain either block or inline
\begin_inset LatexCommand \index{inline}
\end_inset
elements, but not both at the same time.
In other words, one Entry in a table might contain a paragraph
\begin_inset LatexCommand \index{paragraph}
\end_inset
or a list while another contains simply #PCDATA or another inline
\begin_inset LatexCommand \index{inline}
\end_inset
markup,
\begin_inset LatexCommand \index{markup}
\end_inset
but no single Entry can contain both.
\layout Quotation
Because the content model of an Entry allows both kinds of markup,
\begin_inset LatexCommand \index{markup}
\end_inset
each time the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
parser encounters an Entry, it has to decide what variety of markup
\begin_inset LatexCommand \index{markup}
\end_inset
it contains.
SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
parsers are forbidden to use more than a single token
\begin_inset LatexCommand \index{token}
\end_inset
of lookahead to reach this decision.
In practical terms,
\begin_inset LatexCommand \index{terms}
\end_inset
what this means is that a line feed or space after an Entry start tag causes
the parser
\begin_inset LatexCommand \index{parser}
\end_inset
to decide that the cell contains inline
\begin_inset LatexCommand \index{inline}
\end_inset
markup.
\begin_inset LatexCommand \index{markup}
\end_inset
Subsequent discovery of a paragraph
\begin_inset LatexCommand \index{paragraph}
\end_inset
or another block element
\begin_inset LatexCommand \index{element}
\end_inset
causes a parsing error.
\layout Quotation
All of these are legal:
\begin_deeper
\layout Code
\begin_inset Include \verbatiminput{entry-right}
\end_inset
\end_deeper
\layout Quotation
However, each of these is an error:
\begin_deeper
\layout Code
\begin_inset Include \verbatiminput{entry-wrong}
\end_inset
\end_deeper
\layout Standard
Thus, the informal table example above must be corrected to:
\layout Code
\begin_inset Include \verbatiminput{informaltable-right}
\end_inset
\layout Standard
This is done in
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
with a call to
\begin_inset LatexCommand \url[runsed]{runsed}
\end_inset
using
\begin_inset LatexCommand \url[sedscr_tidy2]{sedscr_tidy2}
\end_inset
as the sed script.
See also
\begin_inset LatexCommand \url[Openjade error: <para> not allowed after <entry>]{http://www.karakas-online.de/forum/viewtopic.php?t=965}
\end_inset
.
\end_deeper
\layout Section
TeX errors
\begin_inset LatexCommand \label{tex-errors}
\end_inset
\layout Standard
The material in this section (up to
\begin_inset LatexCommand \ref{structure-of-TeX-errors}
\end_inset
) is taken from the TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
FAQ
\begin_inset LatexCommand \index{FAQ}
\end_inset
item on
\begin_inset LatexCommand \url[How to approach errors]{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=erroradvice}
\end_inset
.
\layout Standard
Since TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
is a macroprocessor,
\begin_inset LatexCommand \index{macroprocessor}
\end_inset
its error messages are often difficult to understand; this is a (seemingly
invariant) property of macroprocessors.
\begin_inset LatexCommand \index{macroprocessors}
\end_inset
Knuth
\begin_inset LatexCommand \index{Knuth}
\end_inset
makes light of the problem in the TeXbook,
\begin_inset LatexCommand \index{TeXbook}
\end_inset
suggesting that you acquire the sleuthing skills
\begin_inset LatexCommand \index{skills}
\end_inset
of a latter-day Sherlock Holmes;
\begin_inset LatexCommand \index{Holmes}
\end_inset
while this approach
\begin_inset LatexCommand \index{approach}
\end_inset
has a certain romantic charm to it, it's not good for the 'production'
user of (La)TeX.
The following (derived, in part, from an article by Sebastian Rahtz
\begin_inset LatexCommand \index{Rahtz}
\end_inset
in TUGboat 16(4)) offers some general guidance in dealing with TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
error reports, and other answers in this section deal with common (but
perplexing) errors that you may encounter.
There's a long list of "hints" in Sebastian's article, including the following:
\layout Itemize
Look at TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
errors; those messages may seem cryptic at first, but they often contain
a straightforward clue to the problem.
See
\begin_inset LatexCommand \ref{structure-of-TeX-errors}
\end_inset
for further details.
\layout Itemize
Read the .log file; it contains hints to things you may not understand, often
things that have not even presented as error messages.
\layout Itemize
Be aware of the amount of context that TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
gives you.
The error messages gives you some bits of TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
code (or of the document
\begin_inset LatexCommand \index{document}
\end_inset
itself), that show where the error "actually happened"; it's possible to
control how much of this 'context' TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
actually gives you.
LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
(nowadays) instructs TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
only to give you one line of context, but you may tell it otherwise by saying
\begin_deeper
\layout Code
\backslash
setcounter{errorcontextlines}{999}
\layout Standard
in the preamble
\begin_inset LatexCommand \index{preamble}
\end_inset
of your document.
\begin_inset LatexCommand \index{document}
\end_inset
(If you're not a confident macro
\begin_inset LatexCommand \index{macro}
\end_inset
programmer, don't be ashamed of cutting that 999 down a bit; some errors
will go on and on, and spotting the differences between those lines can
be a significant challenge.)
\end_deeper
\layout Itemize
As a last resort, tracing can be a useful tool; reading a full (La)TeX trace
\begin_inset LatexCommand \index{trace}
\end_inset
takes a strong constitution,
\begin_inset LatexCommand \index{constitution}
\end_inset
but once you know how, the trace
\begin_inset LatexCommand \index{trace}
\end_inset
can lead you quickly to the source of a problem.
You need to have read the TeXbook
\begin_inset LatexCommand \index{TeXbook}
\end_inset
(see
\begin_inset LatexCommand \url[books about TeX]{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=books}
\end_inset
) in some detail, fully to understand the trace.
\begin_inset LatexCommand \index{trace}
\end_inset
\begin_deeper
\layout Standard
The command
\layout Code
\backslash
tracingall
\layout Standard
sets up maximum tracing.
\begin_inset LatexCommand \index{tracing.}
\end_inset
it also sets the output to come to the interactive terminal, which is somewhat
of a mixed blessing (since the output tends to be so vast - all but the
simplest traces are best examined in a text editor after the event).
\layout Standard
The LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
trace package (first distributed with the 2001 release of LaTeX) provides
more manageable tracing.
\begin_inset LatexCommand \index{tracing.}
\end_inset
Its
\backslash
traceon
\begin_inset LatexCommand \index{traceon}
\end_inset
command gives you what
\backslash
tracingall offers, but suppresses tracing around some of the truly verbose
parts of LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
itself.
The package also provides a
\backslash
traceoff command (there's no "off" command for
\backslash
tracingall), and a package option (logonly) allows you to suppress output
to the terminal.
\end_deeper
\layout Standard
The best advice to those faced with TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
errors is not to panic: most of the common errors are plain to the eye when
you go back to the source line that TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
tells you of.
If that approach
\begin_inset LatexCommand \index{approach}
\end_inset
doesn't work, the remaining answers in this section deal with some of the
most common error messages you may encounter using LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
and a TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
system provided by a common Linux distribution
\begin_inset LatexCommand \index{distribution}
\end_inset
as your starting point.
For more on TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
errors, consult the
\begin_inset Quotes eld
\end_inset
Joy of TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
errors
\begin_inset Quotes erd
\end_inset
section of the
\begin_inset LatexCommand \url[TeX FAQ]{http://www.tex.ac.uk/cgi-bin/texfaq2html?introduction=yes}
\end_inset
.
You should not ordinarily need to appeal to the wider public for assistance
(see
\begin_inset LatexCommand \url[TeX mailing lists]{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=maillists}
\end_inset
), but if you do, be sure to report full backtraces (see errorcontextlines
\begin_inset LatexCommand \index{errorcontextlines}
\end_inset
above) and so on.
\layout Subsection
The structure of TeX errors
\begin_inset LatexCommand \label{structure-of-TeX-errors}
\end_inset
\layout Standard
The material in this section is taken from
\begin_inset LatexCommand \url[the structure of TeX errors]{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=errstruct}
\end_inset
.
\layout Standard
TeX's error messages are reminiscent of the time when TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
itself was conceived (the 1970s): they're not terribly user-friendly, though
they do contain all the information that TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
can offer, usually in a pretty concise way.
\layout Standard
TeX's error reports all have the same structure:
\layout Itemize
An error message
\layout Itemize
Some 'context'
\layout Itemize
An error prompt
\layout Standard
The error message will relate to the TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
condition that is causing a problem.
Sadly, in the case of complex macro
\begin_inset LatexCommand \index{macro}
\end_inset
packages
\begin_inset LatexCommand \index{packages}
\end_inset
such as LaTeX,
\begin_inset LatexCommand \index{LaTeX}
\end_inset
the underlying TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
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
\begin_inset LatexCommand \index{LaTeX}
\end_inset
itself (or by a LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
class or package).
\layout Standard
The context of the error is a stylised representation
\begin_inset LatexCommand \index{representation}
\end_inset
of what TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
was doing at the point that it detected the error.
As noted in approaching errors, a macro
\begin_inset LatexCommand \index{macro}
\end_inset
package can tell TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
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
\begin_inset LatexCommand \index{macro}
\end_inset
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:
\layout Code
\backslash
blah and so on
\layout Standard
produces the error report
\layout Code
! Undefined control sequence.
\layout Code
l.4
\backslash
blah
\layout Code
and so on
\layout Standard
while:
\layout Code
\backslash
newcommand{
\backslash
blah}[1]{
\backslash
bleah #1}
\layout Code
\backslash
blah{to you}, folks
\layout Standard
produces the error report
\layout Code
! Undefined control sequence.
\layout Code
\backslash
blah #1->
\backslash
bleah
\layout Code
#1
\layout Code
l.5
\backslash
blah{to you}
\layout Code
, folks
\layout Standard
If the argument itself is in error, we will see things such as
\layout Code
\backslash
newcommand{
\backslash
blah}[1]{#1 to you}
\layout Code
\backslash
blah{
\backslash
bleah}, folks
\layout Standard
producing
\layout Code
! Undefined control sequence.
\layout Code
\backslash
bleah
\layout Code
l.5
\backslash
blah{
\backslash
bleah}
\layout Code
, folks
\layout Standard
The prompt accepts single-character
\begin_inset LatexCommand \index{single-character}
\end_inset
commands: the list of what's available may be had by typing
\begin_inset LatexCommand \index{typing}
\end_inset
?.
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
\begin_inset LatexCommand \index{TeX}
\end_inset
will attempt to carry on (often with rather little success).
\layout Subsection
LaTeX errors
\begin_inset LatexCommand \label{LaTeX-errors}
\end_inset
\layout Standard
LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
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
\begin_inset LatexCommand \index{TeX}
\end_inset
in the background)
\begin_inset Foot
collapsed false
\layout SGML
The example is from the processing of
\begin_inset LatexCommand \url[the LyX file for the PHP-Nuke HOWTO]{http://www.karakas-online.de/EN-Book/EN-Book.lyx}
\end_inset
.
Visit the
\begin_inset LatexCommand \url[Homepage of the PHP-Nuke HOWTO]{http://www.karakas-online.de/EN-Book/}
\end_inset
to see the result.
]]>
]]> ]]>
]]> Inline graphic
\end_inset
:
\layout Code
This is TeX, Version 3.14159 (Web2C 7.3.1) (format=jadetex 2001.10.25) 7 JAN
2004 07:26
\layout Code
**EN-Book.tex
\layout Code
(EN-Book.tex
\layout Code
JadeTeX 2001/07/19: 3.11
\layout Code
LaTeX Font Info: Try loading font information for T1+ptm on input line
1.
\layout Code
(/usr/share/texmf/tex/latex/psnfss/t1ptm.fd
\layout Code
File: t1ptm.fd 2000/01/12 PSNFSS-v8.1 font definitions for T1/ptm.
\layout Code
)
\layout Code
(jadetex.cfg (/usr/share/texmf/tex/generic/babel/babel.sty
\layout Code
Package: babel 2001/03/01 v3.7h The Babel package
\layout Code
(/usr/share/texmf/tex/generic/babel/english.ldf
\layout Code
Language: english 2001/02/07 v3.3k English support from the babel system
\layout Code
(/usr/share/texmf/tex/generic/babel/babel.def
\layout Code
File: babel.def 2001/03/01 v3.7h Babel common definitions
\layout Code
\backslash
babel@savecnt=
\backslash
count114
\layout Code
\backslash
U@D=
\backslash
dimen131
\layout Code
)
\layout Code
\backslash
l@canadian = a dialect from
\backslash
language
\backslash
l@english
\layout Code
))
\layout Code
(/usr/share/texmf/tex/generic/thumbpdf/thumbpdf.sty
\layout Code
Package: thumbpdf 2001/04/02 v2.10 Inclusion of thumbnails (HO)
\layout Code
Package thumbpdf Warning: You need pdfTeX in PDF mode for driver `pdftex'.
\layout Code
) (/usr/share/texmf/tex/latex/ae/ae.sty
\layout Code
Package: ae 1998/11/17 1.0 Almost European Computer Modern
\layout Code
(/usr/share/texmf/tex/latex/base/fontenc.sty
\layout Code
Package: fontenc 2000/08/30 v1.91 Standard LaTeX package
\layout Code
(/usr/share/texmf/tex/latex/base/t1enc.def
\layout Code
File: t1enc.def 2000/08/30 v1.91 Standard LaTeX file
\layout Code
LaTeX Font Info: Redeclaring font encoding T1 on input line 38.
\layout Code
)
\layout Code
LaTeX Font Info: Try loading font information for T1+aer on input line
96.
\layout Code
(/usr/share/texmf/tex/latex/ae/t1aer.fd
\layout Code
File: t1aer.fd 1997/11/16 Font definitions for T1/aer.
\layout Code
)))
\layout Code
(/usr/share/texmf/tex/latex/ae/aecompl.sty
\layout Code
Package: aecompl 1998/07/23 0.9 T1 Complements for AE fonts (D.
Roegel)
\layout Code
)
\layout Code
Package hyperref Info: Option `plainpages' set `false' on input line 128.
\layout Code
Package hyperref Info: Option `colorlinks' set `true' on input line 128.
\layout Code
Package hyperref Info: Option `bookmarksopen' set `true' on input line 128.
\layout Code
Package hyperref Info: Option `colorlinks' set `true' on input line 128.
\layout Code
Package hyperref Info: Option `breaklinks' set `true' on input line 128.
\layout Code
Package hyperref Warning: Option `pagebackref' has already been used,
\layout Code
(hyperref) setting the option has no effect on input line
128.
\layout Code
)
\layout Code
Elements will be labelled
\layout Code
Jade begin document sequence at 19
\layout SGML
As you can see from the last line, Jade just started its work.
]]>
]]> ]]> ]]> Inline graphic
\layout Standard
It goes on with font checking as follows:
\layout Code
(EN-Book.aux)
\layout Code
\backslash
openout1 = `EN-Book.aux'.
\layout Code
LaTeX Font Info: Checking defaults for OML/cmm/m/it on input line 19.
\layout Code
LaTeX Font Info: ...
okay on input line 19.
\layout Code
LaTeX Font Info: Checking defaults for T1/cmr/m/n on input line 19.
\layout Code
LaTeX Font Info: ...
okay on input line 19.
\layout Code
LaTeX Font Info: Checking defaults for OT1/cmr/m/n on input line 19.
\layout Code
LaTeX Font Info: ...
okay on input line 19.
\layout Code
LaTeX Font Info: Checking defaults for OMS/cmsy/m/n on input line 19.
\layout Code
LaTeX Font Info: ...
okay on input line 19.
\layout Code
LaTeX Font Info: Checking defaults for OMX/cmex/m/n on input line 19.
\layout Code
LaTeX Font Info: ...
okay on input line 19.
\layout Code
LaTeX Font Info: Checking defaults for U/cmr/m/n on input line 19.
\layout Code
LaTeX Font Info: ...
okay on input line 19.
\layout Code
LaTeX Font Info: Checking defaults for PD1/pdf/m/n on input line 19.
\layout Code
LaTeX Font Info: ...
okay on input line 19.
\layout Code
LaTeX Font Info: Checking defaults for T2A/cmr/m/n on input line 19.
\layout Code
LaTeX Font Info: Try loading font information for T2A+cmr on input line
19.
\layout Code
(/usr/share/texmf/tex/latex/cyrillic/t2acmr.fd
\layout Code
File: t2acmr.fd 1999/01/07 v1.0 Computer Modern Cyrillic font definitions
\layout Code
)
\layout Code
LaTeX Font Info: ...
okay on input line 19.
\layout Code
LaTeX Font Info: Checking defaults for TS1/cmr/m/n on input line 19.
\layout Code
LaTeX Font Info: Try loading font information for TS1+cmr on input line
19.
\layout Code
(/usr/share/texmf/tex/latex/base/ts1cmr.fd
\layout Code
File: ts1cmr.fd 1999/05/25 v2.5h Standard LaTeX font definitions
\layout Code
)
\layout Code
LaTeX Font Info: ...
okay on input line 19.
\layout Code
LaTeX Font Info: Checking defaults for LECO/omseco/m/n on input line
19.
\layout Code
LaTeX Font Info: ...
okay on input line 19.
\layout Code
LaTeX Font Info: Checking defaults for LECX/omsecx/m/n on input line
19.
\layout Code
LaTeX Font Info: ...
okay on input line 19.
\layout Code
LaTeX Font Info: Checking defaults for LECY/omsecy/m/n on input line
19.
\layout Code
LaTeX Font Info: ...
okay on input line 19.
\layout Code
LaTeX Font Info: Checking defaults for LEGR/omsegr/m/n on input line
19.
\layout Code
LaTeX Font Info: ...
okay on input line 19.
\layout Code
LaTeX Font Info: Checking defaults for LEHA/omseha/m/n on input line
19.
\layout Code
LaTeX Font Info: ...
okay on input line 19.
\layout Code
LaTeX Font Info: Checking defaults for LEIP/omseip/m/n on input line
19.
\layout Code
LaTeX Font Info: ...
okay on input line 19.
\layout Code
LaTeX Font Info: Checking defaults for LELA/omsela/m/n on input line
19.
\layout Code
LaTeX Font Info: ...
okay on input line 19.
\layout Code
LaTeX Font Info: Checking defaults for LETI/omseti/m/n on input line
19.
\layout Code
LaTeX Font Info: ...
okay on input line 19.
\layout Code
Package hyperref Info: Link coloring ON on input line 19.
\layout Code
(/usr/share/texmf/tex/latex/hyperref/nameref.sty
\layout Code
Package: nameref 2000/05/08 v2.18 Cross-referencing by name of section
\layout Code
\backslash
c@section@level=
\backslash
count115
\layout Code
)
\layout Code
LaTeX Info: Redefining
\backslash
ref on input line 19.
\layout Code
LaTeX Info: Redefining
\backslash
pageref on input line 19.
\layout Code
LaTeX Font Info: Try loading font information for T1+aess on input line
99.
\layout Code
(/usr/share/texmf/tex/latex/ae/t1aess.fd
\layout Code
File: t1aess.fd 1997/11/16 Font definitions for T1/aess.
\layout Code
) [1.0.37]
\layout Code
File: logo1.eps Graphic file (type eps)
\layout Code
\layout Code
File: logo2.eps Graphic file (type eps)
\layout Code
\layout Code
Overfull
\backslash
hbox (2655.0092pt too wide) in alignment at lines 610--899
\layout Standard
Somewhere from this point on, you will start seeing LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
processing
\begin_inset LatexCommand \index{processing}
\end_inset
the pages of your document
\begin_inset LatexCommand \index{document}
\end_inset
one after the other - and outputting errors and warnings like the
\begin_inset Quotes eld
\end_inset
Overfull
\begin_inset LatexCommand \index{Overfull}
\end_inset
\backslash
hbox
\begin_inset Quotes erd
\end_inset
above.
\layout Standard
There are some fairly common error messages and warnings.
I'll cover those here using material from the chapter on
\begin_inset Quotes eld
\end_inset
LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
and LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
errors
\begin_inset Quotes erd
\end_inset
of the Extended Features manual
\begin_inset LatexCommand \index{manual}
\end_inset
for LyX,
\begin_inset LatexCommand \index{LyX}
\end_inset
available from LyX' Help menu.
You should look at a good LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
book for a complete listing.
\layout Itemize
\begin_inset Quotes eld
\end_inset
\family typewriter
\begin_inset LatexCommand \index{typewriter}
\end_inset
LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
Warning:
\family default
\begin_inset Quotes eld
\end_inset
\begin_deeper
\layout Standard
Anything beginning with these word is a warning message for the purpose
of
\begin_inset Quotes eld
\end_inset
debugging
\begin_inset Quotes erd
\end_inset
the LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
code itself.
You'll get messages like this if you added or changed cross-references
or bibliography
\begin_inset LatexCommand \index{bibliography}
\end_inset
entries, in which case, LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
is trying to tell you that you need to make another run.
\layout Standard
You can by-and-large ignore these.
\end_deeper
\layout Itemize
\begin_inset Quotes eld
\end_inset
\family typewriter
\begin_inset LatexCommand \index{typewriter}
\end_inset
LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
Font Warning:
\family default
\begin_inset Quotes erd
\end_inset
\begin_deeper
\layout Standard
Another warning message, this time about fonts
\begin_inset LatexCommand \index{fonts}
\end_inset
which LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
couldn't find.
The rest of the message will often say something about a replacement font
that LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
used.
\layout Standard
You can safely ignore these.
\end_deeper
\layout Itemize
\begin_inset Quotes eld
\end_inset
\family typewriter
\begin_inset LatexCommand \index{typewriter}
\end_inset
Overfull
\begin_inset LatexCommand \index{Overfull}
\end_inset
\backslash
hbox
\family default
\begin_inset Quotes erd
\end_inset
\begin_deeper
\layout Standard
LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
absolutely
\emph on
loves
\emph default
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
\begin_inset LatexCommand \index{LaTeX}
\end_inset
seems to generate at least one of these messages for just about any document
\begin_inset LatexCommand \index{document}
\end_inset
you write.
\layout Standard
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.
\end_deeper
\layout Itemize
\begin_inset Quotes eld
\end_inset
\family typewriter
\begin_inset LatexCommand \index{typewriter}
\end_inset
Underfull
\begin_inset LatexCommand \index{Underfull}
\end_inset
\backslash
hbox
\family default
\begin_inset Quotes erd
\end_inset
\begin_deeper
\layout Standard
Not quite as common as its cousin.
LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
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.
\layout Standard
You can ignore these, too.
\end_deeper
\layout Itemize
\begin_inset Quotes eld
\end_inset
\family typewriter
\begin_inset LatexCommand \index{typewriter}
\end_inset
Overfull
\begin_inset LatexCommand \index{Overfull}
\end_inset
\backslash
vbox
\family default
\begin_inset Quotes erd
\end_inset
and
\begin_inset Quotes eld
\end_inset
\family typewriter
\begin_inset LatexCommand \index{typewriter}
\end_inset
Underfull
\begin_inset LatexCommand \index{Underfull}
\end_inset
\backslash
vbox
\family default
\begin_inset Quotes erd
\end_inset
\begin_deeper
\layout Standard
Warnings about troubles breaking the page.
Once again, just look at the output.
Your eyes will tell you where something has gone wrong.
\end_deeper
\layout Itemize
\begin_inset Quotes eld
\end_inset
\family typewriter
\begin_inset LatexCommand \index{typewriter}
\end_inset
LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
Error: File
\begin_inset Quotes els
\end_inset
Xxxx
\begin_inset Quotes ers
\end_inset
not found
\family default
\begin_inset Quotes erd
\end_inset
\begin_deeper
\layout Standard
The file
\begin_inset Quotes eld
\end_inset
Xxxx
\begin_inset Quotes erd
\end_inset
isn't installed on this system.
This usually appears because some package your document
\begin_inset LatexCommand \index{document}
\end_inset
needs isn't installed.
If you didn't touch the preamble
\begin_inset LatexCommand \index{preamble}
\end_inset
or didn't use the
\family typewriter
\begin_inset LatexCommand \index{typewriter}
\end_inset
\backslash
usepackage{}
\family default
command, then one of the packages
\begin_inset LatexCommand \index{packages}
\end_inset
LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
tried to load is missing.
Use
\family sans
\bar under
H
\bar default
elp\SpecialChar \menuseparator
L
\bar under
a
\bar default
TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
Configuration
\family default
, to get a list of packages
\begin_inset LatexCommand \index{packages}
\end_inset
that LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
knows about.
This file is updated whenever you reconfigure
\begin_inset LatexCommand \index{reconfigure}
\end_inset
LyX (using
\family sans
\bar under
E
\bar default
dit
\bar under
\SpecialChar \menuseparator
R
\bar default
econfigure
\family default
) and tells you which packages
\begin_inset LatexCommand \index{packages}
\end_inset
have been detected and what they do.
\layout Standard
If you
\emph on
did
\emph default
use the
\family typewriter
\begin_inset LatexCommand \index{typewriter}
\end_inset
\backslash
usepackage{}
\family default
command, and the package in question isn't installed, you'll need to install
it yourself.
\end_deeper
\layout Itemize
\begin_inset Quotes eld
\end_inset
\family typewriter
\begin_inset LatexCommand \index{typewriter}
\end_inset
LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
Error: Unknown option
\family default
\begin_inset Quotes erd
\end_inset
\begin_deeper
\layout Standard
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.
\end_deeper
\layout Itemize
\begin_inset Quotes eld
\end_inset
\family typewriter
\begin_inset LatexCommand \index{typewriter}
\end_inset
Undefined control sequence
\family default
\begin_inset Quotes erd
\end_inset
\begin_deeper
\layout Standard
If you've inserted LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
code into your document,
\begin_inset LatexCommand \index{document}
\end_inset
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.
\end_deeper
\layout Itemize
LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
Error: Undefined color `rtlred'
\begin_deeper
\layout Standard
Theoretically, you can define your own colours in jadetex.
\begin_inset LatexCommand \index{jadetex}
\end_inset
cfg.
\begin_inset LatexCommand \index{jadetex.cfg}
\end_inset
For example, the following block of code defines three new colours, rtlred,
rtlblue and rtlgreen (the green being a bit darker than usual):
\layout Code
\backslash
usepackage{color}
\layout Code
\backslash
definecolor{rltred}{rgb}{0.75,0,0}
\layout Code
\backslash
definecolor{rltgreen}{rgb}{0,0.5,0}
\layout Code
\backslash
definecolor{rltblue}{rgb}{0,0,0.75}
\layout Standard
However, no matter where I position this code in jadetex.
\begin_inset LatexCommand \index{jadetex}
\end_inset
cfg
\begin_inset LatexCommand \index{jadetex.cfg}
\end_inset
(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.
\layout Standard
Andreas Ekenbäck (private communication) has found that by having double
declarations of a colour:
\layout Code
\backslash
newcmykcolor{abstractYellow}{0.02 0.02 0.35 0.0}
\layout Code
\backslash
definecolor{abstractYellow}{cmyk}{0.02,0.02,0.35,0.0}
\layout Standard
in jadetex.cfg, it works.
On his Fedora Core 4 workstation, he says, it is even enough to have the
first declaration.
\end_deeper
\layout Standard
Further reading: see the chapter on
\begin_inset Quotes eld
\end_inset
LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
and LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
errors
\begin_inset Quotes erd
\end_inset
of the Extended Features manual
\begin_inset LatexCommand \index{manual}
\end_inset
for LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
for tips on how to handle LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
errors and warnings.
\layout Subsection
TeX capacity exceeded
\begin_inset LatexCommand \label{TeX-capacity-exceeded}
\end_inset
\layout Standard
If you encounter TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
errors, especially
\layout Code
TeX capacity exceeded, sorry [main memory size=384000]
\layout Standard
you may have to set in texmf.cnf
\begin_inset LatexCommand \index{texmf.cnf}
\end_inset
(usually located in /etc/texmf, or where the TEXMFCNF
\begin_inset LatexCommand \index{TEXMFCNF}
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
variable (see
\begin_inset LatexCommand \ref{explain-environment-variables}
\end_inset
) shows):
\layout Code
main_memory = 3839999
\layout Code
main_memory.jadetex = 4999999
\layout Code
hash_extra.jadetex = 25000
\layout Code
pool_size.jadetex = 500000
\layout Code
save_size.jadetex = 15000
\layout Code
save_size = 8000
\layout Standard
FYI, here's how much memory TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
used for this document
\begin_inset LatexCommand \index{document}
\end_inset
(you may see such information in the .log file created by pdfjadetex
\begin_inset LatexCommand \index{pdfjadetex}
\end_inset
which is deleted by default in
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
):
\layout Code
Here is how much of TeX's memory you used:
\layout Code
4847 strings out of 15997
\layout Code
36267 string characters out of 99016
\layout Code
163640 words of memory out of 384000
\layout Code
15827 multiletter control sequences out of 10000+15000
\layout Code
68666 words of font info for 129 fonts, out of 400000 for 1000
\layout Code
14 hyphenation exceptions out of 1000
\layout Code
31i,12n,40p,1588b,3161s stack positions out of 300i,100n,500p,50000b,8000s
\layout Standard
See
\begin_inset LatexCommand \url[my Jade Odyssey]{http://www.karakas-online.de/myJade/}
\end_inset
for more details and ideas on this and other related errors.
\layout Subsection
Fatal format file error; I'm stymied
\begin_inset LatexCommand \label{fatal-format-file-error}
\end_inset
\layout SGML
Well...me too.
]]> ]]> ]]> ]]> Inline graphic
\layout Standard
This what the
\begin_inset LatexCommand \url[TeX FAQ]{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=formatstymy}
\end_inset
says about this error:
\layout Standard
(La)TeX applications often fail with this error when you've been playing
with the configuration, or have just installed a new version.
\layout Standard
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
\begin_inset LatexCommand \index{LaTeX}
\end_inset
or ConTeXt.
\begin_inset LatexCommand \index{ConTeXt.}
\end_inset
From the command you issue, TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
knows which format you want.
\layout Standard
The error message
\layout Code
Fatal format file error; I'm stymied
\layout Standard
means that TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
itself can't understand the format you want.
Obviously, this could happen if the format file had got corrupted,
\begin_inset LatexCommand \index{corrupted}
\end_inset
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
\begin_inset LatexCommand \index{TeX}
\end_inset
binaries on the same machine can understand each other's formats.
So the new version of TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
you have just installed, won't understand the format generated by the one
you installed last year.
\layout Standard
Resolve the problem by regenerating the format; of course, this depends
on which system you are using.
On a teTeX-based
\begin_inset LatexCommand \index{teTeX-based}
\end_inset
system, run
\layout Code
fmtutil --all
\layout Standard
or
\layout Code
fmtutil --byfmt=
\layout Standard
to build only the format that you are interested in.
\layout Standard
I got this error during the PDF
\begin_inset LatexCommand \index{PDF}
\end_inset
processing
\begin_inset LatexCommand \index{processing}
\end_inset
(
\begin_inset LatexCommand \ref{explain-document-creation-PDF}
\end_inset
).
Since pdftex
\begin_inset LatexCommand \index{pdftex}
\end_inset
is the program that was running at this stage, I tried both
\layout Code
fmtutil --all
\layout Standard
or
\layout Code
fmtutil --byfmt=pdftex
\layout Standard
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
\begin_inset LatexCommand \index{hundreds}
\end_inset
of cross-references (probably more than 500) in just one section (see it
in
\begin_inset LatexCommand \url[Credits for version 2.0 of the PHP-Nuke HOWTO]{http://www.karakas-online.de/EN-Book/credits-version-2.0.html}
\end_inset
).
\layout Standard
The solution was to upgrade
\begin_inset LatexCommand \index{upgrade}
\end_inset
pdftex from 0.13d to 1.11b (pdfTeX (Web2C 7.5.2) 3.141592-1.11b)
\emph on
and
\emph default
jadetex
\begin_inset LatexCommand \index{jadetex}
\end_inset
from 1.3 to 3.13.
Note that upgrading pdftex
\begin_inset LatexCommand \index{pdftex}
\end_inset
was not enough, jadetex
\begin_inset LatexCommand \index{jadetex}
\end_inset
had to be upgraded too.
Of course, you would still have to use fmtutil
\begin_inset LatexCommand \index{fmtutil}
\end_inset
as above.
After the upgrades, the error disappeared.
As a nice by-product, document
\begin_inset LatexCommand \index{document}
\end_inset
processing
\begin_inset LatexCommand \index{processing}
\end_inset
seems to be much faster now, although I didn't conduct any benchmarks.
\begin_inset LatexCommand \index{benchmarks}
\end_inset
\layout Subsection
Corrupted NFSS tables
\begin_inset LatexCommand \label{corrupted-NFSS-tables}
\end_inset
\layout Code
(/usr/share/texmf/tex/latex/base/ts1cmr.fd)
\layout Code
! Corrupted NFSS tables.
\layout Code
wrong@fontshape ...message {Corrupted NFSS tables}
\layout Code
error@fontshape else let
f...
\layout Standard
I got this error after I used the RefDB
\begin_inset LatexCommand \index{RefDB}
\end_inset
(
\begin_inset LatexCommand \ref{Refdb}
\end_inset
,
\begin_inset LatexCommand \ref{LyX-Bibliography}
\end_inset
,
\begin_inset LatexCommand \ref{explain-bibliography}
\end_inset
) DSSSL
\begin_inset LatexCommand \index{DSSSL}
\end_inset
stylesheet modifications in the local DSSSL
\begin_inset LatexCommand \index{DSSSL}
\end_inset
stylesheets (
\begin_inset LatexCommand \ref{DSSSL-stylesheets}
\end_inset
,
\begin_inset LatexCommand \ref{explain-DSSSL-stylesheets}
\end_inset
) that control the output.
\layout Subsection
Missing $ inserted
\begin_inset LatexCommand \label{Missing-dollar-inserted}
\end_inset
\layout Standard
You will probably get tons warnings like this one:
\layout Code
! Missing $ inserted.
\layout Code
\layout Code
$
\layout Code
l.17245 ...b/a/bsd/2000/09/06/FreeBSD_Basics.html}
\layout Code
\backslash
endNode{}
\backslash
endSeq{}
\backslash
endNod...
\layout Code
I've inserted something that you may have forgotten.
\layout Code
(See the above.)
\layout Standard
You can see them in the standard output, as well as in the .log file that
is created automatically
\begin_inset LatexCommand \index{automatically}
\end_inset
(if you don't see any .log file, maybe
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
currently deletes it - check the code).
They mean that TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
tried to correct you , because it saw some character that is used in the
mathematics
\begin_inset LatexCommand \index{mathematics}
\end_inset
mode and thought you might have forgotten to switch.
So it inserts a $, which toggles math
\begin_inset LatexCommand \index{math}
\end_inset
mode.
If this is not what you intended (it will most probably not, if your .tex
file is created through the procedure
\begin_inset LatexCommand \index{procedure}
\end_inset
described here), then your only salvation is to escape the character that
triggered this behaviour.
\begin_inset LatexCommand \index{behaviour}
\end_inset
This means that you may have to escape
\layout Itemize
Slashes (/) in URLs, at least when they separate two numbers
\begin_inset LatexCommand \index{numbers}
\end_inset
(not tested)
\layout Itemize
Underscores (_)
\layout Itemize
Carets (^)
\layout Itemize
and generally everything that may have a math
\begin_inset LatexCommand \index{math}
\end_inset
interpretation in TeX/LaTeX/LyX
\layout Standard
FIXME: This needs testing! Till now, I didn't resort to escaping - and stil
things work remarkably well...
\layout Subsection
Unprintable characters
\begin_inset LatexCommand \label{unprintable-characters}
\end_inset
\layout Standard
Inevitably, sooner or later, you will hit a very nasty problem in document
\begin_inset LatexCommand \index{document}
\end_inset
processing:
\begin_inset LatexCommand \index{processing}
\end_inset
some characters in your file will be unprintable! They may appear in the
PDF
\begin_inset LatexCommand \index{PDF}
\end_inset
as black boxes
\begin_inset LatexCommand \index{boxes}
\end_inset
(for example
\begin_inset Formula $>>$
\end_inset
, in the OT1
\begin_inset LatexCommand \index{OT1}
\end_inset
font encoding), or simply wrong.
Here is what you can do to solve this problem:
\layout Standard
If you are using the OT1
\begin_inset LatexCommand \index{OT1}
\end_inset
font encoding
\begin_inset LatexCommand \index{encoding}
\end_inset
\begin_inset Foot
collapsed false
\layout SGML
There are various reasons why you may want to use the Old TeX (OT1)
font encoding: you want to use the original Computern Modern fonts (which
are available only in OT1) and/or have Mathematics (for which the original
CM fonts are still a good choice), or you don't have other fonts, or you
just find CM irresistible.
]]>
]]> ]]>
]]> Inline graphic
\end_inset
, i.e.
if your
\begin_inset LatexCommand \url[jadetex.cfg]{jadetex.cfg}
\end_inset
file contains the line
\layout Code
\backslash
usepackage[OT1]{fontenc}
\layout Standard
then you have to enter the following characters in math
\begin_inset LatexCommand \index{math}
\end_inset
mode:
\layout Itemize
\begin_inset Formula $\backslash $
\end_inset
(backslash)
\layout Itemize
FIXME
\layout Standard
If you are using the T1
\begin_inset LatexCommand \index{T1}
\end_inset
font encoding,
\begin_inset LatexCommand \index{encoding}
\end_inset
i.e.
if your
\begin_inset LatexCommand \url[jadetex.cfg]{jadetex.cfg}
\end_inset
file contains the line
\layout Code
\backslash
usepackage[T1]{fontenc}
\layout Standard
then you can use the ae
\begin_inset LatexCommand \index{ae}
\end_inset
and aecompl
\begin_inset LatexCommand \index{aecompl}
\end_inset
packages
\begin_inset LatexCommand \index{packages}
\end_inset
in order to be able to write almost every european
\begin_inset LatexCommand \index{european}
\end_inset
character:
\layout Code
\backslash
usepackage{ae,aecompl}
\layout Standard
You will not, however, manage to get the two
\begin_inset Formula $<$
\end_inset
symbols,
\begin_inset LatexCommand \index{symbols}
\end_inset
\begin_inset Formula $<<$
\end_inset
, printed correctly.
If your purpose was to get the french quote characters (the
\begin_inset Quotes eld
\end_inset
guillemets
\begin_inset Quotes erd
\end_inset
), then you could replace the ae
\begin_inset LatexCommand \index{ae}
\end_inset
and aecompl
\begin_inset LatexCommand \index{aecompl}
\end_inset
packages
\begin_inset LatexCommand \index{packages}
\end_inset
with the aeguill
\begin_inset LatexCommand \index{aeguill}
\end_inset
package, i.e.
replace the above line in
\begin_inset LatexCommand \url[jadetex.cfg]{jadetex.cfg}
\end_inset
with:
\layout Code
\backslash
usepackage{aeguill}
\layout Standard
If your purpose was to get two
\begin_inset Formula $<$
\end_inset
signs, one after another, just as if you were describing the effect of the
\begin_inset Quotes eld
\end_inset
append
\begin_inset Quotes erd
\end_inset
operator in
\layout Code
cat file1 >> file2
\layout Standard
then you
\emph on
must
\emph default
enter the
\begin_inset Formula $<<$
\end_inset
in math
\begin_inset LatexCommand \index{math}
\end_inset
mode.
\layout SGML
\layout SGML
\layout SGML
Note that the above holds for the standard LyX environment (see
\begin_inset LatexCommand \ref{LyX-environments}
\end_inset
) 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.
\layout SGML
\layout SGML
\layout Standard
For more information on fonts
\begin_inset LatexCommand \index{fonts}
\end_inset
and their encodings, see FIXME.
\begin_inset LatexCommand \index{FIXME}
\end_inset
\layout Section
Other errors
\begin_inset LatexCommand \label{other-errors}
\end_inset
\layout Subsection
Keywords not present in HTML
\begin_inset LatexCommand \label{keywords}
\end_inset
\layout Standard
If you don't see the keywords
\begin_inset LatexCommand \index{keywords}
\end_inset
in the HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
file, then this may be a bug in your stylesheets.
There seems to be a bug in dbcommon.dsl
\begin_inset LatexCommand \index{dbcommon.dsl}
\end_inset
(DocBook DSSSL
\begin_inset LatexCommand \index{DSSSL}
\end_inset
stylesheets 1.73) that prevents this from happening for an article, where
the in within .
The definition of "info-element"
\begin_inset LatexCommand \index{info-element}
\end_inset
in dbcommon.dsl
\begin_inset LatexCommand \index{dbcommon.dsl}
\end_inset
contains
\layout Code
((equal? (gi nd) (normalize "article"))
\layout Code
(select-elements (children nd) (normalize "artheader")))
\layout Standard
but no reference to "articleinfo"
\begin_inset LatexCommand \index{articleinfo}
\end_inset
.
\layout Standard
In dbcommon.dsl,
\begin_inset LatexCommand \index{dbcommon.dsl}
\end_inset
which in my system resides in /usr/share/sgml/docbook/docbook-dsssl-stylesheets
-1.72/common/dbcommon.dsl and belongs to packet docbook-dsssl-style
\begin_inset LatexCommand \index{docbook-dsssl-style}
\end_inset
sheets-1.72-34, replace the definition of info-element
\begin_inset LatexCommand \index{info-element}
\end_inset
with:
\layout Code
;; ======================================================================
\layout Code
(define (info-element #!optional (nd (current-node)))
\layout Code
;; Returns the *INFO element for the nd or (empty-node-list) if no
\layout Code
;; such node exists...
\layout Code
(cond
\layout Code
((equal? (gi nd) (normalize "set"))
\layout Code
(select-elements (children nd) (normalize "setinfo")))
\layout Code
((equal? (gi nd) (normalize "book"))
\layout Code
(select-elements (children nd) (normalize "bookinfo")))
\layout Code
((equal? (gi nd) (normalize "section"))
\layout Code
(select-elements (children nd) (normalize "sectioninfo")))
\layout Code
((equal? (gi nd) (normalize "sect1"))
\layout Code
(select-elements (children nd) (normalize "sect1info")))
\layout Code
((equal? (gi nd) (normalize "sect2"))
\layout Code
(select-elements (children nd) (normalize "sect2info")))
\layout Code
((equal? (gi nd) (normalize "sect3"))
\layout Code
(select-elements (children nd) (normalize "sect3info")))
\layout Code
((equal? (gi nd) (normalize "sect4"))
\layout Code
(select-elements (children nd) (normalize "sect4info")))
\layout Code
((equal? (gi nd) (normalize "sect5"))
\layout Code
(select-elements (children nd) (normalize "sect5info")))
\layout Code
((equal? (gi nd) (normalize "refsect1"))
\layout Code
(select-elements (children nd) (normalize "refsect1info")))
\layout Code
((equal? (gi nd) (normalize "refsect2"))
\layout Code
(select-elements (children nd) (normalize "refsect2info")))
\layout Code
((equal? (gi nd) (normalize "refsect3"))
\layout Code
(select-elements (children nd) (normalize "refsect3info")))
\layout Code
((equal? (gi nd) (normalize "refsynopsisdiv"))
\layout Code
(select-elements (children nd) (normalize "refsynopsisdivinfo")))
\layout Code
((equal? (gi nd) (normalize "article"))
\layout Code
;; Changed by root.
\layout Code
;; node-list-filter-by-gi and articleinfo inserted.
\layout Code
;; Otherwise no keywords are created in articles.
\layout Code
(node-list-filter-by-gi (children nd) (list
\layout Code
(normalize "artheader")
\layout Code
(normalize "articleinfo"))))
\layout Code
(else ;; BIBLIODIV, GLOSSDIV, INDEXDIV, PARTINTRO, SIMPLESECT
\layout Code
(select-elements (children nd) (normalize "docinfo")))))
\layout Code
;; ======================================================================
\layout Subsection
thumbpdf fails
\begin_inset LatexCommand \label{thumbpdf-fails}
\end_inset
\layout Standard
Perhaps the most accurate indicator of a serious error in your document
\begin_inset LatexCommand \index{document}
\end_inset
or settings is the failing of thumbpdf:
\begin_inset LatexCommand \index{thumbpdf}
\end_inset
\layout Code
THUMBPDF 2.8, 2001/01/12 - Copyright (c) 1999-2001 by Heiko Oberdiek.
\layout Code
*** make png files / run Ghostscript ***
\layout Code
**** This file has a corrupted %%EOF marker, or garbage after the %%EOF.
\layout Code
GNU Ghostscript 6.51: Unrecoverable error, exit code 1
\layout Code
!!! Error: Closing Ghostscript (exit status: 1)!
\layout Standard
Although document
\begin_inset LatexCommand \index{document}
\end_inset
processing
\begin_inset LatexCommand \index{processing}
\end_inset
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
\begin_inset LatexCommand \index{eliminate}
\end_inset
it, or revert to a configuration that is known to work.
\layout Standard
However, there is an exception to this rule of thumb: if you see the error
\layout Code
Ghostscript internal error
\layout SGML
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.
]]>
]]> ]]>
]]> Inline graphic
\layout Subsection
sed segmentation fault
\begin_inset LatexCommand \label{sed-segmentation-fault}
\end_inset
\layout Standard
On one occasion, I got the following very disturbing error:
\layout Code
/usr/local/bin/runsed: line 54: 27611 Segmentation fault sed -f $SEDSCR
$x >/tmp/$y$$
\layout Standard
Output of the corrected SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
file broke at a line for no apparent reason.
Openjade
\begin_inset LatexCommand \index{Openjade}
\end_inset
complained (of course) with some errors, but processed the file.
I noticed that something went wrong from the output of thumbpdf
\begin_inset LatexCommand \index{thumbpdf}
\end_inset
(see
\begin_inset LatexCommand \ref{thumbpdf-fails}
\end_inset
): thumbpdf
\begin_inset LatexCommand \index{thumbpdf}
\end_inset
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
\begin_inset LatexCommand \index{segmentation}
\end_inset
fault.
I guess it has to do with the exceptionally long line that sed had to process:
LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
produces very long SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
lines.
It does not break the lines at SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
tags and clutters them on one line for reasons unknown to me.
That particular line was thus more than 3400 characters
\begin_inset Foot
collapsed false
\layout Standard
of SGML text, original text was certainly less than that.
\end_inset
long when it was output without the error.
As soon as I added some innocent
\begin_inset LatexCommand \index{innocent}
\end_inset
text that made it a little longer, it would cause the segmentation
\begin_inset LatexCommand \index{segmentation}
\end_inset
fault above.
I guess this breaks some input line length limitation in sed.
However, this is denied to be the case in the
\begin_inset LatexCommand \url[sed manual on the (non-)limitations on line length]{http://www.gnu.org/software/sed/manual/html_node/sed_11.html#SEC11}
\end_inset
:
\layout Quotation
For those who want to write portable SED scripts, be aware that some implementat
ions 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
\begin_inset LatexCommand \index{GNU}
\end_inset
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).
\layout Standard
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,
\begin_inset LatexCommand \index{paragraph}
\end_inset
admonition
\begin_inset LatexCommand \index{admonition}
\end_inset
(see
\begin_inset LatexCommand \ref{admonitions}
\end_inset
,
\begin_inset LatexCommand \ref{LyX-admonitions}
\end_inset
), code or other environment
\begin_inset LatexCommand \index{environment}
\end_inset
(
\begin_inset LatexCommand \ref{LyX-environments}
\end_inset
) that may persuade LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
to start a new SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
line in the exported SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
text.
\layout Subsection
Acrobat Reader 5 does not show thumbnails in Linux
\begin_inset LatexCommand \label{no-thumbnails-in-acrobat-reader-5}
\end_inset
\layout Standard
The thumbpdf
\begin_inset LatexCommand \index{thumbpdf}
\end_inset
script creates thumbnails
\begin_inset LatexCommand \index{thumbnails}
\end_inset
for the PDF
\begin_inset LatexCommand \index{PDF}
\end_inset
document just fine (see
\begin_inset LatexCommand \ref{explain-thumbnails}
\end_inset
).
Things work fine even with a thumbpdf.tex
\begin_inset LatexCommand \index{thumbpdf.tex}
\end_inset
of version 3.2 and a thumbpdf
\begin_inset LatexCommand \index{thumbpdf}
\end_inset
of version 2.8, i.e.
even if the versions of these two files differ (in which case thumbpdf
\begin_inset LatexCommand \index{thumbpdf}
\end_inset
will issue a warning, see
\begin_inset LatexCommand \ref{openjade-errors}
\end_inset
).
\layout Standard
Yet, one day, I recomputed the PDF
\begin_inset LatexCommand \index{PDF}
\end_inset
version of a document,
\begin_inset LatexCommand \index{document}
\end_inset
only to discover that the thumbnails
\begin_inset LatexCommand \index{thumbnails}
\end_inset
were appearing intermittently in the document:
\begin_inset LatexCommand \index{document}
\end_inset
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,
\begin_inset LatexCommand \index{Windows}
\end_inset
it became clear that this is a problem of Acrobat Reader 5 for Linux and
large thumbnails
\begin_inset LatexCommand \index{thumbnails}
\end_inset
(small thumbnails
\begin_inset LatexCommand \index{thumbnails}
\end_inset
are displayed fine).
\layout Standard
I guess there is nothing you can do about this problem, other than switch
to small thumbnails
\begin_inset LatexCommand \index{thumbnails}
\end_inset
(right-click on the thumbnail area to see the context menu that will allow
you to choose this), or upgrade
\begin_inset LatexCommand \index{upgrade}
\end_inset
to a version of Acrobat Reader that does not suffer from this bug.
\layout Subsection
URLs with underscore display '_' instead of '_'
\begin_inset LatexCommand \label{URLs-with-underscore}
\end_inset
\layout Standard
Any URL
\begin_inset LatexCommand \index{URL}
\end_inset
that has an underscore in it (like the link to
\begin_inset LatexCommand \htmlurl[awkscr_insert_index_items]{awkscr_insert_index_items}
\end_inset
) shows '&lowbar' in place of '_'.
To correct this, you must check the checkbox
\begin_inset Quotes eld
\end_inset
HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
type
\begin_inset Quotes erd
\end_inset
when you insert the URL
\begin_inset LatexCommand \index{URL}
\end_inset
in LyX,
\begin_inset LatexCommand \index{LyX}
\end_inset
see
\begin_inset LatexCommand \ref{fig-insert-url}
\end_inset
.
\layout Standard
\begin_inset Float figure
placement htbp
wide false
collapsed false
\layout Caption
\begin_inset Graphics FormatVersion 1
filename insert-url.eps
display default
size_type 0
rotateOrigin center
lyxsize_type 0
\end_inset
\begin_inset LatexCommand \label{fig-insert-url}
\end_inset
Insert URL with underscores in LyX.
\end_inset
\layout Standard
When you do this, you should NOT write underscores as '_'.
You should write an underscore as is, i.e.
as '_', in both the URL and the Name fields
\begin_inset LatexCommand \ref{fig-insert-url}
\end_inset
.
\layout Standard
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
\begin_inset Quotes eld
\end_inset
.pdf
\begin_inset Quotes erd
\end_inset
attached to it, which is definitely wrong.
Try this link:
\begin_inset LatexCommand \htmlurl[awkscr_insert_index_items]{awkscr_insert_index_items}
\end_inset
, in HTML and in PDF to see the difference!
\layout Subsection
sed: file sedscr_img line 2: Unknown option to `s'
\begin_inset LatexCommand \label{unknown-option-to-s-in-sedscr_img}
\end_inset
\layout Standard
You get the error:
\layout Code
editing mySGML.html
\layout Code
sed: file sedscr_img line 2: Unknown option to `s'
\layout Code
Output written to /tmp/mySGML.html_1402221460
\layout Code
Sed produced an empty file
\layout Code
- check your sedscript.
\layout Code
all done
\layout Standard
When you check the offending line 2 of sedscr_img (remember that sedscr_img
is dynamically generated each time you run lyxtox), you see:
\layout Code
s///g
\layout Standard
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.
\layout SGML
The easiest solution to this seems to be: just avoid using backslash
in figure captions! You cannot have everything in this world, it seems... ]]>
]]> ]]> ]]> Inline graphic
\layout Standard
See
\begin_inset LatexCommand \ref{fig-ISO-DIN-paper-sizes}
\end_inset
for the corrected caption of this specific example.
\layout Chapter
Explaining the magic: the details
\begin_inset LatexCommand \label{explain-magic}
\end_inset
\layout SGML
\layout SGML
\begin_inset LatexCommand \url[William Safire]{http://www.bartleby.com/65/e-/E-SafireWll.html}
\end_inset
\layout SGML
\layout SGML
Knowing how things work is the basis for appreciation, and is thus a source
of civilized delight.
\layout SGML
\layout SGML
\layout Standard
What makes the procedure
\begin_inset LatexCommand \index{procedure}
\end_inset
described here appear to be
\begin_inset Quotes eld
\end_inset
magic
\begin_inset Quotes erd
\end_inset
is not only the
\begin_inset Quotes eld
\end_inset
high-tecness
\begin_inset Quotes erd
\end_inset
of the tools
\begin_inset LatexCommand \index{tools}
\end_inset
involved, but also the highly frustrating fact that each one of the tools
\begin_inset LatexCommand \index{tools}
\end_inset
involved expects its input in different directories and/or formats, making
it really difficult for interfaces or pipes
\begin_inset LatexCommand \index{pipes}
\end_inset
to match the output of one tool to the expected input of another.
In this chapter I will explain the inner working of the involved scripts
that, ultimately, do one thing: ensure that what is expected will be found
in its expected place, in the expected format.
\layout SGML
\layout SGML
Tip:
\layout SGML
\layout SGML
You don't need to read this chapter if you are not interested in the gory
details.
For getting things to work, the
\begin_inset LatexCommand \ref{required-software}
\end_inset
,
\begin_inset LatexCommand \ref{required-preliminary-steps}
\end_inset
,
\begin_inset LatexCommand \ref{writing-in-LyX}
\end_inset
and
\begin_inset LatexCommand \ref{lyxtox}
\end_inset
should suffice.
But if you want to understand how things work, then go on!
\layout SGML
\layout SGML
\layout Section
Document processing
\begin_inset LatexCommand \label{explain-document-processing}
\end_inset
\layout Standard
What happens when you type
\begin_inset Quotes eld
\end_inset
lyxtox
\begin_inset LatexCommand \index{lyxtox}
\end_inset
myTemplate
\begin_inset Quotes erd
\end_inset
? A lot! Let's inspect it step by step:
\layout Standard
The name of the parameter
\begin_inset LatexCommand \index{parameter}
\end_inset
given to the
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
script, myTemplate,
\begin_inset LatexCommand \index{myTemplate}
\end_inset
becomes $1.
Whenever you see $1 in the code examples below, just replace it mentally
with the name you supplied to lyxtox.
\begin_inset LatexCommand \index{lyxtox}
\end_inset
\layout Subsection
Check number of parameters
\begin_inset LatexCommand \label{explain-check-number-of-parameters}
\end_inset
\layout Standard
As in every good script, a rudimentary parameter
\begin_inset LatexCommand \index{parameter}
\end_inset
number check is the very first thing to do:
\layout Code
# Check arguments and issue a help statement, if wrong
\layout Code
#
\layout Code
if [ $# -eq 0 -o $# -gt 1 ]; then
\layout Code
help
\layout Code
exit 1
\layout Code
elif [ $1 = "-h" -o $1 = "--help" ]; then
\layout Code
help
\layout Code
exit 0
\layout Code
fi
\layout Standard
If the number of parameters is not exactly 1, the output of the help() function
is printed, which looks like this:
\layout Code
Usage: lyxtox [-h] [FILENAME_WITHOUT_.lyx_ENDING]
\layout Code
Creates HTML, PDF, RTF, TXT and PS output
\layout Code
from a single LYX source.
\layout Code
Needs: lyx, runsed, sed, sedscr, jadetex.cfg, perl, openjade,
\layout Code
pdfjadetex, DocBook, TeX, LaTeX, thumbpdf, gzip, tar
\layout Code
and all packages required from these.
\layout Code
See http://www.karakas-online.de/mySGML/ for a detailed
\layout Code
description.
\layout Code
EXAMPLE
\layout Code
=======
\layout Code
If your file is myfile.lyx, then do
\layout Code
lyxtox myfile
\layout Code
go get a cup of coffee and be happy :-)
\layout Code
-h, --help Display this help text
\layout Subsection
Set program locations
\begin_inset LatexCommand \label{explain-program-locations}
\end_inset
\layout Standard
If the parameter
\begin_inset LatexCommand \index{parameter}
\end_inset
number check is passed, some program locations are set (adapt them to our
situation!):
\layout Code
# Program locations
\layout Code
\layout Code
# Adapt to your situation.
\layout Code
LYX="/usr/X11R6/bin/lyx"
\layout Code
SED="/usr/bin/sed"
\layout Code
AWK="/usr/bin/awk"
\layout Code
RUNSED="/usr/local/bin/runsed"
\layout Code
SEDSCR="sedscr"
\layout Code
SEDSCRMATH="sedscr_math"
\layout Code
SEDSCRABI="sedscr_abi"
\layout Code
SEDSCRAPP="sedscr_app"
\layout Code
SEDSCRBIB="sedscr_bib"
\layout Code
AWKSCRMATH="awkscr_math"
\layout Code
PERL="/usr/bin/perl"
\layout Code
COLLATEINDEX="/usr/share/sgml/docbook/docbook-dsssl-stylesheets/bin/collateindex.
pl"
\layout Code
UNESCAPEMATH="/usr/local/bin/unescape_math.pl"
\layout Code
TEXMATH2PNGBMP="/usr/local/bin/texmath2pngbmp.pl"
\layout Code
THUMB_PDF="/usr/local/bin/thumbpdf"
\layout Code
OPENJADE="/usr/bin/openjade"
\layout Code
PDFJADETEX="/usr/bin/pdfjadetex"
\layout Code
JADETEX="/usr/bin/jadetex"
\layout Code
DVIPS="/usr/bin/dvips"
\layout Code
GZIP="/usr/bin/gzip"
\layout Code
TAR="/bin/tar"
\layout Code
TIDY="/usr/bin/tidy"
\layout Code
HTMLSPLIT="/usr/local/bin/htmlsplit.awk"
\layout Code
REFDBXP="/usr/bin/refdbxp"
\layout Code
RUNBIB="/usr/bin/runbib"
\layout Code
DATADIR="../"
\layout Code
DOMAIN="www.karakas-online.de"
\layout Standard
Further, the stylesheet
\begin_inset LatexCommand \index{stylesheet}
\end_inset
locations are set (adapt them to your situation too):
\layout Code
HTML_CHUNKS_DSL="lyxtox-html.dsl"
\layout Code
HTML_NOCHUNKS_DSL="lyxtox-onehtml.dsl"
\layout Code
PRINT_PDF_DSL="lyxtox-print-pdf.dsl"
\layout Code
PRINT_PS_DSL="lyxtox-print-ps.dsl"
\layout Code
PRINT_RTF_DSL="lyxtox-print-rtf.dsl"
\layout Code
PRINT_TXT_DSL="lyxtox-print-txt.dsl"
\layout Standard
You only need to change this part, if at all.
The RefDB
\begin_inset LatexCommand \index{RefDB}
\end_inset
part:
\layout Code
HTML_DSL="refdb-html.dsl"
\layout Code
HTML_CHUNKS_DSL="$HTML_DSL#html"
\layout Code
HTML_NOCHUNKS_DSL="$HTML_DSL#onehtml"
\layout Code
PRINT_DSL="refdb-print.dsl"
\layout Code
PRINT_PDF_DSL="$PRINT_DSL#print-pdf"
\layout Code
PRINT_PS_DSL="$PRINT_DSL#print-ps"
\layout Code
PRINT_RTF_DSL="$PRINT_DSL#print-rtf"
\layout Code
PRINT_TXT_DSL="$PRINT_DSL#print-txt"
\layout Standard
works automatically
\begin_inset LatexCommand \index{automatically}
\end_inset
and it is does not play any role how you name (or where you place) the HTML_DSL
\begin_inset LatexCommand \index{HTML_DSL}
\end_inset
and PRINT_DSL files in this case - they will be automatically
\begin_inset LatexCommand \index{automatically}
\end_inset
created through
\begin_inset LatexCommand \url[awkscr_refdb_html]{awkscr_refdb_html}
\end_inset
and
\begin_inset LatexCommand \url[awkscr_refdb_print]{awkscr_refdb_print}
\end_inset
with whatever filename you pass to them for their output respectively,
see the source code of
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
.
\layout Subsection
Set environment variables
\begin_inset LatexCommand \label{explain-environment-variables}
\end_inset
\layout Standard
It's time to set some environment
\begin_inset LatexCommand \index{environment}
\end_inset
variables.
This is where quite a lot of the
\begin_inset Quotes eld
\end_inset
magic
\begin_inset Quotes erd
\end_inset
is hidden! Although they
\emph on
are
\emph default
mentioned somewhere in the respective manpages,
\begin_inset LatexCommand \index{manpages}
\end_inset
a newcomer will have probably never heard of them.
The result: images cannot be found, no matter how
\begin_inset Quotes eld
\end_inset
right
\begin_inset Quotes erd
\end_inset
you did it, as well as some other annoyances regarding font mappings.
This is because different tools
\begin_inset LatexCommand \index{tools}
\end_inset
read different environment
\begin_inset LatexCommand \index{environment}
\end_inset
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
\begin_inset LatexCommand \index{SGML}
\end_inset
parsers or PDF
\begin_inset LatexCommand \index{PDF}
\end_inset
software.
\layout Standard
Since we entered the names of images without any path
\begin_inset LatexCommand \index{path}
\end_inset
information in LyX,
\begin_inset LatexCommand \index{LyX}
\end_inset
openjade
\begin_inset LatexCommand \index{openjade}
\end_inset
needs to be informed of their location with the environment
\begin_inset LatexCommand \index{environment}
\end_inset
variable SGML_SEARCH_PATH:
\begin_inset LatexCommand \index{SGML_SEARCH_PATH}
\end_inset
\layout Code
# Environment variables
\layout Code
# openjade needs this!
\layout Code
# Both absolute and relative paths work!
\layout Code
# SGML_SEARCH_PATH="$PWD/images"
\layout Code
SGML_SEARCH_PATH="./images"
\layout Code
export SGML_SEARCH_PATH
\layout Standard
pdftex
\begin_inset LatexCommand \index{pdftex}
\end_inset
(and pdfjadetex) will look at a different environment
\begin_inset LatexCommand \index{environment}
\end_inset
variable for the location of the image files: TEXPSHEADERS.
\begin_inset LatexCommand \index{TEXPSHEADERS}
\end_inset
For some reason which I don't fully understand,
\backslash
includegraphics
\begin_inset LatexCommand \index{includegraphics}
\end_inset
with pdftex
\begin_inset LatexCommand \index{pdftex}
\end_inset
uses the TEXPSHEADERS
\begin_inset LatexCommand \index{TEXPSHEADERS}
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
variable for the additional paths
\begin_inset LatexCommand \index{paths}
\end_inset
to search.
Also: TEXPSHEADERS
\begin_inset LatexCommand \index{TEXPSHEADERS}
\end_inset
contains the search path
\begin_inset LatexCommand \index{path}
\end_inset
where pdftex
\begin_inset LatexCommand \index{pdftex}
\end_inset
looks up for font mapping file (pdftex.map) and encoding
\begin_inset LatexCommand \index{encoding}
\end_inset
files (*.enc):
\layout Code
# pdftex (and pdfjadetex) need this.
\layout Code
# In my system pdftex.map is located in /var/lib/texmf/dvips/config/,
\layout Code
# while the .enc files are under /usr/share/texmf/dvips/base/.
\layout Code
# TEXPSHEADERS=":${PWD}/images//:/var/lib/texmf/dvips/config/:/usr/share/texmf/d
vips/base/"
\layout Code
TEXPSHEADERS=":${PWD}/images//"
\layout Code
export TEXPSHEADERS
\layout Standard
LaTeX, on the other side, will look at still another variable for the path
\begin_inset LatexCommand \index{path}
\end_inset
to images: TEXINPUTS
\begin_inset LatexCommand \index{TEXINPUTS}
\end_inset
(TEXINPUTS is also defined in the texmf.cnf
\begin_inset LatexCommand \index{texmf.cnf}
\end_inset
file, usually located in the directory pointed to by the TEXMFCNF
\begin_inset LatexCommand \index{TEXMFCNF}
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
variable):
\layout Code
# LaTeX & Co.
need this!
\layout Code
# A relative path does NOT work!
\layout Code
# TEXINPUTS="$PWD/images:$TEXINPUTS"
\layout Code
TEXINPUTS=":${PWD}/images//"
\layout Code
export TEXINPUTS
\layout Standard
The TEXMFCNF
\begin_inset LatexCommand \index{TEXMFCNF}
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
variable points to the directory that contains the configuration files for
TeX:
\begin_inset LatexCommand \index{TeX}
\end_inset
\layout Code
TEXMFCNF="/etc/texmf/"
\layout Code
export TEXMFCNF
\layout Standard
In /etc/texmf/texmf.cnf we read:
\layout Code
% pdfjadetex: Search path for font metric (.tfm) files.
\layout Code
TEXFONTS = .;$TEXMF/fonts/tfm//
\layout Standard
The next environment
\begin_inset LatexCommand \index{environment}
\end_inset
variable we will have to set, is the one that passes options to thumbpdf
\begin_inset LatexCommand \index{thumbpdf}
\end_inset
(see
\begin_inset LatexCommand \ref{thumbpdf}
\end_inset
), for the case that you wish to do so:
\layout Code
# You can pass options to thumbpdf through this environment variable
\layout Code
THUMBPDF=""
\layout Code
export THUMBPDF
\layout Standard
Last but not least, openjade
\begin_inset LatexCommand \index{openjade}
\end_inset
needs to know the locations of the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
catalog files (see
\begin_inset LatexCommand \ref{catalog-paths}
\end_inset
):
\layout Code
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/sgml/CATALOG.iso_ent"
\layout Code
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/sgml/CATALOG.docbook-dsssl-sty
lesheets"
\layout Code
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/sgml/CATALOG.mathml-2.0"
\layout Code
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/sgml/CATALOG.svg-1.1"
\layout Code
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/sgml/CATALOG.docbook_4"
\layout Code
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/sgml/openjade/catalog"
\layout Code
SGML_CATALOG_FILES="$SGML_CATALOG_FILES:/usr/share/refdb/refdb.cat"
\layout Code
export SGML_CATALOG_FILES
\layout Standard
The SP_ENCODING
\begin_inset LatexCommand \index{SP_ENCODING}
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
variable tells Openjade
\begin_inset LatexCommand \index{Openjade}
\end_inset
in which encoding
\begin_inset LatexCommand \index{encoding}
\end_inset
the input file is written in:
\layout Code
SP_ENCODING="ISO-8859-1"
\layout Code
export SP_ENCODING
\layout Standard
Encoding names are case insensitive.
The following named encodings are available (see
\begin_inset LatexCommand \url[Handling of character sets in OpenSP]{http://openjade.sourceforge.net/doc-1.5.1/charset.htm}
\end_inset
):
\layout Description
utf-8
\begin_inset LatexCommand \index{utf-8}
\end_inset
Each character is represented by a variable number of bytes according to
UCS
\begin_inset LatexCommand \index{UCS}
\end_inset
Transformation Format 8 defined in Annex P to be added by the first proposed
drafted amendment (PDAM 1) to ISO/IEC 10646-1:1993.
\layout Description
utf-16
\begin_inset LatexCommand \index{utf-16}
\end_inset
Each character is represented by a variable number of bytes according to
UCS
\begin_inset LatexCommand \index{UCS}
\end_inset
Transformation Format 16 defined in Annex O to be added by the first proposed
drafted amendment (PDAM 1) to ISO/IEC 10646-1:1993.
\layout Description
ucs-2\SpecialChar ~
iso-10646-ucs-2
\begin_inset LatexCommand \index{iso-10646-ucs-2}
\end_inset
This is ISO/IEC 10646 with the UCS-2 transformation format.
Each character is represented by 2 bytes.
No special treatment is given to the byte order mark
\begin_inset LatexCommand \index{mark}
\end_inset
character.
\layout Description
ucs-4\SpecialChar ~
iso-10646-ucs-4\SpecialChar ~
utf-32
\begin_inset LatexCommand \index{utf-32}
\end_inset
This is ISO/IEC 10646 with the UCS-4 transformation format.
Each character is represented by 4 bytes.
\layout Description
unicode
\begin_inset LatexCommand \index{unicode}
\end_inset
Each character is represented according to the utf-16
\begin_inset LatexCommand \index{utf-16}
\end_inset
encoding.
The bytes representing the entire storage object may be preceded by a pair
of bytes representing the byte order mark
\begin_inset LatexCommand \index{mark}
\end_inset
character (0xFEFF).
The bytes representing each character are in the system byte order, unless
the byte order mark
\begin_inset LatexCommand \index{mark}
\end_inset
character is present, in which case the order of its bytes determines the
byte order.
When the storage object is read, any byte order mark
\begin_inset LatexCommand \index{mark}
\end_inset
character is discarded.
\layout Description
euc-jp
\begin_inset LatexCommand \index{euc-jp}
\end_inset
This is equivalent to the Extended_UNIX_Code_Packed_Format_for_Japanese
Internet charset.
Each character is encoded by a variable length sequence of octets.
\layout Description
euc-kr
\begin_inset LatexCommand \index{euc-kr}
\end_inset
This is ASCII
\begin_inset LatexCommand \index{ASCII}
\end_inset
and KSC 5601 encoded with the EUC encoding
\begin_inset LatexCommand \index{encoding}
\end_inset
as defined by KS C 5861-1992.
\layout Description
euc-cn\SpecialChar ~
cn-gb\SpecialChar ~
gb2312
\begin_inset LatexCommand \index{gb2312}
\end_inset
This is ASCII
\begin_inset LatexCommand \index{ASCII}
\end_inset
and GB 2312-80 encoded with the EUC encoding.
\begin_inset LatexCommand \index{encoding}
\end_inset
It is equivalent to the CN-GB MIME
\begin_inset LatexCommand \index{MIME}
\end_inset
charset defined in RFC 1922.
\layout Description
sjis\SpecialChar ~
shift_jis
\begin_inset LatexCommand \index{shift_jis}
\end_inset
This is equivalent to the Shift_JIS Internet charset.
Each character is encoded by a variable length sequence of octets.
This is Microsoft's standard encoding
\begin_inset LatexCommand \index{encoding}
\end_inset
for Japanese.
\begin_inset LatexCommand \index{Japanese}
\end_inset
\layout Description
big5\SpecialChar ~
cn-big5 This is equivalent to the CN-Big5 MIME
\begin_inset LatexCommand \index{MIME}
\end_inset
charset defined in RFC 1922.
\layout Description
is8859-n\SpecialChar ~
iso-8859-n n can be any single digit other than 0.
Each character in the repertoire of ISO
\begin_inset LatexCommand \index{ISO}
\end_inset
8859-n is represented by a single byte.
\layout Description
koi8-r\SpecialChar ~
koi8
\begin_inset LatexCommand \index{koi8}
\end_inset
The koi8-r
\begin_inset LatexCommand \index{koi8-r}
\end_inset
encoding as defined in RFC 1489.
\layout Description
xml
\begin_inset LatexCommand \index{xml}
\end_inset
On input, this uses XML's rules
\begin_inset LatexCommand \index{rules}
\end_inset
to determine the encoding.
\begin_inset LatexCommand \index{encoding}
\end_inset
On output, this uses UTF-8.
\layout Description
windows
\begin_inset LatexCommand \index{windows}
\end_inset
Specify this encoding
\begin_inset LatexCommand \index{encoding}
\end_inset
when a storage object is encoded using your system's default Windows
\begin_inset LatexCommand \index{Windows}
\end_inset
character set.
This uses the so-called ANSI code page.
\layout Description
wunicode
\begin_inset LatexCommand \index{wunicode}
\end_inset
This uses the unicode
\begin_inset LatexCommand \index{unicode}
\end_inset
encoding if the storage object starts with a byte order mark
\begin_inset LatexCommand \index{mark}
\end_inset
and otherwise the windows
\begin_inset LatexCommand \index{windows}
\end_inset
encoding.
\begin_inset LatexCommand \index{encoding}
\end_inset
If you are working with Unicode, this is probably the best value for SP_ENCODIN
G.
\layout Description
ms-dos
\begin_inset LatexCommand \index{ms-dos}
\end_inset
Specify this encoding
\begin_inset LatexCommand \index{encoding}
\end_inset
when a storage object (file) uses the OEM
\begin_inset LatexCommand \index{OEM}
\end_inset
code page.
The OEM
\begin_inset LatexCommand \index{OEM}
\end_inset
code-page for a particular machine is the code-page used by FAT
\begin_inset LatexCommand \index{FAT}
\end_inset
file-systems on that machine and is the default code-page for MS-DOS consoles.
\layout Standard
For OpenSP,
\begin_inset LatexCommand \index{OpenSP}
\end_inset
a suite of SGML/XML processing
\begin_inset LatexCommand \index{processing}
\end_inset
tools related to Openjade,
\begin_inset LatexCommand \index{Openjade}
\end_inset
there are two other environment
\begin_inset LatexCommand \index{environment}
\end_inset
variables that are related to SP_ENCODING
\begin_inset LatexCommand \index{SP_ENCODING}
\end_inset
(see
\begin_inset LatexCommand \url[Handling of character sets in OpenSP]{http://openjade.sourceforge.net/doc-1.5.1/charset.htm}
\end_inset
):
\layout Description
SP_CHARSET_FIXED
\begin_inset LatexCommand \index{SP_CHARSET_FIXED}
\end_inset
If this variable is 1 or YES, then OpenSP
\begin_inset LatexCommand \index{OpenSP}
\end_inset
will operate in fixed character set mode.
\layout Description
SP_SYSTEM_CHARSET
\begin_inset LatexCommand \index{SP_SYSTEM_CHARSET}
\end_inset
This identifies the system character set.
When in fixed character set mode, this character set is used as the internal
character set.
When not in fixed character set mode this character set is used as the
internal character set until the document
\begin_inset LatexCommand \index{document}
\end_inset
character set has been read, at which point the document
\begin_inset LatexCommand \index{document}
\end_inset
character set is used as the internal character set.
The only currently recognized value for this is JIS.
This refers to a character set which combines JIS X 0201, JIS X 0208 and
JIS X 0212 by adding 0x8080 to the codes of characters in JIS X 0208 and
0x8000 to the codes of characters in JIS X 0212.
The default system character set is Unicode 2.0.
\layout Standard
But since lyxtox
\begin_inset LatexCommand \index{lyxtox}
\end_inset
does not use OpenSP,
\begin_inset LatexCommand \index{OpenSP}
\end_inset
we don't need to care about these two, as the manual
\begin_inset LatexCommand \index{manual}
\end_inset
page of Openjade
\begin_inset LatexCommand \index{Openjade}
\end_inset
asserts:
\layout SGML
\layout SGML
\layout SGML
Openjade does not use SP_CHARSET_FIXED and SP_SYSTEM_CHARSET
\layout SGML
\layout SGML
\layout SGML
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.
\layout SGML
\layout SGML
\layout Subsection
Main part
\begin_inset LatexCommand \label{explain-main-part}
\end_inset
\layout Standard
In the main part, the hard work (for your computer) begins:
\layout Standard
The document
\begin_inset LatexCommand \index{document}
\end_inset
is exported from LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
to DocBook
\begin_inset LatexCommand \index{DocBook}
\end_inset
SGML:
\begin_inset LatexCommand \index{SGML}
\end_inset
\layout Code
$LYX -e docbook $1.lyx
\layout Standard
The SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
that is produced by LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
has several shortcomings.
\begin_inset LatexCommand \index{shortcomings}
\end_inset
They have to be corrected.
This is done by calling
\begin_inset LatexCommand \url[runsed]{runsed}
\end_inset
:
\layout Code
$RUNSED $SEDSCR $1.sgml
\layout Standard
which is the subject of the next subsection.
\begin_inset LatexCommand \index{subsection}
\end_inset
\layout SGML
\layout SGML
\layout SGML
Alternative commands
\layout SGML
\layout SGML
\layout SGML
There are quite a few alternative invocations of the various tools at appropriat
e places in the
\begin_inset LatexCommand \url[lyxtox]{lyxtox}
\end_inset
script, in the form of comments.
These are there in order to show you how you can achieve an equivalent
result through other tools.
\layout SGML
\layout SGML
\layout Subsubsection
Runsed, sed and sedscr
\begin_inset LatexCommand \label{explain-runsed-sed-sedscr}
\end_inset
\layout Standard
Runsed
\begin_inset LatexCommand \index{Runsed}
\end_inset
takes as argument the sedscript
\begin_inset LatexCommand \index{sedscript}
\end_inset
to run and the file against which to run it.
It calls sed with
\begin_inset LatexCommand \url[sedscr]{sedscr}
\end_inset
as the
\begin_inset Quotes eld
\end_inset
sed command file
\begin_inset Quotes erd
\end_inset
.
In the sedscr
\begin_inset LatexCommand \index{sedscr}
\end_inset
file itself there is another bunch of
\begin_inset Quotes eld
\end_inset
magic
\begin_inset Quotes erd
\end_inset
going on:
\layout SGML
\layout SGML
Important note:
\layout SGML
\layout SGML
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.
\layout SGML
\layout SGML
\layout Standard
The code
\layout Code
s/<
\backslash
(sect[^>]*
\backslash
)>
\backslash
([^<]*
\backslash
)]*
\backslash
)>/<
\backslash
1
\backslash
3>
\backslash
2/g
\layout Code
s/<
\backslash
(chapter
\backslash
)>
\backslash
([^<]*
\backslash
)]*
\backslash
)>/<
\backslash
1
\backslash
3>
\backslash
2/g
\layout Standard
tells sed to substitute
\begin_inset Foot
collapsed true
\layout Standard
I have inserted some blanks in the code snippet in order to prevent my own
scripts (sedscr!) from matching and changing a code that was meant to be
an example ;-)
\end_inset
\layout Code
< sect1 >< title > some title < anchor id="some label" >
\layout Standard
with
\layout Code
some title
\layout Standard
and
\layout Code
< chapter >< title > some title < anchor id="some label" >
\layout Standard
with
\layout Code
some title
\layout Standard
The code
\layout Code
/^.*
\backslash
\layout Code
\backslash
3<
\backslash
/para>
\backslash
\layout Code
<
\backslash
/caption>
\backslash
\layout Code
<
\backslash
/mediaobject>
\backslash
\layout Code
<
\backslash
/figure>
\backslash
\layout Code
/g
\layout Code
}
\layout Standard
tells sed to substitute
\begin_inset Foot
collapsed true
\layout Standard
I have inserted some blanks in the code snippet in order to prevent my own
scripts (sedscr!) from matching and changing a code that was meant to be
an example ;-)
\end_inset
\layout Code
< figure >< title >< graphic fileref="imagename" > some blanks < anchor
id="some id" >some title< /title >
\layout Standard
with the more elaborate combination of figure and mediaobject
\begin_inset LatexCommand \index{mediaobject}
\end_inset
elements:
\layout Code
\begin_inset Include \verbatiminput{figure}
\end_inset
\layout Standard
There are some remarks due here:
\layout Itemize
The title of the original SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
appears in three places of the new SGML: the title, the phrase for the alternati
ve text and the caption.
\begin_inset LatexCommand \index{caption}
\end_inset
LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
uses the figure caption
\begin_inset LatexCommand \index{caption}
\end_inset
for the title and there is no way we can derive three different texts for
the three different uses in the new SGML.
\begin_inset LatexCommand \index{SGML}
\end_inset
That is why in the output document
\begin_inset LatexCommand \index{document}
\end_inset
the figure title, the alternative text and the figure caption
\begin_inset LatexCommand \index{caption}
\end_inset
are identical.
\layout Itemize
For the PNG
\begin_inset LatexCommand \index{PNG}
\end_inset
format we must prefix the image file name, imagename.png, with the relative
path
\begin_inset LatexCommand \index{path}
\end_inset
(./images) to it, even though we set all environment
\begin_inset LatexCommand \index{environment}
\end_inset
variables correctly (see
\begin_inset LatexCommand \ref{explain-environment-variables}
\end_inset
).
This is not necesary for the other formats.
\layout Itemize
We scale the PDF
\begin_inset LatexCommand \index{PDF}
\end_inset
images to 100%.
I used to scale them down to 65%,
\begin_inset LatexCommand \index{65%}
\end_inset
but this is no longer necessary, after some experimentation with various
scale factors that seem to compensate for this need in the
\begin_inset LatexCommand \url[addd]{addd}
\end_inset
utility.
\begin_inset LatexCommand \index{utility}
\end_inset
See also
\begin_inset LatexCommand \ref{add-density}
\end_inset
.
\layout Itemize
We make use of external SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
entities like %output.print.png; This is a topic of its own which is explained
in detail in
\begin_inset LatexCommand \ref{explain-figures}
\end_inset
.
\layout Standard
A mediaobject
\begin_inset LatexCommand \index{mediaobject}
\end_inset
similar to the above (but without figure id and caption) is inserted whenever
a
\begin_inset Quotes eld
\end_inset
simple
\begin_inset Quotes erd
\end_inset
image, i.e.
one without the float element
\begin_inset LatexCommand \index{element}
\end_inset
with caption,
\begin_inset LatexCommand \index{caption}
\end_inset
is encountered in LyX' SGML.
\begin_inset LatexCommand \index{SGML}
\end_inset
It substitutes a line like
\begin_inset Foot
collapsed true
\layout Standard
I have inserted some blanks in the code snippet in order to prevent my own
scripts (sedscr!) from matching and changing a code that was meant to be
an example ;-)
\end_inset
\layout Code
< graphic fileref="imagename" >
\layout Standard
with a mediaobject
\begin_inset LatexCommand \index{mediaobject}
\end_inset
like
\layout Code
\begin_inset Include \verbatiminput{mediaobject}
\end_inset
\layout Standard
Notice that the text is now simply "Figure", since there was no caption.
\begin_inset LatexCommand \index{caption}
\end_inset
You may change it to something else.
There is also no id available for this mediaobject,
\begin_inset LatexCommand \index{mediaobject}
\end_inset
therefore you cannot cross-reference
\begin_inset LatexCommand \index{cross-reference}
\end_inset
it.
That's why I suggested floats
\begin_inset LatexCommand \index{floats}
\end_inset
in
\begin_inset LatexCommand \ref{LyX-images}
\end_inset
.
\layout Standard
The following sed code
\layout Code
\begin_inset Include \verbatiminput{programlisting}
\end_inset
\layout Standard
will substitute with , while this one:
\layout Code
# Delete the before the tag.
\layout Code
s/ after the tag.
\layout Code
s/<
\backslash
/tgroup><
\backslash
/para>/<
\backslash
/tgroup>/g
\layout Standard
will delete before and before .
\layout Standard
For table captions
\begin_inset LatexCommand \index{captions}
\end_inset
and titles to be output correctly, you have to eliminate
\begin_inset LatexCommand \index{eliminate}
\end_inset
the from any sequence
AND you have to write
a table float (see
\begin_inset LatexCommand \ref{LyX-tables}
\end_inset
, in the inside of which you will have to set the title and the caption
\begin_inset LatexCommand \index{caption}
\end_inset
environment
\begin_inset LatexCommand \index{environment}
\end_inset
on one line, then press , set the environment
\begin_inset LatexCommand \index{environment}
\end_inset
to "Standard" (this will produce the element
\begin_inset LatexCommand \index{element}
\end_inset
we eliminate
\begin_inset LatexCommand \index{eliminate}
\end_inset
here) and continue with the table normally.
A warning about an "end tag for element
\begin_inset LatexCommand \index{element}
\end_inset
"TABLE" which is not open" is the less evil we can get and is harmless (a
LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
bug in 1.2.0, not openjade's):
\layout Code
/<
\backslash
/title>< title >< anchor id="some id" >
\layout Standard
with
\layout Code
\layout Standard
This is done with the following sed code:
\layout Code
s/
\layout Code
\layout Code
\layout Standard
and, as you can easily see, is a customized footer.
Now we proceed to intermix all the above files in the following order into
one HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
document:
\layout Enumerate
part1
\layout Enumerate
title
\layout Enumerate
part2
\layout Enumerate
body
\layout Enumerate
part3
\layout Standard
At the end we get a HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
document that is customized to the design of our site
\emph on
and
\emph default
can easily be checked for compliance to the HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
standards!
\layout SGML
\layout SGML
HTML Parameters and Chunking
\layout SGML
\layout SGML
You can achieve a similar result by setting the html-header-tags parameter
accordingly in the HTML DSSSL stylesheet (
\begin_inset LatexCommand \ref{DSSSL-stylesheets}
\end_inset
,
\begin_inset LatexCommand \ref{explain-DSSSL-stylesheets}
\end_inset
).
The html-header-tags parameter should contain a list of the the HTML HEAD
tags that should be generated.
The format is a list of lists, each interior list consists of a tag name
and a set of attribute/value pairs: '(("META" ("NAME" "name") ("CONTENT"
"content"))).
\layout SGML
\layout SGML
\layout SGML
\layout SGML
\layout SGML
\layout SGML
\layout SGML
\layout SGML
Of course, you would have to change the html-header-tags parameter in the
.dsl file each time before processing a new document.
You would thus need some kind of placeholders that could be identified
and changed with sed to the actually needed values.
However, this amounts to the same effort that we are currently investing
with our method, which also substitutes various placeholders in parts 1-3.
Obviously, such a flexibility must come at some cost.
Feel free to experiment with the other
\begin_inset LatexCommand \url[HTML Parameters for Chunking]{http://docbook.sourceforge.net/release/dsssl/current/doc/html/r1532.htm}
\end_inset
too!
\layout SGML
\layout SGML
\layout Standard
The footer file,
\begin_inset LatexCommand \url[part3]{part3}
\end_inset
, deserves some extra attention, since it illustrates the kind of customization
\begin_inset LatexCommand \index{customization}
\end_inset
and control over your HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
output that you can achieve with this method: it contains the HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
code that prints three icons
\begin_inset LatexCommand \index{icons}
\end_inset
in a row - a W3C
\begin_inset LatexCommand \index{W3C}
\end_inset
\begin_inset LatexCommand \url[HTML validation]{http://validator.w3.org/check}
\end_inset
icon,
\begin_inset LatexCommand \index{icon}
\end_inset
a
\begin_inset LatexCommand \url[Linux Counter]{http://counter.li.org}
\end_inset
icon
\begin_inset LatexCommand \index{icon}
\end_inset
and an icon
\begin_inset LatexCommand \index{icon}
\end_inset
from the
\begin_inset LatexCommand \url["any browser" ]{http://www.anybrowser.org/campaign/}
\end_inset
campaign.
There are three placeholders
\begin_inset LatexCommand \index{placeholders}
\end_inset
in the link for the HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
validation
\begin_inset LatexCommand \index{validation}
\end_inset
icon:
\begin_inset LatexCommand \index{icon}
\end_inset
_DOMAIN_,
\begin_inset LatexCommand \index{_DOMAIN_}
\end_inset
_DIRNAME_
\begin_inset LatexCommand \index{_DIRNAME_}
\end_inset
and _FILENAME_.
\begin_inset LatexCommand \index{_FILENAME_}
\end_inset
These are substituted on-the-fly
\begin_inset LatexCommand \index{on-the-fly}
\end_inset
(using sed one-line commands) with the domain, directory and filename respective
ly of the file whose footer we are currently processing:
\begin_inset LatexCommand \index{processing}
\end_inset
\layout Code
$SED -e "s/_DOMAIN_/$DOMAIN/g" ${DATADIR}/part3 > part3_1.tmp
\layout Code
$SED -e "s/_DIRNAME_/$1/g" part3_1.tmp > part3_2.tmp
\layout Code
$SED -e "s/_FILENAME_/${BASENAME}/g" part3_2.tmp > part3.tmp
\layout Standard
The result is an icon
\begin_inset LatexCommand \index{icon}
\end_inset
that, when clicked, will automatically
\begin_inset LatexCommand \index{automatically}
\end_inset
pass the URI
\begin_inset LatexCommand \index{URI}
\end_inset
of the
\emph on
current
\emph default
file to
\begin_inset LatexCommand \url[The W3C Validator]{http://validator.w3.org/check}
\end_inset
for HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
validation!
\layout SGML
\layout SGML
Please note:
\layout SGML
\layout SGML
A file containing
\emph on
graphical
\emph default
callouts (see
\begin_inset LatexCommand \ref{callouts}
\end_inset
and
\begin_inset LatexCommand \ref{LyX-callouts}
\end_inset
) will NOT be validated! You will get an error saying
\layout SGML
\layout SGML
document type does not allow element "IMG" here
\layout SGML
\layout SGML
In fact, any HTML standard after 2.0 explicitly forbids <img> from
occuring
\emph on
anywhere
\emph default
inside the parse tree of a <pre> element - and that's where exactly
the graphical callouts most often happen to occur! For example, the HTML 3.2 reference specification
states: PRE has the same content model as paragraphs, excluding
images and elements that produce changes in font size, e.g.
IMG, BIG, SMALL, SUB, SUP and FONT.
If you want your document to be fully compliant, you will have to suppress
the use of graphics for the callouts by setting %callout-graphics% to false
in you stylesheet:
\layout SGML
\layout SGML
(define %callout-graphics%
\layout SGML
;; Use graphics in callouts?
\layout SGML
#f)
\layout SGML
\layout SGML
\layout SGML
\layout SGML
Also note that admonitions (see
\begin_inset LatexCommand \ref{admonitions}
\end_inset
and
\begin_inset LatexCommand \ref{LyX-admonitions}
\end_inset
) will be positioned using valign="center", instead of the right one valign="mid
dle", thus leading again to non validation.
But this is easily corrected by the sed script sedscr_v
al that is run near the end of the lyxtox
script.
\layout SGML
\layout SGML
\layout Chapter
Accessibility
\begin_inset LatexCommand \label{accessibility}
\end_inset
\layout Quotation
A broad definition of accessibility
\begin_inset LatexCommand \index{accessibility}
\end_inset
covers people operating
\begin_inset LatexCommand \index{operating}
\end_inset
under situational limitations as well as functional limitations:
\layout Quotation
\emph on
Functional limitations
\emph default
pertain to disabilities,
\begin_inset LatexCommand \index{disabilities}
\end_inset
such as blindness
\begin_inset LatexCommand \index{blindness}
\end_inset
or limited use of the hands.
Functional limitations can be visual, auditory,
\begin_inset LatexCommand \index{auditory,}
\end_inset
physical, or cognitive
\begin_inset LatexCommand \index{cognitive}
\end_inset
(which includes language and learning disabilities).
\layout Quotation
\emph on
Situational limitations
\emph default
relate to the prevailing circumstatnces, environment,
\begin_inset LatexCommand \index{environment}
\end_inset
or device.
These limitations can affect anybody, not just people with disabilities.
\begin_inset LatexCommand \index{disabilities}
\end_inset
Examples include mobile devices and device limitations, such as having
no mouse, or constraining circumstances, such as interacting with a web
site through a computer integrated into a car's dashboard,
\begin_inset LatexCommand \index{dashboard}
\end_inset
wher the use of the hands and eyes is limited.
\layout Quotation
Shawn Lawton Henry,
\begin_inset LatexCommand \url[Constructing Accessible Web Sites]{http://www.webaim.org/news/2002/books/glasshaus}
\end_inset
.
\layout Standard
Something is accessible if it is able to be used by persons with disabilities.
\begin_inset LatexCommand \index{disabilities}
\end_inset
In the context of computing,
\begin_inset LatexCommand \index{computing}
\end_inset
this generally means that the software or device should be compatible
\begin_inset LatexCommand \index{compatible}
\end_inset
with access aids, and should be able to transform itself into a needed format
(see the
\begin_inset LatexCommand \url[Glossary of Bobby]{http://bobby.watchfire.com:80/bobby/html/en/glossary.jsp}
\end_inset
).
The efficiency
\begin_inset LatexCommand \index{efficiency}
\end_inset
with which information can be accessed by people with various abilities
and disabilities
\begin_inset LatexCommand \index{disabilities}
\end_inset
ultimately determines the degree of accessibility
\begin_inset LatexCommand \index{accessibility}
\end_inset
- it is clear that this is a highly subjective matter.
Nevertheless, various criteria
\begin_inset LatexCommand \index{criteria}
\end_inset
have been developed to help determine how accessible a web page is.
I will follow the priorisation of accessibility
\begin_inset LatexCommand \index{accessibility}
\end_inset
errors as suggested by
\begin_inset LatexCommand \url[Bobby]{http://bobby.watchfire.com:80/bobby/}
\end_inset
in
\begin_inset LatexCommand \url[http://bobby.watchfire.com:80/bobby/html/en/readreport.jsp]{http://bobby.watchfire.com:80/bobby/html/en/readreport.jsp}
\end_inset
:
\layout Description
Priority\SpecialChar ~
1\SpecialChar ~
Accessibility\SpecialChar ~
problems seriously affect a page's usability
\begin_inset LatexCommand \index{usability}
\end_inset
by people with disabilities.
\begin_inset LatexCommand \index{disabilities}
\end_inset
A Bobby
\begin_inset LatexCommand \index{Bobby}
\end_inset
Approved rating can only be granted to a site in which none of the pages
contain accessibility
\begin_inset LatexCommand \index{accessibility}
\end_inset
errors.
Bobby
\begin_inset LatexCommand \index{Bobby}
\end_inset
Approved status is equivalent to Conformance Level A for the Web
\begin_inset LatexCommand \index{Web}
\end_inset
Content Guidelines.
\layout Description
Priority\SpecialChar ~
2\SpecialChar ~
Accessibility\SpecialChar ~
problems are those which you should try to fix.
Although not as vital as Priority 1 access errors, the items in this section
are considered important for access.
If you can pass all items in this section in addition to the Priority 1
section, including relevant User Checks, your page meets Conformance Level
AA
\begin_inset LatexCommand \index{AA}
\end_inset
for the Web
\begin_inset LatexCommand \index{Web}
\end_inset
Content Guidelines.
This is the preferred minimum conformance
\begin_inset LatexCommand \index{conformance}
\end_inset
level for an accessible site.
\layout Description
Priority\SpecialChar ~
3\SpecialChar ~
Accessibility\SpecialChar ~
problems are third-tier
\begin_inset LatexCommand \index{third-tier}
\end_inset
access problems which you should also consider.
If you can pass all items in this section in addition to the Priority 1
and 2 sections, including relevant User Checks, your page meets Conformance
Level AAA for the Web
\begin_inset LatexCommand \index{Web}
\end_inset
Content Guidelines.
\layout Standard
If you think this is
\begin_inset Quotes eld
\end_inset
fine print
\begin_inset Quotes erd
\end_inset
that does not have to bother you, you are wrong: no lesser than the Sydney
Organizing Committee for the Olympic Games (
\emph on
SOCOG
\emph default
) thought the same and was fined to pay A$20000 in a case that was brought
to an australian court - see the
\begin_inset LatexCommand \url[Reader's guide to Sydney Olympics accessibility complaint]{http://www.contenu.nu/socog.html}
\end_inset
for the whole story and an explanation of the court's decision, as well
as
\begin_inset LatexCommand \url[Olympic Failure: A Case for Making the Web Accessible]{http://www.tomw.net.au/2001/bat2001.html}
\end_inset
for the web designer's point of view.
\layout Standard
You also cannot argue that this has happened
\begin_inset Quotes eld
\end_inset
too far away
\begin_inset Quotes erd
\end_inset
from you, perhaps on another continent.
The world grows together and all western
\begin_inset LatexCommand \index{western}
\end_inset
nations have passed legislation
\begin_inset LatexCommand \index{legislation}
\end_inset
that is more or less similar on this point, based on the same legal principles
\begin_inset LatexCommand \index{principles}
\end_inset
of unequal treatment (
\begin_inset Quotes eld
\end_inset
discrimination
\begin_inset Quotes erd
\end_inset
;
\begin_inset Quotes eld
\end_inset
unfavourable
\begin_inset Quotes erd
\end_inset
treatment) and unjustifiable hardship (
\begin_inset Quotes eld
\end_inset
undue
\begin_inset Quotes erd
\end_inset
hardship or
\begin_inset Quotes eld
\end_inset
burden
\begin_inset Quotes erd
\end_inset
).
It is a matter of time until similar cases appear to the courts.
I hope you understand by now the following
\layout SGML
\layout SGML
Important fact:
\layout SGML
\layout SGML
Accessibility is NOT optional!
\layout SGML
\layout SGML
\layout Standard
So what can you do to improve the HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
pages created by the tools
\begin_inset LatexCommand \index{tools}
\end_inset
I presented, from the accessibility
\begin_inset LatexCommand \index{accessibility}
\end_inset
point of view? You can pass any of your generated HTML
\begin_inset LatexCommand \index{HTML}
\end_inset
pages to
\begin_inset LatexCommand \url[Bobby]{http://bobby.watchfire.com/bobby/html/en/index.jsp}
\end_inset
for an accessibilty
\begin_inset LatexCommand \index{accessibilty}
\end_inset
test
\begin_inset Foot
collapsed true
\layout Standard
Note, however, that Bobby itself is just an attempt at automating an accessibili
ty test and has not evaded criticism.
In
\begin_inset LatexCommand \url[Accessible shopping]{http://contenu.nu/article.htm?id=1198}
\end_inset
, for example, we read:
\layout Quotation
Bobby is too primitive and unreliable and has a tendency to give false-negative
results, flunking absolutely everything but the simplest text-only sites.
\end_inset
.
You will be presented with a list of errors, sorted according to priority
as above.
I will discuss them for a typical page that was generated with the tools
\begin_inset LatexCommand \index{tools}
\end_inset
I presented in the previous chapters.
\layout SGML
\layout SGML
Mean tip:
\layout SGML
\layout SGML
Not all of the accessibility errors presented in the following sections
can be reproduced when testing a page that was generated with the method
presented here.
To get the full idea, pass the
\begin_inset LatexCommand \url[the Linux Accessibility HOWTO]{http://www.tldp.org/HOWTO/Accessibility-HOWTO/}
\end_inset
pages for a test at
\begin_inset LatexCommand \url[Bobby]{http://bobby.watchfire.com/bobby/html/en/index.jsp}
\end_inset
. ]]>
]]> ]]> ]]> eek!
\layout Standard
For more information on accessibility,
\begin_inset LatexCommand \index{accessibility}
\end_inset
see
\begin_inset LatexCommand \url[the Bobby Accessibility FAQ]{http://bobby.watchfire.com:80/bobby/html/en/faq.jsp}
\end_inset
and the
\begin_inset LatexCommand \url[the Linux Accessibility HOWTO]{http://www.tldp.org/HOWTO/Accessibility-HOWTO/}
\end_inset
.
\layout Section
Priority 1 accessibility errors
\begin_inset LatexCommand \label{priority-1-accessibility-errors}
\end_inset
\layout Standard
No priority 1 accessibility
\begin_inset LatexCommand \index{accessibility}
\end_inset
errors seem to be there for a page that was generated with lyxtox.
\begin_inset LatexCommand \index{lyxtox}
\end_inset
This is good news, as it means that the pages generated this way do not
pose
\emph on
serious
\emph default
obstacles to people with disabilities.
\begin_inset LatexCommand \index{disabilities}
\end_inset
Provided that we didn't miss anything, we can say that the pages have
\begin_inset Quotes eld
\end_inset
Bobby
\begin_inset LatexCommand \index{Bobby}
\end_inset
Approved status
\begin_inset Quotes erd
\end_inset
, or that they conform to Level A of the Web
\begin_inset LatexCommand \index{Web}
\end_inset
Content Guidelines.
\layout Section
Priority 2 accessibility errors
\begin_inset LatexCommand \label{priority-2-accessibility-errors}
\end_inset
\layout Standard
The explanation texts are from
\begin_inset LatexCommand \url[Bobby]{http://bobby.watchfire.com:80/bobby/}
\end_inset
.
Clicking on any of the problems that
\begin_inset LatexCommand \url[Bobby]{http://bobby.watchfire.com:80/bobby/}
\end_inset
reports will produce a more detailed description of how to fix the problem.
In addition to items that
\begin_inset LatexCommand \url[Bobby]{http://bobby.watchfire.com:80/bobby/}
\end_inset
can examine automatically,
\begin_inset LatexCommand \index{automatically}
\end_inset
a number of items that require manual
\begin_inset LatexCommand \index{manual}
\end_inset
examination are presented in the User Checks section of the Bobby
\begin_inset LatexCommand \index{Bobby}
\end_inset
report.
\layout Description
Nest\SpecialChar ~
headings\SpecialChar ~
properly.
This comes from incorrect nesting
\begin_inset LatexCommand \index{nesting}
\end_inset
of the H elements in the authors environment.
\begin_inset LatexCommand \index{environment}
\end_inset
I could not correct this, as it seems to me a stylesheet/Jade problem.
Of course, you could correct it manually, or with a script, but I think
it is better to correct it before it happens.
\layout SGML
\layout SGML
Why it is bad:
\layout SGML
\layout SGML
Some users skim through a document by navigating its headings (the H1,
H2, H3, H4, H5, and H6 elements).
Some access aids extract the headings to create an outline of the page,
allowing users to get an overview and jump quickly to a desired part.
Incorrect nesting of headings will result in an incorrect outline structure
which may disorient users.
Screen readers rely on these tags to interpret the structure of your pages.
See also
\begin_inset LatexCommand \url["Using real headers"]{http://diveintoaccessibility.org/day_27_using_real_headers.html}
\end_inset
by Mark Pilgrim.
\layout SGML
\layout SGML
\layout Description
Use\SpecialChar ~
a\SpecialChar ~
public\SpecialChar ~
text\SpecialChar ~
identifier\SpecialChar ~
in\SpecialChar ~
a\SpecialChar ~
DOCTYPE\SpecialChar ~
statement.
We have corrected this already in
\begin_inset LatexCommand \ref{HTML-validation}
\end_inset
.
\layout SGML
\layout SGML
Why it is bad:
\layout SGML
\layout SGML
Include a document type declaration at the beginning of a document that
refers to a published DTD (e.g., the HTML 4.01 transitional DTD).
The document type declaration should be appropriate to the markup language
you are using.
\layout SGML
\layout SGML
\layout Section
Priority 3 accessibility errors
\begin_inset LatexCommand \label{priority-3-accessibility-errors}
\end_inset
\layout Description
Provide\SpecialChar ~
a\SpecialChar ~
summary\SpecialChar ~
for\SpecialChar ~
tables.
This refers to the revision history table.
Again, it seems to be a stylesheet/Jade problem.
\layout Description
Identify\SpecialChar ~
the\SpecialChar ~
language\SpecialChar ~
of\SpecialChar ~
the\SpecialChar ~
text.
This helps the computer or assistive device present information in a way
that is appropriate to the language and also helps automatic translation
software that translates text from one language into another.
This should already have been fixed with the techniques of
\begin_inset LatexCommand \ref{HTML-validation}
\end_inset
.
\layout Chapter
Mathematics
\begin_inset LatexCommand \label{mathematics}
\end_inset
\layout Standard
Since LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
is a frontend
\begin_inset LatexCommand \index{frontend}
\end_inset
for LaTeX,
\begin_inset LatexCommand \index{LaTeX}
\end_inset
it is no secret that it has exceptional capabilities
\begin_inset LatexCommand \index{capabilities}
\end_inset
when it comes to typesetting mathematics.
\begin_inset LatexCommand \index{mathematics}
\end_inset
However, when it comes to transforming the .lyx document
\begin_inset LatexCommand \index{document}
\end_inset
to different format, the possibilities are rather limited
\begin_inset Foot
collapsed false
\layout Standard
Even if the starting point is not a LyX document, the task of presenting
Mathematics on the Web is not a trivial one, although (or exactly because)
there is a bunch of solutions to choose from, see
\begin_inset LatexCommand \url[Math Typesetting for the Internet]{http://mathforum.org/typesetting/index.html#T}
\end_inset
.
\end_inset
:
\layout Itemize
For HTML,
\begin_inset LatexCommand \index{HTML}
\end_inset
export to LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
and then use
\begin_inset LatexCommand \url[latex2html]{http://www.latex2html.org}
\end_inset
.
This has some disadvantages:
\begin_deeper
\layout Itemize
Excessive memory usage: latex2html
\begin_inset LatexCommand \index{latex2html}
\end_inset
will consume a lot of memory (FIXME: is this still the case?)
\layout Itemize
Most important: We are talking about an SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
document here and all the DocBook
\begin_inset LatexCommand \index{DocBook}
\end_inset
markup
\begin_inset LatexCommand \index{markup}
\end_inset
will be lost if you transform it back to LaTeX
\begin_inset LatexCommand \index{LaTeX}
\end_inset
- just think about the admonitions
\begin_inset LatexCommand \index{admonitions}
\end_inset
(see
\begin_inset LatexCommand \ref{admonitions}
\end_inset
), callouts
\begin_inset LatexCommand \index{callouts}
\end_inset
(see
\begin_inset LatexCommand \ref{callouts}
\end_inset
) and all the other SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
stuff that will be impossible to transform back!
\end_deeper
\layout Itemize
For PostScript®,
\begin_inset LatexCommand \index{PostScript®}
\end_inset
export to LaTeX,
\begin_inset LatexCommand \index{LaTeX}
\end_inset
then create the .dvi file (by calling LaTeX) and then the PS
\begin_inset LatexCommand \index{PS}
\end_inset
file using dvips.
\begin_inset LatexCommand \index{dvips}
\end_inset
That's O.K., since it directly uses TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
and the mathematics
\begin_inset LatexCommand \index{mathematics}
\end_inset
will be as accurately typeset as possible.
\layout Itemize
For PDF,
\begin_inset LatexCommand \index{PDF}
\end_inset
transform the above PostScript®
\begin_inset LatexCommand \index{PostScript®}
\end_inset
file to PDF
\begin_inset LatexCommand \index{PDF}
\end_inset
using ps2pdf,
\begin_inset LatexCommand \index{ps2pdf}
\end_inset
or some commercial program like the Acrobat®
\begin_inset LatexCommand \index{Acrobat®}
\end_inset
Distiller®.
\begin_inset LatexCommand \index{Distiller®}
\end_inset
Taking the roundtrip
\begin_inset LatexCommand \index{roundtrip}
\end_inset
to PS
\begin_inset LatexCommand \index{PS}
\end_inset
in order to arrive at PDF
\begin_inset LatexCommand \index{PDF}
\end_inset
has some serious drawbacks, though (FIXME: which ones?) After all, pdfjadetex
\begin_inset LatexCommand \index{pdfjadetex}
\end_inset
was developed to avoid
\begin_inset LatexCommand \index{avoid}
\end_inset
exactly these drawbacks, so it would be nice if we could use it.
\layout Itemize
For RTF,
\begin_inset LatexCommand \index{RTF}
\end_inset
no way seems to exist to get mathematics
\begin_inset LatexCommand \index{mathematics}
\end_inset
from LyX
\begin_inset LatexCommand \index{LyX}
\end_inset
in this format.
\layout Standard
The above is not a satisfactory situation.
Even if we
\emph on
can
\emph default
get mathematics
\begin_inset LatexCommand \index{mathematics}
\end_inset
in some formats, we would have to abandon the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
framework we have been using so far.
It would be nice if we could continue to write in a DocBook
\begin_inset LatexCommand \index{DocBook}
\end_inset
SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
document in LyX,
\begin_inset LatexCommand \index{LyX}
\end_inset
using all the excellent math
\begin_inset LatexCommand \index{math}
\end_inset
typestting capabilities
\begin_inset LatexCommand \index{capabilities}
\end_inset
of TeX/LaTeX and then export to whichever of the above formats through our
usual scripts and tools
\begin_inset LatexCommand \index{tools}
\end_inset
like openjade,
\begin_inset LatexCommand \index{openjade}
\end_inset
pdfjadetex
\begin_inset LatexCommand \index{pdfjadetex}
\end_inset
etc.
In fact, as the following example already shows, we can:
\layout Standard
\begin_inset Formula \begin{equation}
{\displaystyle }\int _{a}^{b}x^{2}dx=\frac{1}{3}(b-a)^{3}\label{eq2}\end{equation}
\end_inset
\layout Standard
Let's see what is going on, from the SGML
\begin_inset LatexCommand \index{SGML}
\end_inset
point of view, when you type an equation like
\begin_inset LatexCommand \ref{eq2}
\end_inset
\begin_inset Foot
collapsed false
\layout Standard
as you can see already, cross-references to equations (and with them also
equation labels and titles) do work for all formats too with the method
I will describe.
\end_inset
in LyX:
\begin_inset LatexCommand \index{LyX}
\end_inset
when exported to SGML,
\begin_inset LatexCommand \index{SGML}
\end_inset
this equation yelds the following MathML
\begin_inset LatexCommand \index{MathML}
\end_inset
code:
\layout Code
\begin_inset Include \verbatiminput{equation}
\end_inset
\layout Standard
There are some remarks due here:
\layout Itemize
The TeX
\begin_inset LatexCommand \index{TeX}
\end_inset
code that typesets the equation is enclosed between the tags.
We will make heavy use of this fact later.
\layout Itemize
The equation is again output, this time between the