From owner-freebsd-doc@FreeBSD.ORG Mon Mar 21 07:41:04 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 4011D106564A; Mon, 21 Mar 2011 07:41:04 +0000 (UTC) (envelope-from mrcfve@gmail.com) Received: from mail-qw0-f54.google.com (mail-qw0-f54.google.com [209.85.216.54]) by mx1.freebsd.org (Postfix) with ESMTP id CC6428FC14; Mon, 21 Mar 2011 07:41:03 +0000 (UTC) Received: by qwc9 with SMTP id 9so4336150qwc.13 for ; Mon, 21 Mar 2011 00:41:03 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:sender:in-reply-to:references:date :x-google-sender-auth:message-id:subject:from:to:cc:content-type :content-transfer-encoding; bh=3FRu3D6LoehCN0nLDvQ00xN8/+L21ebglOLWtwfMYys=; b=D9VnJ0uPLxUfbWIoR5BrxA7wtJGv10XfI0dXoW97naQg/A/fA0XZnnZ3RxPgpaixII 47bBkjUIBgZMXI5eZE7SRIK3T5ApSYUem9XnP0GJIE7UjRhS5cRbfaXibzWIjv0aDQgx siLED0xHnm2Z4qlWmpHfDmmF2wSZIxx7hRIts= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:sender:in-reply-to:references:date :x-google-sender-auth:message-id:subject:from:to:cc:content-type :content-transfer-encoding; b=BYa+JkSqHpnrKpGTX3DdW9mytfTkEaHu8nu2WY+2OVKfwT71VZ/tyzAIRQmPTcwMc9 7JCzcVug/OE6TBTaINLhK4aYJ+fE6I/FzkgdBQnLBL9gjonRclK9Ji8vQIGVY10/cpk8 bo+8kI9/IGfqlAQv/7dPyqOvq3AOfI/mydxJw= MIME-Version: 1.0 Received: by 10.224.178.14 with SMTP id bk14mr2947107qab.96.1300691715497; Mon, 21 Mar 2011 00:15:15 -0700 (PDT) Sender: mrcfve@gmail.com Received: by 10.229.86.72 with HTTP; Mon, 21 Mar 2011 00:15:15 -0700 (PDT) In-Reply-To: <4D865AFB.7070105@FreeBSD.org> References: <70FE330E-E1DF-4E2C-AC41-2C5475B00971@gmail.com> <4D865AFB.7070105@FreeBSD.org> Date: Mon, 21 Mar 2011 08:15:15 +0100 X-Google-Sender-Auth: sWmV43X7coLSqW3FknvxukiyCYc Message-ID: From: Marc Fonvieille To: bcr@freebsd.org Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable Cc: freebsd-doc@freebsd.org Subject: Re: Creating epub version of handbooks X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 21 Mar 2011 07:41:04 -0000 2011/3/20 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 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