Re: [Scons-dev] Documentation in EPUB-format
Andrew,
On Oct 13, 2013, at 11:50 AM, Andrew Featherstone
andrew.featherst...@gmail.com wrote:
On 10/10/2013 12:59 AM, William Deegan wrote:
All,
On Oct 9, 2013, at 3:38 PM, Andrew Featherstone
andrew.featherst...@cantab.net wrote:
On 10/09/2013 09:18 AM, Dirk Bächle wrote:
Andrew,
thanks for the update on your progress. Sounds good so far...
On 09.10.2013 00:26, Andrew Featherstone wrote:
Hi Dirk,
Yes my tool takes care of zipping up and formatting the container
correctly. Unfortunately the SCons Zip builder method doesn't support
source files with different compression types; perhaps that's a separate
feature that could be added. For now I'm using the Python zipfile module
directly and achieving what's required.
I had a look at the Zip Builder too. From what I understood you should be
able to call it repeatedly, such that you append files to an already
existing archive. Wouldn't this open the possibility of specifying
different compression modes then?
Whilst that's true, I can't get the desired results. As a simple example
where foo.txt and bar.txt are two files to be compressed using different
compression algorithms
# SConstruct
import zipfile
Zip('out', 'foo.txt', ZIPCOMPRESSION=zipfile.ZIP_STORED)
Zip('out', 'bar.txt', ZIPCOMPRESSION=zipfile.ZIP_DEFLATED)
$ scons
scons: Reading SConscript files ...
scons: *** Two environments with different actions were specified for the
same target: out.zip
Creating a intermediate target doesn't help, as the result is simply nested
zip archives. E.g.
# SConstruct
import zipfile
Zip('tmp', 'foo.txt', ZIPCOMPRESSION=zipfile.ZIP_STORED)
Zip('outer', ['bar.txt', 'tmp.zip'], ZIPCOMPRESSION=zipfile.ZIP_DEFLATED)
results in outer.zip containing bar.txt compressed using the deflate
algorithm, and an archive containing a single uncompressed foo.txt.
The EPUB recipes on the Internet that I found used the simple zip -X9rD
OEBPS to archive the stuff together. So I'm wondering whether it's really
required to support special compression settings...
My understanding of the specification is that the mimetype file needs to be
uncompressed. See
http://www.idpf.org/epub/30/spec/epub30-ocf.html#sec-zip-container-mime .
It's permitted for all files to be uncompressed, but that results in
needlessly large EPUB files. I imagine that lots of EPUB readers are
designed to be tolerant of recipes that compress everything, despite it
being against the specification.
The ZIPCOMPRESSION is stored in the OverrideEnvironment used for the target,
and not on the sources (sadly), in this case.
Definitely worth filing an enhancement report (bug) on tigris.org.
I'm thinking there's likely an entire class of use cases where storing such
on the source rather on the Builder would be useful..
(forced static library,etc)..
-Bill
___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev
Dirk: I've pushed what I've got so far to
https://bitbucket.org/ajf58/scons_docbook/branch/epub . I've run a basic
Docbook through it and generated an EPUB file that passes the validation test
here http://validator.idpf.org/ . In it's current form there's a bug in that
the files added to the OEBPS directory aren't re-added when the source files
are changed. Is it possible for the action functions passed to a Command
builder to modify target and source lists?
Bill: I can raise an issue there if you think that's sensible. A quick glance
at http://scons.tigris.org/ shows a large number of open tickets. Is this
because issues are tracked elsewhere? https://bitbucket.org/scons/scons
itself seems to be active, and indeed shows some work using Ghostscript to
create EPUB files.
scons.tigris.org is the location of the current bug tracker for SCons. So
please file your ticket there..
-Bill
Co-Manager, SCons project___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev
Re: [Scons-dev] Documentation in EPUB-format
Andrew, On 13.10.2013 20:50, Andrew Featherstone wrote: [...] Dirk: I've pushed what I've got so far to https://bitbucket.org/ajf58/scons_docbook/branch/epub . I've run a basic Docbook through it and generated an EPUB file that passes the validation test here http://validator.idpf.org/ . In it's current form there's a bug in that the files added to the OEBPS directory aren't re-added when the source files are changed. Is it possible for the action functions passed to a Command builder to modify target and source lists? this is more the task of an Emitter. If you want to do things properly, you'll have to define an additional set of builders for xsltproc, lxml and libxml2. You can then add your specialized Emitter to the constructors of the single Builders and replace the call of __select_builder() with something like: __builder = __select_builder(__lxml_builder_epub, __libxml2_builder_epub, __xsltproc_builder_epub) . Bill: I can raise an issue there if you think that's sensible. A quick glance at http://scons.tigris.org/ shows a large number of open tickets. Is this because issues are tracked elsewhere? https://bitbucket.org/scons/scons itself seems to be active, and indeed shows some work using Ghostscript to create EPUB files. We currently have the situation that our repository is on bitbucket, while the bug database is still managed by Tigris...as long as we don't have decided where we want to migrate to. Regards, Dirk ___ Scons-dev mailing list Scons-dev@scons.org http://two.pairlist.net/mailman/listinfo/scons-dev
[Scons-dev] Documentation in EPUB-format
Hi Dirk, Yes my tool takes care of zipping up and formatting the container correctly. Unfortunately the SCons Zip builder method doesn't support source files with different compression types; perhaps that's a separate feature that could be added. For now I'm using the Python zipfile module directly and achieving what's required. The other outstanding issue is for me to tidy up the emitter function used to copy some of the resources, such as images, that need to be copied into the OEBPS directory. Hopefully I'll be able to push this work in a complete form to my bitbucket repository towards the end of the week. Regards, Andrew ___ Scons-dev mailing list Scons-dev@scons.org http://two.pairlist.net/mailman/listinfo/scons-dev
Re: [Scons-dev] Documentation in EPUB-Format?
On 06.10.2013 01:24, Bill Deegan wrote: Dirk, How big are the ePub files? vs pdf.. For the full UserGuide, I currently have: PDF = 2394kB vs. EPUB = 219kB , but you have to take into account that the additional graphics for the style and the titlepage eat up a lot of space for the PDF. I haven't tried yet, but I guess additional images would bloat up both formats in about the same way. Regards, Dirk ___ Scons-dev mailing list Scons-dev@scons.org http://two.pairlist.net/mailman/listinfo/scons-dev
Re: [Scons-dev] Documentation in EPUB-format
Andrew, On 06.10.2013 21:07, Dirk Bächle wrote: [...] The DocBook Tool is not (yet) part of the core sources. By keeping compatibility to older SCons and Python versions, we don't force people to upgrade if they want to use the Tool. So this still makes sense, I think. sorry I have to correct myself...it *is* a core Tool by now. Anyway, please publish your changes on your scons_docbook fork and send a short note. Then I'll have a look and we can decide how to take it from there. Dirk ___ Scons-dev mailing list Scons-dev@scons.org http://two.pairlist.net/mailman/listinfo/scons-dev
Re: [Scons-dev] Documentation in EPUB-Format?
I wouldn't use the epub format personally, I almost always use the searchable HTML. But anything that allows for wider adoption is fine with me, especially if it's not much work. On Fri, Oct 4, 2013 at 8:56 AM, Dirk Bächle tshor...@gmx.de wrote: Hi devs, since we're now using DocBook as source format for all our documentation, it would technically be relatively easy to publish things like the MAN page or the UserGuide in EPUB format as well. The latest versions of pandoc ( 1.12.x) offer a DocBook reader and do a, more or less, good job in rendering the single markups. Find a shortened version of the UserGuide attached, as a first example... The question now is: Should we go this route? Then I'd try to integrate an ebook target into the build and bootstrapping process, such that EPUBs get created automatically if pandoc can be found on the current system. Note, how this would add a dependency to pandoc for all the ReleaseManagers...and this currently means installing the full Haskell platform package with approx 400MB. ;) Your comments? Best regards, Dirk ___ Scons-dev mailing list Scons-dev@scons.org http://two.pairlist.net/mailman/listinfo/scons-dev -- Gary ___ Scons-dev mailing list Scons-dev@scons.org http://two.pairlist.net/mailman/listinfo/scons-dev
Re: [Scons-dev] Documentation in EPUB-Format?
Hi Rob, On 05.10.2013 01:42, Managan, Rob wrote: I like the idea since I like ebooks. However, I will be honest and say that for code development I would not be too likely to use it since on my desktop machines I don't have a great epub viewers. it's more like for users starting with SCons and wanting to read more about it...wherever they go. ;) So I guess I would say that if there was no extra effort or file space required go ahead and add it but if the extra effort is noticeable don't bother. Okay, I'll give it a try. Should the EPUBs be just a side-effect of the doc build for now, or should they get archived in the different distribution packages too? Regards, Dirk ___ Scons-dev mailing list Scons-dev@scons.org http://two.pairlist.net/mailman/listinfo/scons-dev
Re: [Scons-dev] Documentation in EPUB-Format?
Dirk, How big are the ePub files? vs pdf.. -Bill On Sat, Oct 5, 2013 at 1:50 AM, Dirk Bächle tshor...@gmx.de wrote: Hi Rob, On 05.10.2013 01:42, Managan, Rob wrote: I like the idea since I like ebooks. However, I will be honest and say that for code development I would not be too likely to use it since on my desktop machines I don't have a great epub viewers. it's more like for users starting with SCons and wanting to read more about it...wherever they go. ;) So I guess I would say that if there was no extra effort or file space required go ahead and add it but if the extra effort is noticeable don't bother. Okay, I'll give it a try. Should the EPUBs be just a side-effect of the doc build for now, or should they get archived in the different distribution packages too? Regards, Dirk __**_ Scons-dev mailing list Scons-dev@scons.org http://two.pairlist.net/**mailman/listinfo/scons-devhttp://two.pairlist.net/mailman/listinfo/scons-dev ___ Scons-dev mailing list Scons-dev@scons.org http://two.pairlist.net/mailman/listinfo/scons-dev
[Scons-dev] Documentation in EPUB-Format?
Hi devs, since we're now using DocBook as source format for all our documentation, it would technically be relatively easy to publish things like the MAN page or the UserGuide in EPUB format as well. The latest versions of pandoc ( 1.12.x) offer a DocBook reader and do a, more or less, good job in rendering the single markups. Find a shortened version of the UserGuide attached, as a first example... The question now is: Should we go this route? Then I'd try to integrate an ebook target into the build and bootstrapping process, such that EPUBs get created automatically if pandoc can be found on the current system. Note, how this would add a dependency to pandoc for all the ReleaseManagers...and this currently means installing the full Haskell platform package with approx 400MB. ;) Your comments? Best regards, Dirk scons.epub Description: application/epub ___ Scons-dev mailing list Scons-dev@scons.org http://two.pairlist.net/mailman/listinfo/scons-dev
Re: [Scons-dev] Documentation in EPUB-Format?
I like the idea since I like ebooks. However, I will be honest and say that for code development I would not be too likely to use it since on my desktop machines I don't have a great epub viewers. So I guess I would say that if there was no extra effort or file space required go ahead and add it but if the extra effort is noticeable don't bother. Just my 2 cents worth. *-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*- Rob Managan email managan at llnl.gov LLNL phone: 925-423-0903 P.O. Box 808, L-095 FAX: 925-422-3389 Livermore, CA 94551-0808 On 10/4/13 5:56 AM, Dirk Bächle tshor...@gmx.de wrote: Hi devs, since we're now using DocBook as source format for all our documentation, it would technically be relatively easy to publish things like the MAN page or the UserGuide in EPUB format as well. The latest versions of pandoc ( 1.12.x) offer a DocBook reader and do a, more or less, good job in rendering the single markups. Find a shortened version of the UserGuide attached, as a first example... The question now is: Should we go this route? Then I'd try to integrate an ebook target into the build and bootstrapping process, such that EPUBs get created automatically if pandoc can be found on the current system. Note, how this would add a dependency to pandoc for all the ReleaseManagers...and this currently means installing the full Haskell platform package with approx 400MB. ;) Your comments? Best regards, Dirk ___ Scons-dev mailing list Scons-dev@scons.org http://two.pairlist.net/mailman/listinfo/scons-dev
