From owner-freebsd-doc@FreeBSD.ORG Sun Mar 20 19:52:30 2011 Return-Path: Delivered-To: freebsd-doc@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 8FDBE106566B for ; Sun, 20 Mar 2011 19:52:30 +0000 (UTC) (envelope-from bcr@FreeBSD.org) Received: from mxout1.bln1.prohost.de (mxout1.bln1.prohost.de [213.160.84.47]) by mx1.freebsd.org (Postfix) with ESMTP id 265308FC1F for ; Sun, 20 Mar 2011 19:52:29 +0000 (UTC) Received: from Benedicts-Macbook-Pro.local (p508D745B.dip.t-dialin.net [80.141.116.91]) (authenticated bits=0) by mx1.bln1.prohost.de (8.14.1/8.14.1) with ESMTP id p2KJqM7e026099 (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NO) for ; Sun, 20 Mar 2011 20:52:22 +0100 Message-ID: <4D865AFB.7070105@FreeBSD.org> Date: Sun, 20 Mar 2011 20:52:27 +0100 From: Benedict Reuschling Organization: The FreeBSD Project User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.6; de; rv:1.9.2.15) Gecko/20110303 Thunderbird/3.1.9 MIME-Version: 1.0 To: freebsd-doc@FreeBSD.org References: <70FE330E-E1DF-4E2C-AC41-2C5475B00971@gmail.com> In-Reply-To: <70FE330E-E1DF-4E2C-AC41-2C5475B00971@gmail.com> X-Enigmail-Version: 1.1.1 OpenPGP: id=4A819348 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit X-Null-Tag: 307f5701907929fb6540ff35887affab Cc: Subject: Re: Creating epub version of handbooks X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: bcr@FreeBSD.org List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 20 Mar 2011 19:52:30 -0000 -----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-----