Creating epub version of handbooks

[Benedict Reuschling]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Am 20.03.11 19:33, schrieb Damjan Marion:
> 
> Hi,
> 
> I want to create epub version of handbooks. I tried to convert sgml to docbook xml and then apply epub XSLT.
> 
> When I try to do "make FORMATS=xml" in handbook directory or use sx/osx i got hundreds of errors  (some of them listed below). 
> 
> Am I doing something wrong or xml creation is broken?
> 
> Thanks,
> 
> Damjan
> 
> 
> /usr/local/bin/sx -xlower -xndata /usr/doc/en_US.ISO8859-1/books/handbook/book.sgml 2> .sxerr | tail -n +2 >> book.xml
> /usr/local/bin/sx:/usr/doc/en_US.ISO8859-1/books/handbook/book.sgml:7:73:W: cannot generate system identifier for public text "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"
> /usr/local/bin/sx:/usr/doc/en_US.ISO8859-1/books/handbook/book.sgml:8:87:W: cannot generate system identifier for public text "-//FreeBSD//ENTITIES DocBook FreeBSD Books Entity Set//EN"
> /usr/local/bin/sx:/usr/doc/en_US.ISO8859-1/books/handbook/book.sgml:9:10:E: reference to entity "books.ent" for which no system identifier could be generated
> /usr/local/bin/sx:/usr/doc/en_US.ISO8859-1/books/handbook/book.sgml:8:0: entity was defined here
> /usr/local/bin/sx:/usr/doc/en_US.ISO8859-1/books/handbook/book.sgml:55:0:E: reference to entity "BOOK" for which no system identifier could be generated
> /usr/local/bin/sx:/usr/doc/en_US.ISO8859-1/books/handbook/book.sgml:7:0: entity was defined here
> /usr/local/bin/sx:/usr/doc/en_US.ISO8859-1/books/handbook/book.sgml:55:0:E: DTD did not contain element declaration for document type name
> /usr/local/bin/sx:/usr/doc/en_US.ISO8859-1/books/handbook/book.sgml:57:5:E: element "BOOK" undefined
> /usr/local/bin/sx:/usr/doc/en_US.ISO8859-1/books/handbook/book.sgml:58:11:E: element "BOOKINFO" undefined
> /usr/local/bin/sx:/usr/doc/en_US.ISO8859-1/books/handbook/book.sgml:59:10:E: element "TITLE" undefined
> /usr/local/bin/sx:/usr/doc/en_US.ISO8859-1/books/handbook/book.sgml:61:15:E: element "CORPAUTHOR" undefined
> 

Hello Damjan,

your approach is a lot like mine when I first tried converting the
FreeBSD documentation set for an epub version. I'll be presenting a
possible solution (more like a migration path) at this years BSDCan:

http://www.bsdcan.org/2011/schedule/events/224.en.html

To answer your question: the problem is that there are countless
FreeBSD-specific entities (like &os; which translates to "FreeBSD" in
the output document) that need to be converted for the XML version of
DocBook. We are still using an older version of DocBook that is based on
SGML in the Doc project that AFAIK can not yet produce XML output. For
epub creation, the source file must be in XML format. Work is in
progress to convert not only these entities that cause these errors, but
also to move to an newer version of DocBook that is XML-based. However,
this takes time because XML is more strict and we also need to make
modifications to our documentation build infrastructure (makefiles and
such) once we are at a pure XML-based doc set.

People are getting more and more interested in the epub format, which is
a good thing. You can get more information about the current status from
my slides at BSDCan (which I will make available as soon as I gave he
talk there). My guess is that there will be epub versions in the
foreseeable future for all documents (faq, handbook, articles, etc.)
that we maintain, because epubs are relatively easy to create (mostly
automatic).

Regards

Benedict Reuschling
FreeBSD Doc Committer

The FreeBSD Documentation Project
FreeBSD German Documentation Project - https://doc.bsdgroup.de
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.8 (Darwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk2GWvEACgkQTSZQLkqBk0jZIQCdECRyy6y5ZZmvQWdKka1jrl2K
8D8AoNADM687GUugFuU8pM9tIPmAEFD6
=VkE5
-----END PGP SIGNATURE-----