Skip site navigation (1)Skip section navigation (2)
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>