Creating epub version of handbooks

Marc Fonvieille blackend at FreeBSD.org
Mon Mar 21 07:41:04 UTC 2011


2011/3/20 Benedict Reuschling <bcr at freebsd.org>:
> -----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).
>

The pdb target exits in our doc building system, since pdb to epub is
possible it can be a solution. However I'm not sure the resulting epub
file is what people are expecting in term of quality (images, links,
etc.) compared to what a direct
SGML --> epub translation should offer.

--
Marc



More information about the freebsd-doc mailing list