Subject:
Document processing with LyX and SGML
From:
"Chris Karakas" ####@####.####
Date:
23 Feb 2004 01:13:56 -0000
Message-Id: <20040223.AOr.81138500@www.karakas-online.de>
(long, but rewarding the patient)
Hello,
I have seen quite a few inquiries on this list over the years for things like:
- How to write in LyX and still be able to produce DocBook SGML that is usable for
serious writer's work?
- How to convert my LaTeX document to SGML?
- How do I create documents like the PHP-Nuke HOWTO:
http://www.karakas-online.de/EN-Book/
with all the formats as in
http://www.karakas-online.de/EN-Book/formats.html
and all the bells and whistles?
I've answered many times that "my scripts do this" and that I was going to release
them with a complete documentation "very soon". I underestimated the task
completely! It took me more than one year to write it, but finally, it is there, a
200-page guide:
Document processing with LyX and SGML:
http://www.karakas-online.de/mySGML/
Grab your favourite format from the Formats section:
http://www.karakas-online.de/mySGML/formats.html
and enjoy! :-)
I will be honoured if the LDP decides to include it in its collection of documents.
Let me describe a little the problem I solve here:
As soon as I understood what SGML is and what DocBook does, I knew this was the way
to go: from that point on, I wanted to write my documents only in DocBook SGML - and
produce all the other formats automatically.
Since I knew LaTeX (as a mathematician who wrote his master's thesis in LaTeX, back
in 1992), I was starting to use LyX. If you ever had to enter some of the formulas I
had to enter in vi and LaTeX, then you will admit that LyX' graphic MathEd is a
great step forward.
I was even more delighted to learn that LyX can export in DocBook SGML. I installed
Jade/Openjade and started experimenting...
It was a disaster! I have written it down for me to remember - and for you to be warned:
http://www.karakas-online.de/myJade/
A real disaster: one tool needs this, the other tool needs that - they work together
only if the X environment variable is set to some cryptic value, but when it's
Wednesday and full moon you have to take into account also the fact that... ;-)
No, that's not what I expect from a working toolchain!
And I was not alone, as I have seen in the course of the years! Even in this list,
there have been threads full of frustration about all the machinery that is needed.
Why? It's not the machinery. It's the fine tuning you *must* do, otherwise *you just
don't get your results*! :-(
Some examples:
- How many people wanted to have images in PDF? Many. How many of them succeeded?
Almost nobody. Why? Because the intricasies of all tools involved are such, that
without a thorough knowledge of what is going on, you are lost. See:
http://www.karakas-online.de/mySGML/explain-figures.html
for the gory details.
- You still want to incorporate images? Say, from the local "images" directory?
Forget it - unless you set the environment variable SGML_SEARCH_PATH to "./images".
Did you know that? As a DocBook/SGML/LDP newbie? I didn't. And I paid - days and
nights of searching why...
- And you still want images? You think you are finished by just setting
SGML_SEARCH_PATH to the right value? Well, you are not. The Postscript file will not
contain them, unless you set the environment variable TEXPSHEADERS correctly! You
see, pdftex (and pdfjadetex) need this...
and many, many other fine examples.
I wanted to write in LyX, then press a button and get everything done. I am proud to
announce that my LyX-to-X scripts do this:
http://www.karakas-online.de/mySGML/lyxtox.html
But not only this:
- They correct LyX' exported SGML code, so that you can use it (otherwise you will
get tons of errors).
- They let you include images, admonitions, callouts from LyX.
- They let you write and publish Mathematics:
http://www.karakas-online.de/mySGML/lyx-mathematics.html
on the Web and in print with TeX quality!
- They produce a PDF with all bells and whistles: bookmarks, thumbnails, hyperrefs,
cross-refs, images, embedded (Computer Modern) fonts for optimal viewing *and*
printing etc. See
http://www.karakas-online.de/mySGML/explain-optimal-pdf.html
- They produce *valid HTML*. That's not to be taken for granted with the standard
tools - just check a document produced by openjade with W3C's HTML validator. See
http://www.karakas-online.de/mySGML/html-validation.html
- They produce HTML code that passes the guidelines for accessibility - that's also
not the case for the standard tools, see
http://www.karakas-online.de/mySGML/accessibility.html
- They create the index automatically for you. LyX offers a very comfortable way of
inserting index entries. But if you ever need to create an Index for a 500 page
document like this one:
http://www.karakas-online.de/EN-Book/i20165.html
then even LyX' manual approach will not serve you. For such cases, the scripts offer
an automatic Index generation:
http://www.karakas-online.de/mySGML/lyx-automatic-index-generation.html
And what about the Bibliography? We have BibTeX, don't we? ;-)
Yes, but BibTeX won't help you with SGML. Instead, the scripts use RefDB (
http://refdb.sourceforge.net ), the only available tool to create HTML, PostScript,
PDF, DVI, MIF, or RTF output from DocBook or TEI sources with fully formatted
citations and bibliographies according to publisher's specifications.
RefDB is integrated transparently: you build you bibliographic database, you define
your bibliographic style, i.e. the style accepted by the journal you want to submit
your work, then the lyxtox script
http://www.karakas-online.de/mySGML/lyxtox
will create (through RefDB) the bibliography SGML file according to that style, then
it will create (on-the-fly!) the necessary extra DSSSL customization layers that
will, in turn, format everything correctly:
http://www.karakas-online.de/mySGML/lyx-bibliography-with-refdb.html
If you'd rather not use RefDB, the scripts will still offer you a solution to your
bibliography problem:
http://www.karakas-online.de/mySGML/lyx-bibliography-without-refdb.html
Thus, what you get is a *complete* solution to your writing needs:
- GUI (LyX), don't bother about SGML.
- Table of Contents,
- cross-references,
- Index,
- Bibliography,
- Mathematics
everything is covered. You press the button, LyX-to-X does the rest - enjoy! :-)
Chris
--
--
Regards
Chris Karakas
http://www.karakas-online.de
