Publishing an O'Reilly book with AsciiDoc
Noah Slater
Firstly, sorry for the amount of questions I've been asking recently, I don't
mean to dominate the mailing list. I have been working on a book for O'Reilly
Media on Apache CouchDB. The book uses AsciiDoc for its source files and we
transform into HTML for the Web and DocBook for O'Reilly.
http://books.couchdb.org/relax/
The book and our build system are still under heavy development (so expect more
questions, heh) but we will release our code when the book gets published.
Many thanks to Stuart for his continued help and patience.
--
Noah Slater, http://tumbolia.org/nslater
Miklos Vajna
> Media on Apache CouchDB. The book uses AsciiDoc for its source files and we
> transform into HTML for the Web and DocBook for O'Reilly.
>
> http://books.couchdb.org/relax/
It would be interesting what software will you use for the figures.
One of my favorites in asciidoc's features is that i can produce both
nice html and pdf output from the same source (recently even for math
formulas in most cases).
http://udrepper.livejournal.com/19751.html <- I read here about
MetaPost, the small pdf size sounds promising, though I have no idea if
it's possible to somehow get it to produce some picture output as well
for html.
So, how do the others draw figures in asciidoc? (Let's exclude asciiart
and/or hand-drawn graphics, I'm far better in programming than in
drawing. :) )
Noah Slater
> On Mon, Dec 08, 2008 at 11:28:08PM +0000, Noah Slater <nsl...@tumbolia.org> wrote:
> > Media on Apache CouchDB. The book uses AsciiDoc for its source files and we
> > transform into HTML for the Web and DocBook for O'Reilly.
> >
> > http://books.couchdb.org/relax/
>
> It would be interesting what software will you use for the figures.
Well, as you can see, at the moment we are using hand drawings and scanning them
in. Our O'Reilly designers will be taking care of converting these into
professional illustrations.
> One of my favorites in asciidoc's features is that i can produce both nice
> html and pdf output from the same source (recently even for math formulas in
> most cases).
Yes, for us - we have a special O'Reilly repository that we can check our
DocBook into and it will spit out nicely formatted PDFs. If I could convince
them to make this hidden tool-chain free software, that would be so amazing. Not
going to happen though. Heh.
> http://udrepper.livejournal.com/19751.html <- I read here about MetaPost, the
> small pdf size sounds promising, though I have no idea if it's possible to
> somehow get it to produce some picture output as well for html.
Have you since PrinceXML?
Unfortunately non-free software. I have had an interesting, and very reasonable,
discussion with them about making this free software. The summary was that they
could not viably afford to right now, but if this became a financial possibility
it would be an option they would strongly consider.
> So, how do the others draw figures in asciidoc? (Let's exclude asciiart and/or
> hand-drawn graphics, I'm far better in programming than in drawing. :) )
Have you seen this:
http://www.websequencediagrams.com/
Unfortunately, this is a hosted service with no source code.
An example can be seen here:
http://tomayko.com/writings/things-caches-do
A good, and very popular, free software alternative is GraphViz.
Thanks,
Bill Harris
Hash: SHA1
Noah Slater <nsl...@tumbolia.org> writes:
> Firstly, sorry for the amount of questions I've been asking recently, I don't
> mean to dominate the mailing list. I have been working on a book for O'Reilly
> Media on Apache CouchDB. The book uses AsciiDoc for its source files and we
> transform into HTML for the Web and DocBook for O'Reilly.
I'll admit that I was a bit curious about the detailed level of your
questions, for I've viewed asciidoc as a nifty way to generate nicely
formatted, lightweight text (I use it regularly for a set of client
reports, for example). I have used DocBook for producing heavier-weight
text in the past (for example, documentation for another client
project), and I had considered the two separately and viewed asciidoc's
DocBook output as a convenient step in the process of generating PDF.
Thanks to your comments, I now see that line is rather blurry. I'm
impressed that you can generate what you need for a book with asciidoc
markup, and I'll think more seriously about this use in the future.
Just curious: is your permanent source the asciidoc source, or are you
using it in a first-pass creation mode and then following up by editing
the xml? And is there an equivalent to xincludes in asciidoc?
Bill
- --
Bill Harris http://facilitatedsystems.com/weblog/
Facilitated Systems Everett, WA 98208 USA
http://facilitatedsystems.com/ phone: +1 425 337-5541
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
iEYEARECAAYFAkk+kc8ACgkQ3J3HaQTDvd/aeQCbBMChHkAoPlrZm9F4+0SMczKp
ZeYAniRKmn0c1GWOVXnExzjHLQwufY6Q
=o6zX
-----END PGP SIGNATURE-----
Noah Slater
> I'll admit that I was a bit curious about the detailed level of your
> questions, for I've viewed asciidoc as a nifty way to generate nicely
> formatted, lightweight text (I use it regularly for a set of client reports,
> for example). I have used DocBook for producing heavier-weight text in the
> past (for example, documentation for another client project), and I had
> considered the two separately and viewed asciidoc's DocBook output as a
> convenient step in the process of generating PDF.
Ah, yes. I'm also trying to make a general purpose AsciiDoc build system along
with the book and release this as free software when we're done. Problems that I
might have been able to bodge around with a configuration hack are much more
tempting for me to "get right" by bugging Stuart on the mailing list. Heh.
> Thanks to your comments, I now see that line is rather blurry. I'm impressed
> that you can generate what you need for a book with asciidoc markup, and I'll
> think more seriously about this use in the future.
Great, I would consider that a great result. Once we're closer to releasing the
book I will add a colophon or similar so that people can point at it and
recommend AsciiDoc for larger projects too. I was chatting with the guys doing
the Scala book for O'Reilly, and they loved it, so I would be surprised if we
were the last folks to use AsciiDoc for this.
> Just curious: is your permanent source the asciidoc source, or are you using
> it in a first-pass creation mode and then following up by editing the xml?
Aside from a quick once over with xmllint to check against the O'Reilly
recommended DocBook DTD we don't do any post-processing on the DocBook or
HTML. My build system will do post-processing, but only to add metadata. The
AsciiDoc core is more than sufficient for generating correct content markup.
> And is there an equivalent to xincludes in asciidoc?
Yes, see § 17.3.1. Include Macros:
http://www.methods.co.nz/asciidoc/userguide.html#X63
Best,
Bill Harris
Hash: SHA1
Noah Slater <nsl...@tumbolia.org> writes:
> Great, I would consider that a great result. Once we're closer to
> releasing the book I will add a colophon or similar so that people can
> point at it and recommend AsciiDoc for larger projects too.
Thanks; that would be great.
>> And is there an equivalent to xincludes in asciidoc?
>
> Yes, see § 17.3.1. Include Macros:
>
> http://www.methods.co.nz/asciidoc/userguide.html#X63
Great; thanks.
Bill
- --
Bill Harris http://facilitatedsystems.com/weblog/
Facilitated Systems Everett, WA 98208 USA
http://facilitatedsystems.com/ phone: +1 425 337-5541
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
iEYEARECAAYFAkk+oNoACgkQ3J3HaQTDvd9f1QCfQEKYugKJYbRANuS1FY38RtOy
KsQAmwdOPIaW2OgMWR3zZ6rmbva/gDls
=J8ob
-----END PGP SIGNATURE-----
Miklos Vajna
> > http://books.couchdb.org/relax/
>
> It would be interesting what software will you use for the figures.
>
> One of my favorites in asciidoc's features is that i can produce both
> nice html and pdf output from the same source (recently even for math
> formulas in most cases).
>
> http://udrepper.livejournal.com/19751.html <- I read here about
> MetaPost, the small pdf size sounds promising, though I have no idea if
> it's possible to somehow get it to produce some picture output as well
> for html.
OK, I played with it a bit, and it looks very impressive.
There are many tutorials here:
http://www.tug.org/metapost.html
I just picked one (http://www.ursoswald.ch/metapost/tutorial.html) and
based on that I tried to see how hard is to create something like
http://frugalware.org/images/logo-new.png
I put out the .mp file, the Makefile and the result to:
http://git.frugalware.org/repos/vmexam/metapost/
Sort of ugly, but that's already far better than doing it with gimp or
other such tool which requires manual skill. ;-)
Lionel
On 14 déc, 08:04, Lionel <lionel.o...@gmail.com> wrote:
> On 9 déc, 13:45, Miklos Vajna <vmik...@frugalware.org> wrote:
using a nice program I used to first draw electronics schematics,
called XCircuit. This is a general purpose schematic drawing app, that
uses PostScript language directly (means that PS is the *native* file
format of the app. You save PS files, you open PS files) and it is
really powerful and helps me to draw a diagram in no time, because of
many keyboard shortcuts. It is somewhat cross-platform (written in Tcl/
Tk), a windows version exists. Here are some links if you want to try:
HomePage: http://www.opencircuitdesign.com/xcircuit/
Windows Port: http://www.geocities.com/sw286000/
I recommend the following download for Windows:
http://www.geocities.com/sw286000/xcircuit-3.6.115-setup.zip
If you try it, I'm sure you can get addicted quite easily.
About HTML, I believe ghostscript + imagemagick (convert -resize
<new_size> foo.eps foo.png) does a good job to produce web-oriented
picture format. I don't know how this could be integrated in Asciidoc
though.... Is the a way to filter some input formats so that you use
EPS for Docbook generation and automatically generated PNG for html?
Have fun.
Lionel
>
>
> > application_pgp-signature_part
> > < 1 000AfficherTélécharger
Miklos Vajna
> It may sound odd, but each time I have to draw diagrams, I end up
> using a nice program I used to first draw electronics schematics,
> called XCircuit. This is a general purpose schematic drawing app, that
> uses PostScript language directly (means that PS is the *native* file
> format of the app. You save PS files, you open PS files) and it is
> really powerful and helps me to draw a diagram in no time, because of
> many keyboard shortcuts. It is somewhat cross-platform (written in Tcl/
> Tk), a windows version exists. Here are some links if you want to try:
>
> HomePage: http://www.opencircuitdesign.com/xcircuit/
>
> Windows Port: http://www.geocities.com/sw286000/
> I recommend the following download for Windows:
> http://www.geocities.com/sw286000/xcircuit-3.6.115-setup.zip
>
> If you try it, I'm sure you can get addicted quite easily.
Looks interesting.
> About HTML, I believe ghostscript + imagemagick (convert -resize
> <new_size> foo.eps foo.png) does a good job to produce web-oriented
> picture format. I don't know how this could be integrated in Asciidoc
> though.... Is the a way to filter some input formats so that you use
> EPS for Docbook generation and automatically generated PNG for html?
You can write a Makefile to do this for you, then define a
backend-dependent 'picture' (or similar) macro which includes the
postscript for dblatex and the png for html.
BTW, did you manage to include postscript in a pdf using
asciidoc/dblatex?
asciidoc's pass macro lets you put anything to the docbook xml, but I
have no idea how to put the '\includegraphics{test.ps}' (where file.ps
is a postscript output) to the docbook xml.
Thanks.
Stuart Rackham
http://www.methods.co.nz/asciidoc/music-filter.html
provides a model, it converts ABC notation to a PNG image which is
linked to the output document.
Cheers, Stuart
Lionel
On 16 déc, 20:54, Miklos Vajna <vmik...@frugalware.org> wrote:
FOP (it seems you use dblatex, in this case I don't know).
Since the EPS inclusion in PDF output is deprecated in current FOP
versions, the best way to achieve this is to:
- convert the eps to pdf (epstopdf does a good job, bounding boxes are
kept, etc.)
- use an add-on for fop that permits inclusion of PDF files directly.
This add-on can be found here: http://www.jeremias-maerki.ch/development/fop/index.html
Here is what I did:
1. I downloaded the add-on in binary versions
2. I copied the 3 jars from the add-on in /usr/share/java (I use
Fedora Linux)
3. I added the following line to /etc/fop.conf so that the add-on is
used:
CLASSPATH=$CLASSPATH:/usr/share/java/fop-pdf-images-1.3.jar:/
usr/share/java/fop-pdf-images-1.3-res.jar:/usr/share/java/PDFBox-0.7.4-
dev.jar
4. I called epstopdf (this task should be done in a filter, like
Stuart explained. For now, I do it manually):
epstopdf --nocompress diagram.eps
5. I used in my asciidoc source file:
image::diagram.pdf["Important Diagram",scaledwidth="50%"]
6. I used my usual 'asciidoc -b docbook' then 'xsltproc' then 'fop'
toolchain
And I got a nice pdf output with my diagram included !
Once I get correct filters to generate pdf and png from eps, that will
be quite easy to use. The only drawback is to install the add-on, and
it seems most distributions don't care about this one so it must be
done manually.
I hope this helps...
Lionel
> Thanks.
>
> application_pgp-signature_part
> < 1 000AfficherTélécharger
Miklos Vajna
> I made some researches about that. I personally use xsl stylesheets +
> FOP (it seems you use dblatex, in this case I don't know).
Yes, you are right.
Thank you for the tutorial. :-)
(At the moment it's not that interesting for me, but I'm sure it's
useful for other FOP users and maybe one day I'll need it.)
andrewsavikas
> Yes, for us - we have a specialO'Reillyrepositorythat we can check our
> them to make this hidden tool-chain free software, that would be so amazing. Not
> going to happen though. Heh.
software. We build our PDFs by using an (admittedly complex)
customization layer on top of the open source DocBook XSL stylesheets
(http://www.sagehill.net/docbookxsl/), triggered by some post-commit
hooks within Subversion. Actual PDF generation (from the XSL-FO
output) is done with AntennaHouse.
We also use the DocBook XSL stylesheets to output EPUB ebook format
(see oreilly.com/ebooks), and alongside Adobe contributed engineering
resources to build those EPUB stylesheets into the package.
HTH,
Andrew Savikas
VP, Digital Initiatives
O'Reilly Media, Inc.
http://toc.oreilly.com