Date: Mon, 21 Mar 2011 08:15:15 +0100 From: Marc Fonvieille <blackend@FreeBSD.org> To: bcr@freebsd.org Cc: freebsd-doc@freebsd.org Subject: Re: Creating epub version of handbooks Message-ID: <AANLkTinkaJvRUb2BwZmWt=r2P1pF%2Bv5C_KDdK_By=VQ7@mail.gmail.com> In-Reply-To: <4D865AFB.7070105@FreeBSD.org> References: <70FE330E-E1DF-4E2C-AC41-2C5475B00971@gmail.com> <4D865AFB.7070105@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
2011/3/20 Benedict Reuschling <bcr@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 d= ocbook xml and then apply epub XSLT. >> >> When I try to do "make FORMATS=3Dxml" in handbook directory or use sx/os= x i got hundreds of errors =A0(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/handboo= k/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 DocB= ook 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 gene= rated >> /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:1= 1:E: element "BOOKINFO" undefined >> /usr/local/bin/sx:/usr/doc/en_US.ISO8859-1/books/handbook/book.sgml:59:1= 0:E: element "TITLE" undefined >> /usr/local/bin/sx:/usr/doc/en_US.ISO8859-1/books/handbook/book.sgml:61:1= 5: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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?AANLkTinkaJvRUb2BwZmWt=r2P1pF%2Bv5C_KDdK_By=VQ7>