Creating epub version of handbooks

[Dru Lavigne]

> 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?
>
> 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.


Sounds like a great talk, Benedict! I'll have to catch it.

If it's any help, Damjan, I used calibre and sigil when creating the epub version of the PC-BSD Handbook. Calibre converted the pdf to epub format and sigil cleaned it up. Calibre warns that manual cleanup will still be needed after conversion; in practice, the conversion process randomly inserts figures into the middle of nearby paragraphs and ordered and unordered lists need to be adjusted so they render properly. I had to use the Linux or Windows version as the FreeBSD port for calibre fails and I haven't had a chance yet to figure out what causes the error to submit a PR. The FreeBSD port of sigil works fine.

Cheers,

Dru