Document processing with LyX and SGML

%ISOnum; %ISOamso; ]> Document processing with LyX and SGML A quest for the Holy Grail of technical documentation Chris Karakas www.karakas—online.de LyX SGML sgmltools docbook dsssl stylesheet formatting linux jade openjade latex unix pdfjadetex jadetex jadetex.cfg sed runsed sedscr density pdf ps rtf txt html dvitops Computer Modern sgml pdfjadetex accessibility bibliography validation dbtextmath refdb index generation htmltidy coolthumbs document processing localization internationalization A method for single-source publishing using LyX and SGML is presented: LyX is used as a comfortable graphical SGML editor. Once the document is exported to SGML from LyX, it undergoes a series of transformations through sed and awk scripts that correct and enhance the SGML markup, compute the Index, insert the Bibliography and the Appendix and take care of the correct invocation of openjade, pdftex, pdfjadetex and all the other necessary programs for the generation of HTML (chunked or not), PDF (with images, bookmarks, thumbnails and hyperlinks), PS, RTF and TXT versions. All aspects of document processing are handled, including automatic Index generation, display of Mathematics in TeX quality both online and in print formats, as well as the use of bibliographic databases with RefDB. Special care is taken so that the document processing is as transparent to the user as possible - the aim being that the user writes in LyX, then presses a button, and the lyxtox script does the rest. 1.4 20.09.2007 CK Added sections on start and end files, HTML headers and footers. Changed chapters resp. sections: Shortcomings and bugs, Main part, LaTeX errors. New files: example.start, example.end, part1, part2, part3, keycombos, keycombos2, acronyms, acronyms2, productnames, productnames2, applications, applications2. Changed files: lyxtox. 1.3 12.03.2006 CK Files changed: sedscr, lyxtox, lyxtox-print-pdf.dsl, lyxtox-print.dsl, awkscr_insert_index_items, ck-style.css, jadetex.cfg, addd. New sed scripts, sedscr_apa and sedscr_ima, take care of alt and title attributes in the HTML format, so that the resulting files remain W3C compliant. Previous versions might not be, because a phrase element inside a textobject was not used for the alt attribute, due probably to a bug in the DSSSL stylesheets. sgmltools is not needed anymore. Corrected a bug in awkscr_insert_index_items that would break index entry insertion after the first entry. Added code in sedscr that will take care of keycombos, acronyms, productnames and index entries of key combinations. Use of a new script, coolthumbs, for the creation of antialiased thumbnails in PDF. Further changes in: The final step, Unprintable characters, SP_ENCODING in "Set environment vars", Using Type 1 fonts, Choosing the right font encoding, Using True Type fonts, Optimal PDF—Figures, Acrobat Reader 5 does not display thumbnails. Added a whole chapter on Localization (work in progress). Simplified addd script. Generated new Index (almost 2000 entries!). 1.2 25.06.2004 CK The tidy scripts have been deactivated in lyxtox. They mess up other areas like callouts or displayed code — but they are still in the package. Corrections to sedscr and awkscr_math scripts to handle inequalities correctly: now writing a < b > c in Math Mode will not result in an Openjade parser error about an "undefined element b". The jadetex.cfg file now contains examples of how to get customized headers and footers in PDF through the fancyhdr package (works only partly — ideas welcome) and also an example of using the underscore package to get underscores correctly in links — but this messes up the smiley names which also contain underscores. 1.1 13.06.2004 CK Discussion of newer LyX versions (newer than 1.2.0), as well as new errors and warnings. Inclusion of sedscr_tidy and sedscr_tidy2 sed scripts that tidy up the SGML code. The lyxtox script contains calls to those two scripts, otherwise no changes have been made to the scripts. 1.0 19.02.2004 CK Initial public release. Terms of distributionDisclaimerNo liability liabilityfor the contents of this documents can be accepted. Use the concepts, examples and other content at your own risk. As this is a new edition of this document,document there may be errors and inaccuracies, that may of course be damaging to your system. Proceed with caution, and although this is highly unlikely, the author does not take any responsibility for that.All copyrights are held by their respective owners, unless specifically noted otherwise. Use of a term in this document documentshould not be regarded as affecting the validity validityof any trademark trademarkor service mark.markNaming of particular products or brands should not be seen as endorsements.endorsements Formats IMPORTANT: Script and Stylesheet Downloads! If you want to download only the scripts and stylesheets of this project, without any documentation, get the following archive: TAR.GZ (Compressed TAR Archive), scripts and stylesheets only (no documentation) This document documentis available in the following formats:HTML (HyperText Markup Language), many HTML HTMLfiles (one for every section), for viewing with any browser HTML (HyperText Markup Language), one big HTML HTMLfileTXT (ASCII Text)RTF (Rich Text Format)PDF (Portable Document Format)PS.GZ (Compressed Postscript)SGML (Standard Generalized Markup Language) (with the Appendix and the Bibliography)LYX (LaTeX frontend LyX) (with the AppendixThe bibliography of this document is generated through RefDB directly in SGML, so that there is no LyX file for it available.) RTF: Page numbers In order to get correct page numbers in Microsoft Word, type the following after opening the document: CTRL END CTRL A F9 In Word Viewer 97, you must instead do: CTRL END ALT V N ALT V P See The OpenJade RTF backend for more details. IMPORTANT: Downloads for offline reading! If you want to download the HTML or RTF formats for offline reading, you will need to download the images as well - PNG for HTML and BMP for RTF, including the callouts! To save you the hassle, I have compiled the following zipped tar archives for offline reading (these contain the scripts and stylesheets too): TAR.GZ (Compressed TAR Archive), many HTML files with images and scripts TAR.GZ (Compressed TAR Archive), one big HTML file with images and scripts TAR.GZ (Compressed TAR Archive), SGML file with images and scripts TAR.GZ (Compressed TAR Archive), RTF file with images and scriptsA tarball tarballcontaining all the above formats, including images and scripts, is also available: TAR.GZ (Compressed TAR Archive), All files LicenseCopyright Copyright© 2004-2006 Chris Karakas. Permission is granted to copy, distribute and/or modify this document documentunder the terms termsof the GNU GNUFree Documentation LicenseLicenseGNU Free Documentation License, Version 1.2 or any later version published by the Free Software FoundationFoundationFree Software Foundation; with no Invariant InvariantSections, with no Front-Cover Front-CoverTexts, and with no Back-Cover Texts. A copy of the license can be found in , as well as at the GNU Free Documentation License . Availability of sources and supportSee for the modifiable modifiablesources sourcesof this document.document Pose your questions in my <productname>Linux</productname> Forum! I've been working on this project since 2000. It is still work in progress. I don't have an "installation script" or similar - you will have to read this document carefully and try the solutions offered. If you have questions, patches, suggestions, problems or (better) solutions, come to my Linux Forum and post them there. I look forward to your feedback! CreditsThe DSSSL DSSSLstylesheets (, ) owe a lot to the DocBook Guide of the Debian Newbiedoc Project, Mandrake's manual-print.dsl manual-print.dslfile (see Customizing Document Production for a detailed description) and the DBTeXMath method. Also, the CSS file for DocBook, ck-style.css, got important elements from the Newbiedoc CSS file for DocBook and Mark Pilgrim's influential dive into Accessibility.RefDB gave me a real solution to my bibliography bibliographyproblem (see , ).Part of is taken from the LyX LyXTutorial, section 2.2 (“Environments”).Part of is taken from the lynx lynxmanpage.The introduction text to is taken from the TeX TeXFAQ FAQitem on How to approach errors. The material in is taken from the TeX TeXFAQ FAQitem on the structure of TeX errors. contains material from the TeX TeXFAQ FAQitem on the fatal format file error. The description of the common LaTeX LaTeXerror messages and warnings in uses material from the chapter on “ LyX LyXand LaTeX LaTeXerrors” of the Extended Features manual manualfor LyX,LyX available from LyX' Help menu.Many other sources sourceshave been used for this work. See for some of them. Although not all of them are present in , they are all quoted at the aproppriate place inside the document.document Please follow the links given there. is taken from W3C's working draft CSS3 Paged Media Module, version of Dec. 18th 2003 and is Copyright Copyright© 2003 W3C (MIT, ERCIM, Keio), All Rights Reserved. Used with permission according to W3C document licence.The CSS file for DocBook that is used in this document document, ck-style.css, uses QBullets in links. See on how to do this. Thanks to Matterform MatterformMedia for providing QBullets QBulletsfor free. If you plan to use them on your website, please observe the QBullets usage terms.The examples for admonition admonitionin the Conventions Section () were taken from the Section on admonitions of the DocBook Guide of the Debian Newbiedoc Project.The method I present is an original work of mine, that arouse out of the desire to “write once, create many” (see how it all started in my Jade installation notes and how it ended in ). I wanted to have a document documentprocessing processingchain with all the bells bellsand whistles, including the ability to process Mathematics Mathematics(), bibliography bibliography(see ) and Index (see ), controlled from one source and one click of a button. My solution uses many well-known methods and packages,packages but the “glue” is original. AknowledgementsThanks to all authors, whose software is used in this work. Their example is a continuous source of inspiration inspirationto me:All software developers, whose software is used in the preparation of this document:document LyX,TeX,LaTeX,pdfTeX,hyperref,openjade,pdfjadetex,thumbpdf,DocBook DSSSL stylesheets,RefDB,DBTeXMath,collateindex,sgmltools,HTML tidy,HTML split,sed,runsed,awk,dvips,coolthumbsand all the standard software used in a GNU/Linux system.Many thanks to Gareth Anderson and Jeremy Malcolm for their comments, suggestions and bug reports. Jeremy Malcolm pointed to missing .start and .end files in the online 1.3 version - many thanks! Thanks also to Gloomy,Gloomy for the moral support during the hard times. Conventionsadmonitions Admonitions Admonitionsare little pictures used to emphasize emphasizesomething of importance to the reader. The four types used are: Note Using a hammer to put together your computer is bad. Tip Do not hit your thumb with the hammer, it hurts! Important Watch where you're swinging that hammer! Caution Hitting your thumb with a hammer may lead to an unwanted trip to the hospital! Warning Do not, under any circumstances, admit that you hit your own thumb with a hammer. The ridicule you will face is astounding! access keys Access keys enable navigation through the document,document without relying on a mouse. The following keys have been given special meaning in this document:documentP Previous page.N Next page.H Home of the document document(Table of Contents).U Up (takes you one level up the section hierarchy).If you also happen to be reading the document documentfrom its original location, then the following access keys can also be used:S Start (takes you to the author's start page).T The current (“This”) page, without the Sitemenu on the left.M The current page in a frameset, where the left frame contains a Menu. To use the access keys, you have to simultaneously press a modifier key, which may vary from browser to browser. For example in NN6+/Mozilla, the modifier key is ALT, so you have to use ALT N to go to the next page, and ALT P to come back. In other browsers such as IE6, the access keys just give focus to the associated link, so the sequence becomes ALT N Enter . Try it, you'll like it! ]]> ]]> ]]> ]]> Inline graphic AbbreviationsSGML SGML(Standard Generalized Markup MarkupLanguage) The superset supersetof all the markupmarkup languages, SGML SGMLis a generalized schema for tagging structure data in an application-independent application-independentway.XML XML(eXtensible Markup MarkupLanguage) XML is an SGML SGMLfor tagging structured data according to an accompanying DTD DTDwhich defines the collection of tags and the rules rulesfor ordering and nesting nestingthem. This allows for labelling domain-specific domain-specificdata in a consistent consistentway which allow s new applications to match the input file with the DTD DTDto parse, validate validateand manipulate the data stream.streamDSSSL DSSSL(Document Style Specifications Specificationsand Semantics SemanticsLanguage) A scheme-basedscheme-based language for rendering renderingSGML SGMLdocuments, DSSSL DSSSLcode will specify the placements and font manipulations for each tag in the specified DTD.DTD While many shops prefer the XSL XSLmethod of doing the same formatting formattingfunction, DSSSL DSSSLis the most common method in the DocBook DocBookand OpenJade OpenJadeworld.XSL XSL(eXtensible Style Language) A text format specification specificationlanguage which is itself an XML; many sites prefer XSL XSLto DSSSL DSSSLbecause the same editing tools toolsused for the document documentcan also be used on the stylesheet.stylesheetDocBook DocBookA document documentdefinition markup markuplanguage which defines a set of SGMLSGML tags for the specific purpose of producing technical documentation. DocBook DocBookis used with a DSSSL DSSSLor XSL XSLto create document documentsource files which will be portable across different display methods, for example, one documentdocument which renders in Postscript, Windows Windowsand Java JavaHelp, PDF,PDF RTF,RTF ASCII ASCIIand HTML.HTML IntroductionDo you want to create professionally formatted documents? Tired of always having to change the font settings, to insert or delete pagebreaks,pagebreaks to format your text for printing, monitor, or web view? Do you find yourself spending hours of your life into formatting formattingissues that you wish you never had to be conftonted with? Did you, during your editing efforts, ever get the uncomforting feeling that you are inventing the wheel wheelfor th 39th time? Well, in fact you are! This document documentwill show you how to use the power of Open Source tools toolslike LyX and sgmltools to create the documents you've dreamed of, while, as a nice side effect, concentrating on what deserves most of your attention: Content, not Formatting! I will describe a method by which all you have to do is to write your documentdocument in LyX, then run the . lyx lyxfile through a script that will produce the SGMLSGML source and, from it, the HTML,HTML TXT,TXT RTF,RTF PDF PDFand PS PSformatted documents, complete with table of contents, embeddedembedded pictures, fonts,fonts thumbnails thumbnails(for PDF) and other goodies.The general idea When writing LyX LyXdocuments, formatting formattingshould be the last thing on your mind. Concentrate on writing a clear and concise document.document The sgml parser parserwill take care of the formatting.formattingWe've all heard of WYSIWYG.WYSIWYG LyX is WYGIWYM.WYGIWYM WYGIWYM WYGIWYMstands for "What You Get Is What You Mean". This means if you mean for text to represent source code you assign it a source code environment environment(Lyxese for style), and it formats the way you meant it to. You needn't worry about formatting formattingduring the writing of your document.document If you don't like the way it looks upon finishing and printing it out, you can change the way styles map to formatting,formatting and those styles will consistently change throughout the document.document Line of attack The method described here follows a line of attack defined by the following:We will put everything in a shell script. We don't want to bother about anything else. We want to ponder comfortably upon the meaning of life while drinking drinkingsome coffee coffeeor tea,tea watching our computer do the work for us - personally, a very rewarding experience :-)We will use sed to correct LyX' SGML SGMLoutput. The more we are able to correct, the more SGML SGMLfeatures we get out of our plain vanilla vanillaLyX.LyXWe use the sgmltools package which hides a lot of details from the end user, giving nonetheless all the power of the involved tools.toolsThe current version of the lyxtox script does not make use of sgmltools, due to the need of processing intermediate results for the integration of Mathematics, Bibliography etc., as well as problems in the processing that turned out to be very difficult to debug, see runbib not working from lyxtox.We will adapt the DocBook DSSSL stylesheets to our personal needs and taste.The end product shall be a directory ready to upload to our web server with all files, links, images and formats necessary. Required software The method described in this document documentrequires a well-configured well-configuredLinux system, armed with a heavy machinery machineryof various software packages:packages LyX LyX (of course!), see . You MUST use the 1.2.0 version of LyX, offered in ! Newer versions will NOT work, unless you tweak the sed scripts of this package.DocBook , see .sgmltools , see (currently not needed).Openjade, pdfjadetex pdfjadetexand jadetex jadetexsee .TeX TeXand LaTeXLaTeX , see .sed, runsed and awk, see .thumbpdf, see .dvips, ghostscript ghostscriptand ImageMagik,ImageMagik see .Lynx, the text browser,browser see . Lynx Lynxwill be used to convert convertthe HTML HTMLoutput in plain text, thus giving us the TXT TXTversion of our document.documentHTMLtidy, see RefDB, if you want to use bibliographies bibliographieswith entries taken from a bibliographybibliography server and formatted automatically automaticallyaccording to the author guidelines of the Journal you are submitting your paper,paper see . Perl, for the Index generation through the collateindex.collateindexpl script (see ).coolthumbs, if you want antialiased thumbnails in PDF.In the following, I will describe the required software in more detail. Of course, I cannot cover all details. See the documentation that comes with each tool and, for an alternative description, the Apendix of DocBook: The definitive Guide. Version-specific tweaks! The method I will describe (more precisely, the sed script that corrects LyX' SGML output) is tailored to LyX 1.2.0-91, a rather dated version I use from a SuSE RPM. If you have a newer version of LyX, you will almost certainly have to tweak sedscr, since SGML output has been corrected in the newer 1.3.x versions. But the important thing is the method, not the version-specific tweaks, which you should be able to figure out yourself with a firm knowledge of sed, regular expressions and the help of this guide! ]]> ]]> ]]> ]]> Inline graphic Currently, you should stick to the rather dated 1.2.0 version from one of the RPMs in , for reasons discussed in LyX 1.3.4 not suitable for Mathematics work in DocBook.I have not investigated the portability portabilityof the method across operating operatingsystems. I have developed and tested it on a (rather dated) SuSE Linux 7.3 system and, more recently, on a SuSE Linux 9.0 system. Portability Portabilityto other operating operatingsystems is dependent on the availabilityavailability of the software needed and the scripting scriptingfacilities offered. Any porting portingefforts are welcome.LyX In case you are wondering what LyX LyXis, here is what http://www.lyx.org says on the subject:

LyX LyXis an advanced open source document documentprocessor that encourages an approachapproach to writing based on the structure of your documents, not their appearance. LyX LyXlets you concentrate on writing, leaving details of visual layout layoutto the software.LyX LyXruns on many Unix Unixplatforms,platforms OS/2, and under Windows/Cygwin (this port requires an X server). It can also run natively nativelyon Mac OS X, thanks to the Qt/Mac library.LyX LyXproduces high quality, professional professionaloutput -- using LaTeX,LaTeX an industrialindustrial strength typesetting engine, in the background;background LyX LyXis far more than a front-end to LaTeX,LaTeX however. No knowledge of LaTeX LaTeXis necessary to use LyX,LyX although it will give a user more power.LyX LyXis stable and fully featured. It has been used for documents as large as a thesis,thesis or as small as a business letter. Despite its simple GUI GUIinterface (available in many languages), it supports tables, figures,figures and hyperlinked hyperlinkedcross-references, and has a best-of-breedbest-of-breed math matheditor.

Get a suitable version of LyX LyXavailable fo your distribution.distribution I prefer to get the source RPM,RPM like lyx-1.2.0-91.lyx-1.2.0-91src.rpm and then compile it with Update: Versions 1.3.2 and 1.3.4 of LyX LyXdo NOT work for our purposes! Version 1.3.2 brings the error Counter does not exist: sect1 and version 1.3.4 does not contain the “begin{equation}” commands in the alt part of the equation element element(see LyX 1.3.4 not suitable for DocBook and Mathematics work), thus making all our efforts to use the DBTeXMathDBTeXMath method (see ) fail in vain. I am currently in contact with the LyX LyXdevelopment team to iron these problems out. In the meantime, if you are having difficulties with your own LyX LyXversion, you can use the following RPMs to install version 1.2.0-91 which is guaranteed to work:LyX v. 1.2.0-91 i386 for SuSE 7.3 binary RPMLyX v. 1.2.0-91 i586 for SuSE 9.0 binary RPMIf you want to compile version 1.2.0-91 for your own Linux system, here are the source RPMs:LyX v. 1.2.0-91 i386 for SuSE 7.3 source RPMLyX v. 1.2.0-91 i586 for SuSE 9.0 source RPMNote that the two source RPMs are practically identical, up to the lyx.lyxspec file and an extra dif file for src/frontends/xforms/GUIRunTime.C. This is due to the renaming of some packages packagesunder SuSE 9.0, which makes changes in the “# usedforbuild” part of the spec file necessary, as well as to the check for the xforms package version that accepts only versions 0.88 and 0.89 - while in SuSE 9.0 we have already arrived at xforms 1.0-137! See How to compile an older version for a newer system in RPM for the details.You might have to install doxygen doxygen(SuSE: Series d, install with YaST). The rebuild process of rpm creates a new RPM RPMpacket of LyX,LyX as one can see from the last lines of the long output:Install the newly created RPM RPMpackage as usual, either with YaST,YaST or with Please note: As you can see from the above output of the rebuild command, LyX requires the following packages and libraries to be already installed on your system: Requires: tetex te_latex /bin/bash /bin/sh /usr/bin/perl /usr/bin/python ld-linux.so.2 libICE.so.6 libSM.so.6 libX11.so.6 libXpm.so.4 libc.so.6 libc.so.6(GLIBC_2.0) libc.so.6(GLIBC_2.1) libc.so.6(GLIBC_2.1.3) libforms.so.0.89 libjpeg.so.62 libm.so.6 libm.so.6(GLIBC_2.0) libstdc++-libc6.2-2.so.3 On SuSE systems, if you install Lyx with the above rpm command, it is a good idea to either run SuSEconfig,SuSEconfig or just the part of SuSEconfig SuSEconfigthat is relevant to LyX,LyX /sbin/conf.d/SuSEconfig.lyx:On other systems, you may have to reconfigure reconfigureLyX by hand: This is done from the menu Edit-->Reconfigure. See .Now your LyX LyXis up-to-date. You just have to write your document documentwith it. Since LyX LyXcomes with a well written Tutorial (written itself in LyX), as well as User Guide (both easily acessed from the Help menue), I will not delve into the details of writing with LyX LyXhere. DocBook Here is what the LDP-Author-Guide says about DocBook:DocBook

To explain what DocBook DocBookis, we must first take a look at what SGML SGMLand XML are, and their relationship to DocBook.DocBookThe Standard Generalized Markup MarkupLanguage (SGML) is a language that is based on embedding embeddingcodes within a document.document In this way, it is similar to HTML,HTML but there is where any similarities end. The power of SGML SGMLis that unlike WYSIWYG WYSIWYG(What You See Is What You Get), you don't define things like colors, or font sizes, or even some kinds of formatting.formatting Instead, you define elements (paragraph, section, numbered list) and let the SGML SGMLprocessor and the end program worry about placement, colors, fonts,fonts and so on. HTML HTMLdoes the same thing, and is actually a subset of SGML.SGML SGML SGMLhas really three parts that make it up. First is the Structure, which is what is commonly called the DTD,DTD or Document Type Definition. The DTD DTDdefines the relationship between each of the elements (or tags). The DocBook DocBookDTD,DTD used to create this document,document is an example of this. The DTD DTDlists the rules rulesthat the content must follow. Second is the DSSSL DSSSLor Document Style Semantics Semanticsand Specification SpecificationLanguage. The DSSSL DSSSLtells the program doing the rendering renderinghow to convert convertthe SGMLSGML into something that a human can read. It tells the renderer to convert converta title tag into 14 point bold if it is going to RTF RTFformat, or to turn it into a <h1> tag if it is going to HTML.HTML Finally there is the Content, which is what gets rendered by the SGML SGMLprocessor and is eventually seen by the user. This paragraph paragraphis content, but so is a graphic image, a table, a numbered list, and so on. Content is surrounded by tags to separate each element.element

The following features must be installed to make DocBook DocBookusable (the RPMRPM names and versions I mention refer to the ones I have installed on my SuSE Linux 7.3 system): The DocBook DocBookDTD DTDversion 4.1 or version 3.1. LyX, starting from version 1.2.0, uses version 4.1 while older versions use version 3.1. (RPM: docbook_4-4.1-97 docbook_4-4.1-97and docbook_3-3.1-98 docbook_3-3.1-98respectively. I have also html-dtd-2001.11.7-0 installed, ). More recent versions, like docbook_3-3.1-468 and docbook_4-4.2-362 also seem to work O.K.The ISO ISOentities,entities that define some standard SGML SGMLentities (e.g. >, <, etc.) (RPM: iso_ent-2000.11.03-122. The newer iso_ent-2000.11.03-531 also seems O.K.)The Norman Walsh's DocBook DSSSL modular stylesheets(RPM: docbook-dsssl-stylesheets-1.78-78).docbook-dsssl-stylesheets-1.72-34. The 1.72 and 1.78 versions are known to work. The 1.79 version has some problems (for example, it does not display the information in <othercredit> elements, see Trouble with new version of lyxtox scripts), so it is not recommended. You can get the 1.78 version from docbook-dsssl-stylesheets-1.78-78.Jade/jadetex/openjade (version 3.0) (RPM: openjade-1.3-289,openjade-1.3-289 jade_dsl-1.2.1-369, jade_dsl-1.2.1-369,jadetex-3.11-65). See also SGMLtools-lite SGMLtools-lite(RPM: sgmltools-lite-3.0.2-164). Currently not needed, see also .Of course, you have to satisfy all the dependencies of the above packages.packages This can be quite a nightmare if you choose to do it “by hand”, as you can read in my Jade installation notes. sgmltools sgmltools-lite sgmltools-liteis a package whose purpose is to simplify the document documentcreation process from SGML SGMLto some other format. It takes the complexity complexityof the various commands involved and takes care of all the invocations invocationsand the options required. I used sgmltools-lite-3.0.2-164.sgmltools-lite-3.0.2-164 However, the current version of the scripts does not use sgmltools sgmltoolsanymore, so you don't need it. Some code of the print.dsl print.dslfile of this package was used in the lyxtox lyxtoxstylesheets, but again, no changes are needed on your part. Openjade, pdfTeX and JadeTeXOpenjade Openjaderenders the SGML SGMLdocuments (that we will export from LyX) to the various other formats, like HTML,HTML RTF,RTF LaTeX LaTeXetc. I use:openjade-1.3-289: renders and validates the SGML SGMLcode based on the DTD DTDand DSSSL DSSSLstylesheet. pdfTeX-0.13d. I had to upgrade upgradeto for the same reason I had to upgrade upgradeopenjade.JadeTeX-3.11-65 JadeTeX-3.11-65(needed to process the TeX TeXformat created by openjade openjadewhen called with the “-b tex” option). Due to an error in a rather exotic situation (see ), I recently had to upgrade upgradepdfTeX pdfTeXto version 1.11b, or more precisely (Web2C 7.5.2) 3.141592-1.11b, and JadeTeX JadeTeXto version 3.13 - definitely recommended.See the LDP LDPAuthor's Guide for more details on these programs. TeX and <application>LaTeX</application> LyX LyXis a LaTeX LaTeXfront end. It was primarily designed with TeX TeXand LaTeX LaTeXin mind. It provides a more or less WYSIWYG WYSIWYGenvironment environmentfor TeX/LaTeX. Further, since we will use the TeX TeXformat to create PDF PDFdocuments through pdfjadetex,pdfjadetex we will need as much TeX TeXrelated machinery machineryas we can get. This practically means that you should install all the TeX TeXand LaTeX LaTeXpackages that come with your didtribution.didtribution For example:te_etex-1.0.7-319texinfo-4.0-268tetex-1.0.7-319te_latex-1.0.7-319te_pdf-1.0.7-476db2latex-0.5.1-15 Dvips, Ghostscript and ImageMagikYou'll need dvips dvipsfor the creation of the PostScript�PostScript�PostScript� is a registered trademark of Adobe Systems Incorporated, and is the main page description language in the UN*X world. format. You will need Ghostscript Ghostscriptfor the creation of thumbnails thumbnailsfor PDF PDF(see ), as well as for various conversions of your images (see ), where ImageMagik ImageMagikwill also play a central role:typewriterdvipspart of the tetex package on my SuSE system, see .typewriterghostscripttypewriterxdvipart of the tetex package on my SuSE system, see .typewriter ghostview ghostview(package gv-3.5.8-718)The latter two programs are previewer for files in Dvi and PostScript� PostScript�format. If you don't know what a dvi-file dvi-fileis, you've probably also never worked with LaTeX LaTeXand should read the Tutorial document documentbefore proceeding further. thumbpdfThe thumbpdf thumbpdfpackage by Heiko OberdiekOberdiek installs the Perl program thumbpdf thumbpdfon your system. With the help of thumbpdf thumbpdfand Ghostscript Ghostscript(which should also be installed), you can create thumbnails thumbnailsfor the PDF PDFdocument (to be seen when you click on the “thumbnails” register card in Acrobat� Acrobat�ReaderAcrobat� is a registered trademark of Adobe Systems Incorporated. ). Thumbnails are embedded embeddedimages of the document's pages, drawn in small size and resolution.resolution Their purpose is to facilitate navigation through the document document(of course only if the PDF PDFviewer supports them). Thumbnails will be created automatically automaticallyby the lyxtox script and will be embedded embeddedin the PDF PDFdocument whithout any user intervention (see for a detailed description). You just have to take care that the thumbpdf thumbpdfpackage is installed. You can download thumbpdf thumbpdffrom CTAN: thumbpdf. After download and extraction of the package, the filesreadme.txt (documentation)thumbpdf.tex (pdftex)thumbpdf.sty (pdf(e)tex, pdf(e)latex, (e)tex, (e)latex)should be moved totexmf/doc/generic/thumbpdf/readme.txttexmf/tex/generic/thumbpdf/thumbpdf.textexmf/tex/generic/thumbpdf/thumbpdf.styrespectively. The Perl script itself, thumbpdf.pl,thumbpdf.pl may be renamed to thumbpdf:thumbpdfEnsure that the execute permission is set:then move the file to a directory where the shell can find it (according to the PATH PATHenvironment environmentvariable, e.g. /usr/local/bin/):Requires:Perl5 Perl5(version 5 of the perl perlinterpreter).Ghostscript:Thumbnail generation: version 5.50 or better 6.0.Thumbnail inclusion with ps2pdf:ps2pdf version 6.0.pdfTeX. Sed and awksed is a stream streameditor. A stream streameditor is used to perform basic text transformations on an input stream stream(a file or inpu t from a pipeline). We will use sed extensively through scripts like runsed, that is a wrapper wrapperaround sed that takes a “sed script”, like sedscr, containing sed commands, as a first argument and the file to be transformed as a second. awk searches files for lines (or other units of text) that contain certain patterns.patterns When a line matches one of the patterns,patterns awk awkperforms specified actions on that line. awk awkkeeps processing processinginput lines in this way until it reaches the end of the input files. We will use awk awkto split the sed processed files into header, body bodyand footer, in order to be able to manipulate these parts separately, before reassemblying them into a final document documentfor further processing.processingMost probably, your Linux distribution distributionhas already installed sed and awkawk for you. In case it hasn't, use the package management managementtool of the distributiondistribution to install them, or compile them from the source, if you feel like. LynxLynx is a fully-featured fully-featuredWorld Wide Web Web(WWW) client for users running cursor-addrescursor-addressable, character-cell character-celldisplay devices (e.g., vt100 terminals,terminals vt100 emulators emulatorsrunning on Windows Windows95/NT or Macintoshes,Macintoshes or any other "curses-oriented" display). It will display hypertext hypertextmarkup markuplanguage (HTML) documents containing links to files residing on the local system, as well as files residing on remoteremote systems running Gopher, HTTP,HTTP FTP, WAIS, and NNTP NNTPservers. Current versions of Lynx Lynxrun on Unix,Unix VMS, Windows Windows95/NT, 386DOS and OS/2 EMX.We will use Lynx Lynxto transform the generated HTML HTMLversion of our documentdocument to the plain text version, so you should have Lynx Lynxinstalled on your system. HTML tidyWhen editing HTML HTMLit's easy to make mistakes. Wouldn't it be nice if there was a simple way to fix these mistakes automatically and tidy tidyup sloppy sloppyediting into nicely layed out markup?markup Well now there is! Dave Raggett's HTML HTMLTIDY TIDYis a free utility utilityfor doing just that. It also works great on the atrociously hard to read markup markupgenerated by specialized HTML HTMLeditors and conversion tools tools(like the ones we will be using), and can help you identify where you need to pay further attention on making your pages more accessible to people with disabilities disabilities(see ).Tidy Tidyis able to fix up a wide range of problems (which is very good if you are trying to produce valid HTML,HTML as described in ) and to bring to your attention things that you need to work on yourself. Each item found is listed with the line number and column so that you can see where the problem lies in your markup.markup Tidy Tidywon't generate a cleaned up version when there are problems that it can't be sure of how to handle. These are logged as "errors" rather than "warnings". See htmltidy for more details. We call htmltidy htmltidyfrom within the lyxtox script (see for the details). Download it and install it somewhere in your path.path Refdb Alternative way for Bibliography You are not confined to using RefDB whith my lyxtox script. If you don't feel like building your own bibliographic database, you can skip this section and just supply a bibliography.lyx file together with your LyX document. Set the process_RefDB variable in lyxtox to "0" and it will use your own bibliography.lyx to produce a bibliography.sgml file, instead of trying to create one automatically through RefDB. The bibliography.lyx file should then contain the SGML code for the references list, in the SGML environment of LyX. The GNU/Linux Command-Line Tools Summary HOWTO uses this approach, for example. See the bibliography.lyx and bibliography.sgml files in the Formats section of GNU/Linux Command-Line Tools Summary HOWTO. Be warned however, that writing a bibliography file with all your references in SGML is not fun and does not solve the problem of formatting those references to the style of the journal (or medium) you are submitting your work (for this you would need an extra DSSSL stylesheet). In the long run, these two disadvantages will work against you to the point of being a real pain, especially if you submit the same work to more than one journals with conflicting formatting style guidelines regarding references. Read Who should use refdb? - it will help you decide whether you need RefDB or not. RefDB problems Currently, version 0.9.4-pre5 of RefDB worked fine for some time, then, after adding a few citations and a few pages more to this document, refdbxp started to segfault. I tried 0.9.4, just released, but got installation problems and a "could not read from refdbd" message each time I tried anything. However, this does not mean that the following is untested or that RefDB does not work - during the short time I got it to work, it worked fine, as did all the scripts and stylesheets I present here. It also does not mean that refdbxp will segfault on your system - as always, YMMV. RefDB RefDBis a reference database databaseand bibliography bibliographytool for SGML,SGML XML, and LaTeX/BibTeX documents. It allows users to share databases over a network. It is lightweight lightweightand portable to basically all platforms platformswith a decent C compiler. And it's released under the GNU GNUGeneral Public License License .RefDB RefDBis currently known to build and run out of the tarball tarballon at least these platforms:platformsLinuxFreeBSDNetBSDSolaris Solaris(using gcc)OSX/DarwinWindows+CygwinRefDB RefDBappears to be the only available tool to create HTML,HTML PostScript,PostScript PDF,PDF DVI,DVI MIF, or RTF RTFoutput from DocBook DocBookor TEI TEIsources sourceswith fully formatted citations citationsand bibliographies bibliographiesaccording to publisher's specifications. If you want to include bibliographies bibliographiesin LyX LyX, RefDB RefDBis the way to go. The standard way, using BibTeX,BibTeX will NOT work in our SGML SGMLcontext.To install RefDB,RefDB it is highly recommended to get the newest version currently available. Due to various bugs,bugs versions older than 0.9.4-pre5 0.9.4-pre5will not work. By the time you read this, version 0.9.4 should be out and you should use that one - here I will describe the installation procedure procedurefor the 0.9.4-pre50.9.4-pre5 version:Download RefDB RefDBfrom the RefDB downloads page, along with the Perlmod Perlmodpackage, currently RefDB-perlmod-0.3.tar.gz RefDB-perlmod-0.3.tar.gz(you can skip the latter if you don't require the MARC and Pubmed Pubmedimport filters). First, install any Perl modules you need, such as RefDB-perlmod,RefDB-perlmod MARC::Record MARC::Recordand MARC::Charset:MARC::CharsetFor RefDB-perlmod:RefDB-perlmod:RefDB-perlmodYou get an output like:After that, install perlmod withFor the other two modules, MARC::Record MARC::Recordand MARC::Charset,MARC::Charset the installation can be done in the usual manner for CPAN CPANmodules:I could not install MARC::Charset MARC::Charsetbecause it needs Perl 5.8.0 - however, this does not interfere with my method here, so you can safely skip it.After the Perl modules, you must install the libdbi libdbipackage: Go to the libdbi homepage and download the latest libdbi libdbiversion libdbi-0.7.2.tar.gz.libdbi-0.7.2.tar.gz. Then go to the libdbi-drivers homepage and download the latest libdbi-drivers libdbi-driverspackage libdbi-drivers-0.7.1.tar.gz.libdbi-drivers-0.7.1.tar.gz Then, uninstall uninstallany previous libdbi libdbior RefDB RefDBpackage with from their source directory and you are ready for the installation of libdbi:libdbiAdapt the configure options to your situation, those above are the ones I use in my old SuSE system. The installation of libdbi-drivers libdbi-driversis accomplished similarly:Note the “--with-mysql” and “--with-pgsql” options in the configure command above: for every libdbi libdbidatabase driver you plan to use, you have to insert the aproppriate “--with-” option. Type “./configure --help” to see all options. However, it makes no sense to say you want libdbi-drivers libdbi-driversto be compiled with the pgsql pgsqldriver, for example, if you don't have PostgreSQL PostgreSQLinstalled and running. In the "make check", you must give the database databaseadministrator's name and password password(not that of a user, as in the 0.6.x version). Just accept the other values offered:The output of “make check” starts with: ]]>and continues with the outcome of various tests (create a database,database select a database,database list tables etc.). After all tests are completed successfully, you will (hopefully) seeFinally, you are ready for the installation of RefDB RefDB(instructions pertain to version 0.9.4-pre5:0.9.4-pre5You must adapt the options of the configure command to your situation. Read the excellent RefDB documentation for more details.This completes the RefDB RefDBinstallation - but you are not done yet! You must create the refdb refdbdatabase and grant grantyourself all privileges on it. In MySQL,MySQL on the mysql mysqlpromt, you type:On the shell prompt, type:to populate the refdb refdbdatabase. Note that the refdb refdbdatabase is NOT the database databaseyou will use for your bibliography bibliographyentries, but a central repository repositoryof information necessary for RefDB's internal functions. The refdb name has changed between versions! For version 0.9.4-pre5, the database is called refdb, NOT refdb1! That "central repository" of RefDB used to be called "refdb", then it became "refdb1" and in 0.9.4-pre5 "refdb" again. I didn't know this and I kept on getting errors saying without telling me why! After I changed in src/refdba.c to I was able to see that the reason was that it was trying to connect to refdba, and NOT to refdba1: The next step is to create the global configuration files. There are half a dozen of them, one for each RefDB RefDBtool. They are very well commented, so you will not encounter any problems in setting up the options there.Further, you will have to import some citation citationstyles. There are only two readily available: J.Biol.Chem.xml J.Biol.Chem.xmland Eur.J.Pharmacol.Eur.J.Pharmacolxml,Eur.J.Pharmacol.xml both in the /usr/src/refdb-0.9.4pre5/styles directory. To import them, start the RefDB RefDBadministration tool refdba refdbaand type:in the refdba refdbaprompt. Then, you can check which styles you have using the liststyle liststylecommand in refdba:refdbawhich will produce:You must also create at least one database databasethat will hold your bibliographicbibliographic entries. For example, to create the ck_refdb ck_refdbdatabase, start refdba refdbaand type on the refdba refdbaprompt:If you want to enter the bibliographic bibliographicentries via a web interface interfaceand not from the command line, you have to configure Apache Apacheby inserting the following in its configuration file (adapt it to your situation accordingly): ]]> ]]>then copy some programs in the cgi-bin cgi-bindirectory:and restart Apache.ApacheTo test RefDB,RefDB start the refdbd refdbddaemon with:You should see something like:If you don't have a database databaseserver correctly configured, although you asked for support of it in the libdbi-drivers libdbi-driversconfigure command on compilationcompilation time, you will get an error like the above for PostgreSQL PostgreSQL(libpgsql.so). In refdba,refdba typeIf the server outputs look like the following:then you know that everything is working fine. See the RefDB documentation for more details. Required preliminary stepsJust installing the required software (see ) will not do the trick. There are quite a few details that will need your attention and will have to be configured correctly. In this section I will discuss all those preliminary steps. Don't worry, you will need to do them only once. Then, you may forget them forever.Reconfigure LyX Before you write anything in LyX,LyX and after having installed all the required packages packages(see ), you should reconfigure reconfigureLyX to let it take into account all this software. Just do Edit-->Reconfigure. Check the output of this command (if you did not put LyX LyXin the background,background you should see it in the x terminal you started LyX LyXin). You should see among others:If you don't, you miss the docbook DSSSL DSSSLstylesheets (see ) or something else went wrong. Don't continue before you fix this. Adapt the DocBook DSSSL stylesheets There are a lot of changes that must be done in the DocBook DocBookDSSSL DSSSLstylesheets. The best way to incorporate them is to keep copies of the following files in your working directory:lyxtox-print.dsl, lyxtox-print-pdf.dsl, lyxtox-print-ps.dsl, lyxtox-print-rtf.dsl, lyxtox-print-txt.dsl and lyxtox-print-howto.dsl. These control the style of the print formats (i.e. all formats except HTML). They contain some code from the original print.dsl print.dslfile of the sgmltools-litesgmltools-lite package (located in /usr/share/sgml/stylesheets/sgmltools/print.dsl, see ), but also code from the RefDB RefDB(), DBTeXMath DBTeXMath() and the Mandrake Mandrakeprint-manual.dsl.lyxtox-html.dsl: this file will be used as the DSSSL DSSSLstylesheet to control the HTML HTMLoutput in many HTML HTMLfiles (one HTML HTMLfile per section).lyxtox-onehtml.dsl: this file will be used as the DSSSL DSSSLstylesheet to control the HTML HTMLoutput in one big HTML HTMLfile (Jade option: nochunks).See for an explanation of the changes that have been incorporated in the above files. Make sure that their location is correctly set in lyxtox:Also, you must insert "PDF"PDF in the notation.class notation.classof the /usr/share/sgml/docbook_4/dbnotn.mod file: ]]>If you still use LyX LyXv.1.1.x, you should change /usr/share/sgml/docbook_3/dbnotn.mod to include “PDF” in the list of accepted file extensions:extensions ]]>If you omit this change, you will get a 'value of attribute "FORMAT" cannot be "PDF"' error when trying to produce a PDF PDF(due to a 'format=”PDF”' attribute attributein the code for images, see ). This error is also discussed in .Open each one of the DSSSL DSSSLstylesheets that you copied in your working directory and check if the paths pathsused there are correct. The affected files are:lyxtox-html.dsllyxtox-onehtml.dsllyxtox-print.dslCheck whether the paths pathsin the ENTITY declarations are correct for your system. For example, in lyxtox-html.dsl you must check whether the following ENTITY declarations are correct: ]]> ]]>Practically, this amounts to checking the right path pathfor refdblib.dsl and refdbvar.dsl in your system. Repeat this check for the other two files. Stylesheet location and RefDB Currently, if you use RefDB, the above stylesheets have to be in the current directory (i.e. where also lyxtox is in). This is because in this case the refdb-html.dsl and refdb-print.dsl will be used. They are automatically generated from the RefDB stylesheet (e.g. J.Biol.Chem.dsl) which, in turn, is also automatically generated by RefDB (see for all the details). refdb-html.dsl and refdb-print.dsl will point to the above lyxtox-*.dsl stylesheets for further processing, but they don't do it through a catalog (at the moment). Thus the lyxtox-*.dsl files have to be in the same directory, unless you change the generating awkscr_refdb_html and awkscr_refdb_print scripts. Adapt pdftex.cfg pdftex pdftex(part of the te_pdf package which you hopefully installed in ) uses a file pdftex.cfg (located in /var/lib/texmf/pdftex/config/pdftex.cfg on my system), which contains amongst other things the names of the so-called “map files”. There is currently only one of these files there, pdftex.map (located in /var/lib/texmf/dvips/config/pdftex.map on my system). It contains the mapping between the short names (like hlsu8r) and the long PostScript� PostScript�names (like LucidaSans-Bold) of the fonts.fonts It must contain the mappings for the Computer Modern fonts fonts(lines like “ cmr9 cmr9CMR9 <cmr9.pfb”), in order to be able to use them in PDF.PDF Normally, this is already done by your distribution distributionand you don't need to change anything. On other systems, the mapping for the Computer Modern fonts fontsmay be located in a different file (perhaps under the name cm.map). Check your TeX/LaTeX documentation. Adapt jadetex.cfgjadetex.cfg is the configuration file for pdfjadetex pdfjadetex(see ). You should copy it in your working directory. You will definitely want to adapt jadetex.cfg to reflect the right author, keywords etc. for the PDF PDFdocument (scroll to the end of jadetex.jadetexcfg to find the relevant code): baseurl={http://www.karakas-online.de/mySGML/}, pdftitle={Document processing with LyX and SGML}, pdfsubject={Linux,document formatting}, pdfauthor={Copyright \textcopyright 2003, Chris Karakas}, pdfkeywords={Linux SGML LyX DSSSL DocBook} The baseurl will be added in front of any relative WWW link that you have in your PDF document. The pdftitle will appear as the title of your PDF document in Acrobat� Reader under File-->Document Info-->General. The pdfsubject will appear as the subject of your PDF document in Acrobat� Reader under File-->Document Info-->General. 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. 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. You can see the above information when you choose File-->Document Info-->General, see .

General document info. ]]> ]]> ]]> ]]> General document info. General document info. These are the minimum required changes for jadetex.jadetexcfg. You may change a lot of other settings for the PDF PDFoutput. The jadetex.jadetexcfg file itself contains a lot of code which you may use as a point of departure for your explorations (don't forget to backup the original before you change it!). Some of the more advanced settings are discussed in . But if you are not interested in the gory details, you are already done with the above. Check paths of catalog files Check the lyxtox script and adapt the catalog catalogfiles paths paths(see ) to your situation. You may already have a master catalog cataloginstalled on your system by your distribution.distribution In my SuSE system, I have one in /etc/sgml/catalog. Open the file and pick the catalogs you need, adding them to the SGML_CATALOG_FILES variable as follows:Not all catalogs from /etc/sgml/catalog should be added to SGML_CATALOG_FILES,SGML_CATALOG_FILES although in theory, you should be able to just add the master catalog catalogand let it do the rest (FIXME: I had problems with that, need to investigate why). Also, add the RefDB RefDBcatalog only if you have RefDB RefDBinstalled: Adapt the preample Put the following lines in the preample preample(menue Layout-->Preample) of your LyX LyXdocument: ]]> ]]> ]]> ]]> ]]> ]]> ]]>If you don't want to do this for each and every document documentyou write in LyX,LyX you can put the above lines at the very start of the template file docbook_article.lyx (located in /usr/share/lyx/templates in my system) as follows: ]]> ]]> ]]> ]]> ]]> ]]> ]]> IMPORTANT: If you use RefDB (), you have to change the bibliography entity to basename.bib.sgml, where basename is the name of your file, without the ending. Example: if your file is myTemplate.lyx and you use RefDB, then the bibliography entity should be declared as follows in the preample: ]]> See , , and for an explanation of this magic magicregarding the Appendix, Bibliography, Index and the figures figuresrespectively. Admonitions For graphical admonitions admonitions(see ), you will need to copy the admonitions admonitionsgraphics. These are expected in /usr/share/sgml/docbkdsl/images by pdfjadetex,pdfjadetex as the following error shows:This is because the lyxtox-print.dsl file (see ) contains the linesThe images themselves are installed in /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/images by the package docbook-dsssl-stylesheets-1.72-34 docbook-dsssl-stylesheets-1.72-34on my SuSE 7.3 system. Instead of changing the location in lyxtox-print.dsl, I have decided to copy them: Warning: DO NOT use a relative path, as in the commented line below! You will get errors of the form LaTeX Warning: File `./images/important.pdf' not found on input line 5223. although the files will be there. Most curiously, the images may nevertheless be included, but thumbpdf will fail! The above is valid only for the print formats (like PDF,PDF PS,PS RTF RTFetc.). For the HTML HTMLoutput we use the lyxtox-html.dsl and lyxtox-onehtml.dsl, for many HTML HTMLfiles and one HTML HTMLfile respectively. There, the directory of the admonition admonitiongraphics is specified with the following code:Create a directory with the same name as the . lyx lyxfile in your working directory, but without the . lyx lyxending:Change to that directory and extract the admonitions archive:This will create a subdirectory subdirectory“images”, with all admonition admonitiongraphics in it, in all the formats needed. Alternatively, you could copy the admonition admonitionimages in the various formats into the images directory. The images contained are:If you have only the GIF GIFversions of the admonitions,admonitions you can use the adddscr script as follows:Instead of “gif”, you can use whatever version you happen to have (like “png”, “bmp” etc). The adddscr adddscrscript will convert convertthe format you designated into PNG PNGfirst, then use the addd script to add density density(see and ) and finally will create all the other formats with ImageMagik ImageMagik(see ).See for the background.background Callouts You can control various parameters regarding callouts calloutsin the .dsl files (see and ). You should especially check the path pathto the callout images. In our case, it has to be “./images/callouts” , i.e.the images will be located in a subdirectory subdirectoryof the images directory, which in turn will be located inside the directory of the HTML HTMLfiles. Change to the myTemplate myTemplatedirectory (we created it in ) and extract the callouts archive:This will create a subdirectory subdirectory“images/callouts”, with all callouts calloutsgraphics in it, in all the formats needed. Alternatively, you could copy the admonition admonitionimages in the various formats into the images/callouts directory. The images contained are:If you have only the GIF GIFversions of the callouts,callouts you can use the adddscr script:Instead of “gif”, you can use whatever version you happen to have (like “png”, “bmp” etc). The adddscr adddscrscript will convert convertthe format you designated into PNG PNGfirst, then use the addd script to add density density(see and ) and finally will create all the other formats with ImageMagik ImageMagik(see ). Add density to imagesSince you will be creating various output formats from the same SGML SGMLsource, you are going to need not only the png images, but also the pdf ones. Those need a special preparation in order to be embedded embeddedin the PDF PDFdocument: we need to “add densitydensity” to them. This is one of the many reasons that the tools toolsdescribed in this documentdocument fail to incorporate images in PDF PDFwhen ran “out-of-the-box”.The gory details behind this are described in . Here, I will describe the most straightforward way to get working images for your PDF PDFdocuments. For this purpose I have written a small utility,utility which I call addd (for add density). Download it, make it executable and put it somewhere like /usr/local/bin. It calls two programs which you should also have installed on your system: convert convert(package ImageMagick) and eps2png. You should also download the adddscr script, make it executable and put it in the images directory. The adddscr adddscrscript expects a parameter,parameter which should be one of the usual image file endings endingslike “gif”, “png”, “jpg” etc. The idea is the following: you have all your images under the images directory and they are all of the same type, say GIF.GIF Then you just callThe adddscr adddscrscript will convert convertall GIFs in the current directory to PNGPNG format, then call the addd utility utilityto add the right density densityto each image. Since addd produces .pdf and .eps from a given .png image and adddscr adddscrproduces an additional .bmp, you end up with all the required image formats with the right properties for the subsequent inclusion in the various documents, be it PS,PS PDF PDFor RTF.RTF You may then delete your GIFs, you will not need them anymore (see Burn All GIFs.If your images are all of type JPG,JPG just call in the images directory. If you just produced a sole image, you must call addd manually and then convert convertthe png file to bmp. Example: Suppose you have just produced an image in JPG JPGformat, say myimage.jpg. Then do: Caution 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! Run sed and awk scriptsCopy the following files in your working directory:sedscr (a sed script that corrects LyX' exported SGML SGMLfile), sedscr_top (a sed script you can use to eliminate eliminatethe “_top” target attribute attributeof links whose link text contains a given regular expression string of your choice),sedscr_val (a sed script that effects all changes that are necessary for the HTMLHTML document documentto validate validateas conforming to the HTML HTMLstandards,standards see for this subject),sedscr_ris (a sed script that can create full RIS RISdatasets out of a file containings URLs - included only for your convenience and not absolutely necessary for our method, see more details in , and ),sedscr_abi (a sed script that will append appendthe SGML SGMLentities (as defined in the Preample,Preample see ) for the Appendix, the Bibliography and the Index at the end of the corrected SGML SGMLfile, see ),sedscr_app (a sed script that will insert a label labeland title in the Appendix, as well as change the end tag from </article> to </appendix>),sedscr_cit (a sed script that will create a LyX LyXfile containing citation citationlabels, to be used in citations),sedscr_bib (a sed script that corrects the Appendix code, for the case we insert a bibliography bibliographyafter it, see ),awkscr_math (an awk awkscript that prepares the Mathematics Mathematicsparts, like equations,equations for further processing,processing see , , ),awkscr_refdb_html and awkscr_refdb_print, used to create the necessary stylesheets if you are using RefDB RefDB(see , and ),sedscr_tidy, a very rudimentary script that tries to reduce line length of the SGMLSGML file by inserting newlines after <para> and </para> tags. Also sedscr_tidy2, another sed script, to correct the first tidy script. You would run these two as follows:However, they don't produce correct results, so the calls are commented in the lyxtox script.sedscr_ima, a sed script that is used to produce another sed script, sedscr_img (sedscr_img is not included, as it is produced dynamically from the SGML file of the document and the sed script sedscr_ima).sedscr_apa, a sed script that is used to erase <acronym>, <productname> and <application> tags from the alt and title texts in the dynamically created sed script sedscr_img.lyxtox, the main script that creates all documents using the above scripts and and the rest of the required software (),Copy runsed somewhere like /usr/local/bin. lyxtox and runsed should be executable.runsed is a simple script that I modified from the original runsed runsedscript found in O'Reilly's Unix Power Tools, Chapter Chapter34, Section 3 “Testing and Using a sed Script: checksed, runsedrunsed”. It simply takes two filenames as an argument and then runs sed on the second file using the first file as a sed script:A sed script is a script that tells sed what to do. sed, sed,in turn, is a powerful line editor suitable for batch processing processing(see ). You don't have to worry about runsed,runsed sedscr sedscrand lyxtox.lyxtox You may want to have a look at lyxtox,lyxtox just to ensure that all paths pathsare correctly set and that you get some idea of what it does. It is very well commented. The gory details are in . Set up your start and end scriptsYou are going to need two scripts, with the endings endings.start and .end respectively, and the same basename basenameas your LyX LyXdocument (without the LyX LyXending). Example: if you are processing processingmyLyxfile.lyx, then you can create myLyxfile.start and myLyxfile.end. These files can contain code of your choice to be executed at the start and at the end of the lyxtox script. The .start file should contain at least the lines:\©<\/a> 2002-2006 Chris Karakas<\/a>" ]]>The values for TITLE, FORMATSFILE, COPYRIGHT, HOMEFILE etc. are used in the HTML file generation. You may need them or not, depending on whether you use them in your part1, part2 and part3 files, which are responsible for your custom header and footer (see ).The values for process_math and process_RefDB are necessary. If you don't use mathematics (see ), set process_math to 0. If you don't use RefDB (see ), set process_RefDB to 0.See example.start for an example of a .start file.The .end file (myLyXfile.end in our example above) is there for you to add whatever additional processing steps you like. I use it to create all the tar archives found in , but you can use it for whatever you like. Here is a typical .end file that you would use to massage the HTML files a bit (with sedscr_val, in order to make them HTML standards compliant) and then create all those tar archives found in :See example.end for an example of an .end file. Set up custom headers and footersUse part1, part2 and part3 to customize your headers and footers. You will not need to touch part1, unless you wish to change the DOCTYPE setting. You will, however, certainly want to adapt part2 (for the headers) and part3 (for the footers). These files are full-blown examples that demonstrate what you can do to enhance navigation and searching:For the header (part2):Add META tags, for example for the character encoding (), the CSS () or favicon: ]]> ]]> ]]> ]]>Add a logo image: Karakas Online

]]>Add a site search field that lets your visitors do a site-specific Google search. First some Javascript constants: ]]> ]]> ]]> ]]> ]]>and then a few lines further down, the actual search field: ]]> ]]> ]]> ]]>Start ]]>" width="18" height="9" hspace="2" /> ]]>_TITLE_ ]]>" width="18" height="9" hspace="2" /> ]]>This page ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]>Display Sitemenu ]]> ]]> ]]> ]]> ]]>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: ]]>chinese ]]>french ]]>german ]]>italian ]]>japanese ]]>korean ]]>portuguese ]]>spanish ]]> ]]>DOMAIN is set in the .start file (see ), DIRNAME is replaced in lyxtox with the parameter you passed it: part2_2.tmp ]]>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 everything 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: part2_3.tmp ]]>Add some “breadcrumbs”, i.e. navigation links separated by a “|”. 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: ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]>Send to a friend | PDF | RTF | PS | TXT | Other formats ]]> ]]> ]]> ]]> ]]>For the footer:Add a timestamp and a “permalink” (a permanent link, which people can use to link to the page): ]]> ]]> ]]> ]]> ]]> ]]>http://_DOMAIN_/_DIRNAME_/_FILENAME_ ]]> ]]> ]]> ]]> ]]> ]]> ]]>Add breadcrumb navigation links (“Start”, “Document title”, “This page”) and Google site search: ]]> ]]> ]]> ]]>Start ]]>" width="18" height="9" hspace="2" /> ]]>_TITLE_ ]]>" width="18" height="9" hspace="2" /> ]]>This page ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]>Display Sitemenu ]]> ]]> ]]> ]]> ]]>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: ]]>chinese ]]>french ]]>german ]]>italian ]]>japanese ]]>korean ]]>portuguese ]]>spanish ]]> ]]>Finally, add some icons. Some of them point to the validator services of the W3C (see ). 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 “http%3A%2F%2F_DOMAIN_%2F_DIRNAME_%2F_FILENAME_” for the CSS validator, but is is enough to use “http://validator.w3.org/check/referer” for the HTML validator. And don't miss the special link to “validate your browser”! :-) ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]>GNU Free Documentation Licence" title="GNU Free Documentation Licence"> ]]> ]]> ]]> ]]>Linux Counter registered user #314103" title="Linux Counter"> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> How to set the constants in the part* files 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. Set up your bibliographic databaseIf you don't want to use RefDB, 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 bibliographicreferences each time by hand in pure SGML SGMLin a separate file, see . If you want to use RefDB,RefDB to take advantage of all the automated processing processingoffered to you by a bibliographic database,database RefDB RefDBand the lyxtox script, there is some prelimnary work to do: before you use your bibliographicbibliographic treasures in citations citationsand the reference list, you have to import them into the RefDB RefDBdatabase you created during installation of the RefDB RefDBpackage (see ). Further, you must give the name of your database databaseas the value of the RefDB_dbRefDB_db variable in lyxtox and also set process_RefDB to “1”, indicating you wish bibliographic bibliographicprocessing processingthrough RefDB.RefDBAdding references boils down to running the addref command with proper input files. The input files have to be valid RIS RISfiles. They may contain one or more RIS RISdatasets.An example of a RIS RISfile is refdb.ris. A typical bibliographic bibliographicentry in the RIS RISformat looks like:Each line starts with a two-letter two-lettertag followed by the string “ - “ (two spaces, a dash, and another space). Each RIS RISdataset starts with the TY TY(type) tag and ends with the ER ER(End of Reference) tag. In between, tag sequence is arbitrary. The meaning of the tags is:TY: Citation type. Can attain many values, some of the most usual being:ABST (abstract reference)BOOK (whole book reference)COMP (computer program)DATA DATA(data file) ELEC ELEC(electronic citation)GEN (generic)JOUR (journal/periodical reference)ID: Unique citation citationID IDstring. This can either be explicitly set by you, or automatically automaticallyset by the RefDBRefDB system. It plays the same role as the citation citationkey in the standard methods provided by LyX LyXfor citation citationpurposes (see ).AU: Author. Synonym: A1.A1TI: TitleKW: KeywordRP: Reprint status. Can be one of IN FILEFILENOT IN FILEFILEON REQUEST MM/DD/YYPB: PublisherUR: URL URL(for electronic citations)Multiple AU AUand KW KWtags are possible. For a complete list of the RIS RIStags and their possible values see Writing RefDB data input - here is a more elaborate example of a bibliographic bibliographicentry in RIS RISformat, taken from this document:documentTo build your own bibliographic bibliographicdatabase, you thus need all your references in the RIS RISformat. If you found your reference in the web edition of some scientific scientificjournal, or one of the specialized bibliographic bibliographicdatabases on the Internet, like PubMed, chances are that you will be able to copy the RIS RISversion of the bibliographicbibliographic 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 filtersshipped with RefDB,RefDB use the Web Webinterface interface(which you installed in ), or write all those tags and their values by hand.For automatic import, RefDB RefDBoffers the following input filters:filtersdos2unix: A simple shell script to convert converttext files like RIS RISdocuments from DOS-style line endings endingsto Unix-style line endings. Most refdb refdbtools need their input files with Unix-style line endings.endings This is a valuable tool to import reference databases from Windows Windowsreference managers.med2ris.pl: A tool to convert convertPubmed Pubmeddata in both the tagged taggedand the XML format to RIS.RISbib2ris: A tool to convert convertBibTeX data to RIS.RISdb2ris: A tool to convert convertreference data in DocBook DocBookSGML/XML documents to RIS.RISmarc2ris.pl: A tool to convert convertreferences in MARC format to RIS.RISTo import all references from a RIS RISfile called, say, refdb.refdbris, start refdbc and then type:Once you have populated your own bibliographic bibliographicdatabase 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.refdbris (this will overwrite any existing refdb.refdbris file, so take care):0 ]]>Open the refdb.refdbris file with a text editor and examine it. Pay special attention to the values of the ID IDfield - we will use this field in a somewhat tricky way to refer to the bibliographic bibliographicentries from LyX.LyX How this is done, is explained in . Use a CSS for DocBook The following two definitions in the HTML HTMLstylesheets (see ) specify the CSS CSSthat is to be used for HTML HTMLoutput:Of course, you may decide that you don't need a CSS,CSS in which case you should define %stylesheet% %stylesheet%to “#f”. But this is only part of the story! You may discover that your HTML HTMLdocuments still need the ck-style.css,ck-style.css even if you set %stylesheet% %stylesheet%to “#f”! This is because of the extra processing processingthat the header, body bodyand footer are subject to, as described in . You will have to change part2 too to reflect the right CSS.CSSTalking about a “right” CSS CSSfor DocBook,DocBook you may find out that there not so many out there available - see CSS for DocBook for a rare example. The problem is that the HTML HTMLproduced by the tools toolspresented here uses its own classes which don't seem to be widely used outside DocBook.DocBook Instead of inventing the wheel wheelfor the third time, just grab my ck-style.css 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. Use coolthumbscoolthumbs is a small, fine script that will create antialiased thumbnailsthumbnails for your PDF PDFdocument (those icons iconsthat look like miniature copies of your pages, in the left column of Acrobat Reader, besides the bookmarks bookmarkstab). Whithout it, the thumbnails thumbnailswill look “high contrast” or “edgy”. Using coolthumbs will produce hight quality thumbnails,thumbnails with the help of Ghostscript Ghostscriptand The GIMP (which, of course, you must also have installed, if you decide to use it). You can get coolthumbs from the Linux LaTeX-PDF HOW-TO (I would love to include it here, but unfortunately its copyright copyrightnotice does not allow it explicitly).Install coolthumbs in, say, /usr/local/bin. Then enter its location in lyxtox lyxtoxand set the use_coolthumbs parameterparameter to 1:These are the values I had to change in my copy of coolthumbs:The location of The GIMP:Width and height of the thumbnails:thumbnailsSome explanation on the choice of those values is due here: the ISO/DIN paper papersizes (in mm) for the various DIN paper papersizes are shown in (taken from Paper size).ISO/DIN paper sizes A B C 0 841x1189 1000x1414 917x1297 1 594x841 707x1000 648x917 2 420x594 500x707 458x648 3 297x420 353x500 324x458 4 210x297 250x353 229x324 5 148x210 176x250 162x229 6 105x148 125x176 114x162 7 74x105 88x125 81x114 8 52x74 62x88 57x81 9 37x52 44x62 40x57 10 26x37 31x44 28x40

From we see that if, as the author of coolthumb says, the values of 82/106 are "pretty much dead-on" for US Letter paper,paper then the values 74/105 must be just as "dead on" for DIN paper paper(we try to match one paper paperside 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,paper but DIN papers have the same aspect ratio throughout the whole paper paperrange (see ), 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.paper

ISO-DIN paper sizes. ]]> ]]> ]]> ]]> ISO-DIN paper sizes. ISO-DIN paper sizes. DPI (dots-per-inch) value for the thumbnails:thumbnailsThis 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:Of course, YMMV (=Your Monitor May Vary ;-)).I use thumbpdf thumbpdfversion 3.2, so I set Writing in LyX, thinking in SGML You have now installed the required software (see ) and taken the required preliminary steps (see ) to ensure that everything is in place and configured correctly. In this chapter I will describe how write in LyX LyXin order to achieve the desired results. This may at first look trivial,trivial but is not: LyX LyXis a frontend frontendfor LaTeX.LaTeX It was designed with TeX/LaTeX in mind, not SGML.SGML The TeX TeXlanguage and the LaTeX LaTeXmacros describe a document documentnot only from the structural point of view (using markup markupthat expresses facts like “this is a paragraphparagraph”, “this is an itemized itemizedlist”), but also from the descriptive one (“use 12pt 12pthere”, “indent 5cm there”). SGML,SGML on the other side, separates structure from style. It is clear that when you export a TeX/LaTeX document documentnot each and every TeX/LaTeX construct that is possible in LyX LyXwill find its equivalent in SGML.SGML 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 processingprocessing of LyX' SGML SGML(done by lyxtox using runsed and sedscr). Remember this each time you try something in LyX,LyX only to find out that it does not work in SGML.SGML Use the .lyx version of this document as a template 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 ). Load the LyX version 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 LyX environmentsDifferent parts of a document documenthave different purposes; we call these parts environments. Most of a document documentis made up of regular text. Section (chapter, subsection,subsection etc.) titles let the reader know that a new topic or subtopic subtopicwill be discussed. Certain types of documents have special environments.environments A journal article will have an abstract,abstract and a title. A letter will have neither of these, but will probably have an environmentenvironment that gives the writer's address.Environments are a major part of the “What You See Is What You Mean” philosophy philosophyof LyX.LyX A given environment environmentmay require a certain font style, font size, indenting,indenting line spacing, and more. This problem is aggravated, because the exact formatting formattingfor 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 standardsfor indenting;indenting and bibliography bibliographyformats can vary widely. LyX LyXlets you avoid avoidlearning all the different formatting formattingstyles.The Environment box is located on the left end of the toolbar (just under the File menu). It indicates which environment environmentyou're currently writing in. While you were writing your first document,document it said “Standard,” which is the default environment environmentfor text. Now you will put a number of environments environmentsin your new document documentso that you can see how they work. You'll do so with the Environment menu, which you open by clicking on the “down arrow” icon iconjust to the right of the Environment box. Don't use the "Paragraph" environment! Use "Standard" instead! Using "Paragraph" interferes with the changes that runsed and sedscr try to effect in the SGML code as exported by LyX. Writing paragraphs in LyX is treated in - although there is actually nothing more to say on this subject for the moment. Just choose "Standard" and write. ]]> ]]> ]]> ]]> Inline graphic An important thing to keep in mind is that whatever environment environmentyou set in LyX, it will NOT, per se, affect the formatting formattingof your document! LyXLyX environments environmentstell something about the structure of the document,document never about its formatting formatting(at least not in the context we will be using them here, i.e. as equivalent to SGML SGMLtags). Thus, an environment environmentof “Standard” will induce the <para> tag when exported to SGML SGMLfrom LyX.LyX The following quote from the sgml-tools sgml-toolsmailing list deals with a common misconception misconceptionof <para> (see Use of <Para> within <ListItem> mangles list items):

> I think the definition of <Para> means to start on a new line and break on a new line.At the risk of being pedantic,pedantic I think you're making a mistake of interpreting DocBook DocBookmarkup markuptags as having any bearing on format, which they do not. This is unlike many HTML HTMLtags, so if that's the particular SGML SGMLDTD that you have more experience with, it may be coloring your intepretation.DocBook DocBooktags (and to be honest,honest most SGML SGMLDTDs) 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 formattingon how you want to present marked up text.In DocBook,DocBook the <Para> element elementis just defined as a "paragraph"paragraph, a container containersort of element elementfor other inline,inline and some block, elements. It says nothing about starting nor breaking on a newline,newline although of course such could be selected by a style sheet as an implementation.implementation In that respect the more tags you have in a document document(and the more granularitygranularity of the information so tagged) the better - it gives the formatter formatterand style sheet the most flexibility in handling how the formatted output should appear.

We talk about stylesheets in , , , and . Authors, Credits, RolesIf you have a more complicated situation than just an author for your document,document like affiliations,affiliations translators, contributors etc., here's the right way to enter such information in LyX,LyX so that it can be exported to SGML:SGMLCreate an environment environment() of type “SGML” just after the title and before the abstract.abstract There, enter the information as in the following example: Chris Karakas Webmaster www.karakas-online.de Conversion from LyX to DocBook SGML, Index generation Chris Karakas www.karakas-online.de Translation from italian Chris Karakas www.karakas-online.de ]]> KeywordsThe metainformation metainformationon keywords keywordsis 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 keywordsin the header as there are still some search engines around that use them (Google does not). Here's how you enter keywords keywordsin LyX:LyXAfter the title and before the abstract,abstract create an environment environment() of type “SGML”. There, enter the keywords keywordsas in the following example: ]]>LyX ]]>SGML ]]>DocBook ]]> ]]> Revision historyYou enter a revision history as follows: Create an environment environment() of type “SGML” that is located after the abstract abstractand before the first chapter/section. In this environment,environment enter the revision history as in the following example: ]]> ]]>1.2 ]]> ]]>29.05.2003 ]]> ]]>CK ]]> ]]>Some remarks about this revision. ]]> ]]> ]]> ]]>1.1 ]]> ]]>13.02.2003 ]]> ]]>CK ]]> ]]>Some remarks about this revision. ]]> ]]> ]]>Revision numbers numbersshould be entered in reverse order (i.e., the latest revision should appear first on the list). ParagraphsDo NOT use the “Paragraph” environment environment() when writing a paragraph.paragraph Use “Standard” instead. Using “Paragraph” interferes with the changes that runsed and sedscr try to effect in the SGML SGMLcode as exported by LyX.LyX Cross references Cross-references work in exactly the same way as usually in LyX:LyX you first insert a label label(choosing Insert-->Label from the menu), then insert a cross-reference cross-referenceat a point of your choice (choosing Insert-->Cross-reference from the menu). BUT: You can't cross-reference cross-referenceanything! Although it is certainly possible in LyX,LyX it will not work when exported to SGML:SGML you will get the errorSee for a discussion of this error. For the moment, just remember that the only cross-references that work for our purposes are cross-references tochapters, sections, subsections,subsections subsubsectionsfigurestablesbut that's quite enough for cross-referencing.cross-referencing Always set labels! 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 for more tips on this important issue. Mass insertion of cross-references in LyXIf you have to add hundreds hundredsof cross-references in just one section (e.g. more than 500, as in Credits for version 2.0 of the PHP-Nuke HOWTO), you will soon notice that, although a single cross-reference cross-referenceis inserted very easily in LyX LyX(just choose Insert->Cross-reference from the menu, then choose the label labelof the reference you want), it becomes a real pain if you have to enter hundreds hundredsof them.My solution to this was to write a script that reads a LyX LyXfile and outputs another LyX LyXfile that contains references to all labels of the first one. It was then easier to copy the references from the file thus created, paste them in Credits for version 2.0 of the PHP-Nuke HOWTO and then delete the unneeded ones, than try to insert all cross-references by hand using the LyX LyXmenu.The following script, call it lyxrefs, will print a LyX LyXfile in standard output, containing cross-references to each and every label labelof the LyX LyXfile whose name was passed on the command line as argument: all-references.tmp ]]> fig-references.tmp ]]> tab-references.tmp ]]>The script will even create three sections, with cross-references to all labels, all figures figuresand all tables respectively. If you named it lyxrefs,lyxrefs you would call it as follows: refs.lyx ]]>Then refs.lyx refs.lyxwill contain cross-references to all labels of some-LyX-file.lyx.some-LyX-file.lyx You can open refs.lyx refs.lyxwith LyX,LyX copy all or part of the cross-references there and paste them in some-LyX-file.lyx. The cross-references in Credits for version 2.0 of the PHP-Nuke HOWTO were entered this way. Images You insert an image quite simply: from the menu, choose Insert-->Graphics. Enter the basename basenameof your image (this is the name without the ending), followed by the ending “.eps”. Example: If your image is called myimage.png, enter “myimage.eps” in the file field. Don't worry that LyX LyXcannot 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.paths The scripts will take care of this (see for the gory details). You just enter “myimage.eps”, that's all.If you want to see figure captions captionsand titles (and the “alternative text” in HTML), or if you want to be able to reference a figure, or see your figure in the “List of Figures” that is created automatically,automatically then you have to use floats.floats Follow the instructions exactly as given:Be sure that your cursor cursoris in the “Standard” environment.environmentFrom the menu, choose Insert-->Floats-->Figure.In the float, insert an image as explained previouslyWhile the cursor cursoris still besides the (empty) figure box and inside the float, change the environment environmentto “Caption” ().Now you see the text “Figure#:” to the left of the image box, followed by the image box . Insert a label label(Insert-->Label) directly after (to the right of) the image box. Through this label labelyou will be able to cross-reference cross-referencethis figure in your document.document Type the figure caption captiontext directly after the label.label It will become the figure title and caption captiontext (there is currently no way to get different texts for figure title and caption captiontext from LyX,LyX although SGML SGMLwould support this. If you find an alternative, please send it to me).Inline graphicsI will disappoint you: there is no way to include inline inlinegraphics with the method described in this document document- see for the reason.Well, almost... ]]> ]]> ]]> ]]> Inline graphic You have always the possibility to write SGML SGMLin LyX:LyX just create an environment environment() of type SGML SGMLand enter your text (in <para> elements), followed by Substitute “1” with the basename basenameof the inline inlinegraphic (i.e. the name without path pathinformation and without ending). Of course all necessary formats (PNG, EPS,EPS PDF PDFand BMP) with the right density densitysettings must be available under the ./images directory, see . Caution: 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 Admonitions There is no “Admonition” environment environmentin LyX,LyX just as there are no “Admonitions” in TeX/LaTeX. Admonitions Admonitionsare a DocBook DocBookSGML SGMLelement.element They are those text passages which alert the reader of some important fact (see for examples). They carry titles like “Caution!”, “Important!”, “Note”, “Tip”, “Warning!”. There is no oher way to introduce admonitions admonitionsin a LyX LyXDocBook document,document than by creating an SGML SGMLenvironment environmentand inserting the necessary SGML SGMLcommands there. Here is an example for “Caution”: ]]>Caution ]]> ]]> ]]> ]]>which looks like this: Caution 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! Since the environment environmentis SGML,SGML you can put any legal (from the DTD DTDpoint of view) SGML SGMLtag inside <caution>/</caution>, not only <para> or <title>. Here is a more complicated example that uses an itemized itemizedlist (through the <itemizedlist> tag) , this time for the “Tip” admonition:admonition ]]>Tip ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]>It looks like this: Tip FYI, all changes presented here refer to variables that were originally defined in one of the following files: /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/html/dbparam.dsl /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/print/dbparam.dsl /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/print/db31.dsl As said above, you should not change these files directly, because you will run into a lot of work when you upgrade them. Another example (of a "Note" admonition) that makes use of a code example (though the <screen> tag): ]]>Please note: ]]> ]]> ]]> ]]> ]]> ]]>It will look like this: Please note: A file containing graphical callouts (see and ) will NOT be validated! You will get an error saying document type does not allow element "IMG" here Callouts Callouts are those reverse-video reverse-videocircled numbers numbersor "(1)", "(2)", etc. that you see appended to selected lines in some code examples, like the following: baseurl={http://www.karakas-online.de/mySGML/}, pdftitle={Document processing with LyX and SGML}, pdfsubject={Linux,document formatting}, pdfauthor={Copyright \textcopyright 2004, Chris Karakas}, pdfkeywords={Linux SGML LyX DSSSL DocBook} The baseurl will be added in front of any relative WWW link that you have in your PDF document. The pdftitle will appear as the title of your PDF document in Acrobat� Reader under File-->Document Info-->General. The pdfsubject will appear as the subject of your PDF document in Acrobat� Reader under File-->Document Info-->General. 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. 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. Just as is the case with admonitions admonitions(see ), there is no LyX LyXenvironment environment() for callouts callouts(there is no such environment environmentfor TeX/LaTeX either, which is the reason why it is absent from LyX LyXtoo). The only way to get callouts calloutsto work with LyX LyXist to create an SGML SGMLenvironmentenvironment and put the SGML SGMLcode there. For the example above, here is what you would have to write in the SGMLSGML environment:environment ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]>Reader under File-->Document Info-->General. ]]> ]]> ]]> ]]> ]]>Reader under File-->Document Info-->General. ]]> ]]> ]]> ]]> ]]>Reader under File-->Document Info-->General. You may add copyright information as shown here. ]]> ]]> ]]> ]]> ]]>Reader under File-->Document Info-->General. Keywords are separated by blanks. ]]> ]]> ]]> ]]> TablesFor table captions captionsand titles to be output correctly, you have to insert tables in the following way: Be sure that your cursor cursoris in the “Standard” environment environment(see ).Insert a table float (from the menu: Insert-->Floats-->Table)You get a table float containing one line. Change the environment environmenton that line to “Caption”.You see the text “Table#:” and the cursor cursoris positioned immediately to the right of it. Insert a label labelfor the table (from the menu: Insert-->Label).After the label,label on the same one line: type the table title and press <enter>. This will produce a <para> element elementwe will eliminate eliminatein sedscr (see ).On the new line, insert your table as usual.A warning about an "end tag for element element"TABLE" which is not open", when processing processingthe SGML SGMLfile with Jade,Jade is the less evil we can get (see ) and is harmless (probably caused by a LyX LyXbug in version 1.2.0).A LyX LyXrelated 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 LyXUser's Guide):Split it into two tables, to correctly handle pagebreaks pagebreaksand margins.Select the Longtable button in the Table Layout dialog. This automatically automaticallysplits splitsthe table over more pages, if it is too high. After doing this, the list of Longtable buttons activate themselves and you may now define:FirstHead: 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.Head: 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-tablemultipage-table except for the first page if FirstHead is defined.Foot: 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-tablemultipage-table except for the last page if LastFoot is defined.LastFoot: 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-table.NewPage: This forces a pagebreak after the row where this flag is defined.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 empty. In this context, first means first in this order: Foot, LastFoot,LastFoot Head, FirstHead. See the typewriterTableExamples.lyx example file to see how this works. Use the Width entry in the Table Layout dialog to restrict the width of the table till it fits horizontally.A table can also be placed in a float, as described below, which will allow TeX TeXto place it as well as it can within the page.One last remark: Longtable and Rotate 90� use special LaTeX LaTeXpackages, so you should look into LaTeX configuration in the Help menu to see if your system supports these features. Table of contents LyX LyXprovides its own command for the creation of a Table of Contents (from the menu: Insert-->Lists&TOC-->Table of Contents) - but you should not use it! Whether a table of contents will be created or not is entirely controlled by the stylesheets (see and ). For example, the following code in a stylesheet stylesheetspecifies that a Table of Contents has to be created for document documenttype “Article”: List of figures, tables and equations A list of figures figuresis created automatically automaticallyfor the document documenttype “ DocBook DocBookbook SGMLSGML”. You don't need to undertake anything here. The same is true for lists of tables and equations.equations This is true as long as you use the DSSSL DSSSLstylesheets (that form part of DocBook,DocBook see) with their default settings. In case you don't get a list, when you think you should, read in about the generate-book-lot-list stylesheet stylesheetparameter. EpigraphsAn epigraph is a short inscription at the beginning of a document documentor component. LyX LyXonly provides the “Quotation” environment,environment which is mapped onto the blockquote SGML SGMLelement,element when exported. For an epigraph epigraphas such, there is no provision (as is the case with all SGML SGMLtags that do not have a clear correspondence to TeX/LaTeX environmentsenvironments - see for the notion of an environment environmentin LyX). 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: ]]> ]]> ]]> ]]> Inline graphic ]]>William Safire ]]> ]]> ]]> ]]>See for how the end result looks like. SGML code in program listingsIf you want to write executable SGML SGMLcode in LyX,LyX e.g. to implement an admonition admonition(see ) or a callout (see ), there is no problem: just create an environment environmentof type “SGML” and enter your code there. It will be part of the exported SGML SGMLfile.But if you want to give some example SGML SGMLcode, 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 SGMLcode contains “<![CDATA[” and “]]>”, it is likely to interefere with the normal SGML SGMLprocessing,processing causing errors like the following:0:382:323:E: marked section end not in marked section declaration ]]>To include a file, choose from the menu Insert-->Include file. In the dialog box, choose “Verbatim” and enter the file name. The file should best be located in the same directory as the SGML SGMLfile exported from LyX LyX(but need not necessarily to).LyX LyXwill use the “inlinegraphic” SGML SGMLtag to include the file. This will collide with inline inlinegraphics, if you want to include them using this method too (see and ). FilenamesIt would be nice to have a “Filename” environment environmentfor DocBook DocBookSGML SGMLarticles or books in LyX,LyX it would make computer documentation much nicer. But I was unable to find one, or a workaround workaroundto it. If you find a way, please let me know. Of course, a poor man's solution could be to mark marka filename with the “!” button, making it part of an <emphasis> tag, which would then appear in italics. But this contradicts the very idea of SGML SGML- separation separationof content from formatting.formattingLabels as filenamesYou should always put a label labelafter the chapter/section/subsection/subsubsection title (from the LyX LyXmenu: Insert-->Label). The text you use for the label labelwill become the name of the HTML HTMLfile that contains that chapter/section etc. See for the code that controls this setting in the stylesheets (it is the use-id-as-filename DSSSL parameter. that does this). SEO (Search Engine Optimization) tips There is circumstancial evidence that the search engines (especially Google) weigh substantially the keywords that appear between <H1>, <H2>, <H3> tags (that's the chapter's and sections' titles) especially if they also appear as part of the HTML filename. You are thus well advised to follow some simple rules for your titles (er...filenames ]]> ]]> ]]> ]]> Inline graphic ): Always create a label. Failing to do so, will produce and automatic, nothing-saying filename. You loose a potential (although small) ranking boost from the search engines, if your section is about, say, blue widgets, but is called x543.html, instead of blue-widgets.html. The label should contain the same text as the title. The title you enter in LyX will automatically be the HTML title in the header part of the resulting HTML file (this is a meta-information, not visible to you, but very well visible to the search engines), as well as the title inside the <H1>, <H2>, or <H3> tag that is produced in the HTML body automatically as well. If the label is similar to the title, then the HTML filename will be similar to the titles (meta-title and actual text title) of the text inside it. This wil be rewarded with more weight in the search engine ranking, resulting in a higher place in the SERPS (Search Engine Result Pages). And believe me, even if you hate search engines, it is much easier to find a chapter by reading "talking" filenames, like blue-widgets.html, than cryptic ones like x543.html! Dont'use blanks. Use hyphen “-” instead. This makes use of the fact that for most search engines “-” is equivalent to a blank. This is not the case for underscore “_”. Don't use illegal characters, i.e. characters that are not allowed in HTML filenames. Cool labels don't change!There is one thing to keep in mind when regrouping:regrouping chapter and section labels - DON'T change existing ones! You may change their position, but please not the label.label Subsection Subsectionand subsubsection subsubsectionlabels can be changed without problem.Why? Because chapters and sections will become separate HTML HTMLdocuments. There is a DSSSL DSSSLstylesheet setting which controls how deep a level will still produce a separate HTML HTMLdocument (see the decription of chunk-section-depth in ). The name of the documents will be the label labelof the chapter and section respectively. This is a behaviour behaviourwe explicitly set in the DSSSL DSSSLstylesheets (see ) through the use-id-as-filename DSSSL parameter.. Obviously, you can move a section around, without affecting the HTML HTMLname of the resulting file, if you don't change its label.label You can of course change its contents, put it somewhere else as a section of a different chapter etc., but you should leave the label labeluntouched.The problem is that, if the document documentis already on the Web Weband 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,label the HTML HTMLname changes. Consequently, the link from the search engines is no longer valid. The same is true for private bookmarks,bookmarks or public bookmark lists.But there is more to it: it's not only a matter of waiting 2-3 weeks for the new HTML document that contains the old (a bit reorganized) content to be indexed by the search engines. It's that the old name might have been at page 1 of the SERPS (Search Engine Result Pages) of some search engine for some keyword, because a lot of other people linked to it. Now, with a changed label and, consequently, a new HTML file name, those links do not reference the new document, and it gets a ranking close to "nowhere" (because search engines, notably Google, take links to a document to mean "votes" for that document and rank that document accordingly). The result: nobody finds it. ]]> ]]> ]]> ]]> Inline graphic It's not a question of sacrificing quality! I am not trying to tie up your hands in favour of a higher search engine ranking here! This discussion is not one of quality vs. ranking, but one of consistency. All I am advocating is: keep your labels (and consequently your filenames) consistent between various releases of your document! Once you have chosen a label for a chapter of section, stick with it. Please also note that we are not talking about the title of a chapter or section, but its label. "Label" is LyXese for the "SGML id". You get a label from the "Insert -> Label" menu of LyX. Don't confuse title and label in this discussion! For example, suppose a chapter with the title “Blue widgetswidgets” is at around place 6 out of 2,5 million (!) for "blue widgets" on Google.Google If you change the label labelof the chapter from "blue-widgets"blue-widgets to something else, then the original URI URIwill disappear and you loose readers. Of course, changing the title also affects the SERPS SERPS(Search Engine Result Pages), but not as drastically as to eliminate eliminatethe document documentaltogether. However, Google Googlelikes a title that is correlated correlatedto the file name, so a title "Blue widgets" and a label label"blue-widgets" are optimal from the SEOSEO (Search Engine Optimization) point of view (see ).“But you are talking me into subjecting my writing to the whims of a search engine!”, you might counter. Nothing more far away than that! The point is not to restrict your writing. The point is: you write whatever you like, however you like and structure it as you please. There are rules rulesfor good writing that you might choose to observe, or not. There are also rules rulesfor good “copy” , from the point of view of keywords,keywords search engines and ranking ranking- which you are also free to observe or defy. Then, at some point, you decide to put the document documenton the web. People will come, read it and, hopefully, find it good. Those people may like your document documentso much, as to go into the trouble to say something like "there's a cool document documenton blue widgets widgetsin this link here" - and link to it. Hundreds of people may do this perhaps - even thousands. Imagine the effort!Now you come up with a new restructuring of you document document- fine! You change the content - also fine! Then you change the label labelfrom: Blue widgets ]]>to:Blue widgets revisited ]]>In LyX,LyX this is equivalent to changing the title from “Blue widgetswidgets” to “Blue widgets widgetsrevisited” and the label labelfrom “blue-widgets” to “blue-widgets-2”. Perhaps you thought it would be a nice idea to change the title to reflect the reorganization.reorganization This will affect your ranking rankingtoo, but then, almost everything that you write will affect it, so we will not discuss it here. (Actually, it will affect it a little more because it's on the title - but that's again not the point.). But by changing that label labelfrom “blue-widgets” to “blue-widgets-2” you just managed to throw your document documentfrom place 6 to place 600 (or 6000, or...) in the SERPS.SERPS You just killed all the efforts of thousands of people that linked to your document!Why? Because labels become filenames in the document documentprocess from SGML SGMLto HTMLHTML (see for a detailed explanation of this process). The document documentthat would be blue-widgets.blue-widgetshtml now is blue-widgets-2.html. The original blue-widgets.blue-widgetshtml is nowhere to be found in your domain - hundreds,hundreds or even thousands of links on the Web Webnow point to vacuum!Google Google- and every other search engine - sees this and takes the old URLURL 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 label(and the resulting HTML HTMLfilename) at your whim. Thus, noone points to the new "reorganized"reorganized document.document It is rated very low and appears at place...uhmm 1 million something, out of 2,5 million results for "blue widgets", where nobody will find it and nobody will read it. Remember, the original document documentranked at place 6 out of 2,5 million!You might think that, since the label-to-filename label-to-filenameconnection exists only for the “chunked” version (the version where openjade openjadeis instructed to split the documentdocument into separate HTML HTMLfiles, one per chapter or section, the so-called “chunks”, as explained in ), the “unchunked” document documentwill save you from this disaster. You are correct, the "single chunk chunkdocuments" (single, big HTML HTMLfile, TXT,TXT PDF PDFor PS PSversions) will not be affected . If you only make the big HTML HTMLfile, or the TXT,TXT PDF PDFand PS PSversions of your document documentavailable on the web, then you are not affected. But if you also made the chunked chunkedHTML HTMLversion available at some point, the search engines will prefer to return results from this version, than from the others. There are various reasons for this, one of them being that search engines don't read a document documentthat is too long till the end and will thus index small chunks chunksmuch better than huge textst. Another reason is that you need more links to a PDF PDFdocument, to force a search engine to consider it important for indexing.indexingSo forget about the huge, one-chunk one-chunkdocs as a search engine strategy.strategy If you want to be found by the SEs, you must rely on the chunked chunkedversions - and perhaps a little on PDF,PDF but only a little.However, my point goes even further: we are not talking about a user who is searching for a unique, multiple keyword keywordphrase that identifies the content of your reorganized reorganizeddocument. We are talking about a user who just searches for, two keywords:keywords “blue widgetswidgets”. If you change the label,label you change the filename of the chunked chunkedversion. If you do so, the search engine will NOT think "Ahh...the file blue-widgets.blue-widgetshtml is not there, let's present the huge document documentthat contains all chapters, including the one on blue widgets widgets- at the same ranking rankingplace"! There are three resons that this will not happen - and you should not rely on it:First, the search engine does not know that blue-widgets.blue-widgetshtml is just a chunk chunkof some "whole" document,document book1.html. There is nothing that a search engine does to find this out - not with today's technology.technology The two documents are different from the search engine point of view.Second, the big one, book1.html, contains much more text, therefore the importance of the "blue widgets" chapter is "diluted" from the surrounding, irrelevant text (irrelevant to what the user is searching with those keywords,keywords namely "blue widgets"). This has to do with “ keyword keyworddensitydensity”, titles, structure and other “on-page” factors that the search engine calculates and takes into account for each page. Therefore, the document documentwill rank at a place that is way back - invisible to all but the most determined searchers, practically dead.Third, if you are a HOWTO author, you may put your document documenton The Linux Documentation Project, which is a great place with good exposure exposureto the Web,Web but that alone does not guarantee good ranking.ranking What is also important, is that people link to it. But if you change an existing label,label thus changing the filename of the chunked chunkedversion (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.URL You destroy what you were able to gather up to that point in terms termsof search engine visibility.visibility You start anew. Use permanent redirects, if you do choose to change the label! Let me put a preemtive disclaimer here: I know that you can put a "HTML permanent redirect" in your .htaccess file to indicate that the resource is now somewhere else, under a different name. But this makes URL management difficult for a webmaster. How on earth shall the webmaster know which labels some author, whose document he hosts on his website, changed in his last reorganization? Is he supposed to do nothing else a whole day, other than chasing diff outputs and editing .htaccess files? Just because the author wants to keep his freedom of changing labels at his whim? Remember, if it is a free document, it will find its way to other people's websites. People may link to files of those websites containing your document, even more often than they do to yours. When you release a new version with changed labels (and accordingly, filenames), do you send a list of changed labels to all those webmasters who host it, with the request to update their .htaccess files? Certainly not. Nevertheless, if you are the author and have decided to change the label of some chapter or section, don't let your web server send an "Error 404: not found" for the old URI. Let it send a “permanent redirect” instead. See Managing URIs and the links therein, for the preferred ways to handle this situation. But again, a redirect has to be in your .htaccess file (or web conf file) until the last request has been seen in your web logs for the old URI (theoretically, at least, otherwise you loose the visitor). How long is this? One year? Ten years? How big does your .htaccess become if an author starts "reorganizing" his labels(!) every other week? How much of a performance penalty will you have to pay for your web server having to read and process huge .htaccess files on every page request? Thus, every redirect will hurt you, either in terms of visibility in the SERPS, or in terms of complexity, or both. But if you change a label, don't forget the permanent redirect. For the above reasons, most of the time, you will not feel the need to change labels while reorganizing, but think doubly about it if you must. Your best bet is to choose a label labelwisely (for the same reasons that you would Choose URIs wisely), perhaps with a name that is a bit more general than you might wish, but will still fit if you choose to change content, or even title, later on. Cool URIs don't change. Cool labels don't change either. ]]> ]]> ]]> ]]> Inline graphic ExamplesThere is no “Example” environment environmentin LyX LyXfor document documenttypes of DocBook DocBookSGML SGMLbook/article. You could certainly “simulate” it with a pure SGML SGMLenvironment,environment just as we did it for admonitions admonitions() and callouts callouts(), but I will not pursue this further here. MathematicsYou write Mathematics Mathematicsin LyX LyXthe 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: (eq1) \[ \sum _{n=1}^{\infty }\frac{x^{n}}{n}=\ln \left(\frac{1}{1-x}\right)\] ]]> ]]> ]]> ]]> Whatever you type in math,math it will be typeset by TeX TeXand be available in all formats - HTML,HTML PDF,PDF PS PSand RTF! Isn't it great? You should nevertheless read to ensure that you installed the necessary software for math mathprocessingprocessing and to get an idea of what is going on in the background.background There are more Mathematics Mathematicsexamples for LyX LyXin , where the subject is discussed in more details. AppendixLyX LyXoffers the possibility to mark marka part of the document documentas being the Appendix: from the top menu, choose Layout -> Start Appendix here. Unfortunately, this will not work when the document documentis exported to SGML.SGML We are thus left alone and have to implement a workaround.workaround I have implemented the following solution:The writer provides an extra LyX LyXfile, with the fixed name “appendix.lyx”, in the same directory as the main document.documentThe appendix.appendix lyx lyxfile must be of type “ DocBook DocBookarticle (SGML)”, to be chosen from the LyX LyXmenu: Layout -> Document. A document documenttype of “ DocBook DocBookbook (SGML)” will NOT work, even if the main document documentis of book type! This is because if you set the document documenttype to book, you will have to start with Chapters (instead of Sections) and then you will get parsing errors from openjadeopenjade saying that CHAPTER is not allowed by the DTD DTDat that place.The appendix appendixis marked as such, using LyX' menu: Layout -> Start Appendix here, with the cursor cursorat the very start of the Appendix.That's all! The lyxtox script will check if a file called appendix.appendix lyx lyxis there and will take the aproppriate steps to incorporate it into the document document(see ). How to insert cross-references to the Appendix 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. BibliographySo 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 To begin with, here is just a test citation:citationcitation: . And another one: . Take the time to examine them and their formatting formattingin the version (HTML, PDF,PDF PS,PS RDF or TXT) you are currently reading.Bibliography without RefDBAs stated in , you are not confined to using RefDB whith my lyxtox script. If you don't feel like building your own bibliographic bibliographicdatabase, you can just supply a bibliography.bibliography lyx lyx file together with your LyX LyXdocument. Set the process_RefDB variable in lyxtox to "0" and it will use your own bibliography.bibliography lyx lyxto produce a bibliography.bibliographysgml file, instead of trying to create one automatically automaticallythrough RefDB.RefDB The bibliography.bibliography lyx lyxfile should then contain the SGML SGMLcode for the references list, in the SGML SGMLenvironment environmentof LyX.LyX The GNU/Linux Command-Line Tools Summary HOWTO uses this approach,approach for example.This means that if you don't want to use RefDB,RefDB but still want to have a bibliography, your bibliography.bibliography lyx lyxfile should look like: ]]> ]]> ]]> ]]> ]]>Karakas ]]>Chris ]]> ]]>]]>Neuronale Lernregeln und andere Methoden f�r lineare Assoziation und Trennung ]]> ]]>BoD GmbH, Norderstedt ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> elements here ]]> ]]> ]]>The whole code should be in the LyX LyXSGML SGMLenvironment environment(see for an explanation of LyX LyXenvironments). You can even insert URLs and cross-references the usual LyX LyXway (from the LyX LyXInsert menu) and they will be correctly exported to SGML.SGML The layout layoutof bibliography.bibliography lyx lyxshould be “ DocBook DocBookChapter Chapter(SGML)” (to be set from the LyX LyXLayout menu). You don't need anything in the preample preampleor elsewhere. See the bibliography.lyx file in the Formats section of GNU/Linux Command-Line Tools Summary HOWTO for an example.To cite citea reference from a reference list created this way, you have to switch to the SGML SGMLenvironment environmentfor the whole paragraph paragraphcontaining the citation,citation then write as in the following example: ]]>KARAKAS1992 for more details on ]]> ]]>Note that we use the value of the xreflabel xreflabelattribute attributeto refer to the reference entry. Formatting your Reference List. Note that this way of creating a Reference List and citations does NOT cover formatting of either citations or the entries in the Reference List itself. Note also that each journal (or medium) has its own formatting expectations as far as the Bibliogrphy is concerned. You will have to write your own DSSSL driver file to accomodate for this need. RefDB () takes this burden out of your work for the slight overhead of setting up a database and installing the RefDB package (). Bibliography with RefDBYou don't need to care about a bibliography.bibliographysgml file if you use RefDB RefDB- the lyxtox file will create it automatically automaticallywith the help of RefDB,RefDB totally transparently transparentlyto you. All you need is install and set up RefDB RefDB(see and respectively), and set the following variables in lyxtox:Process_RefDB Process_RefDBto “1”.RefDB_db RefDB_dbto the name of the RefDB RefDBdatabase containing the bibliographicbibliographic entries you plan to cite cite(you created this database databasein , the name in the example was “ck_refdb” and is the default one in lyxtox - you should of course change this).REFDB_style REFDB_styleto the style of the journal you want your Bibliography to conform to. Note that this name must contain a dot at the end, because lyxtox will create, the file ${REFDB_style}dsl. Example: for REFDB_style="J.Biol.Chem.", lyxtox will automatically automaticallycreate (through RefDB) the file J.Biol.Chem.dsl,J.Biol.Chem.dsl i.e. the “dsl” ending is appended without any extra dot. The default value is “J.Biol.Chem.”, one of the two standard styles shipped with RefDB,RefDB and should get you starting. See How to manage bibliography styles for more details on bibliography bibliographystyles in RefDB.RefDBThe only thing that remains is... cite citeof course!Citing with RefDB RefDBin LyX LyXis a bit tricky, since LyX LyXdoes not allow citing the way RefDB RefDBis expecting it: with a role attribute attributewith the value “REFDB” in the SGML SGMLcitation code. Of course, we could use a pure SGML SGMLenvironment environmentas in and write: ]]> ]]> ]]>each time we want to cite citesomething. But there is a better way: RefDB RefDBcan create that SGML SGMLcode automatically,automatically if it finds something like: ]]>"KARAKAS1992" ]]> ]]>in the SGML SGMLfile. But how can we convince LyX LyXto output something like the above for each citation citationwhen it exports our file to SGML?SGMLThe solution I found to this is:Export all the bibliographic bibliographicentries you plan to use in a file, say refdb.refdbris (see on how to do this).Use the awkscr_cit AWK AWKscript to create a new LyX LyXfile from refdb.refdbris: citlabels.lyx ]]>The citlabels.lyx citlabels.lyxfile is a LyX LyXfile containing only labels, one for each bibliographic bibliographicentry in refdb.refdbris. The labels have the prefix "cit:" to distinguish them from true labels. To stay with the above example, the bibliographic bibliographicentry with ID ID“KARAKAS1992” will produce a label label“cit:KARAKAS1992” in the citlabels.lyx citlabels.lyxfile created by awkscr_cit.awkscr_citOpen the citlabels.lyx citlabels.lyxfile in LyX,LyX together with your document.documentTo cite citean entry, you (mis)use the “Insert Cross-ReferenceCross-Reference” feature of LyX:LyX from the LyX LyXmenu, choose “Insert -> Cross Reference”. In the upcoming upcomingdialog box there is a drop-down drop-downlist field called “Buffer”. The Buffer Bufferserves as the source of the labels you want to reference. Usually, “Buffer” is set to the current file. You change this to “citlabels.lyx” by clicking on the dropdown field and choosing the citlabels.lyx citlabels.lyxfile. Now you are presented with all labels of citlabels.lyx.citlabels.lyx Choose the label labelcontaining the ID IDof the RefDB RefDBbibliographic bibliographicentry you want to cite.cite In our example, you choose “cit:KARAKAS1992”, if you want to cite citethe entry with ID ID“KARAKAS1992”. That's all! Don't worry about that “cit:” prefix, sedscr takes care about it. For every cross-reference to a label labelof the form “cit:IDsome”, sedscr sedscrwill create a citation of the form:in the exported SGML SGMLfile. Then, lyxtox will call the aproppriate RefDB RefDBtools to transform this citation citationtoor some more complex form according to the bibliographic bibliographicstyle in use. Again, you don't have to worry about this procedure.procedure Just create the citlabels.lyx citlabels.lyxfile as shown above and insert cross-references to its labels in place of your citations.citations You don't have to bother about SGML SGMLcode and you can't get the ID's wrong since you get a list of all available labels in citlabels.lyx citlabels.lyxto choose from. On the other hand, you can't get anything but “simple” citations citationsthis way, but at the moment I can live with that. See for a detailed explanation of what lyxtox and RefDB RefDBdo for you in the background backgroundto produce correctly formatted citationscitations and a correctly formatted Reference List.More elaborate solutions (using a citlabels.lyx file containing two or more labels for each bibliographic ID, each one with a different prefix, serving different citation purposes, "simple" or "complex" ones) are possible, but my hope is that this work will convince the LyX development team to incorporate RefDB directly in LyX in a future version. In the meantime, the method presented works fine - here and now. ]]> ]]> ]]> ]]> Inline graphic Index The index will be generated automatically automaticallyby the lyxtox script (which will call the collateindex.collateindexpl Perl script that came with the docbook-dsssl-stylesheets docbook-dsssl-stylesheetspackage you installed in ) as a separate file. You must arrange to have this file incorporated into your document.document The easiest way to do this is by file entity entityreference. In the preample preampleof your document,document add an internal subset that defines the index file entity:entity ]]>We have done this already in . See for the sed scripts that insert the appendix appendixSGML SGMLentity at the end of the SGML SGMLfile and for the explanation of the subsequent index generation.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:LyX from the menu, choose either Insert-->”Index entry of preceding word” (which I personally find easier), or Insert-->”Index entry”, then enter the required word. Don't underestimate the importance of an Index! 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. Automatic Index generationLyX LyXprovides an easy way to insert an Index entry (see ): from the menu, choose either Insert-->”Index entry of preceding word” (which I personally find easier), or Insert-->”Index entry”, then enter the required word. This method works fine - if you have a small document,document with only a few keywords keywordsto insert. But what if your document documenthas grown to hundreds hundredsof pages, with hundreds (or even thousands) of index entries to insert? See the Index of the PHP-Nuke HOWTO for an example of an Index that cannot be generated manually - unless you want to drive yourself crazy!Clearly, for a comprehensive Index of large documents, an automatic procedureprocedure is necessary. However, the general problem of automatic Index generation is subject of extensive (and still not conclusive) research researchand I am not going to address it in its full generality generalityhere. For our purposes, even a semi-automatic semi-automaticprocedure procedurewould be very helpful. To this end, I have created the following 4 scripts:sedscr_list_index_items: lists all index entries contained in a LyX LyXdocument.sedscr_delete_index_items: deletes all index entries from a LyX LyXdocument.awkscr_create_index_items: creates a list of words used in a LyX LyXdocument. The list can be subsequently edited manually, mostly deleting unwanted or uninteresting words, to yield a list of words that are used in the documentdocument and are interesting enough to be part of its Index.awkscr_insert_index_items: uses an externally supplied document documentcontaining a list of index entries to insert an index entry in a LyX LyXdocument for every word appearing in that list.They can be used in the following semi-automatic semi-automaticIndex generation procedure:procedure Optional: create a list of all existing index entries in your document.document This is useful not only because you are going to eliminate eliminateall index entries from the document documentin the next step, but also as a backup of the index entries that were currently in use - you might want to reuse them in some later step.To create a list of all existing index entries in your document,document type: indexitems ]]>The generated indexitems indexitemsfile will contain a list of all index entries in document.documentlyx, 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 awkscripts that follow, so don't let it irritate you.To get an alphabetically sorted list of index items, without duplicate entries and with all symbols symbolsat the beginning of the list, use the sort and uniq utilities as follows: indexitems.sorted ]]>Remove all previous index entries from the LyX LyXdocument. You need this preliminary step because, if you forget to remove already existing index entries, a subsequent run of the awkscr_insert_index_items script may substitute even the existing index terms terms(those already inside the LyX LyX\index commands) with LyX LyX\index commands. This may or may not happen, depending on the regular expressions expressionsused in the current implementation implementationof awkscr_insert_index_items, but it is better to err on the side of caution. What will happen, however, is that repeated invocations invocationsof awkscr_insert_index_items will add index entries besides already existing ones. You will thus end up with a document documentthat contains double index entries for each index term in your indexitems indexitemsfile. Besides, there is another reason why you might want to remove all index entries from your LyX LyXdocument: a LyX LyXtext cluttered clutteredwith index entries may still be a breeze to read for a computer, but quite a headache headacheto read for humans.To remove all index entries from a LyX LyXdocument, type: document-noindexitems.lyx ]]>The generated document-noindexitems. lyx lyxwill contain everything from document.documentlyx - except the index entries.Create a list of all index entries to be used in the LyX LyXdocument. This is the most difficult part: as said above, this problem is not trivial.trivial We will thus content ourselves with a list of all words used in the document.document Once we have all words, we can still edit the list manually and delete all unwanted entries. This is what makes this procedure proceduresemi-automatic and not automatic. The idea is that it is still better having to delete 10000 lines from a 12000 line document,document than having to insert 2000 index entries from the LyX LyXInsert menu.To create a list of all words used in a LyX LyXdocument, type: words ]]>There is even some code in awkscr_create_index_items that checks whether the current word is in some “trivia” list of trivial trivialwords and discards it. In such a case, you would call the script with two arguments, as follows: words ]]>However, this part of the code is either too slow, or buggy, so it is commented for the moment (feel free to send corrections or suggestions).It is a good idea to sort your words alphabetically and delete double entries, so do: words-unique ]]>Once the list of all words of your document documentis 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 punctuationat the end and so on. This is still hard if your document documentis 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,document which gives me an estimate estimateof 8000 menu selections with the mouse - unfortunately no keyboard bindings bindingswere found to work on my system).You should delete all lines containing characters that could be interpretedinterpreted as metacharacters of regular expressions:expressions *, +, ?, $, &, ^, \ - and probably many others. Don't try to escape them, it will not work: awkscr_create_index_items will replace the correct, string with the escaped string, adding an index entry for the escaped escapedstring too! This is not what you will want. What is rather needed here is a mechanism to search for the escaped escapedstring, but replaced it with the verbatim one (i.e. the string without the escaping backslashes). This is still work to be done (FIXME).Practically, this restriction means that you will have to add your index entries for symbols symbolslike *, +, ?, $, &, ^, \ manually, each time after you run awkscr_create_index_items.Once you have a file, say indexitems,indexitems with all words that should appear in the Index of a LyX LyXfile, type: document-indexitems.lyx ]]>to create from document-noindexitems. lyx lyxa document documentwith index entries (document-indexitems.lyx) for all words in indexitems.indexitems Long execution time! The current implementation of awkscr_insert_index_items takes really long to execute, if the indexitems file is large: For 3000 words in indexitems, producing about 9000 index entries in the final document (of which 3000 are duplicate), the script may well need 1-2 hours on a Pentium 3.4 GHz - go get a cup of coffe! ]]> ]]> ]]> ]]> Inline graphic Some notes on awkscr_insert_index_items's mode of operation: The “-” in the above invocation invocationis important: it forces the awk awkscript to continue reading from standard input, after it has read indexitems.indexitems This, together with the codein awkscr_insert_index_items, causes the words in indexitems indexitemsto be imported into the indexentry[] associative array.The file separator in awkscr_insert_index_items is set to the semicolon “;”, instead of the default, which is space. This makes it possible to enter index entries with more than one words. Accordingly, the awkscr_create_index_items script appends a semicolon at the end of each word it prints - you should leave these untouched!awkscr_insert_index_items follows a simple algorithm algorithmto insert the index entries at the right places in the document:document to insert an index entry, we have to know what LyX LyXenvironmentenvironment () we are in. In essence, this means we have to parse the LyX LyXdocument. Since the \ layout layoutcommands in the LyX LyXfile do NOT have what we would call “closing tags” in other markup markuplanguages, we cannot tell awk awk“if you are between the start and the end of the Paragraph environment,environment do the following”, or anything like that - there is no easy way to find the “end “ of an environment,environment given all the environment environmentnestings that are possible. Luckily, another easy way exists: whenever a \ layout layoutcommand is encountered, we are in the environment environmentspecified by that \ layout layoutcommand, so we only need to set a variable, call it layout, accordingly:...and so onClearly, we should not insert index entries everywhere, e.g. in the “Code” environment.environment That's why we check if we are in the "Standard", "Itemize", “Enumerate”, "Quotation"Quotation, "Description" environment environment(warning: the way sedscr works currently, you should not insert index entries in the “Caption” environment) and, if we are (and only then), we substiture every word in the indexentry[] array with the LyX LyX“insert index entry” command:Some tips regarding the (necessary) manual manualediting of the words file, the file output by awkscr_create_index_items above: Leave the semicolons at the end of each line untouched! They are needed as record separators in the awk awkscripts.You will see a lot of words (or their declinations) that are not useful. It is one thing to have a lot of words and another to have a set of really useful words and phrases. That's the price we pay for the simplicity of our method.You may need to supply some extra terms termsyou feel are missing from that file. Feel free to do this, awkscr_insert_index_items does not know how you created the indexitems indexitemsfile you give it. Keep backups of your word lists from subsequent runs of the scripts. Combine word lists from other projects. No matter how long your word list, only the terms termsthat really appear somewhere, will make it to the Index, so don't worry if your list is too long - given enough computing computingtime, that is.Take care to delete everything in your word list that looks like a regular expression with metacharacters - because it will be interpreted interpretedas such, with unpredictable results (unless you really know what you are doing). I once had “.*” on one line and I forgot to delete it. I then wondered how come that my document documentwas full of index entries to “.*” while the text was almost gone! See regular expressions, for a brief introduction to regular expressions.expressionsTake out any “:”, “;”, “?” from the end of the words, as well as enclosing double quotes. Those characters are already taken care of when it comes to inserting the entries, i.e. the indexentries file should contain only the “pure” words, without any punctuation punctuationsigns. Don't leave in “config” if your LyX LyXfile contains “config.php”. If you do, the latter will look ugly in the LyX LyXeditor, as it will contain an index entry for “config” just in the middle of it. This will not affect the rendered formats, however.Don't leave in words that might form parts of a LyX LyXcommand. I once left “Enumerate” in my word list. The resulting LyX LyXfile contained an index entry for “Enumerate” in front of every item in every enumeration list! Clearly, the awk awkscript awkscr_insert_index_items “sees” the LyX LyXcommands in the file that are invisible to you. This bug has been fixed in the current version of the script, but there maybe others lurking around.Finally, there are a few known limitations of the collateindex collateindexscript that creates the index (see Automatic Indexing with the DocBook DSSSL Stylesheets:Duplicate page numbers numbersare not suppressed in the index. If the document documentcontains three indexing indexinghits on page 4, the generated index will contain 4, 4, 4.Ranges are not automatically automaticallyconstructed. If the document documentcontains indexing indexinghits on pages 4, 5, 6, and 7, the generated index will contain 4, 5, 6, 7 instead of 4-7. The final step: invoking lyxtox If you have followed all the above, your working directory should now contain:Now, to create all the other formats from your LyX LyXsource, you just call lyxtox with one argument: the name of your . lyx lyxfile without the . lyx lyxending: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 For a detailed explanation of what is going behind the scenes, see .Now, let's see a more realistic example: the creation of the GNU/Linux Command-Line Tools Summary HowTo. This HowTo is an attempt to provide a comprehensive summary of useful command-line tools toolsavailable to a GNU/Linux based operating operatingsystem, i.e. commands needed by the majority of users. The document documentis authored by Gareth Anderson and I assist him in the document conversion process. So, how do I go about such a project?Here's howSee also How to correctly invoke the lyxtox script.: My home directory is /home/chris. This is not my working directory for a lyxtox lyxtoxproject. 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.Now, I change to the working directory and make sure I have all files mentioned above. These are at leastand 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.So now I have created the filesas exact copies of the original ones (which are, as I said, in some other directory).Now, in the /home/chris/myLinuxCommands directory, I create (or copy) the LyX LyXfile that I want to process. In our case, this is the gnu-linux-tools-summary.lyx file, together with bibliography.bibliographylyx bibliography.lyxand appendix.appendixlyx. In other cases, the bibliography.bibliographylyx bibliography.lyxand appendix.appendixlyx are not needed, so they are not there.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 LyXfile is gnu-linux-tools-summary.lyx, I call lyxtox lyxtoxwith the basename basenameof gnu-linux-tools-summary.lyx, i.e. with "gnu-linux-tools-summary", as its first and only parameter:parameterThe name of the parameter parameteris $1 in the lyxtox lyxtoxscript.(Of cource, I have taken care to adjust all parameters at the start of lyxtoxlyxtox to my situation, as described in ).If all goes well, I get another directory inside my working directory, named exactly as the parameter parameterof the script, in our case gnu-linux-tools-summary. Everything I need is there: the one, big HTML HTMLfile, the many HTML HTMLfiles ("chunks"), the PDF,PDF PS.PSGZ, TXT TXTfiles, the images directory, the math mathdirectory...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! Indeed, it is here: http://www.karakas-online.de/gnu-linux-tools-summary/. ]]> ]]> ]]> ]]> Inline graphic 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 lyxtoxinvocationinvocation Notice that you are supposed to have an "images" directory inside your working directory. Mine is /home/chris/myLinuxCommands/images. 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. Errors and warnings 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.Here are some examples of possible errors:LyX errorstext class not available: If you get:do "Layout-->Document" on any LyX LyXdocument 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 classI use. You should see something like: If not, then somehow the reconfigure reconfigurecommand above (see ) did not find all your classes. Openjade errorsDTDDECL catalog entries are not supported: Jade Jadedoes not support the DTDDECL catalog catalogdirective directiveand it complains loudly if it encounters one. You may safely ignore this warning. See here for more details.xref to ANCHOR unsupported: This seems to be a Jade/Docbook problem and not a LyX LyXone. LyX LyXis capable of inserting cross-references to arbitrary positions in a text. For this purpose, it creates an anchor anchorwith the id tag aproppriately set in the SGML SGMLfile: ]]>The cross-reference cross-referenceitself is placed with the xref xrefelement:element ]]>The error means that this mechanism of cross-referencing cross-referencingis unsupported. This is why I change ]]>to ]]>with sed (see ). This way, at least cross-references to sections created by LyX LyXwill work in SGML.SGMLvalue of attribute "LINKEND" must be a single token: the label labelyou used for a section contains spaces. Change spaces to, say, underscores or dashes.value of attribute "ID" must be a single token: you used a cross-reference cross-referenceto a label labelthat contains spaces. Do not change the cross-reference.cross-reference Change the label:label change spaces to, say, underscores or dashes.end tag for "SECT3" which is not finished: You probably have an empty subsubsection,subsubsection e.g. you just outlined your documents and some subsubsections have a title but no content (yet). I consider this warning to be a bug. Or is it a feature???end tag for element "LISTITEM" which is not open: this may be a bug of LyX' SGMLSGML generation. It happens when in an itemize itemizeenvironment environmentyou use a higher depth, possibly with nested nesteditem lists and subsequent paragraphs that you want to be on the same identation identationlevel as the outer item. Not critical."keep-with-next:" is not a valid keyword in a make expression for flow object class "paragraph": Didn't track trackit down, but seems harmless.value of attribute "FORMAT" cannot be "PDF": Openjade Openjadetell us:

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

this means that the list of accepted formats does not contain “PDF”. Such a list appears in the following files:/usr/share/sgml/db3xml/dbnotnx.mod/usr/share/sgml/docbk30/docbook.dtd/usr/share/sgml/docbook_3/dbnotn.mod/usr/share/sgml/sdb/sdocbook.dtd/usr/share/sgml/db41xml/dbnotnx.mod/usr/share/sgml/docbook_4/dbnotn.modGiven that LyX LyXproduces a SGML SGMLfile containing as the first line, meaning that it uses DocBook DocBookV4.1 (1.1.x versions still used DocBook DocBookV3.0), we only need to insert "PDF"PDF in the /usr/share/sgml/docbook_4/dbnotn.mod file: ]]>If you still use LyX LyXv.1.1.x, you should change /usr/share/sgml/docbook_3/dbnotn.mod to include “PDF” in the list of accepted file extensions:extensions ]]>Also, in the dbparam.dsl dbparam.dslfile for the print formats (located in /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/print/dbparam.dsl on my system), zou would need to add “pdf” to the list of allowed graphic extensions:extensionsHowever, this is not necessary, since we use the technique of “ customization customizationlayers” (see ) and define %graphic-extensions% %graphic-extensions%in lyxtox-print.dsl as shown above. Due to the nature of the DSSSL DSSSLlanguage (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.Reference `4' on page 1 undefined on input line 180: Some cross-refernce cross-refernceyou use is probably misspelled.misspelled But this is somewhat difficult to achieve with LyX,LyX since LyX LyXprovides you with a list of all the labels currently available for cross-referencing.cross-referencing The other occasion where you will see this error is in the first (or even second?) invocation invocationof LaTeX LaTeXfor a particular format. You need at least 3 LaTeX LaTeXpasses 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.cross-reference LaTeX_Font_Warning: Some font shapes were not available, defaults substituted: If you installed the Computern Modern fonts,fonts you probably don't need to worry about this error. If you check the fonts fontsused in the PDF PDFfile (File-->Documet Info-->Fonts-->List all fonts), you will probably find out that only some seldomly used characters were not rendered with CM fonts.fonts That's O.K. for me.Overfull \hbox (30.17416pt too wide) in paragraph at lines 5425--5425: You will get dozens of this. It is a typical LaTeX LaTeXwarning informing you that a line got some points too wide (mostly because there was some word that LaTeX LaTeXcould not hyphenate). Read the LaTeX LaTeXdocumentation for this (but only if you want to produce a really perfect PDF PDFdocument)./usr/share/sgml/stylesheets/sgmltools/print.dsl:53:6:E: 3rd argument for primitive "string-append" of wrong type: "#f" not a string: This is probably caused because %graphic-default-extension% %graphic-default-extension%is set to “false” (“#f”), while in lyxtox-print.dsl we try to concatenate the %admon-graphics-path%,%admon-graphics-path% the name of the admonition admonitionand %graphic-default-extension% %graphic-default-extension%to a full name of the admonition admonitiongraphic. It is harmless, due to the way we use the graphics (see ).Warning: Version of thumbpdf.tex' does not match with perl script!: thumbpdf thumbpdfcomplains even if the version is a newer one:But if you have the newest version, as in the above case, there is no need to worry about this error. end tag for "SECT1" which is not finished: You may see this openjade openjadeerror also for “SECT2”, “SECT3” and so forth. This may come up if you have written just the title of the section, subsectionsubsection or subsubsection subsubsectionrespectively, but you did not enter any text there. Just enter something, even a single word like “FIXME” (author's note to himself: this is a literal FIXME,FIXME not a meta-FIXME!), to remind you of the missing text, and the error should go away.document type does not allow element "SECT2" here: This is a similar error to the previous one. You most probably created a subsection subsectionwhich is not contained in a section, but is dircetly contained in a chapter. Similar errors will occur if you ommit environment environmentlevels that are “in between” the current one and its parent.length of name token must not exceed NAMELEN (44): You have an ID IDon the line where this error comes up - and this ID IDis too long, longer than NAMELEN, which is 44 in my case. Use a shorter ID.ID What in SGL comes as the ID IDof a chapter, section, figure or table, in LyX LyXit is a label.label Thus you should check your labels and make sure they are not longer than 44 characters.Alternatively, change the value of NAMELEN in the file pointed to by the SGMDCL directive directivein your catalog catalogfiles: The lyxtox script uses, among others, the following catalog:catalog /usr/share/sgml/CATALOG.docbook-dsssl-stylesheets. You can see this in the line: In this catalog,catalog I have changed the SGMLDECL line from:toto reflect the correct path pathto the DocBook DocBookdeclaration file in my system. You must thus change the value of the NAMELEN variable in the file where the SGMLDECL points to, i.e.Note that this may be specific to SuSE 9.0. Other distributions may have corrected it. docbook/docbook-dsssl-stylesheets/dtds/decls/docbook.dcl. There, change to, for example: See the error 'character "_" is_not allowed in the value of attribute "ID"' below for more changes you might need to make in the DocBook DocBookdeclaration file.character ":" is_not allowed in the value of attribute "ID": You have a LyX LyXlabellabel that contains “:”. Delete the “:” , as the label labelof a chapter, section, figure, table etc. is going to be the ID IDof that element elementand “:” is not allowed in IDs. However, this only the short answer. For an in-depth explanation, see the next item.character "_" is_not allowed in the value of attribute "ID": You have a LyX LyXlabellabel that contains “_”. Delete the “_” , as the label labelof a chapter, section, figure, table etc. is going to be the ID IDof that element elementand “_” is not allowed in IDs. However, as said in the previous item, this is only the tip of the iceberg. A tip of the hat to Tony Graham for the following detailed information in Allowed characters in element id's!The characters allowed in an ID IDare those allowed in an SGML SGML"NAME". The characters that are allowed to appear in “names” in SGML SGML(the id attribute attributeis defined in SGML SGMLas such a “NAME”) are set in what is known as the “ SGML SGMLdeclarationSGML declaration” of your document.document By default, the first character must be a letter, and any other characters may be a letter or a digit.You can add to this by specifying the additional characters in your SGMLSGML 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 SGMLstandard itself that adds "." and "-" as "name" characters (but not as "name start" characters). This is what's used in the DocBook DocBookSGML SGMLDeclaration, docbook.dcl.The specific portion of the SGML SGMLDeclaration of interest here is the "naming rules". Jade's default inferred SGML SGMLDeclaration uses the same naming rulesrules as SGML's "Reference Concrete Syntax". To allow underscores in entity entitynames (and other SGML SGMLnames), you need to supply an SGML SGMLDeclaration that includes the underscore character. Using the DocBook DocBookSGML SGMLDeclaration as an example, you need to add "_" to the LCNMSTRT and UCNMSTRT parameters:The NAMING portion specifies both uppercase and lowercase forms of the additional "name start" and "name" characters (since names are folded to uppercase when the "GENERAL" parameter parameterhas the value YES"). You need to add it in two places because you are declaring the uppercase and lowercase forms, which just happen to be the same.You can reference your SGML SGMLDeclaration by including it in the JadeJade command line before the filename for your SGML SGMLfile (or before your DTD DTDif also including the DTDDTD filename in the command line). You can also reference an SGML SGMLDeclaration to infer by using the "SGMLDECL" keyword keywordin your catalog catalogfile. (See "charset.htm" from the nsgmls distribution distributionfor more information on the catalog catalogformat. FIXME:FIXME URL!)Now, what does all that mean for our specific situation?The lyxtox script uses, among others, the following catalog:catalog /usr/share/sgml/CATALOG.docbook-dsssl-stylesheets. You can see this in the line: In this catalog,catalog change the SGMLDECL line from:toNote that we have taken away the comments and corrected the path pathto the declaration.But that's NOT enough!You must also change the file where the SGMLDECL points to, i.e.Note that this may be specific to SuSE 9.0. Other distributions may have corrected it. docbook/docbook-dsssl-stylesheets/dtds/decls/docbook.dcl. There, change to:i.e. add the underscore to LCNMCHAR and UCNMCHAR.This solves the problem at its root! See also character "_" not allowed in value of attribute ID.general_entity_"d_op"_not_defined_and_no_default_entity: When you enter an URL URLin LyX,LyX you are asked to enter the URL URLand the Name of the link in a window that pops up. Whatever you enter in the URL URLfield, will be automatically automaticallytaken care by LyX:LyX if it contains special characters, like ampersands,ampersands they are replaced with their SGML SGMLequivalent (see SGML entities). But whatever you enter in the Name field, it will passed “as is” to SGML.SGML If you feel lazy and just copy the URL URLin the Name field, you must take care to replace special characters with their SGML SGMLentities 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 likeinstead of Linux Forum of Chris ]]>then you should write it asi.e. replace “&” with its SGML SGMLentity “&”.element "BODY" undefined: BODY? Which body?body You don't remember to have entered anything like this in you text? Well, check for “<body>” somewhere in the text (not the code environments,environments as those have been taken care already by LyX). You have to replace the “<” and “>” with their SGML SGMLentities “<” and “&gt” respectively. When you correct it, the other two errorswill disappear too, since they are just follow-ups of the first one.character data is not allowed here: This simply means that you did not replace some special character with its SGML SGMLentity. Have a look at the tables in SGML entities, try to guess which character is meant in the error (the SGML SGMLlines produced by LyX LyXcan become longer than Proust's), and replace it.But the reason for this error may also lie in the fact that you forgot to change the LyX LyXenvironment environment(see ) from SGML SGMLto Standard and the text contains some special characters, like dashes. In this case, the text is interpreted interpretedin the SGML SGMLcontext and the special characters give rise to misunderstandings and errors in th parser.parser Just change the environment environmentfrom SGML SGMLback to Standard (or whatever else it should be) and the error will disappear.document type does not allow element "MEDIAOBJECT" here: This error happens because sed (more precisely, the sed commands in sedscr) did not manage to change the SGML SGMLthat LyX LyXproduced for a figure. The reason sedscr failed lies probably in some strange arrangement of the starting SGML SGMLtags for the figure. The best cure is to enter a “forced new line” by pressing Strg+Enter at the end of the line that precedes the offending figure. This will force the whole SGML SGMLcode to start on a new line and will make identification identificationby sedscr easier. The next time you run lyxtox, the correct SGML SGMLcommands for the figure will be generated and the error will disappear.an attribute value must be a literal unless it contains only name characters: How on earth could this happen? Well, if you are like me and always try new possibilities with LyX LyXand SGML,SGML then you will encounter this error if you enter an URL URLwhile in the SGMLSGML environment.environment There, of course, you cannot just use LyX' menu Insert->URL - you have to write the SGML SGMLcode for an URL URL<ulink url=”http://www.somesite.com”>. Now, if you forget to enclose the URL URL(the “ attribute attributevalue”, as the error says, of the “url” attribute attributein the ulink element) in double quotes, then you will get that error.document type does not allow element <para> (after <entry> in a table): You shouldn't get this error when you use the scripts desribed here - simply because the sedscr_tidy2 script takes care that it does not occur. However, if you do get it, it is nice to know why:Due to the way the SGML SGMLparser works, the following piece of code describing an informal table will produce a “ document documenttype does not allow elementelement <para>” error:The reason is the so-called “Pernicious Mixed Content Problem”. From the Definitive Guide to DocBook on the <entry> element:

The content model of the Entry element elementexhibits a nasty peculiarity that we call pernicious mixed content.[18]Every other element elementin DocBookDocBook contains either block elements or inline inlineelements (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 SGMLparser, anyway) where inlineinline markupmarkup can occur.Table entries are different; they can contain either block or inline inlineelements, but not both at the same time. In other words, one Entry in a table might contain a paragraph paragraphor a list while another contains simply #PCDATA or another inline inlinemarkup,markup but no single Entry can contain both.Because the content model of an Entry allows both kinds of markup,markup each time the SGML SGMLparser encounters an Entry, it has to decide what variety of markup markupit contains. SGML SGMLparsers are forbidden to use more than a single tokentoken of lookahead to reach this decision. In practical terms,terms what this means is that a line feed or space after an Entry start tag causes the parser parserto decide that the cell contains inlineinline markup.markup Subsequent discovery of a paragraph paragraphor another block element elementcauses a parsing error.All of these are legal:However, each of these is an error:

Thus, the informal table example above must be corrected to:This is done in lyxtox with a call to runsed using sedscr_tidy2 as the sed script. See also Openjade error: <para> not allowed after <entry>. TeX errorsThe material in this section (up to ) is taken from the TeX TeXFAQ FAQitem on How to approach errors.Since TeX TeXis a macroprocessor,macroprocessor its error messages are often difficult to understand; this is a (seemingly invariant) property of macroprocessors.macroprocessors KnuthKnuth makes light of the problem in the TeXbook,TeXbook suggesting that you acquire the sleuthing skills skillsof a latter-day Sherlock Holmes;Holmes while this approachapproach 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 RahtzRahtz in TUGboat 16(4)) offers some general guidance in dealing with TeXTeX 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:Look at TeX TeXerrors; those messages may seem cryptic at first, but they often contain a straightforward clue to the problem. See for further details. Read the .log file; it contains hints to things you may not understand, often things that have not even presented as error messages. Be aware of the amount of context that TeX TeXgives you. The error messages gives you some bits of TeX TeXcode (or of the documentdocument itself), that show where the error "actually happened"; it's possible to control how much of this 'context' TeX TeXactually gives you. LaTeXLaTeX (nowadays) instructs TeX TeXonly to give you one line of context, but you may tell it otherwise by sayingin the preamblepreamble of your document.document (If you're not a confident macro macroprogrammer, 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.) As a last resort, tracing can be a useful tool; reading a full (La)TeX tracetrace takes a strong constitution,constitution but once you know how, the trace tracecan lead you quickly to the source of a problem. You need to have read the TeXbook TeXbook(see books about TeX) in some detail, fully to understand the trace.traceThe command sets up maximum tracing. tracing.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).The LaTeX LaTeXtrace package (first distributed with the 2001 release of LaTeX) provides more manageable tracing.tracing. Its \ traceon traceoncommand gives you what \tracingall offers, but suppresses tracing around some of the truly verbose parts of LaTeX LaTeXitself. The package also provides a \traceoff command (there's no "off" command for \tracingall), and a package option (logonly) allows you to suppress output to the terminal. The best advice to those faced with TeX TeXerrors is not to panic: most of the common errors are plain to the eye when you go back to the source line that TeX TeXtells you of. If that approach approachdoesn't work, the remaining answers in this section deal with some of the most common error messages you may encounter using LyXLyX and a TeX TeXsystem provided by a common Linux distribution distributionas your starting point. For more on TeX TeXerrors, consult the “Joy of TeX TeXerrors” section of the TeX FAQ. You should not ordinarily need to appeal to the wider public for assistance (see TeX mailing lists), but if you do, be sure to report full backtraces (see errorcontextlineserrorcontextlines above) and so on.The structure of <application>TeX</application> errorsThe material in this section is taken from the structure of TeX errors.TeX's error messages are reminiscent of the time when TeX TeXitself was conceived (the 1970s): they're not terribly user-friendly, though they do contain all the information that TeX TeXcan offer, usually in a pretty concise way.TeX's error reports all have the same structure:An error messageSome 'context'An error promptThe error message will relate to the TeX TeXcondition that is causing a problem. Sadly, in the case of complex macro macropackages packagessuch as LaTeX,LaTeX the underlying TeX TeXproblem 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 LaTeXitself (or by a LaTeX LaTeXclass or package).The context of the error is a stylised representation representationof what TeX TeXwas doing at the point that it detected the error. As noted in approaching errors, a macro macropackage can tell TeX TeXhow 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 macrocalled 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:produces the error reportwhile:produces the error report\bleah ]]>If the argument itself is in error, we will see things such asproducing \bleah ]]>The prompt accepts single-character single-charactercommands: the list of what's available may be had by typing typing?. One immediately valuable command is h, which gives you an expansion of TeXs original prcis message, sometimes accompanied by a hint on what to do to work round the problem in the short term. If you simply type 'return' (or whatever else your system uses to signal the end of a line) at the prompt, TeX TeXwill attempt to carry on (often with rather little success). LaTeX errorsLaTeX LaTeXoutput 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 TeXin the background)The example is from the processing of the LyX file for the PHP-Nuke HOWTO. Visit the Homepage of the PHP-Nuke HOWTO to see the result. ]]> ]]> ]]> ]]> Inline graphic :LaTeX package ]]>LaTeX file ]]>As you can see from the last line, Jade just started its work. ]]> ]]> ]]> ]]> Inline graphic It goes on with font checking as follows:LaTeX font definitions ]]> ]]> ]]>Somewhere from this point on, you will start seeing LaTeX LaTeXprocessing processingthe pages of your document documentone after the other - and outputting errors and warnings like the “ Overfull Overfull\hbox” above. There are some fairly common error messages and warnings. I'll cover those here using material from the chapter on “ LyX LyXand LaTeX LaTeXerrors” of the Extended Features manual manualfor LyX,LyX available from LyX' Help menu. You should look at a good LaTeX LaTeXbook for a complete listing.“typewriter LaTeX LaTeXWarning:“Anything beginning with these word is a warning message for the purpose of “debugging” the LaTeX LaTeXcode itself. You'll get messages like this if you added or changed cross-references or bibliography bibliographyentries, in which case, LaTeX LaTeXis trying to tell you that you need to make another run.You can by-and-large ignore these.“typewriter LaTeX LaTeXFont Warning:”Another warning message, this time about fonts fontswhich LaTeX LaTeXcouldn't find. The rest of the message will often say something about a replacement font that LaTeX LaTeXused.You can safely ignore these.“typewriter Overfull Overfull\hbox”LaTeX LaTeXabsolutely loves to spew these out. They are warning you about lines that were too long and run past the right margin. Almost always, this is unnoticeable in the final output. Or, only one or two characters extend past the margin. LaTeX LaTeXseems to generate at least one of these messages for just about any document documentyou write.You can ignore these stupid messages. Your eyes will tell you if there's a problem with something that's too wide; just look at the output.“typewriter Underfull Underfull\hbox”Not quite as common as its cousin. LaTeX LaTeXseems to like to print lines that are a bit too wide as opposed to ones that are a bit too narrow. We have no idea why.You can ignore these, too.“typewriter Overfull Overfull\vbox” and “typewriter Underfull Underfull\vbox”Warnings about troubles breaking the page. Once again, just look at the output. Your eyes will tell you where something has gone wrong.“ typewriter LaTeX LaTeXError: File ‘Xxxx’ not found” The file “Xxxx” isn't installed on this system. This usually appears because some package your document documentneeds isn't installed. If you didn't touch the preamble preambleor didn't use the typewriter\usepackage{} command, then one of the packages packagesLyX LyXtried to load is missing. Use Help&lyxarrow;La TeX TeXConfiguration, to get a list of packages packagesthat LyX LyXknows about. This file is updated whenever you reconfigure reconfigureLyX (using Edit&lyxarrow;Reconfigure) and tells you which packages packageshave been detected and what they do.If you did use the typewriter\usepackage{} command, and the package in question isn't installed, you'll need to install it yourself.“typewriter LaTeX LaTeXError: Unknown option”Error messages beginning with this are trying to tell you that you specified a bad or undefined option to a package. Check the package's documentation.“typewriterUndefined control sequence”If you've inserted LaTeX LaTeXcode into your document,document but made a typo, you'll get one of these. You may have forgotten to load a package. In any case, this error message usually means that you used an undefined command.LaTeX LaTeXError: Undefined color `rtlred'Theoretically, you can define your own colours in jadetex.jadetexcfg.jadetex.cfg For example, the following block of code defines three new colours, rtlred, rtlblue and rtlgreen (the green being a bit darker than usual):However, no matter where I position this code in jadetex.jadetexcfg jadetex.cfg(i.e. either before or after the call to hypersetup), I get the above error. For the time being, my remedy is to stick to the standard colours. Please inform me if you find a better solution.Andreas Ekenb�ck (private communication) has found that by having double declarations of a colour:in jadetex.cfg, it works. On his Fedora Core 4 workstation, he says, it is even enough to have the first declaration.Further reading: see the chapter on “ LyX LyXand LaTeX LaTeXerrors” of the Extended Features manual manualfor LyX LyXfor tips on how to handle LaTeXLaTeX errors and warnings. TeX capacity exceededIf you encounter TeX TeXerrors, especially you may have to set in texmf.cnf texmf.cnf(usually located in /etc/texmf, or where the TEXMFCNF TEXMFCNFenvironment environmentvariable (see) shows):FYI, here's how much memory TeX TeXused for this document document(you may see such information in the .log file created by pdfjadetex pdfjadetexwhich is deleted by default in lyxtox):See my Jade Odyssey for more details and ideas on this and other related errors. Fatal format file error; I'm stymiedWell...me too. ]]> ]]> ]]> ]]> Inline graphic This what the TeX FAQ says about this error:(La)TeX applications often fail with this error when you've been playing with the configuration, or have just installed a new version.The format file contains the macros that define the system you want to use: anything from the simplest (Plain TeX) all the way to the most complicated, such as LaTeX LaTeXor ConTeXt.ConTeXt. From the command you issue, TeX TeXknows which format you want.The error messagemeans that TeX TeXitself can't understand the format you want. Obviously, this could happen if the format file had got corrupted,corrupted but it usually doesn't. The commonest cause of the message, is that a new binary has been installed in the system: no two TeX TeXbinaries on the same machine can understand each other's formats. So the new version of TeX TeXyou have just installed, won't understand the format generated by the one you installed last year.Resolve the problem by regenerating the format; of course, this depends on which system you are using. On a teTeX-based teTeX-basedsystem, runor ]]>to build only the format that you are interested in.I got this error during the PDF PDFprocessing processing(). Since pdftex pdftexis the program that was running at this stage, I tried both orbut 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 hundredsof cross-references (probably more than 500) in just one section (see it in Credits for version 2.0 of the PHP-Nuke HOWTO). The solution was to upgrade upgradepdftex from 0.13d to 1.11b (pdfTeX (Web2C 7.5.2) 3.141592-1.11b) and jadetex jadetexfrom 1.3 to 3.13. Note that upgrading pdftex pdftexwas not enough, jadetex jadetexhad to be upgraded too. Of course, you would still have to use fmtutil fmtutilas above. After the upgrades, the error disappeared. As a nice by-product, document documentprocessing processingseems to be much faster now, although I didn't conduct any benchmarks.benchmarks Corrupted NFSS tablesI got this error after I used the RefDB RefDB(, , ) DSSSL DSSSLstylesheet modifications in the local DSSSL DSSSLstylesheets (, ) that control the output. Missing $ insertedYou will probably get tons warnings like this one: ]]> above.) ]]>You can see them in the standard output, as well as in the .log file that is created automatically automatically(if you don't see any .log file, maybe lyxtox currently deletes it - check the code). They mean that TeX TeXtried to correct you , because it saw some character that is used in the mathematics mathematicsmode and thought you might have forgotten to switch. So it inserts a $, which toggles math mathmode. If this is not what you intended (it will most probably not, if your .tex file is created through the procedure proceduredescribed here), then your only salvation is to escape the character that triggered this behaviour.behaviour This means that you may have to escapeSlashes (/) in URLs, at least when they separate two numbers numbers(not tested)Underscores (_)Carets (^) and generally everything that may have a math mathinterpretation in TeX/LaTeX/LyXFIXME: This needs testing! Till now, I didn't resort to escaping - and stil things work remarkably well... Unprintable charactersInevitably, sooner or later, you will hit a very nasty problem in documentdocument processing:processing some characters in your file will be unprintable! They may appear in the PDFPDF as black boxesboxes (for example $ > > $ ]]> ]]> ]]> ]]> , in the OT1 OT1font encoding), or simply wrong. Here is what you can do to solve this problem:If you are using the OT1OT1 font encodingencodingThere 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 , i.e. if your jadetex.cfg file contains the linethen you have to enter the following characters in math mathmode: $ \backslash $ ]]> ]]> ]]> ]]> (backslash)FIXMEIf you are using the T1T1 font encoding,encoding i.e. if your jadetex.cfg file contains the linethen you can use the aeae and aecomplaecompl packages packagesin order to be able to write almost every europeaneuropean character:You will not, however, manage to get the two $ < $ ]]> ]]> ]]> ]]> symbols,symbols $ < < $ ]]> ]]> ]]> ]]> , printed correctly. If your purpose was to get the french quote characters (the “guillemets”), then you could replace the ae aeand aecompl aecomplpackages packageswith the aeguillaeguill package, i.e. replace the above line in jadetex.cfg with:If your purpose was to get two $ < $ ]]> ]]> ]]> ]]> signs, one after another, just as if you were describing the effect of the “append” operator in> file2 ]]>then you must enter the $ < < $ ]]> ]]> ]]> ]]> in math mathmode. Note that the above holds for the standard LyX environment (see ) and probably all other environments where you use the same font as in the body text. You don't need to worry about characters in the code environment, probably because programming code is usually written in the ASCII encoding and LyX uses CDATA in <screen> or <programlisting> environments, where ASCII (or, maybe the value of the SP_ENCODING environment variable) is the expected input encoding for Openjade. For more information on fonts fontsand their encodings, see FIXME.FIXME Other errorsKeywords not present in HTML If you don't see the keywords keywordsin the HTML HTMLfile, then this may be a bug in your stylesheets. There seems to be a bug in dbcommon.dsl dbcommon.dsl(DocBook DSSSL DSSSLstylesheets 1.73) that prevents this from happening for an article, where the <keywordset> in within <articleinfo>. The definition of "info-element"info-element in dbcommon.dsl dbcommon.dslcontainsbut no reference to "articleinfo"articleinfo.In dbcommon.dsl,dbcommon.dsl which in my system resides in /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/common/dbcommon.dsl and belongs to packet docbook-dsssl-styledocbook-dsssl-stylesheets-1.72-34, replace the definition of info-element info-elementwith: thumbpdf fails Perhaps the most accurate indicator of a serious error in your documentdocument or settings is the failing of thumbpdf:thumbpdfAlthough document documentprocessing processingwill 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 eliminateit, or revert to a configuration that is known to work.However, there is an exception to this rule of thumb: if you see the errorthe 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 sed segmentation faultOn one occasion, I got the following very disturbing error:/tmp/$y$$ ]]>Output of the corrected SGML SGMLfile broke at a line for no apparent reason. Openjade Openjadecomplained (of course) with some errors, but processed the file. I noticed that something went wrong from the output of thumbpdf thumbpdf(see ): thumbpdf thumbpdfprints 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 segmentationfault. I guess it has to do with the exceptionally long line that sed had to process: LyX LyXproduces very long SGML SGMLlines. It does not break the lines at SGML SGMLtags and clutters them on one line for reasons unknown to me. That particular line was thus more than 3400 charactersof SGML text, original text was certainly less than that. long when it was output without the error. As soon as I added some innocent innocenttext that made it a little longer, it would cause the segmentation segmentationfault above. I guess this breaks some input line length limitation in sed. However, this is denied to be the case in the sed manual on the (non-)limitations on line length:

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

The only remedy if this limit does exist (as it seems to be in my case), is to shorten your text, or introduce a paragraph,paragraph admonition admonition(see , ), code or other environment environment() that may persuade LyX LyXto start a new SGML SGMLline in the exported SGML SGMLtext. Acrobat <application>Reader</application> 5 does not show thumbnails in LinuxThe thumbpdf thumbpdfscript creates thumbnails thumbnailsfor the PDF PDFdocument just fine (see ). Things work fine even with a thumbpdf.tex thumbpdf.texof version 3.2 and a thumbpdf thumbpdfof version 2.8, i.e. even if the versions of these two files differ (in which case thumbpdfthumbpdf will issue a warning, see ). Yet, one day, I recomputed the PDF PDFversion of a document,document only to discover that the thumbnails thumbnailswere appearing intermittently in the document:document some (few) appeared, the rest showed just a blank thumbnail. After an extensive Internet search (with very few results on the subject...) and a check with both Acrobat Reader 5 for Linux and Acrobat Reader 7 for Windows,Windows it became clear that this is a problem of Acrobat Reader 5 for Linux and large thumbnails thumbnails(small thumbnails thumbnailsare displayed fine).I guess there is nothing you can do about this problem, other than switch to small thumbnails thumbnails(right-click on the thumbnail area to see the context menu that will allow you to choose this), or upgrade upgradeto a version of Acrobat Reader that does not suffer from this bug. URLs with underscore display '&lowbar;' instead of '_'Any URL URLthat has an underscore in it (like the link to awkscr_insert_index_items) shows '&lowbar' in place of '_'. To correct this, you must check the checkbox “ HTML HTMLtype” when you insert the URL URLin LyX,LyX see .

Insert URL with underscores in LyX. ]]> ]]> ]]> ]]> Insert URL with underscores in LyX. Insert URL with underscores in LyX. When you do this, you should NOT write underscores as '&lowbar;'. You should write an underscore as is, i.e. as '_', in both the URL and the Name fields . FIXME: This still does not solve the problem in PDFs: there, the underscore is interpreted mathematically, making the character following the underscore to appear as a subscript. Moreover, if the link does not have an ending, it gets the standard ending for PDFs, namely “.pdf” attached to it, which is definitely wrong. Try this link: awkscr_insert_index_items, in HTML and in PDF to see the difference! sed: file sedscr_img line 2: Unknown option to `s'You get the error:When you check the offending line 2 of sedscr_img (remember that sedscr_img is dynamically generated each time you run lyxtox), you see:/ ISO/DIN paper sizes.

/g ]]>Now it's clear what the error is: the caption to a figure contains a backslash (in "ISO/DIN"), which is used by sed as a regular expression delimiter. The easiest solution to this seems to be: just avoid using backslash in figure captions! You cannot have everything in this world, it seems... ]]> ]]> ]]> ]]> Inline graphic See for the corrected caption of this specific example. Explaining the magic: the details William Safire Knowing how things work is the basis for appreciation, and is thus a source of civilized delight. What makes the procedure proceduredescribed here appear to be “magic” is not only the “high-tecness” of the tools toolsinvolved, but also the highly frustrating fact that each one of the tools toolsinvolved expects its input in different directories and/or formats, making it really difficult for interfaces or pipes pipesto 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. Tip: You don't need to read this chapter if you are not interested in the gory details. For getting things to work, the , , and should suffice. But if you want to understand how things work, then go on! Document processingWhat happens when you type “ lyxtox lyxtoxmyTemplate”? A lot! Let's inspect it step by step:The name of the parameter parametergiven to the lyxtox script, myTemplate,myTemplate becomes $1. Whenever you see $1 in the code examples below, just replace it mentally with the name you supplied to lyxtox.lyxtoxCheck number of parametersAs in every good script, a rudimentary parameter parameternumber check is the very first thing to do:If the number of parameters is not exactly 1, the output of the help() function is printed, which looks like this: Set program locationsIf the parameter parameternumber check is passed, some program locations are set (adapt them to our situation!):Further, the stylesheet stylesheetlocations are set (adapt them to your situation too):You only need to change this part, if at all. The RefDB RefDBpart:works automatically automaticallyand it is does not play any role how you name (or where you place) the HTML_DSL HTML_DSLand PRINT_DSL files in this case - they will be automatically automaticallycreated through awkscr_refdb_html and awkscr_refdb_print with whatever filename you pass to them for their output respectively, see the source code of lyxtox. Set environment variablesIt's time to set some environment environmentvariables. This is where quite a lot of the “magic” is hidden! Although they are mentioned somewhere in the respective manpages,manpages a newcomer will have probably never heard of them. The result: images cannot be found, no matter how “right” you did it, as well as some other annoyances regarding font mappings. This is because different tools toolsread different environment environmentvariables 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 SGMLparsers or PDF PDFsoftware. Since we entered the names of images without any path pathinformation in LyX,LyX openjade openjadeneeds to be informed of their location with the environment environmentvariable SGML_SEARCH_PATH:SGML_SEARCH_PATHpdftex pdftex(and pdfjadetex) will look at a different environment environmentvariable for the location of the image files: TEXPSHEADERS.TEXPSHEADERS For some reason which I don't fully understand, \ includegraphics includegraphicswith pdftex pdftexuses the TEXPSHEADERS TEXPSHEADERSenvironment environmentvariable for the additional paths pathsto search. Also: TEXPSHEADERS TEXPSHEADERScontains the search path pathwhere pdftex pdftexlooks up for font mapping file (pdftex.map) and encoding encodingfiles (*.enc):LaTeX, on the other side, will look at still another variable for the pathpath to images: TEXINPUTS TEXINPUTS(TEXINPUTS is also defined in the texmf.cnf texmf.cnffile, usually located in the directory pointed to by the TEXMFCNF TEXMFCNFenvironment environmentvariable):LaTeX & Co. need this! ]]>The TEXMFCNF TEXMFCNFenvironment environmentvariable points to the directory that contains the configuration files for TeX:TeXIn /etc/texmf/texmf.cnf we read:The next environment environmentvariable we will have to set, is the one that passes options to thumbpdf thumbpdf(see ), for the case that you wish to do so:Last but not least, openjade openjadeneeds to know the locations of the SGML SGMLcatalog files (see ):The SP_ENCODINGSP_ENCODING environment environmentvariable tells OpenjadeOpenjade in which encoding encodingthe input file is written in:Encoding names are case insensitive. The following named encodings are available (see Handling of character sets in OpenSP):utf-8 utf-8Each character is represented by a variable number of bytes according to UCSUCS Transformation Format 8 defined in Annex P to be added by the first proposed drafted amendment (PDAM 1) to ISO/IEC 10646-1:1993.utf-16 utf-16Each character is represented by a variable number of bytes according to UCS UCSTransformation Format 16 defined in Annex O to be added by the first proposed drafted amendment (PDAM 1) to ISO/IEC 10646-1:1993.ucs-2 iso-10646-ucs-2 iso-10646-ucs-2This 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 markcharacter.ucs-4 iso-10646-ucs-4 utf-32 utf-32This is ISO/IEC 10646 with the UCS-4 transformation format. Each character is represented by 4 bytes.unicode unicodeEach character is represented according to the utf-16 utf-16encoding. The bytes representing the entire storage object may be preceded by a pair of bytes representing the byte order mark markcharacter (0xFEFF). The bytes representing each character are in the system byte order, unless the byte order mark markcharacter is present, in which case the order of its bytes determines the byte order. When the storage object is read, any byte order mark markcharacter is discarded.euc-jp euc-jpThis is equivalent to the Extended_UNIX_Code_Packed_Format_for_Japanese Internet charset. Each character is encoded by a variable length sequence of octets.euc-kr euc-krThis is ASCII ASCIIand KSC 5601 encoded with the EUC encoding encodingas defined by KS C 5861-1992.euc-cn cn-gb gb2312 gb2312This is ASCII ASCIIand GB 2312-80 encoded with the EUC encoding.encoding It is equivalent to the CN-GB MIMEMIME charset defined in RFC 1922.sjis shift_jis shift_jisThis 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 encodingfor Japanese.Japanesebig5 cn-big5 This is equivalent to the CN-Big5 MIME MIMEcharset defined in RFC 1922.is8859-n iso-8859-n n can be any single digit other than 0. Each character in the repertoire of ISO ISO8859-n is represented by a single byte.koi8-r koi8 koi8The koi8-r koi8-rencoding as defined in RFC 1489.xml xmlOn input, this uses XML's rules rulesto determine the encoding.encoding On output, this uses UTF-8.windows windowsSpecify this encoding encodingwhen a storage object is encoded using your system's default Windows Windowscharacter set. This uses the so-called ANSI code page.wunicode wunicodeThis uses the unicode unicodeencoding if the storage object starts with a byte order mark markand otherwise the windows windowsencoding.encoding If you are working with Unicode, this is probably the best value for SP_ENCODING.ms-dos ms-dosSpecify this encoding encodingwhen a storage object (file) uses the OEMOEM code page. The OEM OEMcode-page for a particular machine is the code-page used by FATFAT file-systems on that machine and is the default code-page for MS-DOS consoles.For OpenSP,OpenSP a suite of SGML/XML processing processingtools related to Openjade,Openjade there are two other environment environmentvariables that are related to SP_ENCODING SP_ENCODING(see Handling of character sets in OpenSP):SP_CHARSET_FIXED SP_CHARSET_FIXEDIf this variable is 1 or YES, then OpenSP OpenSPwill operate in fixed character set mode.SP_SYSTEM_CHARSET SP_SYSTEM_CHARSETThis 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 documentcharacter set has been read, at which point the document documentcharacter 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.But since lyxtox lyxtoxdoes not use OpenSP,OpenSP we don't need to care about these two, as the manual manualpage of Openjade Openjadeasserts: Openjade does not use SP_CHARSET_FIXED and SP_SYSTEM_CHARSET OpenJade ignores the SP_CHARSET_FIXED and SP_SYSTEM_CHARSET environment variables and always uses Unicode as its internal character set, as if SP_CHARSET_FIXED was 1 and SP_SYSTEM_CHARSET was unset. Thus only the SP_ENCODING environment variable is relevant to OpenJades handling of character sets. Main partIn the main part, the hard work (for your computer) begins:The document documentis exported from LyX LyXto DocBook DocBookSGML:SGMLThe SGML SGMLthat is produced by LyX LyXhas several shortcomings.shortcomings They have to be corrected. This is done by calling runsed:which is the subject of the next subsection.subsection Alternative commands There are quite a few alternative invocations of the various tools at appropriate places in the lyxtox script, in the form of comments. These are there in order to show you how you can achieve an equivalent result through other tools. Runsed, sed and sedscrRunsed Runsedtakes as argument the sedscript sedscriptto run and the file against which to run it. It calls sed with sedscr as the “sed command file”. In the sedscr sedscrfile itself there is another bunch of “magic” going on: Important note: The changes in LyX' SGML code presented here pertain strictly to LyX version 1.2.0! The 1.1.x versions needed slightly (and subtly) different changes and the same may be true for future versions of LyX. Examples of sed commands for previous LyX versions are presented in the sedscr file in comments. Use (or construct) the right sed commands for the right changes for your LyX version! The success of this method depends crucially on this. The code]*\)>$[^<]*$<anchor $[^>]*$>/<\1 \3>\2/g ]]><![CDATA[s/<$chapter$>$<title>[^<]*$<anchor $[^>]*$>/<\1 \3>\2/g ]]></screen><para>tells sed to substitute<footnote><para>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 ;-)</para></footnote> </para><screen><![CDATA[< sect1 >< title > some title < anchor id="some label" > ]]></screen><para>with</para><screen><![CDATA[<sect1 id="some label" ><title>some title ]]></screen><para>and</para><screen><![CDATA[< chapter >< title > some title < anchor id="some label" > ]]></screen><para>with</para><screen><![CDATA[<chapter id="somelabel"><title> some title ]]></screen><para>The code</para><screen><![CDATA[/^.*<figure><title><graphic/{ ]]><![CDATA[s/<figure><title><graphic fileref="$[^"]*$">[ ]*<anchor id="$[^"]*$">$[^<]*$<\/title>[ ]*<\/figure>/\ ]]><![CDATA[<figure id="\2">\ ]]><![CDATA[ <title>\ ]]><![CDATA[ \3\ ]]><![CDATA[ <\/title>\ ]]><![CDATA[ <mediaobject>\ ]]><![CDATA[ <\!\[ \%output\.print\.png; \[\ ]]><![CDATA[ <imageobject>\ ]]><![CDATA[ <imagedata fileref="\.\/images\/\1.png" format="PNG">\ ]]><![CDATA[ <\/imageobject>\ ]]><![CDATA[ \]\]>\ ]]><![CDATA[ <\!\[ \%output\.print\.pdf; \[\ ]]><![CDATA[ <imageobject>\ ]]><![CDATA[ <imagedata fileref="\1.pdf" format="PDF" scale="65">\ ]]><![CDATA[ <\/imageobject>\ ]]><![CDATA[ \]\]>\ ]]><![CDATA[ <\!\[ \%output\.print\.eps; \[\ ]]><![CDATA[ <imageobject>\ ]]><![CDATA[ <imagedata fileref="\1.eps" format="EPS">\ ]]><![CDATA[ <\/imageobject>\ ]]><![CDATA[ \]\]>\ ]]><![CDATA[ <\!\[ \%output\.print\.bmp; \[\ ]]><![CDATA[ <imageobject>\ ]]><![CDATA[ <imagedata fileref="\1.bmp" format="BMP">\ ]]><![CDATA[ <\/imageobject>\ ]]><![CDATA[ \]\]>\ ]]><![CDATA[ <textobject>\ ]]><![CDATA[ <phrase>\3<\/phrase>\ ]]><![CDATA[ <\/textobject>\ ]]><![CDATA[ <caption>\ ]]><![CDATA[ <para>\3<\/para>\ ]]><![CDATA[ <\/caption>\ ]]><![CDATA[ <\/mediaobject>\ ]]><![CDATA[<\/figure>\ ]]><![CDATA[/g ]]><![CDATA[} ]]></screen><para>tells sed to substitute<footnote><para>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 ;-)</para></footnote> </para><screen><![CDATA[< figure >< title >< graphic fileref="imagename" > some blanks < anchor id="some id" >some title< /title > ]]></screen><para>with the more elaborate combination of figure and mediaobject <indexterm><primary>mediaobject</primary></indexterm>elements:</para><screen><![CDATA[]]><inlinegraphic fileref="&file1008;" format="linespecific"><![CDATA[ ]]></screen><para>There are some remarks due here:</para><itemizedlist><listitem><para>The title of the original SGML <indexterm><primary>SGML</primary></indexterm>appears in three places of the new SGML: the title, the phrase for the alternative text and the caption.<indexterm><primary>caption</primary></indexterm> LyX <indexterm><primary>LyX</primary></indexterm>uses the figure caption <indexterm><primary>caption</primary></indexterm>for the title and there is no way we can derive three different texts for the three different uses in the new SGML.<indexterm><primary>SGML</primary></indexterm> That is why in the output document <indexterm><primary>document</primary></indexterm>the figure title, the alternative text and the figure caption <indexterm><primary>caption</primary></indexterm>are identical.</para></listitem><listitem><para>For the PNG <indexterm><primary>PNG</primary></indexterm>format we must prefix the image file name, imagename.png, with the relative path <indexterm><primary>path</primary></indexterm>(./images) to it, even though we set all environment <indexterm><primary>environment</primary></indexterm>variables correctly (see <xref linkend="explain-environment-variables">). This is not necesary for the other formats. </para></listitem><listitem><para>We scale the PDF <indexterm><primary>PDF</primary></indexterm>images to 100%. I used to scale them down to 65%,<indexterm><primary>65%</primary></indexterm> but this is no longer necessary, after some experimentation with various scale factors that seem to compensate for this need in the <ulink url="addd">addd</ulink> utility.<indexterm><primary>utility</primary></indexterm> See also <xref linkend="add-density">.</para></listitem><listitem><para>We make use of external SGML <indexterm><primary>SGML</primary></indexterm>entities like %output.print.png; This is a topic of its own which is explained in detail in <xref linkend="explain-figures">.</para></listitem></itemizedlist><para>A mediaobject <indexterm><primary>mediaobject</primary></indexterm>similar to the above (but without figure id and caption) is inserted whenever a “simple” image, i.e. one without the float element <indexterm><primary>element</primary></indexterm>with caption,<indexterm><primary>caption</primary></indexterm> is encountered in LyX' SGML.<indexterm><primary>SGML</primary></indexterm> It substitutes a line like<footnote><para>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 ;-)</para></footnote> </para><screen><![CDATA[< graphic fileref="imagename" > ]]></screen><para>with a mediaobject <indexterm><primary>mediaobject</primary></indexterm>like</para><screen><![CDATA[]]><inlinegraphic fileref="&file1009;" format="linespecific"><![CDATA[ ]]></screen><para>Notice that the text is now simply "Figure", since there was no caption.<indexterm><primary>caption</primary></indexterm> You may change it to something else. There is also no id available for this mediaobject,<indexterm><primary>mediaobject</primary></indexterm> therefore you cannot cross-reference <indexterm><primary>cross-reference</primary></indexterm>it. That's why I suggested floats <indexterm><primary>floats</primary></indexterm>in <xref linkend="LyX-images">.</para><para>The following sed code</para><screen><![CDATA[]]><inlinegraphic fileref="&file1010;" format="linespecific"><![CDATA[ ]]></screen><para>will substitute <programmlisting> with <screen>, while this one:</para><screen><![CDATA[# Delete the <para> before the <tgroup> tag. ]]><![CDATA[s/<tgroup/<tgroup/g ]]><![CDATA[# Delete the </para> after the </tgroup> tag. ]]><![CDATA[s/<\/tgroup><\/para>/<\/tgroup>/g ]]></screen><para>will delete <para> before <tgroup> and </para> before </tgroup>.</para><para>For table captions <indexterm><primary>captions</primary></indexterm>and titles to be output correctly, you have to eliminate<indexterm><primary>eliminate</primary></indexterm> the <para> from any sequence </title><para><tgroup> AND you have to write a table float (see <xref linkend="LyX-tables">, in the inside of which you will have to set the title and the caption<indexterm><primary>caption</primary></indexterm> environment <indexterm><primary>environment</primary></indexterm>on one line, then press <enter>, set the environment <indexterm><primary>environment</primary></indexterm>to "Standard" (this will produce the <para> element <indexterm><primary>element</primary></indexterm>we eliminate <indexterm><primary>eliminate</primary></indexterm>here) and continue with the table normally. A warning about an "end tag for element <indexterm><primary>element</primary></indexterm>"TABLE" which is not open" is the less evil we can get and is harmless (a LyX <indexterm><primary>LyX</primary></indexterm>bug in 1.2.0, not openjade's):</para><screen><![CDATA[/<\/title><tgroup/s/<\/title><tgroup/<\/title><tgroup/ ]]></screen><para>Further, for the cross-references to tables to work, we have to substitute<footnote><para>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 ;-)</para></footnote> </para><screen><![CDATA[< table >< title >< anchor id="some id" > ]]></screen><para>with </para><screen><![CDATA[<table id="some id"><title> ]]></screen><para>This is done with the following sed code:</para><screen><![CDATA[s/<table>[ ]*<title>[ ]*<anchor $[^>]*$>/<table \1><title>/g ]]></screen><para>Some minor issues still remain:</para><para>Substitute 'ldquo' with 'quot' and 'rdquo' with 'quot':</para><screen><![CDATA[s/\“/\"/g ]]><![CDATA[s/\”/\"/g ]]></screen><para>But we are not done with the quots yet: In <othercredit> we have to substitute<footnote><para>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 ;-)</para></footnote> </para><screen><![CDATA[& quot ; ]]></screen><para>with " :</para><screen><![CDATA[/<othercredit/s/\"/"/g ]]></screen><para>And: substitute<footnote><para>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 ;-)</para></footnote> </para><screen><![CDATA[& amp ; copy ; ]]></screen><para>with &copy. This will produce a Copyright <indexterm><primary>Copyright</primary></indexterm>symbol, instead of "&copy":</para><screen><![CDATA[s/\©/\©/g ]]></screen><para>Also, substitute &xxxx; with the character it representes - somehow these entities <indexterm><primary>entities</primary></indexterm>do not work:</para><screen><![CDATA[s/[/[/g ]]><![CDATA[s/]/]/g ]]><![CDATA[s/{/{/g ]]><![CDATA[s/}/}/g ]]><![CDATA[s/$/$/g ]]><![CDATA[s/%/%/g ]]><![CDATA[s/#/#/g ]]><![CDATA[s/|/|/g ]]><![CDATA[s/�/�/g ]]><![CDATA[s/_/_/g ]]><![CDATA[s/\/\\/g ]]><![CDATA[s/~/~/g ]]></screen><para>Finally, for the index to be created, we have to insert the index creation command. Comment this if you don't want an index: to substitute<footnote><para>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 ;-)</para></footnote> </para><screen><![CDATA[< /book > ]]></screen><para>with<footnote><para>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 ;-)</para></footnote> </para><screen><![CDATA[&index; ]]><![CDATA[< /book > ]]></screen><para>the following sed code is needed:</para><screen><![CDATA[/<\/book>/s/<\/book>/\&index;\ ]]><![CDATA[<\/book>/ ]]></screen><para>A similar sed code is there for the article document <indexterm><primary>document</primary></indexterm>type. Currently, this part has been commented and transfered to the <ulink url="sedscr_abi">sedscr_abi</ulink> script which inserts the entities <indexterm><primary>entities</primary></indexterm>for the Appendix, the Bibliography and the Index at once at the end of the document,<indexterm><primary>document</primary></indexterm> before the closing </book> or </article> tags.</para></sect3> <sect3 id="tidying-up-the-SGML-code"><title>Tidying up the SGML codeFinally, two calls to runsed with sedscr_tidy and sedscr_tidy2 as the script files will “ tidy tidyup” the SGML SGMLfile:sedscr_tidy consists simply of the following lines:It does practically nothing else than insert a newline newlinebefore an opening bracket (a "<") or a closing one (a ">"). After this transformation has taken place for the whole document,document runsed is called with sedscr_tidy2 as the sed script:sedscr_tidy2 will do some corrections, because the changes of sedscr_tidy went a bit too far: It will delete any newline newlinebefore the closing "]]>" of CDATA CDATAelementsand it will bring <entry> and <para> elements on the same line, i.e. it will delete any newlines between them. It will do the same for the closing </para> and </entry> pairs. Both pairs occur inside tables and due to the Pernicious Mixed Content Problem they should not contain any line feed or space in-between, or the parserparser will think that the table cell contains inline inlinemarkup markupand issue the warning that the “ document documenttype does not allow element element<para>” at that place. See the discussion of the “ document documenttype does not allow element element<para>” error in , as well as in Openjade error: <para> not allowed after <entry>. Tidy scripts mess up code snippets The tidy scripts will mess up any part of your file that contains the < and > brackets. Especially code that is included verbatim (i.e. without the use of some external entity) and contains such brackets will look awkward. Callouts will also be affected. I have deactivated the call to the scripts in the lyxtox file until I find a better solution (BTW, nsgmls will break with errors so it does not lend itself to SGML code tidying either). If potentially affected code is included with the help of an external entity though, then the tidy scripts might work fine for you. Key combinationsThe sedscr file also contains code that will add markup for keykeycombos combinationscombinations, key:The above code, for example, will substitute every occurence of the string “ CTRL X Y CTRL-X-Y ” with:thus adding the right DocBook markup for the key combination and also an index entry for it too. There is also code for “ CTRL X CTRL-X ” or only “CTRL”. Instead of “CTRL”, you can also have “ESC” or “ALT” - there is code for them too. The user can thus just write “ CTRL ALT DEL CTRL-ALT-DEL ” or “ESC” or “ ALT F4 ALT-F4 ” and the scripts will take care of markup and indexing. Acronyms, product names, applicationsThere is also automatic markup insertion for acronymsacronyms, product namesproduct names and applicationsapplications:For acronyms:For product names:For applications:The principle is the same for all three: substitute any occurence of the acronym, product name or application with the appropriate DocBook markupmarkup. For example, an string “GNU” is replaced by:(GNU is an acronym), while a “Linux” is replaced by:(Linux is a product name in this case) and “TeX” (an application) is replaced byIt is up to you which acronyms, product names or applications you want to have automatically marked up this way (they will appear in small caps if you didn't change anything in the standard stylesheets), so feel free to add or remove your favourites from the code in sedscr.This concludes the transformation of LyX' SGML SGML(specific parts were not covered here - for the Mathematics Mathematicspart, see , for the citations citationspart, see ). runsed copies the original SGML SGMLfile to a backup file with the .bak ending, then writes the output of sed to a temporary file with a random name, compares the two files and, if something has changed, replaces the original file with the temporary one, otherwise outputs a warning that the file did not change. Alt attributes for imagesBefore we continue, we have to take care of a problem that seems to be caused by a bug in the DSSSL stylesheetsstylesheets used: although we add a <phrase> element to the <textobject>'s (see the code in sedscr), it seems that it is not used for alt attributesalt attribute in the resulting images during HTML creation. This makes the resulting HTML documents fail the HTML validationvalidation, HTML test of the W3C (see ).I have decided to resolve this problem with another sed script, this time a dynamic one! First, the SGML file of the document is passed to sed using sedscr_ima: ${SEDSCRIMG} ]]>This produces a sed script (${SEDSCRIMG) called sedscr_img. We create a second sed script, ${SEDSCRGRA}, which we will use in order to substitute "graphXXXX" with the real name of the graphic file in ${SEDSCRIMG:]*\)".*>/s\/graph\1\/\2\/g/p' $1.sgml > ${SEDSCRGRA} ]]>We now use the sed script ${SEDSCRGRA} (sedscr_gra) to substitute "graphXXXX" with the real name of the graphic file in ${SEDSCRIMG}Yup, we use a sed script to change another sed script...:This last step transforms sedscr_img, but it stil contains <acronym>, <productname> and <application> tags. To erase them from the alt and title texts in the sed script ${SEDSCRIMG}, we use the sed script sedscr_apa:Finally, we add the necessary sed commands for the alt and title texts of smilies./".\/images\/icon_smile.png" alt="smile" title="smile">/g' ]]>> ${SEDSCRIMG} ]]>/".\/images\/icon_wink.png" alt="wink" title="wink">/g' ]]>> ${SEDSCRIMG} ]]>/".\/images\/icon_cool.png" alt="cool" title="cool">/g' ]]>> ${SEDSCRIMG} ]]>/".\/images\/icon_eek.png" alt="shock" title="shock">/g' ]]>> ${SEDSCRIMG} ]]>/".\/images\/icon_frown.png" alt="frown" title="frown">/g' ]]>> ${SEDSCRIMG} ]]>Now we have computed a sed script, ${SEDSCRIMG}, that adds alt and title tagstag, alttag, title to the images in every HTML file that is applied on. Here's how it looks like for this document:/

/g ]]>/

/g ]]>/".\/images\/icon_smile.png" alt="smile" title="smile">/g ]]>/".\/images\/icon_wink.png" alt="wink" title="wink">/g ]]>/".\/images\/icon_cool.png" alt="cool" title="cool">/g ]]>/".\/images\/icon_eek.png" alt="shock" title="shock">/g ]]>/".\/images\/icon_frown.png" alt="frown" title="frown">/g ]]>We will use it in a moment... Document creation: HTMLAfter some cleaningthe document documentcreation begins:For the one HTML HTMLfile, the steps are:Index initialization (-N option):Create one HTML HTMLfile. We use openjade openjadefor that. Older versions used sgmltools sgmltoolsas follows:Notice that we pass "-i output.print.png output.print.png-V nochunks nochunks-V html-index" html-index"to openjadeopenjade through the -j option. Current versions use openjade openjadedirectly: $1.html ]]>The -i option to openjade openjadetells it to include the output.print.png output.print.pngentity (see the structure of the mediaobjects mediaobjectsput in place by runsed runsedabove), while the preample preample(see ) tells it to ignore all such entities.entities Since the command line option overrides all others, the output.print.pngoutput.print.png entity entityis included for the HTML HTMLoutput, while the othe ones are ignored (see also ).Index creation:Generation of one HTML HTMLfile (the index will be included). Again, older versions used sgmltools:sgmltoolsbut newer ones use openjade:openjade $1.html ]]>Tidy Tidythe HTML HTMLcode:Correct header and footer. First, split the HTML HTMLdocument in title and body bodyparts. The title will be put in title.tmp, the body bodyin body.tmp:body.tmpSecond, put the right header and footer in the file (see ): ${HTMLFILE} ]]>> ${HTMLFILE} ]]>' >> ${HTMLFILE} ]]>> ${HTMLFILE} ]]>Substitute the placeholders placeholdersDOMAIN, DIRNAME, FILENAME etc. in the header (part2) and footer file (part3) with the current values: part2_1.tmp ]]> part2_2.tmp ]]> part2_3.tmp ]]> part2_4.tmp ]]> part2_5.tmp ]]> part2_6.tmp ]]> part2_7.tmp ]]> part2.tmp ]]>> ${HTMLFILE} ]]>> ${HTMLFILE} ]]> part3_1.tmp ]]> part3_2.tmp ]]> part3_3.tmp ]]> part3_4.tmp ]]> part3_5.tmp ]]> part3_6.tmp ]]> part3_7.tmp ]]> part3.tmp ]]>> ${HTMLFILE} ]]>If you have set the values of TITLE, FORMATFILE, HOMEFILE etc. in your .start file (see ) and you use them somewhere in your part* files, they will be replaced with those values too. The same is true for DATE: you can use it in your headers and footers to produce the timestamp automatically.Add alt and title attributes to images. We use the sed script sedscr_img, that we computed in :Finally, do some housekeeping, removing all intermediate files:For the HTML HTMLoutput with many files (chunks), the procedure procedureis analogous to the above, so I will not repeat it here. Document creation: PDFFor the print formats, the index is recreated (we need page numbers numbersinstead of HTML HTMLlinks). Notice the -p option to collateindex collateindexand the use of the saved copy of HTML.HTMLindex in the current directory - this is because the raw index data are generated with the HTML HTMLstylesheet,stylesheet even for the print formats (see ):and the images directory is copied under $1 (the myTemplate myTemplatedirectory, in our example):For the PDF PDFoutput, the steps are:Generate the PDF PDFdocument in a first pass:Notice that now only the output.print.pdf output.print.pdfentities entitiesin the mediaobjects mediaobjectsare included (see the discussion of this for the HTML HTMLoutput above, as well as in ).The generated PDF PDFin the 1st pass does not have thumbnails thumbnailsyet. Generate thumbnails thumbnailsnow (do not confuse the script THUMB_PDF THUMB_PDF(thumbpdf) with the environment environmentvariable THUMBPDF,THUMBPDF which passes additional options to the THUMB_PDF THUMB_PDFscript ):Generate PDF PDFagain (2nd pass), to incorporate the thumbnails.thumbnails The following two commands are equivalent to(up to the use of the stylesheet,stylesheet that is), but we have to run them separately, because otherwise we cannot process the file produced by thumbpdf thumbpdf- sgmltoolssgmltools will always want a filename of the form @jobname.tpt, where jobname is its PID (process id) (difficult to guess...). On the other side, thumbpdf thumbpdfwill produce $1.ptp. So we have to "simulate"simulate sgmltools sgmltoolswith the following two commands:This will produce a tex file from the SGML SGMLsource:This will produce a PDF PDFfile from the tex file. This PDF PDFfile will have thumbnails!We must call pdfjadetex pdfjadetexa second time, because the first time there was no .aux file and the bookmarks bookmarkswere not created:A third pass of pdflatex pdflatexis needed, in order to get the page numbers numbersin the Table of Contents computed. See the PRINT_PDF_DSL PRINT_PDF_DSLused above for the parameters that control printing and placement of ToC:Our PDF PDFdocument, with all its bells bellsand whistles, is now ready! Document creation: RTF and TXTThe RTF RTFand TXT TXToutputs are easy. For the RTF,RTF we just have to do:and for the TXT:TXT $1.txt ]]>i.e. we use the Lynx Lynxtext browser browserwith the -dump option to create a text version from the one, big HTML HTMLfile we created previously. Document creation: PSFor the PS PSoutput, we have a little more work: we have to set the printer to "cmz"cmz, so that dvips dvips(which will be called either through sgmltools,sgmltools as in older versions of the script, or directly, as in newer ones) will search for the file config.cm (located in /var/lib/texmf/dvips/config/config.cm on my system), which contains the mappings for the "Computer-Modern"Computer-Modern fonts.fonts We use "cmz"cmz instead of "cm" in order to embed embedthe font in the PS PSfile, thus making it portable (there is also a file config.cmz):As with PDFJADETEX PDFJADETEXin , again 3 passes are necessary:An equivalent command would be but you would have to use the right stylesheet stylesheet(in this invocation,invocation the sgmltools-ps sgmltools-psstylesheet is used, which is mapped, through the /etc/sgml/aliases file to "-//SGMLtools//DOCUMENT Docbook DocbookStyle Sheet for Print//EN"#print.ps, which in turn is mapped, through the sgmltools sgmltoolscatalog file /usr/share/sgml/stylesheets/sgmltools/sgmltools.cat, to print.dsl#print.ps, i.e. the print.ps id of the print.dsl print.dslfile in the same directory where sgmltools.sgmltoolscat is also located - phew...). Housekeeping and special processingOur documents are now all ready. What follows is just general housekeeping:housekeeping move all documents in the HTMLHTML directory and remove the .tpt file. Remove all .pdf, .eps, .gif and .jpg images from ./images under $1 (myTemplate in our example, ./images in the current directory is not affected!). From what has been created, leave only $1.sgml and index.sgml in the current (working) directory:You may continue with the processing,processing calling tar to create various archives,archives or sed to further tweak tweakthe HTML HTMLcode of the files. I leave these steps as an example for the interested reader. If you don't need this special processing,processing you should comment it! DSSSL stylesheetsIn we copied these .dsl files to the current working directory:lyxtox-print.dsl, lyxtox-print-pdf.dsl, lyxtox-print-ps.dsl, lyxtox-print-rtf.dsl, lyxtox-print-txt.dsl and lyxtox-print-howto.dsl. These control the style of the print formats (i.e. all formats except HTML). lyxtox-html.dsl: this file controls the HTML HTMLoutput in many HTML HTMLfiles (one HTML HTMLfile per section).lyxtox-onehtml.dsl: this file controls the HTML HTMLoutput in one big HTML HTMLfile (Jade option: nochunks).Every change you wish to do should normally go in one of these three files - often even to more than one, e.g. when your change affects the HTML HTMLoutput for both one and many files (“chunks”). You should leave the original files that came with the Norman Walsh Walshstylesheets unchanged and put your changes in the above files instead. Technically, this amounts to writing your own “driver” file. This is the easiest way to incorporate your preferences preferencesand remain flexible during upgrades. TXT and HOWTO print targets Currently, the lyxtox-print-txt.dsl and lyxtox-print-howto.dsl are not used, but are included here for your convenience and for the sake of completeness. You can thus see the common pattern used in all print stylesheets and use it for your own purposes. For the TXT format I currently use the “onehtml” target: after the one, big HTML file has been rendered, Lynx (the text browser) is called with the -dump and -nolist options to create a text version directly from HTML, without any stylesheet for text. Note that, for a very complex document like the PHP-Nuke HOWTO (more than 500 pages, 1000 links to external URLs, 1500 cross-references, 2500 Index entries, 400 files in the “chunked” HTML version), the call to sgmltools with the “-b txt” option breaks with an error (caused probably by too many warnings about cross-references), although it works with smaller and less complex documents. The “howto” print target is not used at all, but is included following the example of the print.dsl file that comes with the original sgmltools package. The basic driver file looks like this (see Customizing the Stylesheets): ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]>Make sure that you specify, in the system identifier,identifier the full path pathto the docbook.dsl docbook.dslfile that you want to customize; for example, /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/print/docbook.dsl (this is already done in the stylesheets provided, at least as long as your other settings, like Catalogs () are correct).You can add your own definitions, or redefinitions, of stylesheet stylesheetrulesrules and parameters whereoccurs in the example above.A lot of work, research researchand experimentation has been invested in the above three stylesheet stylesheetfiles, so let's explain some of the most important changes they introduce:To generate a Table of Contents for articles, %generate-article-toc% %generate-article-toc%has been set to true:To get a title page for articles, %generate-article-titlepage% %generate-article-titlepage%has been set to true:The CSS CSShas been set to “ck-style.css”:Note that this setting will be overwritten by the technique described in . You will have to enter the correct CSS CSSin part2 too. The CSS CSSfile used here, ck-style.css, is a CSS for DocBook, especially crafted for the classes that appear in the automatically automaticallygenerated HTML HTMLcode of the DocBook DocBookstylesheets. It incorporates some other fine features as well, like an elaborate font-controlling mechanism that passes the accessibility accessibilitytests (see ) and is still browser-independent, or a user-specified user-specifiedicon iconas a list bulletbullet - up to a rotating globe globethat appears besides links that do not belong to a user-specifiable “local” domain (i.e. links that point “outside” the document documentcollection currently viewed). The CSS CSSfile is discussed in detail in .The width of the table that contains verbatim environments environments(like program listings) has been set to max. 95%. This is not the same as the value used in the CSS CSS(see ) for the PRE.SCREEN PRE.SCREENand PRE.PROGRAMLISTING environments,environments which should be 100%.“PDF” has been added to the list of mediaobject mediaobjectnotations.notations Otherwise, no images will be displayed in PDF PDF(see also ):The default graphic extension extensionhas been changed to “png”:“pdf” and “tex” have been added to the list of graphic extensions extensions- otherwise you will get errors (see ):Use graphics for admonitions admonitions(see ) and callouts callouts(see ):The admonition admonitiongraphics path pathhas been set to “./images”:The callouts calloutsgraphics path pathhas been set to "./images/callouts/":The callout graphics extension extensionhas been set to “png”:The code that produces the full name of admonitions admonitionshas been changed:In lyxtox-print.dsl (which uses elements taken from Mandrake's manual-print.dsl), in order to be able to have URLs in PDF:PDFMandrake. ]]>To be able to use Computer Modern fonts:fontsTo use chapter/section/subsection labels as filenames for the respective HTML HTMLfiles:ID attributes as name for component HTML files? ]]>In lyxtox-html.dsl, to be able control what section levels get put into separate HTML HTMLfiles (chunks) in the chunked chunkedversion, the chunk-section-depth chunk-section-depthhas been included (taken from the html/dbchunk.dsl file, which on my system is /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/html/dbchunk.dsl with full name):A value of 1 for chunk-section-depth chunk-section-depthmeans that the chunks chunksare the individual SECT1 elements, i.e. the Sections. A value of 2 means that the chunks chunksare the individual SECT2 SECT2elements, i.e. the SubSections SubSectionsand so on. SECT1, SECT1,SECT2 SECT2and SECT3 SECT3are the SGML SGMLtags used to denote a Section, SubSectionSubSection and SubSubSection SubSubSectionrespectively. There is no meaning in using chunk-section-depth chunk-section-depthwith values higher than 3, at least not with LyX,LyX since SubSubSubsections SubSubSubsectionsis the deepest level you can use in LyX LyX(at least with the default settings).However, as painful experimentation has shown, setting a higher value for chunk-section-depth chunk-section-depthwill have no effect, if “sect2”, “sect3” etc. are not contained in the chunk-element-list chunk-element-listlist. The list contains the elements that constitute chunks.chunks If you take an element elementout of the list, the chunk-section-depth chunk-section-depthabove will not have any effect. Thus, to have chunks chunkson sect2, sect3 etc., you must have them included in this list. chunk-element-list chunk-element-listis originally defined in the html/dbchunk.dsl file (just like chunk-section-depth), which on my system is /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/html/dbchunk.dsl with full name. See also Naming of generated html code from sgml documents. Note that if you include “sect3” (SubSubSubsections) in the chunk-element-list chunk-element-listlist, you will get chunkschunks on SubSubSubsections,SubSubSubsections no matter if your chunk-section-depth chunk-section-depthis only 2 and not 3!To force the table of contents to be on a separate HTML HTMLpage and not contain any section:The reason that Norm added support for merging mergingthe first sect1 into the file with its parent is because the alternative is really ugly in the case that you have a chapter (title) immediately followed by a section (title) (see Use of <Para> within <ListItem> mangles list items). Tip That's why you should try to put at least some introductory text after a chapter title and before the first section of the chapter! FIXME: LyX inserts an extra </listitem> here, if I don't have this line...To get a list of figures figuresat the start of the document,document the generate-book-lot-list must contain “figure”, as in the following example:The same must be the case if you want a list of tables (“table”), examples (“example”) or equations equations(“equation”). Normally, you will not have to touch this (i.e. your customization customizationlayer need not contain this code), as the above setting is the default one (for books).To be able to display “other credit”, “release info” and “publisher” information on a book's title page, these elements must be added to the book-titlepage-recto-elements book-titlepage-recto-elementslist:and the same must be done for the article-titlepage-recto-elements article-titlepage-recto-elementslist, if we want to display them in articles' title pages too:and the following code must be added:...and many other details. You are encouraged to read the source of the stylesheets (lyxtox-html.dsl, lyxtox-onehtml.dsl, lyxtox-print.dsl, lyxtox-print-pdf.dsl, lyxtox-print-ps.dsl, lyxtox-print-rtf.dsl, lyxtox-print-txt.dsl, lyxtox-print-howto.dsl)! Important DocBook files FYI, all changes presented here refer to variables that were originally defined in one of the following files: /usr/share/sgml/stylesheets/sgmltools/print.dsl /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/html/dbparam.dsl /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/print/dbparam.dsl /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/print/db31.dsl /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/print/dbchunk.dsl As said above, you should not change these files directly, because you will run into a lot of work when you upgrade them. For a list of all parameters, with references to the files that use them, see the /usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.72/html/XREF file. If you are looking for a parameter and you can't find the file it's in, the XREF file is your friend. Inline graphicsThere is no way to include inline inlinegraphics with the method described in this document document- here's why:In theory, you could put something like]*>/\ ]]>\ ]]>\ ]]>\ ]]>\ ]]>\ ]]>\ ]]>\ ]]>\ ]]>\ ]]>\ ]]>\ ]]>\ ]]>\ ]]>\ ]]>\ ]]>\ ]]>\ ]]>\ ]]>Inline graphic<\/phrase>\ ]]>\ ]]>/g ]]>in sedscr and thus substitute the <inlinegraphic> element element(which is produced by LyXLyX whenever you choose Insert-->Include File, then “Verbatim” ) with an <inlinemediaobject> along the lines of . But LyX LyXuses <inlinegraphic> also for verbatim inclusions of files. We make use of this feature in , where we see how to include potentially problematic SGML SGMLcode in program listings.listings Unfortunately, there is no way to tell which purpose the <inlinegraphic> element elementserves in the SGML SGMLfile that is exported from LyX,LyX a file inclusion of program code, or an inline inlineimage. The code above would make the substitution substitutionin both cases, which would definitely mess things up. Tip Nevertheless, you can try it, if you are sure that your code does not include any other files, only images. There is a caveat though: you should create files with the same basename (i.e. without the ending) in the working directory, in addition to the ones you create in ./images. Example: if you want to include an icon named wink.png inline, then you have to create wink.png, wink.eps, wink.pdf and wink.bmp in ./images (as shown in ) and a (possibly empty, it doesn't really matter) file named "wink" in ./. This is because when you will try to Insert-->Include File, LyX will not allow you to enter a fantasy name in the filename field and, on the other side, you must enter the filename without the ending and without the directory path, in order for the above code to work in sedscr. Catalogs A catalogue catalogueis a text file containing the translation rules rulesof the public identifier identifierto system's files.The identifier identifiersystems used by SGML SGMLand by some tools toolsare based on cataloguescatalogues that perform the translation of these identifiers identifiersto files that hold the necessary definitions. For tools toolsto be able to find the necessary catalogue(s), the environmentenvironment variable SGML_CATALOG_FILES SGML_CATALOG_FILESshould be set, as explained in . In my system, the sgmltools-lite sgmltools-litepackage installed the /etc/sgml/catalog file. Its content can be used to set SGML_CATALOG_FILES SGML_CATALOG_FILESas follows:However, as recent versions of lyxtox lyxtoxdo not use sgmltools,sgmltools I use the relevant (and only those!) lines of my “master” catalog catalogfile in /etc/sgml/catalog to define SGML_CATALOG_FILES SGML_CATALOG_FILESas:Generally, you'll need to set the SGML_CATALOG_FILES SGML_CATALOG_FILESenvironment environmentvariable to all the catalogs that you have under the directory you installed the DocBook DocBookstylesheets (probably something like /usr/share/sgml or /usr/local/sgml, see and for the packages packagesthat install stylesheets). If you want to learn more on catalogues cataloguesand the way they are constructed, see Creating and modifying catalogues. CSS See and for the details of using a CSS CSSfor the HTML HTMLoutput. The proposed ck-style.css ck-style.cssis a CSS CSStailored to the HTML HTMLproduced by DocBook.DocBook It also takes into account some modern approaches to accessibility accessibility(see , for more on accessibility accessibilityof DocBook DocBookgenerated HTML HTMLpages).For example, you can control the navigation header style withand the navigation footer style withThe concepts of margin, border and padding paddingfollow a page model that is described in W3C's working draft CSS3 Paged Media Module, version of Dec. 18th 2003. , taken from this document document(Copyright © 2003 W3C (MIT, ERCIM, Keio), All Rights Reserved) illustrates the various geometric geometricnotions of this page model. Note that the XSL area model is deliberately very similar to the CSS CSSone.

CSS page area model. ]]> ]]> ]]> ]]> CSS page area model. CSS page area model. If you output admonitions admonitionsas tables, rather than graphics (see ), then you can control their style with a code like the following (shown here for the "Important" admonition):Screen output (code) is controlled by while examples and the Table of Contents byAn “external link” icon iconto absolute links (i.e. links starting with “http:”) is added throughHowever, this alone would put the icon iconon every link with an absolute URL,URL including links pointing to the local domain. This is corrected by“External link” icons iconstell you what a link will do before you click on it. There are icons iconsspecifically designed for this purpose, like QBullets. QBullets QBulletsare a collection of elegant, animated icons iconsthat attach to hypertexthypertext links to indicate their function. You can download Qbullets for free from matterform matterformmedia.To use this idea for footnotes,footnotes the name attribute attributeis used as a selector:selectorThis will select all links whose href attribute attributestarts with "#FTN" and appendappend a note icon iconto them, which will even show an animated page curl upon passing with the mouse over it (hover). The links whose href attribute attributestarts with “#FTN” look like [1] ]]>and point to a footnote.footnote The footnote footnoteitself also contains a link - which points back to the referring text. That link will not be affected by the above selection, since its href attributeattribute does not start with “#FTN” :[1] ]]>To display a back icon iconbesides those links, a selector selectoron the name attributeattribute is used: String matching on attributes is a CSS3 feature! To be able to use string matching on attributes, as we have done in the QBullets examples above, the user must view our document with a browser that supports this CSS3 feature. If you are wondering whether your browser belongs to this cutting edge category (Mozilla 1.5 does, tip, tip ]]> ]]> ]]> ]]> Inline graphic ), you can do this W3C browser test on CSS selectors and test for "Substring matching attribute selector". To get an icon iconin place of the usual bullet bulletin itemized itemizedlists, the list-stylelist-style property is used for the UL ULtag:Last but not least, a cross-browser cross-browserrelative font setting can be achieved with BODY P { ]]>which is indeed too complicated to explain here in all its depth. See Dive into Accessibility, day 26 for this. AppendixAs already noted in , we can't include the Appendix in the main document,document even if we mark markit as an appendix appendixwith LyX' aproppriate check box in the Layout -> “Start Appendix here” menu item. We must include an extra LyX LyXdocument of DocBook DocBookarticle type that is marked as an Appendix itself and contains our Appendix.If such a file with the name appendix.appendix lyx lyxexists, lyxtox will take a series of actions to incorporate it into the final SGML SGMLdocument automatically:automaticallyThe appendix.appendix lyx lyxfile is exported to SGML:SGMLA series of SGML SGMLcode corrections take place through successive runs of 3 sed scripts:With the sedscr_abi sed script, the ending tags </book> or </article> are substituted with SGML SGMLcode that inserts the SGML SGMLentities of the Appendix, Bibliography and Index as defined in the Preample Preample(see ). For example, the following sed commands from sedscr_abi:sedscr_abi/s/<\/book>/\ ]]>/ ]]>will substitute ]]> ]]>Note that the inserted lines before the closing </book> tag contain SGMLSGML entities entitiesthat were defined as SYSTEM files with the names appendix.appendixsgml, bibliography.bibliographysgml and index.sgml respectively in the Preample Preample(see ). Similar sed commands in sedscr_abi sedscr_abiwill do the same for the closing </article> tag.The sedscr sed script will correct the SGML SGMLcode of appendix.appendixsgml, as it will do for the main document.document See for an explanation of its inner workings.Finally, the sedscr_app sed script will replace the first line of appendix.appendixsgml and its subsequent 3 lines with the correct SGML SGMLincantation for an Appendix:Appendix ]]>It also replaces the closing </article> tag (remember that we created the appendix.appendix lyx lyxfile as a document documentof type "DocBook article (SGML)", see ) with the right </appendix> one.If Mathematics Mathematicsprocessing processingis ON (with the variable $process_math set to 1 at the start of lyxtox), the appendix.appendixsgml file is undergone the same transformations as the main document documentusing the awkscr_math awkscr_mathawk script (explained in ): appendix.awk.sgml ]]>Openjade Openjade(), called by the lyxtox script, will process both the main document documentand appendix.appendixsgml and will insert the contents of the latter in place of the appendixappendix SGML SGMLentity that was inserted by sedscr_abi above. BibliographyTo create a bibliography bibliographysection, LyX LyXoffers two possibilities: one using the citation citationkeys of your free choice and one using keys of bibliographicbibliographic entries in a BibTeX BibTeXdatabase. Neither of them produces SGML SGMLcode when the document documentis exported to SGML, so we have to search for other methods. Before I explain the RefDB RefDBmethod, which suits our purposes perfectly, I will first decribe both standard methods to give you an idea of the classic bibliography bibliographycreation process in a TeX/LaTeX system with LyX.LyX You can read more about them in the LyX LyXUser's Guide and Extended Features Guide respective, both accessible from LyX' Help menu.Standard Bibliography methods in LyXBoth standard methods have in common that they make use of the Bibliography environment environment() to list references. When you first open a Bibliography environment,environment LyX LyXadds a large vertical verticalspace, followed by the heading “Bibliography” or “References,” depending on the document documentclass.class The heading is in a large boldface font. Each paragraph paragraphof the Bibliography environment environmentis a bibliography bibliographyentry. At the beginning of the first line of each paragraph,paragraph you will see a grayish box showing a number. If you click on it, you will get a dialog in which you can set a key and a label. The key is the symbolic symbolicname by which you will refer to this bibliographybibliography entry. For example, suppose your first entry in the bibliography bibliographywas a book about LaTeX.LaTeX We could choose the key “latexguide” for that entry. You can also give a label,label which will be displayed in the gray inset box.The key field isn't useless. You can refer to your bibliography bibliographyentries using the Insert->Citation Reference command. Just choose the key inside in the panel Bibliography keys, then transfer it to the Inset Keys panel with the left arrow. Multiple references can be placed by selecting more than one key. This is the first standard way of creating a bibliography bibliographyin LyX.LyXThe second standard way of creating a bibliography bibliographywith LyX LyXuses BibTeX.BibTeX BibTeX BibTeXis, it is a system for creating a large database databaseof your most used journal references. For all future articles you write, you only need to include this standard database databaseand reference the appropriate key to each reference. To use BibTeX BibTeXfor inserting references in your document,document proceed as follows: at the very end of your document,document select Insert->Lists & TOC->BibTeX Reference. In the resulting dialog, fill out the dialog boxes boxesas follows: Database: enter the name of your typewriter.bib file *without* the typewriter.bib extension.extension For searching multiple typewriter.bib files, just enter them in the desired order, separated by commas. Style: enter the name of your BibTeX BibTeXstyle file *without* the typewriter.bst extension.extension The default style is typewriterplain (which should be included in your LaTeX LaTeXdistribution,distribution so you don't have to worry about creating it).For each citation,citation assuming that the source is in the typewriter.bib file, just call Insert->Citation Reference at the correct location in the text, and enter the appropriate reference key. The RefDB methodThe problem with both methods is that they don't “speak” SGML.SGML Of course, you can use BibTeX BibTeXto create a DVI DVIdocument containing citationscitations and bibliography bibliographyand from there take the route to PS PSand PDF,PDF or even to HTML HTMLthrough a tool like LaTeX2HTML,LaTeX2HTML but this is not the route we want to take. We want to take the route through SGML SGML- and that's where both methods fail to follow us.The general principle of the RefDB RefDBmethod is straightforward: each citationcitation that you want to be treated as a RefDB RefDBcitation needs to have a role attributeattribute with the value "REFDB". Each citation citationdefines at least one xref xrefelement.element The value of the linkend attribute attributeencodes the ID IDof the required reference in the database database(if you need references in several databases, this attributeattribute can additionally specify the database). RefDB RefDBuses this information to generate a DocBook DocBookbibliography bibliographyelement.element This contains an entry for each requested reference. These entries are labelled with ID IDattributes that match the xref xreflinkend attributes attributesin the text. Each RefDB-generated reference entry defines a xreflabel xreflabelattribute attributewhich holds the text that is to be displayed at the position of the corresponding xref xrefelements.This is all it takes for single and unique citations,citations i.e. with one xref xrefelement elementper citation citationelement elementand only one occurrence throughout the text. Both multiple occurrences of the same citation citationin the text and multiple citations citations(more than one xref xrefelements per citation citationelement) make things a bit more difficult.Some output formats require a different formatting formattingfor the first citationcitation of a publication publicationin the text and all subsequent citations citationsof the same publication. The first citation citationis identical with the above mentioned default case. All following citations citationsof the same publication publicationneed an additional xrefxref endterm attribute attributewhich points to an additional bibliomset bibliomsetelement elementwhich in turn contains the text to be displayed for subsequent citations.citations The endterm attribute attributehas the same value as the linkend attribute attributeexcept that the letter "S" (as in subsequent) is appended to the attribute.attribute See Processing expectations for the refdb DocBook bibliography output.Compare the way you would use BibTeX BibTeXwith LaTeX LaTeX(and LyX) to the way you use RefDB RefDB to produce a Bibliography (see RefDB and BibTeX comparison):With the BibTeX BibTeXmethod, you proceed as follows:You enter your LaTeX LaTeXreferences into a flat-file flat-filedatabase in the BibTeXBibTeX format.You use style files in the powerful but somewhat cryptic BibTeX BibTeXformat for your LaTeX LaTeXdocuments.In a LaTeX LaTeXdocument, you specify with the \bibliography command which external bibliography bibliographyfile to use. You specify with \cite commands which references you want to cite cite(and appear in your bibliographybibliography). LyX LyXdoes this automatically automaticallyfor you.You run latex latexon your LaTeX LaTeXdocument. This will create an .aux file which contains (among other stuff) a list of all citations.citationsThen you run bibtex bibtexon your LaTeX LaTeXdocument. This will use the bibliography bibliographystyle you specified in the document documentand will create a cooked bibliography bibliographyin a .bbl file.Finally you run latex latexonce or twice again to finalize your document.documentWith the RefDB RefDBmethod, you proceed as follows:You enter your references for a SGML SGMLor XML document documentinto a SQL SQLdatabase. Input can be either RIS,RIS DocBook,DocBook or BibTeX.BibTeX As RefDB RefDBis Unix-style, you can write other import filters filtersin any language that can send output to either stdout or to a file. Using a SQL SQLdatabase means better scalability scalabilityfor large collections collectionsand added benefit if you share your data with colleagues (think workgroups,workgroups departments, access control...)You specify the bibliography bibliographyand citation citationstyles for SGML SGMLand XML documents in XML files which are essentially templates for the sequence and appearance of bibliography bibliographyand citation citationelements. These are also loaded into a database.database This means they are pre-parsed,pre-parsed which speeds up the formatting formattingof bibliographies.bibliographiesIn an SGML SGMLor XML document,document you specify an external entity entitywith the name of the SMGL SMGLor XML file that will contain your bibliography.bibliography In DocBook DocBookdocuments you specify with <citation><xref..></citation> constructs which references you want to cite.cite Parenthetical and textual citations citationsare supported.RefDB RefDBuses a DSSSL DSSSLscript to extract a list of all citations citationsfrom SGML SGMLor XML documents into an XML document document(which you can edit to add other, not cited references)Then you run a RefDB RefDBtool on your SGML SGMLor XML document.document This will use the bibliography bibliographystyle you specified on the command line and will create a cooked bibliography bibliographyin a SGML SGMLor XML file. It will also create a small stylesheet stylesheetdriver file specific for your bibliography style.Finally you run Jade Jadeor an XSLT processor on your document documentto transform it to the final output. This step uses the RefDB-created RefDB-createddriver files to format the RefDB RefDBbibliographies (leaving alone potential other bibliographies) and the RefDB RefDBcitations (leaving alone potential other citations). The stylesheet stylesheetdriver files essentially take care of character properties like font weight, posture etc. for various parts of the citation citationor bibliography.bibliography The citations citationsare neatly hyperlinked hyperlinkedwith the references in the bibliographybibliography in all output formats that support this. Your sources remain intact! Please note that neither BibTeX nor RefDB do any "search-and-replace"-style mangling of your sources. The cooked bibliography is kept in an external file in both cases. This way it is easy to reformat your document for a different bibliography style without touching the document source. And the whole thing works for DocBook, TEI, and any other reasonable DTD (with a little stylesheet tweaking, that is). Let's see how lyxtox handles all this complexity complexityin the background backgroundfor you:When sedscr is run through runsed from lyxtox:it makes a lot of changes to the SGML SGMLfile $1.sgml that was previously exported by LyX LyX(see for an in-depth description of them). The following code in sedscr takes care of citations citationsthat were entered as described in :This sed code will substitute every cross-reference to a label labelof the form “cit:IDsome” with a citation of the form:in the exported SGML SGMLfile. Then, lyxtox will call refdbxp:refdbxp $1.full.sgml ]]>to transform all citations citationsof the above form to one of the form:But how are the citations citationsand references going to be formatted? We need special DSSSL DSSSLinstructions for those parts of our document! Fortunately, RefDB RefDBprovides us with the aproppriate stylesheet.stylesheet It is generated dynamically each time, using as input the style name we entered in lyxtox as the value of the REFDB_style REFDB_stylevariable (see ), with a call to runbib runbibfrom lyxtox:This will produce the stylesheet stylesheet${REFDB_style}dsl (notice the absence of a dot before the dsl ending). For example, if REFDB_style REFDB_styleis “J.Biol.Chem.”, then the above call to runbib runbibwill create J.Biol.Chem.dsl.J.Biol.Chem.dsl J.Biol.Chem.dsl J.Biol.Chem.dsllooks like this: ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]>This means the following:For online output (id=”html”), take those define's into account and then proceed to use the part of the stylesheets with ID ID“docbook-refdb-html” (use=”docbook-refdb-html”). Openjade Openjadewill look at the external specification specificationwith id “docbook-refdb-html” at the end: ]]>and will see that is is the document documentwhose name is the "docbook-refdb-html.dsl" SGML SGMLentity (document="docbook-refdb-html.dsl"). It will then consult the entity entitydeclarations at the start of the stylesheet:stylesheet ]]>and find out that the docbook-refdb-html.docbook-refdb-htmldsl entity entityis the one with the public identifier identifier"-//Markus Hoenicka//DOCUMENT RefDB RefDBDocBook html stylesheet//EN", it will search the catalog catalogfiles (see ) and, since the lyxtox script stores the RefDB RefDBcatalog file in its SGML_CATALOG_FILES SGML_CATALOG_FILESvariable:openjade openjadewill finally be able to locate the document documentcontaining the rest of the DSSSL DSSSLinstructions necessary for processing processingthe Bibliography. It turns out that, on my system, this is the /usr/share/refdb/dsssl/html/docbook-refdb.dsl, but this depends on how you compiled RefDB RefDB- on the value of the --prefix option precisely. The same procedure procedureis followed for the print output (the id=”print” part).But wait a minute! That /usr/share/refdb/dsssl/html/docbook-refdb.dsl, does it contain any special code for Mathematics,Mathematics like the one in ? No. Does it contain any of the other special DSSSL DSSSLprocessing as described in ? Again, no. It is a “driver” file containing only the RefDB-specific RefDB-specificDSSSL DSSSLinstructions - for the rest, it jumps directly to the standard DocBook DocBookstylesheets of Norman Walsh,Walsh through the use=”docbook” attribute,attribute just as our J.Biol.Chem.dsl J.Biol.Chem.dsljumps to /usr/share/refdb/dsssl/html/docbook-refdb.dsl through the use="docbook-refdb-html" attribute.attributeOf course, you can tweak tweakthe /usr/share/refdb/dsssl/html/docbook-refdb.dsl to include both the Mathematics Mathematics(DBTeXMath) and all the other specific code, but this is not acceptable. Clearly, we need an automatic solution.Fortnunately, there is one: use the ${REFDB_style}dsl stylesheet stylesheetthat RefDBRefDB created automatically automaticallyfor us, to create two new DSSSL DSSSLdriver files, one for HTML HTMLand one for print output. these stylesheets will take care to jump first to our other DSSSL DSSSLfiles - the latter ones will then jump to the standard DocBook DocBookstylesheets.To implement this solution, two new scripts are necessary, awkscr_refdb_html and awkscr_refdb_print. The lyxtox script calls them as follows: $HTML_DSL ]]> $PRINT_DSL ]]>Both take as input the newly created ${REFDB_style}dsl stylesheet stylesheet(J.Biol.Chem.dsl in our example) and produce a new HTML HTMLand print DSSSL DSSSLstylesheet respectively. Here is the awkscr_refdb_html script : ]]> ]]> ]]> ]]> ]]>" ]]>" ]]>" ]]>" ]]> ]]> ]]> ]]>This scriptPrints the necessary entity entitydeclarations that have to come at the top of the new DSSSL DSSSLstylesheet.For every HTML HTMLid (there are currently two of them, “html” and “onehtml”), print as style specification specificationcontaining all lines that do NOT start with “<” in the style specification specificationfor the “html” id in the given file, i.e. the newly created ${REFDB_style}dsl stylesheet.stylesheet In our example, it prints every line not starting with “<” in the following part of J.Biol.Chem.dsl J.Biol.Chem.dslthat comprises only the style specification for the id=”html” part: ]]> ]]> ]]> ]]>Obviously, the lines that do NOT start with a “<” are those define's - and those are exactly the lines we are interested in, everything else will be replaced by our own code.Prints aproppriate external specifications that point to our own stylesheets that contain the rest of our customization.customizationThe output looks like this (see also refdb-html.dsl): ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]>We then process our SGML SGMLfile with this stylesheets for HTML HTMLoutput!Let's examine for a moment what the new stylesheet stylesheetdoes:lyxtox calls openjade openjadeand tells it to use the “html” id of this stylesheet.stylesheet This is because, in case RefDB RefDBprocessing processingis on, the stylesheet stylesheetfor HTMLHTML chunked chunkedoutput is defined by:and HTML_DSL HTML_DSLis the name of the file created by awkscr_refdb_html awkscr_refdb_htmlabove: $HTML_DSL ]]>That “#html” is a special Jade/Openjade construct that tells it to start processingprocessing at id=”html” of the given stylesheet.stylesheetThe new stylesheet stylesheet(which will bear the name refdb-html.dsl,refdb-html.dsl if HTML_DSLHTML_DSL is left to its default value) jumps to id “lyxtox-html” which, by the same reasoning as we saw for the original J.Biol.Chem.dsl J.Biol.Chem.dslfile previously, will be found in the lyxtox-html.dsl file that contains all our non-RefDB-specific non-RefDB-specificcustomization.customization lyxtox-html.dsl, on the other hand, is constructed in such a way that it will call the standard DocBook DocBookstylesheets with a use=”docbook” attribute attribute- and the processing processingchain is closed!Processing for print output is done similarly: awkscr_refdb_print awkscr_refdb_printcreates a new print stylesheet stylesheetfrom ${REFDB_style}dsl, refdb-print.dsl, then this new stylesheet stylesheetis called from lyxtox with an id of “print-pdf”, “print-ps”, “print-rtf” or “print-txt” respectively for each one of the print formats:Just as its HTML HTMLcounterpart above, refdb-print.dsl is constructed in such a way that it will call our lyxtox-print-pdf.dsl, lyxtox-print-pdf.dsl etc. stylesheets with use attributes attributeslike use="lyxtox-print-pdf", use="lyxtox-print-ps" etc. respectively. Those stylesheets, in turn, will jump to the standard DocBook DocBookstylesheets with a use=”docbook” attribute.attributeHow does a typical RefDB RefDBbibliography look like? lyxtox copies the $1.bib.sgml file (wher $1 is the argument passed to it) to the file with the fixed name bibliography.bibliographysgml:The &bibliography; entity entitythat sedscr_abi appends to our SGML SGMLfile is mapped automatically automaticallyto bibliography.bibliographysgml through the line ]]>in the preample preampleof our document document(see ). Thus, you only have to look at bibliography.sgml - a typical entry there looks like: ]]> ]]>11) ]]> ]]> ]]>11) ]]> ]]> ]]> ]]>Karakas ]]> ]]> ]]> ]]> ]]>Karakas ]]> ]]> ]]> ]]>11) ]]> ]]> ]]>11. ]]> ]]> ]]>Karakas ]]>C. ]]> ]]> ]]> ]]>1999) ]]> ]]> ]]>BoD GmbH, Norderstedt ]]> ]]> ]]> ]]>As you can see, it is based on bibliomixed and bibliomset elements. The content of a bibliomixed bibliomixedelement elementincludes all necessary punctuationpunctuation for formatting formatting- we say that bibliomixed bibliomixedentries are “cooked”. The creator of RefDB,RefDB Markus Hoenicka, says the following about the role of bibliomixed bibliomixedelements in RefDB RefDB(see Formatting DocBook bibliographies):

RefDB RefDBdoes use bibliomixed bibliomixedon purpose. I think the choice between raw and cooked is a compromise between philosophyphilosophy and ease of implementation,implementation speed of execution etc. I see the main purpose of auto-generating auto-generatingbibliographies not in creating beautiful and philosophically correct *source* documents, but to help users create correct *formatted* output. The intermediate bibliography bibliographyelement elementis a means to achieve this. The DocBook DocBookDTD DTDexplicitly defines the bibliomixed bibliomixedelement elementto create bibliographic output that would be too tedious or complicated to create on the stylesheetstylesheet level alone.

Index Before you can process your document,document you must make sure that index.sgml exists. This is a chicken and egg eggproblem, but it can be solved with the collateindex.collateindexplcollateindex.pl command:or, as in lyxtox:The -N option creates a new index; -o indentifies the name of the output file. This name must be the same as the name you specified in the preample preample(see ). The collateindex.collateindexpl script is part of the docbook-dsssl-stylesheets docbook-dsssl-stylesheetspackage (see ). There are a multitude of options to collateindex.collateindexpl;collateindex.pl see the reference page for more information.Creating an index is a multi-step,multi-step two-pass process (see Automatic Indexing with the DocBook DSSSL Stylesheets):In order to create an index, you must first generate the raw index data. This is done with the HTML HTMLstylesheet stylesheet(even if you want print output). That's why in lyxtox we use the same copy of HTML.HTMLindex which was created with the “no-chunks” HTML HTMLstylesheetstylesheetAfter you created the HTML.HTMLindex file, you can generate your final document documentas usual using whichever stylesheet stylesheetis appropriate. The generated document documentwill contain the index:Using sgmltools,sgmltools as in older versions of lyxtox:lyxtoxFor one big HTML HTMLfile:(notice the nochunks nochunksoption we pass to openjade openjadethrough sgmltools)For many HTML HTMLfiles (one per chapter/section):and for PDF:PDFAnd using openjade openjadeand pdfjadetex pdfjadetexas in newer versions:For one big HTML HTMLfile: $1.html ]]>For many HTML HTMLfiles (one per chapter/section):and for PDF:PDF Tip Whether an index has to be created or not, can be controlled by setting html-index to "#t" in the stylesheets (see and ) as follows (original code is in dbparam.dsl, but it is better not to touch it): Default is false ("#f"). I preferred to let the default untouched and insert the external entity "index" at the end of the document using runsed and sedscr, see . If you decide to set html-index you will have to comment this in sedscr. Tip You can change the name of the file to which index data will be written by setting html-index-filename in the stylesheets (see and ) as follows (original code is in dbparam.dsl, but it is better not to touch it): Default is HTML.index. I preferred to let the default untouched. If you decide to set html-index-filename, you will have to adapt lyxtox to reflect the name change. Optimal PDF HTML HTMLis quite limited when it comes to advanced formatting formattingcapabilitiescapabilities (although this has somewhat changed with the advent of CSS,CSS see and ). On the other side, the layout layoutof a PDF PDFdocument remains unchanged, regardless of the output medium,medium be it monitor, or printer. It retains all its typographic typographicfinesse and is not (at least easily) modifiable.modifiable These properties, together with the availability availabilityof free PDF PDFreaders, like Acrobat� Acrobat�Reader or xpdf, have rendered PDF PDFa very popular format. But PDF PDFis not a simple print format. It incorporates features that bear similarities to HTML HTML: you can insert hypertext hypertextlinks to point either to some other place in the same documentdocument (a cross-reference), to other PDF PDFdocuments, or even to WWW WWWpages. You can have the Table of Contents as a link tree to the left (“bookmarks”), extended Document Information (author, keywords,keywords creator, embedded embeddedfonts etc.), or thumbnails thumbnails(we will talk in for the details of thumbnail generation), which are small pictograms pictogramsof the document's pages to aid visual navigation.In this section I will discuss the details of incorporating all these advanced features in the PDF PDFdocument generated by DocBook DocBookthrough LyX.LyXFrom .lyx to .pdf The classic way to transform a . lyx lyxdocument to PDF PDFformat is to follow a three-pass three-passprocedure:procedure first, the .lyx document documentis exported to DVI,DVI then to PS PSthrough dvi2ps,dvi2ps then the PS PSversion is tranformed to PDF PDFthrough software like the commercial Acrobat� Acrobat�Distiller�Distiller�Distiller� is a registered trademark of Adobe Systems Incorporated. , or the freely available Ghostscript.Ghostscript (via ps2pdf).This classic three-pass three-passprocedure procedureis not only complicated, it also loses some information through the intermediate DVI DVIformat. The results are often not acceptable: the most frequent problem is bad presentation of the character glyphs glyphsthat make up the document document(see Quality of PDF from PostScript):Wrong type of fonts fontsused, which is the commonest cause of fuzzy text.ghostscript ghostscripttoo old, which can also result in fuzzy text.Switching to font encoding encodingT1,T1 which is yet another possible cause of fuzzy text.Another problem - missing characters - arises from an aged version of Acrobat�Acrobat� Distiller�.Distiller�Finally, there's the common confusion that arises from using the dvips dvipsconfiguration file -Ppdf, the weird characters.It would be much better to produce the PDF PDFversion directly from the TeXTeX (i.e. LyX) output. The pdftex pdftexpackage (see ) was created with this objective in mind. pdftex pdftex(and pdfjadetex) creates the PDF PDFdocument in one pass from the TeXTeX format. A disadvantage of pdftex pdftexand pdfjadetex pdfjadetexused to be the complexity complexityof the preliminary steps (see , especially ) needed to get a LaTeX LaTeXdocument converted to PDF,PDF escecially when it contained images. Not anymore: the method described here automates the format transormationstransormations for the images and hides the complexity complexityof the commands involved in three files (sedscr, jadetex.cfg, lyxtox). See . Figures This is a serious problem most people fail in first place. LaTeX LaTeX(and LyX) expects the images to be in encapsulated encapsulatedPostScript� (.eps) format (see ). On the other hand, pdfjadetex pdfjadetex(see ) is not capable of dealing with eps (only with PDF,PDF JPEG,JPEG PNG PNGor MetaPost), we will have to convert convertthe images to encapsulated encapsulatedPDF (.epdf) format, while still carrying the .pdf ending! This is best done by the addd script, which in turn uses convert convert(from the Image Magick package) and eps2pdf. The script works as follows (FIXME: The script has been simplified. I didn't test it extensively though. The following describes the old script):Some variables are set first: CONVERT="/usr/bin/convert" DENSITY=133 The location of the convert utility. It is part of the ImageMagick package, so you must have ImageMagick installed. The "dots-per-inch" of the device where the image was made. If you plan to use the addd script to add density to screenshots, then this is the DPI value of the monitor where the screenshots were made. The script echoes some information about the file it processes and the calculated constants:constantsWe use ImageMagik ImageMagikto convert convertthe PNG PNGimage to encapsulated encapsulatedPDF (EPDF, a format different from encapsulated encapsulatedPostScript�, EPS), adding density and antialiasing (so that texts are more readable). This is necessary in order for the bitmapped bitmappedimage to behave correctly in the PS PSdocument and is a point often and easily missedA PostScript� and an encapsulated PostScript� file differ only in the bounding box statement. The preamble of the PostScript� file contains, for examplewhile the preamble of the encapsulated PostScript� file containsThus, the PostScript� file specifies an absolute position for the image, while the encapsulated PostScript� file does not. The encapsulated PostScript� file will be offset by some amount, to be determined by the program that includes it. Knowing this, you can easily convert from one format to the other manually, just by editing the BoundingBox statement. (O.K., there is another small difference: the PostScript� file contains a showpage command that instructs the printer to print the page after rendering it.):We then use ImageMagick again to convert the PNG image to encapsulated encapsulatedPostScript�A PostScript� and an encapsulated PostScript� file differ only in the bounding box statement. The preamble of the PostScript� file contains, for examplewhile the preamble of the encapsulated PostScript� file containsThus, the PostScript� file specifies an absolute position for the image, while the encapsulated PostScript� file does not. The encapsulated PostScript� file will be offset by some amount, to be determined by the program that includes it. Knowing this, you can easily convert from one format to the other manually, just by editing the BoundingBox statement. (O.K., there is another small difference: the PostScript� file contains a showpage command that instructs the printer to print the page after rendering it.) format, adding antialiasing again: But we are still not done! pdfjadetex pdfjadetexwill accept encapsulated encapsulatedPDF images (.epdf), but only if they end in .pdf! We thus have to rename the EPDF EPDFimage to a PDF PDFone:This procedureprocedure will create pdf and png files with the right resolutionresolution (density) informationinformation. Unfortunately the eps file that is also created as a by-product, will display somewhat smaller. FIXME: This may be the result of ghostviewghostview not using the right DPIDPI when it displays the image, so it may be a problem of my system configuration.You can automate the “add density” procedure using the adddscr script, which is included in the packages that you will find in :The adddscr script accepts one parameter: the format from which you want to start the conversion. The idea is the following: suppose you have a set of GIFs, but no PNGs or any other format. Then you can change to the directory of the images, typeand get your GIFs converted to PNGs, then get EPDF (renamed as PDF) and EPS version with added density. If you only have, say, BMP versions, just typeand the script will convert your BMPs to PNGs first, then to all other formatsformats, adding density on the way.For example, you can use the adddscr adddscrscript the very first time you install the docbook-dsssl-stylesheets RPM. The RPM package offers GIFGIF, EPSEPS and PDFPDF versions of admonitionsadmonitions (see ) and calloutscallouts (see ). The EPS and PDF versions surely come with the density of the systemsystem (read: monitormonitor) they were created on, so it may not be wise to add density to them once again (if you do it, it may make the admonition and callout icons display smaller or larger than they should in PDF and PS documents)Although, I must say that I had to add the right density to the EPS and PDF versions too, after all - the original ones appeared too large in the PDF and PS documents.. However, while you might want to leave the EPS and PDF versions untouched, you definitely need PNG and BMP versions of the images. Here's where the adddscr script comes in handy:Comment the line that adds density in adddscr:change to the directory of the admonitions and callouts:then typeDo the same for the callouts:Now you have PNG and BMP versions of all your admonition and callout icons!Depending on your stylesheets, you may need to copy them to wherever they expect the icons to be, e.g. /usr/share/sgml/docbkdsl/images or somewhere else. YMMV.If you wondered why your images dont't get included in the PDF, although you meticulously prepared everything “right”, now you know why! But there's more to it - read on! ]]> ]]> ]]> ]]> Inline graphic But what is this "density" anyway? From problem downsampling: You should think of a digital image as a rectangular pixel grid. Suppose you have an image of 1500 by 2000 pixels. The image could be printed (on paper) or viewed (on screen). For that purpose, you have to tell the printer software or the "display" utility program how large an image pixel should be printed as. Suppose you want a single image pixel for a single printer dot, at 300 dots per inch (dpi). That means that the image will come out of the printer with a size of about 5 inch by 6.6 inch (or 127 mm by 169 mm). But the image file (normally) only knows about its pixel size (1500x2000), not its size at which it should be printed (since you could as well print it at double or half of the size; that's up to the printer software). However, some image formats (e.g. TIFF, EPS, EPDF) allow to store the "density", i.e., the real physical size of a pixel, as extra (header) information. This is what we have to do with our EPS and PDF images too. Having converted the images to all possible formats and having used the right parameters for each format, still does not mean we are done! If we are not very careful about the way we will use them, we will end up in a real mess, even though all seems to be right according to the packages,packages the SGML SGMLspecification, the Stylesheets etc. The problem is that when you generate "print" output, the stylesheets don't have any means to know which print format you mean, EPS,EPS PDF PDFor RTF RTF-- there's no way to provide them with that information yet. Given the choice of PNG,PNG BMP BMPor EPS EPSthey'll choose EPS EPSevery time. As we've said, pdfjadetex pdfjadetexdoesn't handle .eps files.The solution is to use parameter parameterentities entities(if that's an unfamiliar term, read the FreeBSD Documentation Project Primer for New Contributors: Entities, there's a section in there which explains them, and gives examples of using them to conditionally include certain parts of your document).In a nutshell,nutshell start your document documentlike this: ]]> ]]> ]]> ]]> ]]> ]]>Adjust that as necessary, depending on which version of the DTD DTDyou're using. The key bits are the ENTITY lines.Then, when you want to include an image, do this (see the explanation of the sedscr file in ):Now, when you process your document documentwith "openjade ...", the "%output.print.xxx;" is replaced by the word "IGNORE". This tells Jade Jadeto ignore that section of the document.document The overall effect is that no image will be included, neither PNG,PNG nor PDF,PDF nor EPS,EPS nor BMP.BMPIn order to get one (and only one) image included, you have to tell JadeJade that one or other of the %output.print.xxx; entities entitiesmust contain "INCLUDE" rather than "IGNORE". You can do this on the command line with the "-i" flag. So if you're producing a HTML HTMLfile, you would do (see lyxtox and ):If you're producing a PDF PDFfile, you would do (see lyxtox and ):and so on. With the -j option to sgmltools sgmltoolsyou can pass options to Jade Jade- we thus pass the aproppriate "-i output.print.xxx" for each format. Using openjade openjadeand pdfjadetex,pdfjadetex these commands are equivalent to: $1.html ]]>and:respectively. Yes, it's a kludge. But once incorporated in a script (like sedscr, see ), that doesn't have to bother us any more. I owe it to Nik ClaytonClayton, who posted it to the docbook-apps mailing list on June 8th, 2000 . It works great! Thanks Nik. Using Type 1 Fonts If you want a PDF PDFdocument that not only excels when printed, but also when displayed on the screen, it is advisable to embed embedType 1 fonts,fonts even though the document documentmay increase in size. The reason is is that by default TeX/LaTeX uses bitmapped bitmappedfonts fontsinstead of Type1 Type1or TrueType TrueTypeones. The resolution resolutionof these bitmapped bitmappedfonts fontsmatches that of the printer on the system you create the document.document This is rarely the same resolution resolutionof the monitor or printer the reader will use. This change in resolution resolutionresults in terrible quality when displaying these fonts fontson a screen. or printing it on a printer, whose resolution resolutiondoes not match the one of the bitmapped bitmappedfont. The solution to the problem is to force TeX/LaTeX to use Type1 Type1fonts fontswhich are scalable scalableand thus resolution-independent. There are two ways to achieve this:Use of the standard PostScript� PostScript�fontsfontsUse of Type1 Type1versions of Computer Modern (CM) fonts.fontsI chose the latter method. I like the look of the TeX documents that use Computer Modern fonts. ]]> ]]> ]]> ]]> Inline graphic I am not alone with this predilection:predilection most people use Computer Modern to start with, and even those relative sophisticates who use something as exotic as Sabon often find themselves using odd characters from CM without really intending to do so (see The wrong type of fonts in PDF). Fortunately, rather good versions of the CM fonts fontsare available from the AMS (who have them courtesy courtesyof Blue Sky Research and Y&Y, see Blue Sky Research and Computer Modern fonts for some historical background) and most modern systems have the fontsfonts installed ready to use (if yours doesn't, go get them from the Comprehensive TeX Archive Network archives: Blue Sky CM Type 1 fonts, or any other CTAN CTANmirror). There are six DSSSLDSSSL variables for defining parameters for changing fonts.fonts%title-font-family% %title-font-family%the font used for all titles. Example: titles, glossaryglossary entries.%admon-font-family% %admon-font-family%the font used for admonissions.admonissions Example: note.%guilabel-font-family% %guilabel-font-family%the font used for GUIGUI text. Example: guimenuitem.%mono-font-family% %mono-font-family%the font used for elements needing typewriter typewriteror monospacemonospace text. Example: file names, commands and URLs.%refentry-font-family% the font used for references.%body-font-family% %body-font-family%the font used for bodybody text.By default, these variables may take the following values:HelveticaPalatinoBookmanCourierWingdingsAvant-GardeNew-Century-SchoolbookTimes-RomanZapf-DingbatsComputer-Modern-TypewriterComputer-Moder-SansComputer-ModernComputer-Modern-Caps-And-Small-CapsOther font names may be used, but they correspond to one of the fonts fontsin the list above. For example:Arial = iso-sanserif = HelveticaHelveticaCourier-New = CourierCourierTimes-New-Roman = iso-serif = Times-RomanTimes-RomanWingDings = WingdingsWingdingsTo use other fonts,fonts they must be T1 T1fonts, the coding used by TeX.TeX These are listed in the file called t1***.fd, where *** is the font code. The first letter represents the font provider; the next two letters represent the font name. In addition, we must ensure that all required files are present in our installation, i.e. the .tfm, .afm, .vf, .pfm and .pfb files for each .fd file.We must ensure that Jadetex can associate the font name, e.g. Utopia, with the code name of the font (for Utopia, "put"). This is done by adding lines such as the following to the jadetex.cfg file: where *** again represents the three-letter code and "font_name" is the... font name. For example, to use the Utopia font, the following line would be added to the jadetex.cfg file: Following Customizing Document Production, we can include these lines in the jadetex.cfg file (currently commented, since they make sense only if you have those fonts fontsinstalled - uncomment accordingly):The font declarations are preceded by \makeatletter and followed by \makeatother to properly escape the "@" symbol.Now, if we wish titles to be formatted using Fonttxr and body bodytext with Concrete, all that is necessary is to add the following lines to lyxtox-print-pdf.dsl:And in order to use Computer Modern fonts fontsin the PDF PDFdocument , we write the following in the print stylesheet,stylesheet lyxtox-print-pdf.dsl (see ):Now, if the T1 T1font encodingencoding is used, i.e. if the jadetex.cfg file contains the linethe EC ECfonts will be used instead of the CM ones. Since there are no Type1 Type1EC ECfonts available, pdftex pdftexwill use bitmappedbitmapped ones, yielding poor quality PDF PDFfiles. Fortunately, there is a workaround:workaround the ae aepackage provides virtual EC ECfonts based on the CM ones, so that the Type1 Type1CM fonts fontscan be used in the output file. However, not all EC ECcharacters are available in this way. The aecomplaecompl package defines the missing characters as bitmapped bitmappedfonts.fonts To use them you should have the following in jadetex.jadetexcfg:or justIn this way the output file will use CM fonts fontsfor all except some rarely used characters. pdfjadetex pdfjadetexwill end saying something like: < ]]> ]]>meaning that it has embedded embeddedall fonts fontsshown in angle brackets into the PDF PDFfile. See High quality PDF output from LaTeX and TeX for more details. Tip: You can check the fonts used in the PDF file by choosing File-->Documet Info-->Fonts-->List all fonts in Acrobat� Reader. You will see that the fonts are embedded (not totally, but as a subset, which is the legally correct way) in the PDF document, see .

Document Info: Fonts. ]]> ]]> ]]> ]]> Document Info: Fonts. Document Info: Fonts. However, today other solutions to the font quality problem exist as well: instead of using virtual Type 1 fonts fonts(which is what you do when you use the ae,ae aecompl aecompland aeguillaeguill packages), you may choose to use “true” Type 1Not to be confused with “True Type” fonts. fonts fontsby installing one of the new CM-super,CM-super CM-LGC CM-LGCor Latin Modern Latin Modernfonts. From Finding 8-bit Type 1 fonts:CM-super CM-superis an auto-tracedauto-traced set which encompasses all of the T1 T1and TS1 encodings as well as the T2* series (the family of encodings that cover languages based on CyrillicCyrillic alphabets). These fonts fontsare pretty easy to install (the installation instructions are clear), but they are huge: don't try to install them if you're short of disc space.CM-LGC CM-LGCis a similar "super-font" set, but of much more modest size; it covers T1,T1 TS1 and T2{A} encodings (as does CM-super,CM-super and also covers the LGR encodingencoding (for typesetting Greek, based on Claudio Beccari's Metafont sources). CM-LGC CM-LGCmanages to be small by going to the opposite extreme from CM-super,CM-super which includes fonts fontsat all the sizes supported by the original EC EC(a huge range); CM-LGC CM-LGChas one font per font shape, getting other sizes by scaling.scaling There is an inevitable loss of quality inherent in this approach,approach but for the disc-space-challenged machine, CM-LGC CM-LGCis an obvious choice.Latin Modern is produced using a program MetaType1 which, as its name implies, brings the power of the Metafont paradigm to the production productionof Type 1 fonts.fonts The Latin Modern Latin Modernset comes with T1,T1 TS1 LY1 encoded variants (as well as a variant using the Polish QX encoding); for the glyph set it covers, its outlines outlinesseem rather cleaner than those of CM-super.CM-super Latin Modern Latin Modernis more modest in its disc space demands than is CM-super,CM-super while not being nearly as stark in its range of design sizes as is CM-LGCCM-LGC - Latin Modern's fonts fontsare offered in the same set of sizes as the original CM fonts.fonts It's hard to argue with the choice: Knuth's range of sizes has stood the test of time, and is one of the bases on which the excellence of the TeXTeX system rests. Choosing the right font encodingIf you think of a font as being arranged in a table, then the font encodingencoding is nothing else than the way the font's symbols symbols(the “glyphs”) are arranged in the table. If you think of the table as being fixed, then different font encodings arrange the same or different glyphs glyphsin different ways in the table's cells. If you mentally number all table cells sequentially, then for each table cell you have a number and a glyph. The number is the font's internal representation representation(the “encoding”) of the glyph.Fonts Fontsare always encoded in some encoding encoding- that's the nature of a font, being just a table of glyphs.glyphs Thus, in order to use a font that contains the glyphs glyphs(letters, symbols,symbols...) you need, you must tell pdfjadetex pdfjadetexand jadetex jadetexwhich encoding encodingto use. For example, to use the T1 T1font encodingencoding, the jadetex.cfg file must contain the lineTo use the OT1 OT1encoding,encoding you must have:There are some factors that affect the choice of font encoding:encodingYour language. More precisely, the glyphsglyphs you want to present in your document document(if you find the word “glyphs” confusing, just read “letters” or “symbols”). If your language is english, then you can use both the T1 T1and the OT1 OT1font encoding.encoding If your language is french, then you have to use the T1 T1encoding. The same is true for many european europeanlanguages. FIXME:FIXME encodings for other languages.Mathematics. If you don't display any Mathematics,Mathematics you can choose from a wider choice of fonts fontsand font encodings. But if you use Mathematics,Mathematics your document documentwill look better if you choose a font family that contains mathematical mathematicalsymbols as well. A font family that contains excellent mathematical mathematicalfonts is Computer Modern. Computer Codern came originally only in the OT1 OT1encoding.encoding This is fine, as long as you use only english. For european europeanlanguages, you have to use the T1 T1encoding. Now, if you have Mathematics Mathematicsand write in some european europeanlanguage (e.g. french, where you need accented letters and the like), then your choice is becoming narrower: you need a good Mathematics Mathematicsfont, say Computer Modern, but you also need T1 T1encoding. This leads to the use of virtual EC ECfonts with the ae aeand aecompl aecomplpackages,packages as discussed in .The symbols symbolsyou want to use. Some symbols symbolsare available in one encoding,encoding but not in another. For example, $ < < $ ]]> ]]> ]]> ]]> is missing from the OT1 OT1encoded Computer Modern fonts,fonts but you can still get it in the PDF PDFand PS PSif you enter math mathmode in Lyx and type the two $ < $ ]]> ]]> ]]> ]]> there. However,if your purpose is to get the french quotes (“guillemets”), then you might just as well choose the T1 T1encoding and the aeguill aeguillpackage:Quality. You might not want to use the aeguill aeguillpackage, because the fonts fontsit defines are not as perfect as the original Computer Modern fonts,fonts leading to (maybe imperceptible, but nonetheless existent) inaccuracies and inconveniences in the resulting PDF.PDF So you might decide to use the OT1 OT1font encoding encodingand the original Computer Modern fonts,fonts entering your $ < < $ ]]> ]]> ]]> ]]> and $ > > $ ]]> ]]> ]]> ]]> always in math mathmode in LyX.LyX Note that the HTML HTMLversions of your document documentwill then contain small images in place of those symbols,symbols since lyxtox will treat them as mathematical mathematical“ inline inlineequationsequations” (see ).Note that today other solutions to the font quality problem exist as well: instead of using virtual Type 1 fonts fonts(which is what you do when you use the ae,ae aecompl aecompland aeguillaeguill packages), you may choose to use “true” Type 1 fonts fontsby installing one of the new CM-super,CM-super CM-LGC CM-LGCor Latin ModernLatin Modern fonts,fonts see . Using True Type fontsFIXME: To be done. For the moment, see Using TrueType fonts with TeX via Postscript Type1 format. The idea is: Transform the TT font to Type1 Type1(see ) using ttf2pt1. Take care of naming conventions for the new font.Integrate the newly created Type 1 font in your TeX TeXinstallation. If you observed naming conventions, then this step might be done automatically.automaticallyIn one of the last output lines of ttf2pt1, the font name was printed, for example:Use that name in the lyxtox-print-pdf.dsl file (see ):Of course, since this is a T1 T1font, the T1 T1font encodingencoding has to be used, i.e. the jadetex.cfg file must contain the line The hyperref package The hyperref package by Sebastian RahtzRahtz und Heiko OberdiekOberdiek expands the cross-referencing cross-referencingcapabilities of LaTeX LaTeXintroducing \special commands that can be interpreted interpretedby a driver (like pdfjadetex) to produce hypertext hypertextlinks to places in the same document document(cross-references), other PDF PDFdocuments, or even WWW WWWpages.We pass options to the hyperref hyperrefpackage in the jadetex.cfg configuration file. Either the classic \usepackage, or the new \ hypersetup hypersetupcommand can be used for this purpose. I use the latter. If you use the \ usepackage usepackagemethod, you should always specify the driver like inIn addition to the base URL,URL author, title, subject and keywords keywords(which you have already set up correctly in ), there are a lot of other options that can be set in jadetex.cfg (see Erstellung von pdf-Dokumenten mit LaTeX (in german) ):open settings:pdfpagemode: Determines how the document documentwill open in Acrobat�.Acrobat� If no mode is explicitly chosen, but the bookmarks bookmarksoption is set, UseOutlinesUseOutlines is used.NoneUseThumbs: show thumbnails.thumbnailsUseOutlines: show bookmarks.bookmarks FullScreenpdfstartpage: Determines on which page the PDF PDFdocument is opened. pdfstartview: FitB FitBor FitH:FitH Set the startup page view. paper size settings: The keywords keywordsfor paper papersize may directly appear in the hypersetup hypersetupcommand, since they are boolean variables. (draft=true is equivalent to draft.) . An overview of the possible settings is presented in .Paper sizes with hyperref Paper size option Meaning draft all hypertext options are turned off debug extra diagnostic messages are printed in the log file a4paper 210mm x 297mm a5paper 148mm x 210mm b5paper 176mm x 250mm letterpaper 8.5in x 11in legalpaper 8.5in x 14in executivepaper 7.25in x 10.5in

The breaklinks option enables breaking of long hypertext hypertextlinks across lines, the linktopage linktopageoption has the effect that only the page number (and not the chapter/section text) links to the relevant chapter or section. All possible link colour colouroptions are shown in . The frenchlinks frenchlinksoption differentiates links from the rest of the text not through colours, but through small caps instead.Link colours with hyperref Option Standard colour Meaning linkcolor red internal links anchorcolor black anchors citecolor green citations filecolor magenta links to files menucolor red links to Acrobat� menus pagecolor red links to page numbers urlcolor cyan links to WWW pages

See Erstellung von pdf-Dokumenten mit LaTeX for more PDF PDFoptions. Hyphenation If pdfjadetex pdfjadetexencounters a word it does not know how to hyphenate, the word is skipped! In the following example from Customizing Document Production, the french words savoir savoiror �volution were problematical. The error log file contained the following lines:This message tells us that pdfjadetex pdfjadetexdoes not know how to hyphenate savoir,savoir consequently it is skipped. In order for pdfjadetex pdfjadetexto correctly format lines, we must ensure that hyphenation hyphenationis explicitly activated activatedusing the command \def\Hyphenate{1 } in jadetex.cfg and, in addition, that the text is justified (\def\Quadding{justify}). But, in addition, we must explicitly set the language in order to activate the correct hyphenation hyphenationmodule (with \def\Language{UK}).Internet addresses can become quite long, even longer than a single line. jadetex jadetexdoesn't hyphenate them properly. Actually, no hyphenation hyphenationrule prevents it from inserting a hyphen after the double slash. The url package was developed by Donald Arseneau to solve these problems. To use it, you must tell jadetex jadetexto load it. You do this by inserting the following in the jadetex.cfg file (see and for more on jadetex.jadetexcfg):We must also ensure that openjade openjadeproperly transforms the <ulink> and <filename> elements into jadetex jadetexcommands. See for more on this. Bookmarks Bookmarks are a navigation aid for the Acrobat� Acrobat�Reader. They are a tree-like tree-likestructure that reflects the chapter/section structure of the document.document The nodes of the tree are the chapter/section texts, which link directly to the respective chapter/section. The behaviour behaviourof bookmarks bookmarkscan be customised with the following commands (since they are boolean variables, they can appear directly in the hypersetuphypersetup command, e.g. to switch it explicitly off, use e.g. bookmarksopen=false):bookmarks: bookmarks bookmarksare created even if the \ tableofcontents tableofcontentscommand is not present. bookmarksopen: Expand all bookmarks.bookmarks bookmarksnumbered: bookmarksnumbered:Include section numbers numbersin bookmarks.bookmarksbookmarksopenlevel: The maximal tree depth of bookmarks bookmarksto open PDF view options The most important options regarding PDF PDFview options are shown in . They are set in jadetex.cfg with the hypersetup hypersetupcommand.PDF view options PDF view option Meaning Values pdfcenterwindow Center the window of the document false, true pdffitwindow Fit document window to the first document page false, true pdfhighlight How to highlight a link button when pressed /I (Inversion), /N (No effect), /O (Outline), /P (Pressed) pdfmenubar Show menu bar false, true pdfnewwindow Open the document in a new window false, true pdfpagelabels Show logical labels, instead of page numbers (use only in \usepackage) false, true pdfpagelayout Controls the page layout upon opening of the document SinglePage (default), OneColumn, TwoColumnLeft, TwoColumnRight pdfpagemode Specifies how to open the document None (default), UseThumbs, UseOutlines, FullScreen pdfstartpage Specifies the opening page of the document 1 (default), other page number pdfstartview Specifies opening size FitH, FitB, pdftoolbar Show viewer's toolbar false, true plainpages Page anchors as arabic numbers false, true

See Erstellung von pdf-Dokumenten mit LaTeX for more PDF PDFoptions. Links to internet sites The url package enables the use of URL URLlinks in the PDF PDFdocument and takes care of their hyphenation.hyphenation To use it, you must tell jadetex jadetexto load it. You do this by inserting the following in the jadetex.cfg file (see also ):We must also ensure that openjade openjadeproperly transforms the <ulink> and <filename> elements into jadetex jadetexcommands. For the <ulink> element,element we want openjade openjadeto copy the text found between the two tags and within parentheses, i.e. the address given in the id attribute.attributeIn order to do this, we use the customization customizationas described by Pascal Lo R� in Customizing Document Production: we create a sosofo sosofoof type formatting-instruction.formatting-instruction We added a new flow-object flow-objectto those already defined in the DSSSL DSSSLstylesheets: Mandrake. ]]>This addition allows us to insert arbitrary, non-formatted text into the output file. Then we can insert suitable TeX TeXinstructions into the intermediate output. This new flow-object flow-objectis called formatting-instruction.formatting-instruction The usage syntax of formatting-instruction formatting-instructionis as follows:The value of the data variable is inserted into the output file. Note that the “\” character must be escaped escapedwith an addition '\'. For example, in order to insert the TeX TeXfunction,\penalty, you would use the following:Now, in order to get hypertext hypertextlinks in PDF,PDF the ulink element elementis redefined in lyxtox-print.dsl with the help of formatting-instruction formatting-instruction(see Using Jade for SGML transformations for the class class"formatting-instruction"formatting-instruction and and for the lyxtox-print.dsl file):The text to be edited is accessed by data-of (current-node). Because this text requires special formatting formatting(italics?), we must call the (process-children) function. The address is returned by attribute-string attribute-string(normalize “url”). To construct the string, we concatenate using the command string-append, and assign the result to data in the sosofo.sosofo This nicely produces hypertext hypertextlinks in PDF.PDFHowever, the <ulink> element elementis not only used for URLs, but also for the index generation (see ). Since we redefined it above, it is going to be used for the index too (remember, the changes you do in the stylesheets, as discussed in , will take precedence over the defaults). We thus have to copy the code from dbindex.dsl dbindex.dslfor <ulink> elements that are children of <primaryie>, <secondaryie> or <tertiaryie>, which is the case for the index: Thumbnails The thumbpdf thumbpdfpackage by Heiko OberdiekOberdiek installs the Perl program thumbpdf thumbpdfon your system. With the help of thumbpdf thumbpdfand Ghostscript Ghostscript(which should also be installed), you can create thumbnails thumbnailsfor the PDF PDFdocument (to be seen when you click on the “thumbnails” register card in Acrobat� Acrobat�Reader). Thumbnails are embedded embeddedimages of the document's pages, drawn in small size and resolution.resolution Their purpose is to facilitate navigation through the document document(of course only if the PDF PDFviewer supports them).You need at least Ghostscript Ghostscript5.50 in order to be able to use thumbpdf.thumbpdf You need to declare its use in the jadetex.cfg file (see and ) as follows:The PDF PDFdocument with thumbnails thumbnailsis created in a three-pass three-passprocess: The PDF PDFfile without thumbnails thumbnailsis created first.thumbpdf thumbpdfis called and given as argument the basename basenameof the PDF PDFfile. It creates the thumbnails thumbnailsin a file with the same basename basenameand the ending .tpt.The PDF PDFfile is created again. Through the \ usepackage usepackageinstruction above, pdfjadetex pdfjadetexsearches for a .tpt file in the current directory and uses it to embed embedthe thumbnails thumbnailsin the PDF PDFfile.If the parameter parameteruse_coolthumbs is set to 1 in lyxtox lyxtox(that's currently the default), the thumbnails thumbnailswill be generated using the coolthumbs script (see ), which in turn will call The GIMP to create smooth, anti-aliased thumbnails.thumbnails See the Linux LaTeX-PDF HOW-TO for the details of the inner workings of coolthumbs.See also for the PDF PDFdocument creation process. Configuring pdfjadetex The file jadetex.cfg is used whenever you want to override jadetex's or pdfjadtex's default behavior. This file just goes in the current working directory (i.e. where jadetex jadetexis being run from). It seems that pretty much any TeX TeXcode can go in there, but here are some common things. The hyperref package expands the cross-referencing cross-referencingcapabilities of LaTeX LaTeXintroducing \special commands that can be interpreted interpretedby a driver (like pdfjadetex) to produce hypertext hypertextlinks to places in the same document document(cross-references), other PDF PDFdocuments, or even WWW WWWpages. You declare its use in jadetex.jadetexcfg withinserting various options after the curly curlybracket. See .Two-Sided Pages: sometimes, you will want jadetex jadetexto start chapters on the recto rectoside, and try to keep the total count of pages even. This is no longer the default behaviour,behaviour so if you want to revert to it, put the following in jadetex.jadetexcfg:PDF Outlines (bookmarks): PDF PDFoutlines outlinesare a nested,nested tree-like tree-likelist of the hierarchy hierarchyof chapters, sections, etc, each trre node being a link to the relevant chapter or section. These are displayed on the left side of Acrobat� Acrobat�Reader. To enable the listing of bookmarks,bookmarks put this in jadetex.jadetexcfg:jadetex.cfgIf you happen to have a "Citation Reference" or a "Cross Reference" inside of a "Section" (for example "5 The Proof Proof[somebook]"), then you will need to give the linktocpage linktocpageoption to pdftex,pdftex otherwise you will get an error when generating the Table of Contents saying Put the following in jadetex.jadetexcfg:Computer Modern (CM) fonts:fonts The ae aepackage provides virtual EC ECfonts based on the CM ones, so that the Type1 Type1CM fonts fontscan be used in the output file. However, not all EC ECcharacters are available in this way. The aecompl aecomplpackage defines the missing characters as bitmapped bitmappedfonts.fonts To use them you should have the following in jadetex.jadetexcfg:In this way the output will use CM fonts fontsfor all except some rarely used characters Further enhancements The PDF PDFformat offers some possibilities that further enhance its use: Optimization: The document documentcan be optimized for browsing , so that it needs only be partially downloaded to be viewed.Passwords: Using programs like pdlin Download the freely available version (for Windows, Linux und Solaris) under http://www.pdf-tools.com/en/products_evaluation.html; free use is limited to evaluation purposes only, though - you will need a licence for productive work. you can set passwords and permissions regarding printing, changing, selecting and adding text.These enhancements are not used in my scripts, but they certainly could be incorporated if needed.For more information on the creation on powerful PDF PDFdocuments see Erstellung von pdf-Dokumenten mit LaTeX.The manual-print.dsl file, used for the print versions of the Mandrake Linux distribution,distribution contains examples of customizations customizationsthat are beyond the scopescope of this document,document but may very well be useful in a heavy production productionenvironment. These include:Definition of languageForeign text or abbreviationsabbreviationsLong titles Glossary entriesInline InlinegraphicsCharacter fontsfontsand other goodies that make reading of this document documentstrongly recommended for the interested reader. Optimal PSWe discuss some PS-specific PS-specifictopics here - currently only how to embed embedComputer Modern fonts fontsin a PS PSdocument.Embedding Computer Modern fontsThe reason behind embedding embeddingthe Type1 Type1Computer Modern fonts fontsin PostScript�PostScript� (PS) documents is the same as for PDF PDFones (see ): the resolution resolutionof the bitmapped bitmappedfonts fontsthat are used by default by TeX/LaTeX matches that of the printer on the system you create the document.document This is rarely the same resolution resolutionof the monitor or printer the reader will use. This change in resolution resolutionresults in terrible quality when displaying these fonts fontson a screen. or printing it on a printer, whose resolution resolutiondoes not match the one of the bitmapped bitmappedfont. Tip: In recent TeX/LaTeX distributions, freely available Type1 versions of the CM fonts are provided. These appear under the collective name of bluesky. The bluesky fonts can be obtained from CTAN, if not already installed on your system. You can embed embedthe CM fonts fontsin the PS PSdocument using an aproppriate printer with the -P option:I use this comfortable method in the lyxtox script. This will make dvips dvips(which is directly called in the current lyxtox lyxtoxscript, or indirectly called by sgmltools,sgmltools in older versions of lyxtox,lyxtox see ) to read the configuration file config.cmz config.cmz(under /var/lib/texmf/dvips/config/config.cmz on my system). On my system, this file contains only one line:and looking at the psfonts. cmz cmzfile (located in /usr/share/texmf/dvips/bluesky/psfonts.cmz, notice the name “bluesky” in the directory path), I can see that all the necessary mappings from short names to full ones are there. Here are some lines of psfonts.cmz:If no map file like the above can be found, you probably miss something from your distribution,distribution unless you installed TeX/LaTex by hand, in which case you know what you are doing and might try the following (see LaTeX to PDF Guide):Search for a file pdftex.pdftexmap (see ) in your TeX TeXdistribution distribution(located in /var/lib/texmf/dvips/config/pdftex.map on my system). Run a Perl script as follows: cm.map ]]>The created cm.map cm.mapfile instructs dvips dvipsto embed embedthe Type1 Type1outline fontsfonts for the Computer Modern fonts fontsinto the resulting PostScript� PostScript�file. Add to your presonal .dvipsrc the following line This tells dvips dvipsto use the font map you just created in addition to the system-wide system-wideconfiguration files.The LyX LyXUser's Guide (available through the menu: Help-->User's Guide) contains a whole chapter devoted to the configuration of dvips dvipsand Ghostscript Ghostscriptfor LyX LyX(Section 2.6, as of LyX LyX1.2.0), which is definitely recommended reading. HTML validationThe W3C is maintaining a HTML validator service at The W3C Validator. If you try it using various URLs from pages on the Internet that were created using the methods described in this document (i.e. DocBook SGML, openjade etc.), you may be surprised that so many of them will return the following error from W3C when validated ]]> ]]> ]]> ]]> Inline graphic : This is because their authors did not take the trouble to examine the created HTML HTMLdocuments and enhance them to conform to the HTML HTMLstandards.standards There is, in fact, some amount of work involved, if you want your HTMLHTML documents to obey the standards standardsset by the W3C W3C- but this work too is automated in the scripts presented here! Let's have a look how this is done:The above error from the W3C W3CHTML Validator Validatorcomes from the fact that the documents, as produced by openjade openjadeand the configuration settings discussed so far, do not include something like ]]>But even if they did, the all-important DOCTYPE DOCTYPEstatement ]]>would also be missing, making validation validationagainst a HTML HTMLDTD DTDimpossible. This may be a deliberate “feature” of the tools toolsinvolved in the document documentcreation chain. But it also may have its root to an option that went unnoticed by me throughout the time! If you happen to know of such an option (perhaps in the HTMLHTML stylesheet?stylesheet), please don't hesitate to contact me.The way I decided to close this gap is an idea I borrowed from Hugo van der Kooij while reading his document documenton how to setup your own docbook processing: after the HTML HTMLdocument has been created, proceed by extracting 2 parts out of it, the title part and the body bodypart, both stored in separate temporary files called title.tmp and body.bodytmp respectively. This splitting splittingpart is done by an awk script called htmlsplit.awk. You should also have created three text files your replacement HTML HTMLcode up until the <title> tag - this is what we will call part1,the title part, containing the title (or even some navigational navigationalmenu structure specific to your website, but we will not pursue it here further, see Hugo's original document documentfor this) - this is what we will call part2,the footer part - which we will call part3.Part1 looks like ]]> ]]> ]]> ]]>so that is where the DOCTYPE DOCTYPEstatement goes! Part2 Part2contains: ]]> ]]> ]]> ]]>so there is where the encoding encodinginformation goes! I have also set the backgroundbackground colour colourto fit my site's design. Part3 Part3contains ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]>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 HTMLdocument:part1titlepart2bodypart3At the end we get a HTML HTMLdocument that is customized to the design of our site and can easily be checked for compliance to the HTML HTMLstandards! HTML Parameters and Chunking You can achieve a similar result by setting the html-header-tags parameter accordingly in the HTML DSSSL stylesheet (, ). 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"))). 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 HTML Parameters for Chunking too! The footer file, part3, deserves some extra attention, since it illustrates the kind of customizationcustomization and control over your HTML HTMLoutput that you can achieve with this method: it contains the HTML HTMLcode that prints three icons iconsin a row - a W3C W3CHTML validation icon,icon a Linux Counter icon iconand an icon iconfrom the "any browser" campaign. There are three placeholders placeholdersin the link for the HTML HTMLvalidation validationicon:icon _DOMAIN_,_DOMAIN_ _DIRNAME_ _DIRNAME_and _FILENAME_._FILENAME_ These are substituted on-the-fly on-the-fly(using sed one-line commands) with the domain, directory and filename respectively of the file whose footer we are currently processing:processing part3_1.tmp ]]> part3_2.tmp ]]> part3.tmp ]]>The result is an icon iconthat, when clicked, will automatically automaticallypass the URIURI of the current file to The W3C Validator for HTML HTMLvalidation! Please note: A file containing graphical callouts (see and ) will NOT be validated! You will get an error saying document type does not allow element "IMG" here In fact, any HTML standard after 2.0 explicitly forbids <img> from occuring anywhere 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: (define %callout-graphics% ;; Use graphics in callouts? #f) Also note that admonitions (see and ) will be positioned using valign="center", instead of the right one valign="middle", thus leading again to non validation. But this is easily corrected by the sed script sedscr_val that is run near the end of the lyxtox script. Accessibility

A broad definition of accessibility accessibilitycovers people operating operatingunder situational limitations as well as functional limitations: Functional limitations pertain to disabilities,disabilities such as blindness blindnessor limited use of the hands. Functional limitations can be visual, auditory, auditory,physical, or cognitivecognitive (which includes language and learning disabilities).Situational limitations relate to the prevailing circumstatnces, environment,environment or device. These limitations can affect anybody, not just people with disabilities.disabilities 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,dashboard wher the use of the hands and eyes is limited.Shawn Lawton Henry, Constructing Accessible Web Sites.

Something is accessible if it is able to be used by persons with disabilities.disabilities In the context of computing,computing this generally means that the software or device should be compatible compatiblewith access aids, and should be able to transform itself into a needed format (see the Glossary of Bobby). The efficiency efficiencywith which information can be accessed by people with various abilities and disabilities disabilitiesultimately determines the degree of accessibilityaccessibility - it is clear that this is a highly subjective matter. Nevertheless, various criteria criteriahave been developed to help determine how accessible a web page is. I will follow the priorisation of accessibility accessibilityerrors as suggested by Bobby in http://bobby.watchfire.com:80/bobby/html/en/readreport.jsp:Priority 1 Accessibility problems seriously affect a page's usability usabilityby people with disabilities.disabilities A Bobby BobbyApproved rating can only be granted to a site in which none of the pages contain accessibility accessibilityerrors. Bobby BobbyApproved status is equivalent to Conformance Level A for the WebWeb Content Guidelines.Priority 2 Accessibility 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 AAfor the Web WebContent Guidelines. This is the preferred minimum conformance conformancelevel for an accessible site.Priority 3 Accessibility problems are third-tier third-tieraccess 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 WebContent Guidelines.If you think this is “fine print” that does not have to bother you, you are wrong: no lesser than the Sydney Organizing Committee for the Olympic Games (SOCOG) thought the same and was fined to pay A$20000 in a case that was brought to an australian court - see the Reader's guide to Sydney Olympics accessibility complaint for the whole story and an explanation of the court's decision, as well as Olympic Failure: A Case for Making the Web Accessible for the web designer's point of view. You also cannot argue that this has happened “too far away” from you, perhaps on another continent. The world grows together and all western westernnations have passed legislationlegislation that is more or less similar on this point, based on the same legal principlesprinciples of unequal treatment (“discrimination”; “unfavourable” treatment) and unjustifiable hardship (“undue” hardship or “burden”). It is a matter of time until similar cases appear to the courts. I hope you understand by now the following Important fact: Accessibility is NOT optional! So what can you do to improve the HTML HTMLpages created by the tools toolsI presented, from the accessibility accessibilitypoint of view? You can pass any of your generated HTML HTMLpages to Bobby for an accessibilty accessibiltytestNote, however, that Bobby itself is just an attempt at automating an accessibility test and has not evaded criticism. In Accessible shopping, for example, we read:

Bobby is too primitive and unreliable and has a tendency to give false-negative results, flunking absolutely everything but the simplest text-only sites.

. 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 toolstools I presented in the previous chapters. Mean tip: 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 the Linux Accessibility HOWTO pages for a test at Bobby. ]]> ]]> ]]> ]]> eek! For more information on accessibility,accessibility see the Bobby Accessibility FAQ and the the Linux Accessibility HOWTO. Priority 1 accessibility errorsNo priority 1 accessibility accessibilityerrors seem to be there for a page that was generated with lyxtox.lyxtox This is good news, as it means that the pages generated this way do not pose serious obstacles to people with disabilities.disabilities Provided that we didn't miss anything, we can say that the pages have “ Bobby BobbyApproved status”, or that they conform to Level A of the Web WebContent Guidelines. Priority 2 accessibility errorsThe explanation texts are from Bobby. Clicking on any of the problems that Bobby reports will produce a more detailed description of how to fix the problem. In addition to items that Bobby can examine automatically,automatically a number of items that require manual manualexamination are presented in the User Checks section of the Bobby Bobbyreport.Nest headings properly. This comes from incorrect nesting nestingof the H elements in the authors environment.environment 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. Why it is bad: 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 "Using real headers" by Mark Pilgrim. Use a public text identifier in a DOCTYPE statement. We have corrected this already in . Why it is bad: 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. Priority 3 accessibility errorsProvide a summary for tables. This refers to the revision history table. Again, it seems to be a stylesheet/Jade problem.Identify the language of the 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 . MathematicsSince LyX LyXis a frontend frontendfor LaTeX,LaTeX it is no secret that it has exceptional capabilities capabilitieswhen it comes to typesetting mathematics.mathematics However, when it comes to transforming the .lyx document documentto different format, the possibilities are rather limitedEven 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 Math Typesetting for the Internet.:For HTML,HTML export to LaTeX LaTeXand then use latex2html. This has some disadvantages:Excessive memory usage: latex2html latex2htmlwill consume a lot of memory (FIXME: is this still the case?)Most important: We are talking about an SGML SGMLdocument here and all the DocBookDocBook markup markupwill be lost if you transform it back to LaTeX LaTeX- just think about the admonitions admonitions(see ), callouts callouts(see ) and all the other SGML SGMLstuff that will be impossible to transform back! For PostScript�,PostScript� export to LaTeX,LaTeX then create the .dvi file (by calling LaTeX) and then the PS PSfile using dvips.dvips That's O.K., since it directly uses TeX TeXand the mathematics mathematicswill be as accurately typeset as possible.For PDF,PDF transform the above PostScript� PostScript�file to PDF PDFusing ps2pdf,ps2pdf or some commercial program like the Acrobat� Acrobat�Distiller�.Distiller� Taking the roundtrip roundtripto PS PSin order to arrive at PDF PDFhas some serious drawbacks, though (FIXME: which ones?) After all, pdfjadetex pdfjadetexwas developed to avoid avoidexactly these drawbacks, so it would be nice if we could use it.For RTF,RTF no way seems to exist to get mathematics mathematicsfrom LyX LyXin this format.The above is not a satisfactory situation. Even if we can get mathematics mathematicsin some formats, we would have to abandon the SGML SGMLframework we have been using so far. It would be nice if we could continue to write in a DocBook DocBookSGML SGMLdocument in LyX,LyX using all the excellent math mathtypestting capabilities capabilitiesof TeX/LaTeX and then export to whichever of the above formats through our usual scripts and tools toolslike openjade,openjade pdfjadetex pdfjadetexetc. In fact, as the following example already shows, we can: (eq2) \begin{equation} {\displaystyle }\int _{a}^{b}x^{2}dx=\frac{1}{3}(b-a)^{3}\label{eq2}\end{equation} ]]> ]]> ]]> ]]> Let's see what is going on, from the SGML SGMLpoint of view, when you type an equation like 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. in LyX:LyX when exported to SGML,SGML this equation yelds the following MathMLMathML code:There are some remarks due here:The TeX TeXcode that typesets the equation is enclosed between the <alt> tags. We will make heavy use of this fact later.The equation is again output, this time between the <math> tags. This is MathML.The whole is enclosed in the DocBook DocBook<equation> tags.As you see, LyX LyXis already capable of producing the (excessively verbose) MathML version of our equation. However, the technologies for delivering Math Mathon the Web Webthrough MathMLMathML are in constant constantflow (see a MathML status report). Furthermore, my openjade openjadewill spit dozens of errors, one for each MathMLMathML tag. Even if I were able to eliminate eliminatethese through the use of some extra module, it seems that the quality of the results, be it online or printed, is going to be rather dissapointing, as the following quote by Allin CottrellCottrellthe creator of the DBTeXMath method that we are going to use here clearly indicates:

A dsssl dssslengine such as openjade openjadecan turn the MathML MathMLinto TeX TeXfor you but the results are likely to be disappointing, particularly if you are used to typesetting mathematics mathematicsusing TeX TeXitself. TeX's native mathematical mathematicaltypesetting is near-perfect, only occasionally requiring manual manualtweaking to achieve optimal results; it is also rather comprehensive, with the aid of the AMS (American Mathematical MathematicalSociety) extensions extensionsif need be. But if you take the route of MathML MathMLto TeX TeXvia dsssl dsssland jade, the specifics of the math mathtypesetting must be handled by the dsssl dssslstylesheet.stylesheet David CarlisleCarlisle put some work into this a few years back (for which we can be grateful), but he didn't finish the job and nobody else has done so since. Thus if you send MathML MathMLthrough jade to TeX TeXyou are likely to find (a) that those elements that are recognized by the stylesheets are typeset less adeptly than by TeX TeXitself (with clumsy-looking clumsy-lookingspacing), while (b) various important elements may not be recognized at all. For example in my field of statistics the overbar (denoting the arithmetic mean) is a common modifier,modifier but it is simply ignored. Other formulations common in statistics are also ignored, or are not dealt with properly, so this route is not really usable for me.

Allin CottrellCottrell has introduced the DBTeXMath method, which I have slightly modified and incorporated in the method I presented so far. In the following sections I will first describe the necessary steps and software, then the explanation of the details.DBTeXMathYou probably already have almost all the necessary software installed on your system for the DBTeXMath method to work on it, but let's have a look at it anyway:Perl: The method is heavily based on some post-processing post-processingdone by Perl scripts, so Perl is a must. Any modern version should do, so just install the Perl package and the Perl modules of your distribution.distribution The three .dsl files (stylesheets) as discussed in . They already contain all necessary changes to process Mathematics,Mathematics so you will just need to copy them to the aproppriate locations - but you have done that already in .TeX, LaTeX LaTeX(see ), dvips dvipsand convert convert(see ) are also used heavily, but you already have installed those, didn't you?So far, you might not have to install anything additional, but the following is definitely new:The unescape_math.pl and texmath2pngbmp.plThe original script was called texmath2png. I added “bmp” to the name, because it now converts to BMP format too. scripts. Please use the ones provided here and not the original ones, as I have made some changes to them. Copy them somewhere in your system, preferably in /usr/local/bin and make them executable. Adapt the lyxtox to contain the right paths paths(see ).The awkscr_math awk awkscript in the working directory. Of course, you need awk awk() too, but you already needed it in for the htmlsplit.awk script. Writing Mathematics in LyXYou write Mathematics Mathematicsin LyX LyXjust as you would write it anyway, i.e. as if it were going to be processed by TeX TeXand not Jade.Jade The whole combined power of TeX/LaTeX/LyX lies at your fingertips! fingertips!So let 's try some math mathhere! This is a numbered displayed equation: (eq3) \begin{equation} f(x)=\left\{ \begin{array}{cc} \log _{8}x & x > 0\\ 0 & x=0\\ \sum _{i=1}^{5}\alpha _{i}+\sqrt{-\frac{1}{x}} & x < 0\end{array} \right.\label{eq3}\end{equation} ]]> ]]> ]]> ]]> An example of an unnumbered equation: (eq4) \[ \int _{-\infty }^{\infty }\frac{dx}{1+x^{2}}=\pi \] ]]> ]]> ]]> ]]> And here is an example of an inline inlineformula: $ \sum _{n=0}^{\infty }\frac{1}{n!}=e$ ]]> ]]> ]]> ]]> , or again $ \int _{a}^{x}f(t)dt:=F(x)$ ]]> ]]> ]]> ]]> .This is a partially numbered displayed equation: (eq5) \begin{eqnarray} 1 & = & 4-3\label{mathed:fourth-eqn}\\ 2 & = & 7-5\\ 1 & = & e^{2\pi i}\nonumber \\ 16 & \equiv & 2\, (mod\, 7)\label{mathed:fifth-eqn} \end{eqnarray} ]]> ]]> ]]> ]]> while in this one all equations equationsare numbered: (eq6) \begin{eqnarray} 1 & = & 3-2\label{mathed:second-equation}\\ 2 & = & 4-2\\ 4 & \leq & 7. \end{eqnarray} ]]> ]]> ]]> ]]> Now, let's do some more advanced examples: (eq7) \[ f(x):=\left\{ \begin{array}{ll} \frac{1}{q}, & \mathrm{if}\, x=\frac{p}{q}\, (\mathrm{in}\, \mathrm{lowest}\, \mathrm{terms})\\ 0, & \mathrm{if}\, x\, \mathrm{is}\, \mathrm{irrational}\end{array} \right.\] ]]> ]]> ]]> ]]> How about these: a matrix (eq8) \[ \left(\begin{array}{ccc} 1 & 2 & 3\\ 4 & 5 & 6\\ 7 & 8 & 9\end{array} \right),\] ]]> ]]> ]]> ]]> a partially filled matrix (eq9) \[ \left(\begin{array}{ccc} \lambda _{1} & & \\ & \ddots & \\ & & \lambda _{n}\end{array} \right),\] ]]> ]]> ]]> ]]> a continued fraction (eq10) \[ \frac{1}{\left(1+\left(\frac{1}{1+\left(\frac{1}{1+x}\right)}\right)\right)},\] ]]> ]]> ]]> ]]> a limit (eq11) \[ \lim _{x\rightarrow 0}f(x)=L\] ]]> ]]> ]]> ]]> and some inequalities (eq12) \[ E < mc^{2},\] ]]> ]]> ]]> ]]> (eq13) \[ a < b > c,\] ]]> ]]> ]]> ]]> (eq14) \[ a\leq b\geq c.\] ]]> ]]> ]]> ]]> Here is an inline inlineinequality, with a proof of non-negativity of relative entropy ( $ D(p\Vert q)\geq 0$ ]]> ]]> ]]> ]]> ): show that $ \ln x\leq x-1$ ]]> ]]> ]]> ]]> , for $ 0 < x < \infty .$ ]]> ]]> ]]> ]]> Then observe that (here comes an inequality array): (eq15) \begin{eqnarray*} -D(p\Vert q) & = & \sum _{x}p(x)\ln {\frac{q(x)}{p(x)}}\\ & \leq & \sum _{x}p(x)({\frac{q(x)}{p(x)}}-1)\\ & \leq & 0 \end{eqnarray*} ]]> ]]> ]]> ]]> If you are looking at the PDF PDFor PS PSversion of this document,document everything will look perfect, because it was typeset directly by TeX.TeX But if you are reading the HTML HTMLor RTF RTFversion, then you might have noticed that the equation numbering is not continuous. Rather it starts all over from (1) in each multiline equation. This is a bug of the method we use: each equation, be it inline inlineor displayed, one line, or multi-line,multi-line will be processed by TeX TeXas a separate document document(only for HTML HTMLand RTF), starting the numbering from 1 over and over again. Till some TeX TeXGuru Guru(anyone reading?) out there tells me how to work around this, the simplest solution for equation numbering is to follow the rulesrules below:Don't put more than one labels in a multi-line multi-lineequation (an equation array in LaTeX LaTeXjargon). If you absolutely need to, split the equation in two, containing only one label labeleach.Start each equation label labelwith “eq”, followed by a number, like “eq1”, “eq2”, “eq78” etc. My scripts number each displayed equation (i.e. not the inline inlineones) consequtively through the whole document,document automaticallyautomatically assigning an id and a title to them in the SGML SGMLcode. These ids and titles are always of the form “eqxxx” where xxx is the number of the equation and refer to the whole equation, not some line of it. On the other hand, LyX LyXknows only of equation labels assigned to some line of some equation. If you followed the previous rule and if you name the one and only labellabel of your equation with the “eqxxx” label labeldisplayed in its title, then you can refer to it from LyX LyXlike any other cross-reference cross-referenceand everything will work perfectly!The best way to implement the previous rule is to just process your documentdocument once without any labels in equations.equations You will see that all versions will have concise and continuous numbering in the equation titles. You will see titles like “Equation 11-1. (eq2)”. The “11-1” comes from Jade Jadeand means “the first equation of chapter 11”. The “(eq2)” is the title, assigned automatically automaticallyby my scripts. Now, if you want to label labelthis equation in LyX,LyX label labelonly one line of it (first rule) and label labelit “eq2” (second ruleof course, you take away the quotes). The magic behind the mathIt's not the math behind the magic - so you don't have to be afraid of being drown in formulas! Just read on to delve into the details of math document processing that goes behind the scenes while you are drinking that (hopefully not cold) cup of coffee. ]]> ]]> ]]> ]]> Inline graphic The idea behind the DBTeXMath method used here relies on the fact that, as we saw in the code example in above, all the TeX TeXcode for typesetting the equation is contained between the <alt> tags inside the <equation> tags. The <alt> tag is somehow “misused” for this purpose, but we will not bother about this for the moment (see the discussion in ). DBTeXMath DBTeXMathtweaks the stylesheets in order to let the TeX TeXcode be processed and converted in bitmapped bitmappedimages of PNG PNGand BMP BMPformat, for HTML,HTML resp. RTF,RTF orbe processed and typeset directly for PDF PDFand PS.PSThe code between the <math> tags is completely ignored - in fact, it is deleted. The steps in more detail:SGML math code correctionSGML SGMLmath code as exported by LyX LyXis, once again, not perfect and the first step consists in correcting it, just as we did in . We will change the SGML SGMLmath code to fit our needs using again runsed and sedscr. But this time, we are going to need an awk awkscript too, awkscr_math. We'll see in why.ProblemsRegarding Mathematics Mathematicscode, there are four distinct problems in LyX' SGML:SGMLLyX LyXproduces only an <alt>/</alt> tag pair (with the TeX TeXcode in it) and a <math>/</math> tag pair with the MathML representation representationof the equation. This is not enough. The <graphic fileref=”equationimagefile”> is missing. Openjade Openjadewill complain that the end tag for <equation> was reached, but the element elementwas “not complete”. And of course it is right, since the <alt> tag was meant as a textual representation representationof the image (see ), while the <graphic> tag is expected to hold the visual representationrepresentation of it in the form of some image file. Clearly, we will have to create the <graphic fileref=...> tags from the scratch. That's the first problem.The second problem is that LyX LyXexports <equation> even for inline inlineequations! The right tag would be <inlineequation> for inline inlineequations equations(see inlineequation), <equation> for an equation with title (see equation) and <informalequation> for one without (see informalequation). This is very unfortunate, because it makes all equations equations“displayed”, i.e. drawn on a separate line. That's the second problem.The third problem is that the MathML MathMLcode it produces cannot be dealt with by openjade openjade(at least not with the standard modules I have on my system) and thus produces parse errors. Furthermore, we are not going to need it, since the TeX TeXcode inside the <alt> tags will suffice completely for us. We will thus have to delete everything between the <math>/</math> tags. That's the third problem.The fourth problem regards inequalities in Math MathMode. Just writing (eq16) \[ a < b > c\] ]]> ]]> ]]> ]]> will produce and errorbecause the parser parserwill see the brackets around $ b$ ]]> ]]> ]]> ]]> and think that it is an SGML SGMLelement.element That's the fourth problem. SolutionWe will start with the second problem from above, since it is the only one that needs both sed and awk awkto be solved. It is also a nice example of a problem that cannot be solved with only one of themat least not easily: we would probably need two consecutive invocations of sed, or employ some complicated branching. Contrary to my usual predilection, I chose to make it as simple as possible, rather than complex and wonderful. ;-) The next LyX release may render it obsolete anyway.. In order to solve it, an observation was crucial: crucial:whenever a displayed equation occurs, LyX LyXends the preceding line with </para><para>. The idea is therefore to the <equation> tag that follows a line ending in </para><para> to something different than <equation>, so that we can safely say that the rest of remaining <equation> tags denotes actually inline equations equationsand change them accordingly. The following code in sedscr checks if the line ends in </para><para> and if so, gets the next line in the pattern space (N command). It then changes the <equation> to <informalequation>It doesn't matter to what you change it to, as long as it is different from <equation>., prints the line and deletes the pattern space completely:The rest is accomplished in the awk awkscript awkscr_math. We know by now that whatever <equation> tags may have remained, they denote the start of inline inlineequations.equations We thus change <equation> to <inlineequation> and </equation> in </inlineequation>, but only between <equation>/</equation> tags. This is done by the following code in awkscr_math:Finally, we can transform whatever <informalequation> tags remain back to <equation>:By the way, we also did something that is impossible to do in sed: we added a dynamic id and title, both composed of the string “eq” and a dynamically increased counter. The id is the same as the “label” in LyX,LyX the title is what will be displayed in the equation title. By letting the title be equal to the id, we are able to see what id an equation has in the SGML SGMLcode (because it will be displayed in the title) and set the LyX LyXlabel labelfor that equation to be the same (see ), thus making cross-refernces to equations equationspossibleyou can only cross-reference an equation only if you previously set a label to it, but the LyX label cannot (and will not) be exported to SGML, since it refers to a line in a possibly multi-line equation - what id should then be exported to SGML form an equation with three lines, all carrying a label in LyX? .The first problem, create the <graphic fileref=...> tags, requires a decision: which filename to take? A first idea, to use the label labelfrom the TeX TeXcodebetween the <alt> tags, as long as there is one, is not viable: what if the TeXTeX code describes more than one equations equations(an eqnarray), each one labeled with its own label?label I decided to use random filenames in all situations, rather than running into such problems. Due to the random part, such a substitution substitutioncalls for awk,awk rather than sed.The random numbers,numbers which will be the filenames to use, are currently drawn between 10000 and 20000. If you want to change these limits, you can do it in the BEGIN part of awkscr_math:But sometimes, this randomness randomnessis not needed: How to get identical filenames for the equations from run to run If you want the same sequence of random numbers each time you run the script (thus producing the same filenames from run to run), you should comment the seed function srand(). The following code creates the <graphic fileref=...> tag with a random filename in the fileref filerefattribute after the closing </alt> tag:More precisely, it substitutes </alt> with something likeSome remarks: The number used for the filename (10404) is randomly generated (num_ran, in the previous code example). The directory for the images of the equations equationsis images/math. If you need to change it, you will have to do so everywhere in awkscr_math.We make again use of the output.print.xxx output.print.xxxentities entitiesto denote code that has to be IGNOREd or INCLUDEd , depending on the format we are rendering,rendering see and .We specify a PNG PNGfile even for PDF PDFand PS PSprocessing.processing That's not important. These formats will not take into account the <graphic> element elementwhen processed (the stylesheets will take care of this). Nevertheless, we must put a <graphic> tag with some filename there, otherwise openjade openjadewill complain.The important information is that the file 10404.png shall be used to display the equation when the output.print.png output.print.pngentity is included (i.e. only in HTML) and that 10404.bmp shall be used when the output.print.bmp output.print.bmpentityentity is included (i.e. only in RTF).The above substitution substitutiontakes place in the following 4 situations (which cover all math mathsituations in LyX' SGML) in awkscr_math:Between “<alt>\[” and “</alt>”.Between “<alt>$” and “</alt>”.Between “<alt>\begin{equation}” and “</alt>”.Between “<alt>\begin{eqnarray}” and “</alt>”.This solves our first problem.While we are at it, we substitute the “<” and “>” symbols symbols(that appear in inequalities between the alt tags) with their SGML SGMLentitiesThe IF statement in the code avoids the substitution for the brackets that surround the alt tags themselves.:When texmath2pngbmp.pl is executed, it will see those entities entitiesand will substitute them with their numeric equivalents:This solves the fourth problem.The third problem is easier solved: the following code in awkscr_math will substitute everything between <math> and </math> with the empty string (thus creating an empty line):That empty lines do not get printed, is easily seen from the last code block in awkscr_math:which will print every line that is not empty. HTML and RTFThe HTML HTMLand RTF RTFdocument math mathprocessing processingis done partially in the stylesheetsBoth HTML stylesheets contain the same code for Mathematics. () and partially in the texmath2pngbmp.pl script. Math processing in the HTML stylesheetsThe following code in the HTML HTMLstylesheets (found in the docbook.dsl docbook.dslfile of the original DocBook DocBookstylesheet stylesheetpackage) initiates exactly the same processing processingas in the standard stylesheets, with one addition: the (process-math) instruction will start an additional processing step, after the standard one. The process-math process-mathroutine is further specified in the code as follows:This will create a new SGML SGMLfile, equation-list.sgml, in the current directory, that will contain an element elementof type "equation-set"equation-set. That's simply a container containerof equations equationsand some LaTeX LaTeXoptions that may be passed to it from the stylesheet:stylesheet it contains the LaTeX LaTeXoptions in “latexopt”, “density” and “usepackage”, as well as the TeX TeXequation code, enclosed between <texequation>/</texequation> tagsMore precisely, the equation-list.sgml file is itself an SGML document, which should validate against the following DTD: ]]> ]]> ]]> ]]> ]]>. Here's how the equation-list.sgml file may look likeYou can see the equation-list.sgml file for this document here: equation-list.sgml.:\[ ]]>\begin{equation} ]]> ]]>How is the TeX TeXcode extracted from the <alt> elements and inserted in equation-list.sgml? This is the core work and is done by the following code in the HTML HTMLstylesheets:Basically, what the above code does is the following: It processes only text found in the <alt> element elementand only code found inside <informalequation>, <equation> or <inlineequation> tags. It puts this code (the TeX TeXcode of an equation) between <texequation> tags in equation-list.sgml. It also lists the fileref filerefattribute of the <graphic> element.element This completes the Mathematics Mathematicsprocessing processingdone by openjade.openjade We will use the equation-list.sgml file to create PNG PNGand BMP BMPimages of each equation. Math processing with texmath2pngbmp.plThe texmath2pngbmp.pl is called after openjade openjadehas processed the SGML SGMLfile with the stylesheetstylesheet for one HTML HTMLfile. It takes one argument, the file to process. It expects a file with the structure of equation-list.sgml (see ). It basically does the following:It parses the equation-list.sgml file. It extracts “latexopt”, “density” and “usepackage” .For every text found between <texequation> tags, it creates a new TeX TeXfile. In the preample,preample it sets the options found in “latexopt”, “density” and “usepackage”. In the main part, it inserts the text, which is nothing else that the TeXTeX code describing an equation It also unescapes some characters in the TeX code:/g; ]]>.It then calls LaTeX LaTeXto process the TeX TeXfile, dvips dvipsto create the the PostScript� PostScript�file from the .dvi file created by LaTeX,LaTeX convert to convert convertthe PS PSfile to PNG PNGformat with the right density density(the full name of the PNG PNGfile was extracted from equation-list.sgml)convert (once again) to convert convertthe PS PSfile to BMP BMPformat (the full name was calculated from the path pathand basename basenameof the PNG PNGfileThis is new here. The original texmath2png.pl file did not compute BMP versions of the equation images. .At the end of the processing, PNG and BMP images are in images/math, while the HTML and RTF documents contain links to them for each equation. We are ready! We can enjoy Mathematics on the Web in TeX quality! ]]> ]]> ]]> ]]> Inline graphic Note: We only need to call texmath2pngbmp.pl once. The PNG and BMP equation images for the whole SGML file will be created in the right directory and need not be recreated for each HTML or RTF run, since our trick with the output.print.xxx entities will take care for each run to INCLUDE the graphic element with the right filenames in the fileref attribute (see , , ). PDF and PSThe PDF PDFand PS PSdocument math mathprocessing processingis done partially in the print stylesheetThe print stylesheets, lyxtox-print-pdf.dsl and lyxtox-print-ps.dsl both contain the same code for Mathematics. This can be probably modularized further in some next version of the scripts. () and partially in the unescape_math.pl script. It differs substantially from the HTML HTMLand RTF RTFmath mathprocessing processing(): instead of creating images for each equation, the stylesheet stylesheetinstructs openjade openjadeto directly output the TeX TeXcode in the .tex file it produces. We then unescape unescapesome characters in that .tex file and pass it to pdfjadetexpdfjadetex or jadetex jadetexfor the creation of the PDF,PDF resp. DVI DVIfileThe PS version is then only one step away, with the aid of dvips.. Math processing in the print stylesheetThe code for math mathprocessing processingin the print stylesheet stylesheetdoes basically one simple thing: it outputs the text found between the <alt> tags (the TeXTeX code of the equation) in <equation>, <informalequation> and <inlineequation> elements of the input file. It encloses that text between begintexliteral and endtexliteral tags:It also specifies that we plan to use the TeX TeXbackend:TeX backend? ]]>TeX backend. ]]>When openjade openjadeprocesses the an SGML SGMLfile containing equations,equations it will follow the above DSSSL DSSSLcode and produce something like:This is the literal TeX TeXcode for , enclosed in begintexliteral-endtexliteral tags. As you can see, openjade openjade"escapes" some characters (for instance, turning a backslash into \char92{} and a caret into \char94{}), so that unless we take special measures we will end up with a typeset version of the source for the equation rather than the typeset equation. It is here that the unescape_math.pl script comes into play. Unescaping <application>TeX</application> equation codeThe unescape_math.pl script is a simple Perl script that reads the input file (the .tex file created by openjade openjadethrough the print stylesheet stylesheetas in ) line by line and “unescapes” some characters found between begintexliteral and endtexliteral. More precisely, the order of operations for each line is the following:If the line contains begintexliteral, we are entering TeX TeXmath code. Delete begintexliteral.If we are still in TeX TeXmath code, unescape unescapethe code. This is basically a substitution substitutionof a few characters:If the line contains endtexliteral, we are leaving TeX TeXmath code. Delete endtexliteral.The code of the above simple algorithm algorithmis After applying unescape_math.pl to the .tex file, the above “escaped” TeX TeXcode for becomes:which will be perfectly typeset by TeX TeXin the subsequent call of (pdf)jadetex. Note: In the original unescape_math.pl script, step 2 of the algorithm was performed as step 3, after the endtexliteral substitution. This is a bug that comes on the surface when we have one line containing both equation code and endtexliteral. In such a case, the original sequence of steps will only delete endtexliteral, leaving the equation code still "escaped". After this “unescaping”, we get a .tex file that we can either process to a PDF PDFone through pdfjadetexpdfjadetexActually, pdfjadetex has to be called up to three times consecutively to produce table of contents, cross-references etc. correctly. lyxtox already does this for you.or to a PS PSone through jadetexjadetexActually, jadetex has to be called up to three times consecutively to produce table of contents, cross-references etc. correctly. lyxtox already does this for you. and dvips:dvips Problems of the DBTeXMath methodThe DBTexMath DBTexMathmethod provides us with an easy way to get perfectly typeset Mathematics Mathematicsin all 4 formats: HTML,HTML PDF,PDF PS PSand RTF.RTF Moreover, it does this in the context of SGML SGMLprocessing processing- we are not forced to leave our usual procedures and/or markup,markup it integrates nicely in our scripts.Nevertheless, such an approach approachto mathematical mathematicaldocument processing processingis not free from problems:The most important objection comes from a theoretical viewpoint: the <alt> tag is what its name suggests - a tag for an alternative description of the equation. This is not exactly what the TeX TeXcode is, especially from the accessibilityaccessibility point of view (see ). In a message to the docbook-apps mailing list, Michael Smith points out the following:

The DocBook DocBookTC intended the contents of <alt> to be a human-readable text description, using ISO ISOentities entitiesfor any math mathsymbols symbolsthat couldn't be represented with normal characters.But maybe if you use <alt role="tex">, you could tweak tweakthe stylesheets so that to the HTML HTMLoutput they add some generated text like: ]]>That way, to people reading or hearing the alt text in a browser,browser it'll at least be unambiguous to them that what's they're reading/ hearing is TeX TeXmath -- which, depending on the complexity complexityof the equation, they may or may not find "human-readable"human-readableInserting “role=tex” to the <alt> tag can be done very easily in the awkscr_math script..

Labels on displayed equations equationsfor the HTML HTMLand RTF RTFformats will always start at 1, no matter how many equations equationsyou have. I briefly discussed this in , along with some measures to alleviate the problem. Until some TeX TeXGuru Guru(anyone reading?) out there tells me how to work around this, you might want to crop every image of a displayed equation to 90% in the x direction with the -crop option to convert:convertThis will eliminate eliminatethe equation labels from the image. If you follow the rules rulesin , you will still be able to reference equations equationsconcisely and correctly through all chapters and in all formats.Your text should not contain begintexliteral or endtexliteral, otherwise the unescape_math.pl script will try to unescape unescapesome characters between them (and will also delete them). Well, I can live with that one... LocalizationSo here you are, after 200 pages of information bombardement, your eyes wide open in expectation of the last firework: “will it work with my language?”, you ask. This chapter deals with the answer to this question.FIXME: Add: What is internationalization, what localization?localizationHere is “the problem at hand”, as described vividly in Messing about with Unicode, XML, XSL, DSSSL, Tex, Omega, Fop and the rest of the mess:

Let's say you have a source of data that is going to be published. The data comprises text from many, many languages. English. Dutch. Chinese, sure. Malayalam, perhaps. Tibetan, of course. And it contains some pretty weird symbols.symbols Like a shwa -- a topsy-turvy e: . In order to subsume all this data in one character encoding,encoding everything is encoded in Unicode: the current standard for multi-lingual, unified text encoding.encodingYou would like to print your text, publish your text on the web, and perhaps also to prepare it for further editing in a word-processing package. And you don't want to lose your Chinese characters, your IPA signs, or your mathematical mathematicalsymbols.

Work in progress! This chapter is work in progress, so the information in it is incomplete - and may even be inaccurate! Many problems may have disappeared, as distributions made the transition to UTF-8. Others may have surfaced. If you have any hints regarding this complex subject, please contact me, or post in my Linux Forum. One thing that makes this endeavour so difficult, is that it is comprised of many, many steps, each one with its own inputs, output and tools.tools To understand the process, we have to dissect it in those steps:You type something on the console with your keyboard. Each key on your keyboard carries a symbol on it, but this does not mean that when you press it you will see that symbol on the screen. What you see on the screen depends on the keyboard mapping and your console fonts,fonts see . In a GUI GUIenvironment environment(and an X terminal, instead of a text console), the GUI GUImay apply its own mappings and LyX LyXmust know about them too. See , .Finally, some hexadecimal code arrives at LyX LyXas a result of your key pressing. Will LyX LyXdisplay what you expect? This depends on LyX' language configuration, see .Suppose you managed to type something and see it displayed correctly in LyX LyXin the language of your choice. You save the document documentand run lyxtox as in . This will kickstart an avalanche of commands, which will ultimately do the following:Export the document documentfrom LyX LyXto DocBook DocBookSGML.SGML Depending on its language configuration, LyX LyXwilluse the right encoding encodingfor the symbols,symbols letters etc you typed andset the language attribute attribute(“lang”) in the $ < $ ]]> ]]> ]]> ]]> article $ > $ ]]> ]]> ]]> ]]> or $ < $ ]]> ]]> ]]> ]]> book $ > $ ]]> ]]> ]]> ]]> element elementof the exported file. For language set to english, this will produce the lines ]]>near the top of the exported document.document This information is used by the DSSSL DSSSLstylesheets, see .sed and awk awkwill correct the exported SGML SGMLdocument. Will sed and awk awkunderstand your Dutch and Chinese? Or your Malayalam? See and .Openjade Openjadewill transform the corrected SGML SGMLdocument to various formats, including HTML,HTML TeX TeXand RTF.RTF Will Openjade Openjadeunderstand the encoding encodingof the input file? How will Openjade represent it internally? And which encoding encodingwill Openjade Openjadeuse for the output in HTML,HTML TeX TeXand RTF?RTF See .Lynx Lynxwill read the HTML HTML(one file) version and produce the TXT TXTout of it. Will lynx lynxproduce a correct TXT TXTdocument documentfrom the (hopefully correct) HTML?HTML See .Perl scripts transform the TeX TeXversion. Will Perl work as expected in the languages of our example? See .Pdfjadetex transforms the TeX TeXsource into a PDF PDFdocument. Will pdfjadetex pdfjadetexunderstand that its input TeX TeXsource is in some other encoding?encoding How can we tell it? Jadetex transforms the TeX TeXsource (actually a different TeX TeXsource from the above, produced by openjade openjadeusing the lyxtox-print-ps.dsl DSSSL DSSSLstylesheet) to a DVI DVIdocument. Will jadetex jadetexunderstand that its input TeX TeXsource is in some other encoding?encoding How can we tell it? Pdfjadetex and jadetex jadetexare TeX TeXmacro packages packagesand as such they use the underlying TeX TeXinstallation. Will TeX TeXcope with all those languages? See .dvips dvipsreads the DVI DVIdocument produced by jadetex jadetexand outputs a PS PSfile. What must dvips dvipsknow about localization localizationto work with our multilanguage document?document See .Will openjade openjadeproduce the right HTML,HTML TeX TeXand RTF?RTF Will pdfjadetex pdfjadetexproduce a PDF PDFfile in the right encoding?encoding With the right fonts fontsembedded embeddedin the document?document Will jadetex jadetexproduce a DVI DVIdocument with the right encoding encodingand the right fonts?fonts Will dvips dvipsproduce a correct PS PSdocument from the localized DVI?DVI Will lynx lynxproduce the right TXT TXTfrom the localized HTML?HTML What are the open problems related to localization?localization See .Questions over questions...Now let's put the puzzle pieces together! LyX User Guide The following sections are taken from the LyX User Guide: , with its subsections , and and with its subsections , , , . Shell localizationFIXME: What is locale?FIXME: what is charset? What is encoding?encodingFIXME: include localization localizationthrough locale and .bashrc. sed localizationFrom the sed manual page, we see that the following environment environmentvariables affect the execution of sed:LANG Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility utilitywill behave as if none of the variables had been defined.LC_ALL If set to a non-empty string value, override the values of all the other internationalisation variables.LC_COLLATE Determine the locale for the behaviour behaviourof ranges, equivalence classes and multi-character collating elements within regular expressions.expressionsLC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- versus multi-byte characters in arguments and input files), and the behaviour behaviourof character classes within regular expressions.expressionsLC_MESSAGES Determine the locale that should be used to affect the format and contents of diagnostic diagnosticmessages written to standard error.NLSPATH Determine the location of message catalogues cataloguesfor the processingprocessing of LC_MESSAGES . awk localizationFrom the awk manual page, we see that the following environment environmentvariables affect the execution of awk:awkLANG Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility utilitywill behave as if none of the variables had been defined.LC_ALL If set to a non-empty string value, override the values of all the other internationalisation variables.LC_COLLATE Determine the locale for the behaviour behaviourof ranges, equivalence classes and multi-character collating elements within regular expressionsexpressions and in comparisons of string values.LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- versus multi-byte characters in arguments and input files), the behaviour behaviourof character classes within regular expressions,expressions the identification identificationof characters as letters, and the mapping of upper- and lower-case characters for the toupper and tolower functions.LC_MESSAGES Determine the locale that should be used to affect the format and contents of diagnostic diagnosticmessages written to standard error.LC_NUMERIC Determine the radix character used when interpreting numeric input, performing conversions between numeric and string values and formattingformatting numeric output. Regardless of locale, the period character (the decimal-point character of the POSIX locale) is the decimal-point character recognised in processingprocessing awk awkprograms (including assignments in command-line arguments).NLSPATH Determine the location of message catalogues cataloguesfor the processingprocessing of LC_MESSAGES .PATH PATHDetermine the search path pathwhen looking for commands executed by system(expr), or input and output pipes.pipes See the XBD specification,specification Environment Variables.In addition, all environment environmentvariables will be visible via the awk awkvariable ENVIRON. Perl localizationFIXME: Get the information from the Perl manual on locale handling Keyboard localizationTo use LyX LyXproperly, you must set X up correctly. This is especially vital if you're using the international support features of LyX LyXand want to use non-English keyboard mappings. Unfortunately, almost nobody bothers to do this, especially those who've installed Linux on a PC. Administrators of large systems can be guilty of this, too, so don't assume that you're safe if you're using a large system. Any user can instruct X how to use his or her keyboard. You needn't rely on your sysadmin for this - in fact, you shouldn't! The following two programs are all you need to set up your keyboard the way you want it.xmodmap and xkeycapsFirst of all read the man pages for these two programs. They are your best friends when you are trying to set up X key mapping correctly. If you don't have them, install them.xmodmapThis document documentcontains no information on how to use typewriterxmodmap. There is a sample typewriter.Xmodmap file in Customization. To load the new X keyboard mappings, place the command typewriterxmodmap .Xmodmap somewhere in your startup scripts [for example, typewriter.cshrc, typewriter.profile, typewriter.login, or typewriter.xinitrc are all possibilities]. xkeycapsThis program is a dream come true! It brings up a graphical version of your keyboard, allows you to make modifications, and then spits those modifications out to the standard output in a form readable by typewriterxmodmap. It is very useful when you're trying to design a new typewriter.Xmodmap file, though it will require you to do a bit of cut-and-pasting. Modifiers and Mode_switchLyX LyXsupports three modifiers: Shift [S-], Control [C-], and Meta [M-]. Moreover, if one of the keys of your keyboard is configured as a Compose key, then you can use it to enter some characters not available on your keyboard. This compose key can be used either as a modifier modifier(like Shift or Control) or as a prefix key. Here are some examples of what you can do with a Compose key:Compose+e+' $ \rightarrow $ ]]> ]]> ]]> ]]> �Compose+O+R $ \rightarrow $ ]]> ]]> ]]> ]]> �Compose+1+2 $ \rightarrow $ ]]> ]]> ]]> ]]> �Compose+<+< $ \rightarrow $ ]]> ]]> ]]> ]]> �This input method is particularly handy when you use accented characters only from time to time. It works by default for latin1 latin1characters, but other input methods will be used if you setup your locale correctly. Helpful Hints and TipsFirst, open up two xterminals. Use one to edit a new typewriter.Xmodmap file and run typewriterxkeycaps from the other. Using typewriterxkeycaps, remap your keyboard the way you want it. There's a button in typewriterxkeycaps to output the new keymap. Once you hit it, typewriterxkeycaps will spit a bunch of stuff on the xterm you executed it from. Just copy and paste all of that into your typewriter.Xmodmap file, and you're done.You could also save yourself some typing by executing xkeycaps > .Xmodmap. This will create a usable map file. Of course, if you hit the “output keymap” button in xkeycaps more than once, the resulting map file will be a mess. As with all things, xkeycaps is a tool, and only as intelligent as the person on the other end.Also, there are some things you can do to help you get oriented. Try executing the command typewriterxmodmap -v -pm. This will show you all of the currently active modifiers. Also try typewriterxmodmap -v -pke | more to see which keycode numbers numbersare mapped to which symbolic symbolicnames. It will also give you some idea of the syntax of the typewriter.Xmodmap file.There's one thing you'll need to check. Make sure that your Delete and BackSpace keys are not defined as the same key symbol by X! Note that giving these two keys unique symbol names will not necessarily alter the behavior of your programs. Some programs bind Delete and BackSpace to the same operation. Emacs is one. Other programs, however, use Delete and BackSpace for different operations. LyX LyXis one of these programs, and if you have Delete and BackSpace labeled with the same key symbol name, you'll have trouble using LyX.LyX LyX localizationThis section describes how to use LyX LyXwith any language you want. LyX LyXcomes with a default configuration which supports the English language on a U.S.-style keyboard, with a standard U.S. paper papersize and the spell checker set to U.S. English. You can change any or all of these settings as desired, and you can make the changes apply to the current session only, or use them as your new default configuration.If you have a keyboard suited to the language you are using (for example, a german keyboard for writing in German), and you have correctly configured your X environment,environment all you need to do for LyX LyXis tell it your language, the character encoding,encoding and desired paper papersize. Refer to for more information.If, however, you have a U.S.-style keyboard and want to write in a different language than English, you can use an alternate keymap. For example, if you have a U.S.-style keyboard but want to write in Italian, you should configure LyX LyXto use an Italian keymap. Refer to for details. Finally, you may just want to change a few key mappings or create an entirely different keymap (for Vulcan, for instance). You may, for example, normally write in Italian on a U.S. keyboard but want to include an occasional quotation in German. In such a case, you can write your own keyboard mapping or modify an existing one to support the characters you want. The details of how to customize LyX LyXto your own language are way beyond the scope scopeof this manual.manual You can not only alter the keyboard layout,layout you can also change the names of the menus buttons, etc., to reflect your language. If you want to learn more about writing keymap files and tailoring LyXLyX to your native tongue, please see the Customization manual manualfor details.Layout Language OptionsThe Document Layout dialog lets you set the language and character encoding encodingfor your language. Access this dialog by selecting Layout&lyxarrow;Document.Choose your language by clicking on the arrow in the Language combobox of the Document Layout dialog. The default is U.S. English. Scroll to find the language you want and then click on your choice. The language name appears in the window.In LaTeX terms, selecting a language other than default adds Babel support. If you do not have Babel installed, refer to the different LaTeX distributions for it.The Encoding box lets you choose the character encoding encodingmap you want to use. The default is the typewriterASCII encoding encodingwhich is typically sufficient for U.S. English. A superset supersetof the typewriterASCII encoding encodingis the typewriterLatin1 encoding,encoding which includes the characters required by the various Western European languages. The third choice, typewriterLatin2, is for support of Eastern European languages. Click on the dialog and then click on the encoding encodingyou want to use, and it appears in the window. (Refer to for the character encodings.)To change the paper papersize, select Layout&lyxarrow;Paper. Then use the Papersize combobox to select a paper papersize. The default is the U.S. Letter paper papersize.To use any language, papersize,papersize or encoding encodingchange you made, click on the OK button. Your new configuration will now be used as long as you are in the current LyX LyXsession. Keyboard mapping configurationThe preferences preferencesdialog allows you to choose up to two keyboard mappings. This allows you to choose the keymap of your choice for your U.S.-style keyboard. You can choose primary and secondary keyboard languages and then select which one you want to use. Click on the down arrow for the Primary combobox and choose the language keymap you want by clicking on it. The name them appears in the Primary window. Do the same in the Secondary window for a secondary language if you want one. You can then select either your primary or secondary keymap in the Mapping section of the menu, or select No key mapping if you do not want to use an alternate keymap. The Character set window allows you to use different character sets if your language uses more than one. Greek, for example, uses two, and a Greek user can enter typewriteriso-8859-7 in this window and the appropriate character map (a typewriter.cdef file), if available, is loaded. Note that one of the choices for both primary and secondary keymaps is Other. You can use this to select a custom keymap which you've created yourself. For example, current distributions of LyX LyXprovide an typewriteramerican-2 keymap file in the typewriter$LYX_DIR/kbd directory. This keymapping supports some accented characters for other languages in addition to the U.S. keymap. To use the typewriteramerican-2 keymap, select the Options&lyxarrow;Keyboard menu, select other in the primary selection box, enter the name of the keymap (typewriteramerican-2) and click on OK. You should now be able to enter accent characters using the new keymap. Character TablesHere is a table with all the characters in the typewriterLatin1 character set. You should be able to print all these characters directly from the keyboard without using too many modifier modifierkeys (if your keyboard is set up correctly, that is). Note that you must set your font encoding encoding(in the Encoding combobox of the Layout&lyxarrow;Document dialog) to latin1 to use this keyset, and to latin2 to use the typewriterLatin2 keyset. latin1 character set 00 10 20 30 40 50 60 70 80 90 A0 B0 C0 D0 E0 F0 00 0 @ P ' p � � � � � 01 ! 1 A Q a q � � � � � � 02 “ 2 B R b r � � � � � � 03 # 3 C S c s � � � � � � 04 $ 4 D T d t � � � � � � 05 % 5 E U e u � � � � � � 06 & 6 F V f v � � � � � � 07 ` 7 G W g w � � � � � � 08 ( 8 H X h x � � � � � � 09 ) 9 I Y i y � � � � � � 0A * : J Z j z � � � � � � 0B + ; K [ k { � � � � � � 0C , < L \ l | � � � � � � 0D - = M ] m } � � � � � � 0E . > N ^ n ~ � � � � � � 0F / ? O _ o � � � � � �

There are a few things you need to know about . This manual manualis set up --- by hand, mind you --- to print all of these characters. That ain't the default. Nowhere near, in fact. Here are some of the details you'll need to bear in mind when using characters from the typewriterLatin1 character set:The characters at entries A2,A2 A4, A5, A6 and AD -- the cent, the yen, the generic-currency-symbol, the broken vertical verticalbar, and the short dash -- are just plain missing in the default encodings. We don't know where they are or why this is the case.Even if you've selected latin1 in the Document Layout dialog, users who have only the typewriterOT1-fonts for LaTeX LaTeX[or who have the typewriterT1-fonts but aren't using them] will still be missing a few characters: D0, F0, DE, FE, AB, and BB -- the uppercase and lowercase eth and thorn, and the french quotes -- won't show upThis is also true if you do use the T1 encoding, but instruct Openjade to use the Computer Modern family of fonts (in the T1 encoding this time, of course) through the setting of the %body-font-family%, %mono-font-family%, %title-font-family%, %admon-font-family% and %guilabel-font-family% DSSSL variables in the lyxtox-print-pdf.dsl stylesheet (see ) - as you can see very well in the PDF version of this document..Users of typewriterOT1-fonts can, however, get the french quotes [characters AB and BB] if they include the either the package typewriterumlaute.sty or typewritergerman.sty in their documents.This only holds when you want to input these quotes by yourself. The automatic quote feature described in the “Quotes” Subsection of the LyX User's Guide (in the Section “A Few Words about Typography”), will generate automatically LaTeX code adapted to available fonts and packages.If you use OT1 OT1font encoding,encoding i.e. if the jadetex.cfg file contains the line(in which case it wouldn't make sense to use neither of the aeae, aecomplaecompl, aeguillaeguill, umlauteumlaute or german packagespackages, which are for the T1 T1encoding, i.e. you would have commented the lines:or those line would simply not be there), then in this case you must input the following characters in math mathmode (see also the table “How to Typeset Special Characters” in What Is TeX?): $ < < $ ]]> ]]> ]]> ]]> : two “lower than” signs, one after anotherNot to be confused with the french quotes symbol (the “guillemet”).. Enter math mathmode and type the two signs. $ > > $ ]]> ]]> ]]> ]]> : two “greater than” signs, one after anotherNot to be confused with the french quotes symbol (the “guillemet”).. Enter math mathmode and type the two signs.< : “lower than” sign. Enter math mathmode and type the sign.> : “greater than” sign. Enter math mathmode and type the sign.\: backslash. Enter math mathmode and type “\backslash”._: underscore. Enter math mathmode and type “\textunderscore”. From How to use the underscore character:

The underscore character is ordinarily used in TeX TeXto indicate a subscript in maths mode; if you type in the course of ordinary text, TeX TeXwill complain. If you're writing a document documentwhich will contain a large number of underscore characters, the prospect of typing typing\ (or, worse, \textunderscore) for every one of them will daunt most ordinary people.Moderately skilled macro macroprogrammers can readily generate a quick hack to permit typing typingto mean 'text underscore'. However, the code is somewhat tricky, and more importantly there are significant points where it's easy to get it wrong. There is therefore a package underscore which provides a general solution to this requirement.There is a problem, though: OT1 OT1text fonts fontsdon't contain an underscore character, unless they're in the typewriter typewriterversion of the encoding encoding(used by fixed-width fonts fontssuch as cmtt). So either you must ensure that your underscore characters only occur in text set in a typewriter typewriterfont, or you must use a fuller encoding,encoding such as T1,T1 which has an underscore character in every font.

|: vertical verticalbar. Enter math mathmode and type the sign.The following is a full list of all of the accented characters LyX LyXcan display directly. It includes not only the accented characters from the previous table, but also the characters from typewriterISO8859--2 through typewriter4. From typewriterISO8859--1:� � � � � � � � � � � �diaeresis^ � � � � � � � � � �circumflex` � � � � � � � � � �grave� � � � � � � � � � � � �acute~ � � � � � �tilde��cedilla�macronThe dead macron in usually not needed, as you will use a non--dead key for this instead. For example, S-M-minus, or if .Xmodmap is correct, S-M-macron.From typewriterISO8859--2 through typewriter4:\^{H}\^{J}\^{h}\^{\j}\^{C}\^{G}\^{S}\^{c}\^{g}\^{s}circumflex\'{S}\'{Z}\'{s}\'{z}\'{R}\'{L}\'{C}\'{N}\'{r}\'{l}\'{c}\'{n}acute\~{I}\~{\i}\~{U}\~{u}tilde\c{S}\c{s}\c{T}\c{t}\c{R}\c{L}\c{G}\c{r}\c{l}\c{g}\c{N}\c{K}\c{n}\c{k}cedillaThese characters might not look very nice on screen, but they will be just fine when run through LaTeX and printed.\={E}\={e}\={A}\={I}\={O}\={U}\={a}\={\i}\={o}\={u}macron\H{O}\H{U}\H{o}\H{u}hungarian umlautAll the characters above are actively supported by TeX TeXfonts. In addition TeX TeXallows diacritical marks on almost all characters . Also make sure you're using the typewriterT1 font-encoding and have the package typewriterumlaute.sty with the definition file typewriteriso.def installed. International Spellcheck SupportLyX LyXuses the typewriterispell spelling checker. You should configure typewriterispell to work with your system if it does not already. To get the appropriate language dictionary, refer to the typewriterWhere file included with the typewriterispell package. Note that some dictionaries do not support the typewriterLatin1 encoding.encoding If you have selected the typewriterLatin1 encoding encoding(in the Document Layout dialog) with one of these dictionaries, the spellchecker will not work for some people. Refer to the “Spellchecking” section of the LyX User's Guide for more details about international spellchecking. Openjade localizationOpenjade Openjadeonly supports a single pre-defined character repertoire. A character name of the form U-XXXX where XXXX are four upper-case hexadecimal dig- its, is recognized as referring to the Unicode character with that code. For many characters, it is also possible to use the ISO/IEC 10646 name in lower-case with words separated by hyphens.Some common SDATA entity entitynames from the ISO ISOentity sets are recognized and mapped to characters. In addition an SDATA entity entityname of the form U-XXXX, where XXXX are four upper-case hexadecimal digits, is mapped to the Unicode character with that code.OpenJade OpenJadenow supports the standard-chars, map-sdata-entity, add-name- chars, add-separator-chars and char-repertoire declaration element elementforms, allowing a style-sheet style-sheetto define additional character names, sdata entity entitymappings, name characters (i.e. characters allowed in identifiers) and separator characters. Currently the only recognized character repertoire is the built-in repertoire. It has the public identifier identifier"UNREGISTERED::OpenJade//Character Repertoire::OpenJade". dvips localizationThe only localization localizationof dvips dvipsavailable seems to be the redefinition of paper papersize, depending on the user's (or system's) locale. For example, to change the paper papersize to letter format (used in North America), one would doIn SuSE Linux, this is done automatically automaticallyby the SuSEconfig.SuSEconfigtetex script (located in /sbin/conf.d/) by taking into account the LC_PAPER locale: /dev/null ]]> DSSSL stylesheet localizationAs distributed, the stylesheets use English for all generated text, but several other localization localizationfiles are also provided.Switching localizations localizationsis achieved by writing a customization customizationlayer that references the proper localization localizationfile. The customization customizationshould look like this: ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]> ]]>Where dbl1dege.dsl is the name of the localization localizationfile you wish to use (German in this example). See Customizing the Stylesheets. TeX localizationInstall the package latex-ucs (in SuSE Linux it is the RPM RPMpackage latex-ucs-20030605-18.noarch.rpm in the noarch directory of the distribution distributionCDs), or get it from CTAN CTANfrom the directory macros/latex/contrib/unicode, for example from CTAN latex-ucs package. lynx localizationFrom the lynx lynxmanual manualpage:-display_charset=MIMEname set the charset for the terminal output.NATIVE LANGUAGE SUPPORTIf configured and installed with Native Language Support, Lynx Lynxwill display status and other messages inyour local language. See the file ABOUT_NLS in the source distribution,distribution or at your local GNUGNU site, formore information about internationalization.The following environment environmentvariables may be used to alter default settings:LANG This variable, if set, will override the default message language. It is an ISO ISO639 two-letter two-lettercode identifying the language. Language codes are NOT the same as the country codes given in ISO ISO3166.LANGUAGE This variable, if set, will override the default message language. This is a GNU GNUextension extensionthat has higher priority for setting the message catalog catalogthan LANG or LC_ALL.LC_ALL and LC_MESSAGES These variables, if set, specify the notion of native language formatting formattingstyle. They are POSIXly correct.LINGUAS This variable, if set prior to configuration, limits the installed languages to specific values. It is a space-separated list of two-letter two-lettercodes. Currently, it is hard-coded to a wish list.NLSPATH This variable, if set, is used as the path pathprefix for message catalogs.From the Unicode HOWTO:Lynx-2.8 has an options screen (key 'O') which permits to set the display character set. When running in an xterm or Linux console in UTF-8 mode, set this to "UNICODE UTF-8". Note that for this setting to take effect in the current browser browsersession, you have to confirm on the "Accept Changes" field, and for this setting to take effect in future browser browsersessions, you have to enable the "Save options to disk" field and then confirm it on the "Accept Changes" field.Now, again, all a document documentneeds is the following line between the <head> and </head> tags:<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">When you are viewing text files in UTF-8 encoding,encoding you also need to pass the command-line option "-assume_local_charset=UTF-8" (affects only file:/... URLs) or "-assume_charset=UTF-8" (affects all URLs). In lynx-2.8.2 you can alternatively, in the options screen (key 'O'), change the assumed document documentcharacter set to "utf-8"utf-8. Open localization problemsFIXME Shortcomings and bugs Cross-references to elements other than sections or chapters. This seems to be a stylesheet stylesheetand/or Jade/Openjade limitation and not a limitation of LyX LyX(see the discussion of the “ xref xrefto ANCHOR ANCHORunsupported” error in ). Generally, it is a justified decision: the xref xrefneeds a text that will act as hyperling and this has to be supplied by the formatting formattingapplication. The formatting formattingapplication (Jade/Openjade here), in turn, does not in general know what text to put in xref,xref it just has a pointer to an id. But in the special case of figures figures(element <mediaobject>) I would like to see “Figure” (or some predefined text in the current language), followed by the figure number in the text to xref.xref If you modify the stylesheets for this, please send me your solution, so I can include it here.Cross-references that appear in figure captions captionscannot be currently recognized - and this will break the automatic correction of the SGML SGMLcode for figures.figures In sedscr,sedscr we use<graphic fileref="$[^"]*$">[ ]*<anchor id="$[^"]*$"> ]]><![CDATA[$[^<]*$<\/title>[ ]*<\/figure> ]]></screen><para>as the regular expression for LyX' SGML <indexterm><primary>SGML</primary></indexterm>for figures.<indexterm><primary>figures</primary></indexterm> If a cross-reference <indexterm><primary>cross-reference</primary></indexterm>is in the caption,<indexterm><primary>caption</primary></indexterm> this will break the $[^<]*$ subexpression,<indexterm><primary>subexpression</primary></indexterm> which matches everything, up to the first occurence of a “<”. It will not match up to the starting bracket of the ending title tag, but only up to the starting bracket of the cross-reference <indexterm><primary>cross-reference</primary></indexterm>(i.e. of <xref linkend="reference-label">).</para></listitem><listitem><para>Callouts (see <xref linkend="callouts">, <xref linkend="LyX-callouts">) will make your HTML <indexterm><primary>HTML</primary></indexterm>document NOT HTML <indexterm><primary>HTML</primary></indexterm>4.01 Transitional <indexterm><primary>Transitional</primary></indexterm>compliant! The W3C <indexterm><primary>W3C</primary></indexterm>validator will complain that</para><screen><![CDATA[document type does not allow element "IMG" here ]]></screen><para>Thus, if you want HTML <indexterm><primary>HTML</primary></indexterm>4.01 Transitional <indexterm><primary>Transitional</primary></indexterm>compliance (see <xref linkend="HTML-validation">), you will have not to use callouts.<indexterm><primary>callouts</primary></indexterm> I find callouts <indexterm><primary>callouts</primary></indexterm>very useful, so I will be happy to learn of a solution that is standards <indexterm><primary>standards</primary></indexterm>compliant and allows their use.</para></listitem><listitem><para>Figures that are “intended” one level deep in order to be vertically aligned with some preceding text that happens to be in the Description environment <indexterm><primary>environment</primary></indexterm>are not listed in the List of Figures that appears in the front page. This can best be illustrated with an example: see the <ulink url="http://www.karakas-online.de/EN-Book/">PHP-Nuke HOWTO</ulink>. </para><para>Examine the List of Figures below the Table of Contents in the front page.<footnote><para>You will have to scroll to the bottom (perhaps after setting the “focus” with a click somewhere in the text with the mouse, since it is a framed design) to see the List of Figures.</para></footnote> Now go to <ulink url="http://www.karakas-online.de/EN-Book/administration-functions.html">administration functions of PHP-Nuke</ulink>. There are a lot of figures <indexterm><primary>figures</primary></indexterm>there. Some of them are included in the List of Figures, others not. Those that are not included are the “intended” ones (in LyXese <indexterm><primary>LyXese</primary></indexterm>the key word is “ environment <indexterm><primary>environment</primary></indexterm>depth” , which is set to one level deep for those figures,<indexterm><primary>figures</primary></indexterm> in order to be aligned with the text in the Description environment <indexterm><primary>environment</primary></indexterm>above them).</para><para>This is probably a bug of the stylesheets and may have been corrected already in newer versions. FIXME:<indexterm><primary>FIXME</primary></indexterm> I have to investigate this further. Any suggestions welcome.</para></listitem><listitem><para>The <alt> tag for images is not rendered in HTML <indexterm><primary>HTML</primary></indexterm>(see also <ulink url="http://sources.redhat.com/ml/docbook-apps/2002-q3/msg00519.html">Textobject and Alt tag</ulink>). In theory, the <alt> tag should contain the text that is included in the <textobject> tags of the <mediaobject> element.<indexterm><primary>element</primary></indexterm> In practice, it is not. Not with my ancient <indexterm><primary>ancient</primary></indexterm>(v. 1.72) stylesheets and not with newer ones (like v. 1.77, see <ulink url="http://sources.redhat.com/ml/docbook-apps/2002-q3/msg00539.html">Re: Textobject and Alt tag</ulink>). This has consequences for the mathematics <indexterm><primary>mathematics</primary></indexterm>(<xref linkend="mathematics">) part too: the <alt> tag is (mis)used by the DBTeXMath <indexterm><primary>DBTeXMath</primary></indexterm>method (<xref linkend="DBTeXMath">) to store the <application>TeX</application> <indexterm><primary>TeX</primary></indexterm>code that describes the equation displayed in the figure. Since the <alt> tag is not shown in HTML <indexterm><primary>HTML</primary></indexterm>(it is not present in the HTML source code of the rendered file), it will not show up in the TXT <indexterm><primary>TXT</primary></indexterm>version of the document <indexterm><primary>document</primary></indexterm>either. Thus, a mathematics <indexterm><primary>mathematics</primary></indexterm>text in the TXT <indexterm><primary>TXT</primary></indexterm>version will be lacking any information on the equations.<indexterm><primary>equations</primary></indexterm> Let's hope this will be corrected in the future. Note: I have corrected this bug using a set of dynamic sed scripts, see <xref linkend="alt-attributes-for-images">. Still, it would be interesting to know if there is a solution within the stylesheets themselves.</para></listitem><listitem><para>In PDFs the underscore is interpreted mathematically, making the character following the underscore to appear as a subscript. Moreover, if the link does not have an ending, it gets the standard ending for PDFs, namely “.pdf” attached to it, which is definitely wrong. Try this link: <ulink url="awkscr_insert_index_items">awkscr_insert_index_items</ulink>, in HTML and in PDF to see the difference!</para></listitem><listitem><para>The PDF files index will have multiple references to the same page. For example one index entry may have references to page 3,3,3,3,28 sort of thing. This is a known limitation of the collateindex.pl script. Quoting from <ulink url="http://docbook.sourceforge.net/release/dsssl/current/doc/indexing.html">Automatic Indexing with the DocBook DSSSL Stylesheets</ulink>:</para><blockquote><para>Any generated index is perhaps better than none, but there are still a few things that cannot be accomplished:</para><blockquote><para>1. Duplicate page numbers are not suppressed in the index. If the document contains three indexing hits on page 4, the generated index will contain “4, 4, 4”.</para><para>2. Ranges are not automatically constructed. If the document contains indexing hits on pages 4, 5, 6, and 7, the generated index will contain “4, 5, 6, 7” instead of “4-7”.</para></blockquote><para>This is also discussed in <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=4444">Index having multiple entries to the same page in PDF files</ulink>.</para></blockquote></listitem></itemizedlist></chapter> <chapter id="other-methods"><title>Other methods Various other methods exist that are related to the one presented here. This method is unique in that it uses LyX LyXand a lot of script “ glue gluecode” to hide the complexity complexityof writing in SGML SGMLfrom the user. However, if for some reason you prefer to not use LyX,LyX the shell scripts, the stylesheets or some other part of this method, you might want to have a look at the following alternatives:Use a makefile makefilelike the one in DocBook Makefile Templates (in this link, if you open it and scroll up to the end, you will find the influential posting of Nik ClaytonClayton that outlined a working way to get images in all formats of a documentdocument (see ), definitely a recommended reading).Use the makefile of the LDP.Use the O'Reilly O'Reillystylesheets. The collection comprises an initial pass at documenting and publishingpublishing the stylesheets used by ORA to convert convertDocBook documents into HTML HTMLfor CD-ROM CD-ROMpublication, and conversion of DocBook DocBookinto tagged taggedFrame for print publication publicationand for copy returned to non-SGML-using non-SGML-usingauthors.The stylesheets are in the form of a single SGML SGMLdocument which is both a DocBook DocBook<book> documenting the stylesheets and the stylesheets themselves. FIXME: Unfortunately, all my efforts to locate the “ O'Reilly O'ReillyDSSSL DSSSLStylesheets” on the Web Webwere unsuccessfull. The links I had and those I find, all point to non-existent resources.There have been various previous attempts at a script solution to documentdocument generation, see i.e. in the docbook mailing listIn Preparing Cogent Documentation, you will find another detailed discussion of the document documentproduction productionprocess using SGML/XML. Bibliography Note This is not the Bibliography produced by RefDB (), but just a chapter with this misleading title, containing some links to other sources. The RefBDB Bibliography bears the name “Reference List” or “References” and is located even further down, near the end of the document. SGML and XML text processing: Contains a comprehensive list of links to everything around SGML SGMLand XML document documentprocessing.processing Docbook Basics and ReferencesDocBook Modular StylesheetsTroubleshooting LyX for a DocBook bookLDP Author's Resources page - templates, links, and tools.toolsLDP Author GuideDocBook Quick Reference (v3.1, v4.1.2)Norman Walsh DSSSLDocBook: The definitive Guide. You can browse this book online here or you can download it at http://ww w.docbook.org/tdg/index.html.(aus NewbieDocDocbNewbieDocDocbookGuide.htm)For a more compact introduction to SGML SGML, with practical examples that cover most cases, see NewbieDocDocbookGuide.htm.NewbieDocDocbookGuide.htmWriting Self-Published Self-PublishedBooks with Lyx (from books_with_lyx.html).DocBook DocBookwith LyX LyX(from db4lyx.pdf)Automatic Indexing in DocBookRefDB tutorialDocBook DSSSL stylesheets FAQCustomizing Document Production, (PDF version), written by Pascal Lo R� of Mandrake.MandrakeUsing Jade for SGML transformations: explains some of the mechanisms used in Customizing Document Production and in the stylesheets described here.NewbieDoc DocBook Guide: the HTML HTMLstylesheet stylesheetI use comes from this project, with some additions from the ldp.dsl ldp.dslof the Linux Documentation Project.Overview of SGML resourcesSGML and XML on coverpages.orgA gentle introduction to SGMLMathML DSSSL stylesheets: An old collection of tools toolsfor doing MathML MathMLwith DSSSL DSSSLand Jade.JadeGeneral DSSSL stylesheet questionsDocBook FAQDSSSL resources on coverpages.DocBook tools, DSSSL, sgmltool and various other mailing listsDBTeXMathA gentle introduction to MathMLMathML on coverpages.orgDocBook with LyXLyx-DocBook-HOWTO.pdfSetup your own docbook processing: An alternative way to automate document documentprocessingprocessingConvert other formats to DocBook, a comprehensive list of available tools toolsfor converting to DocBookDocBookErstellung von pdf-Dokumenten mit LaTeXHow to convert a LaTeX document into a PDFLaTeX document, by Patrick S. Vogt, Basel Univ., Switzerland. FIXME:FIXME no URL URLfound anymore!From LaTeX to MathML and Back with TeX4ht and PassiveTeXTeX4ht: LaTeX and TeX for HypertextSee Resources there, for more links to alternative converters.Math Typesetting for the InternetReader's guide to Sydney Olympics accessibility complaintOlympic Failure: A Case for Making the Web AccessibleBobby Accessibility TestPreparing Cogent Documentation: Offers a detailed discussion of the document documentproduction productionprocess using SGML/XML.Installing And Using An XML/SGML DocBook Editing Suite &appendix; &bibliography; &index;