Some guys at PyAr are trans­lat­ing the python tu­to­ri­al to span­ish.

That tu­to­ri­al, like all the new python doc­s, us­es sphinx.

Since sphinx is very pop­u­lar, I want rst2pdf to work as well as pos­si­ble as Sphinx's PDF pro­duc­er. So, two dif­fer­ent things itch­ing, I start­ed scratch­ing.

Well, progress has been made. While the sphinx changes cur­rent­ly re­side on­ly on my com­put­er, I will pub­lish them soon, and the rst2pdf changes are al­ready com­mit­ted.

Here's a sam­ple to whet your ap­petite.

As of to­day, rst2pdf sup­ports Chris Liechti's awe­some aafig­ure.

What does it mean? It means you can put this in your doc­u­men­t:

+-------+       +-------+
|   A   |------>|   B   |
+-------+       +-------+

And get this (and as a PDF draw­ing, not as an im­age, so you can copy the text from it):

So it's an awe­some way to add sim­ple di­a­grams to your re­struc­tured text doc­u­ments that look good in plain tex­t, on the we­b, and on PDF.

Aafig­ure can cre­ate lots of in­ter­est­ing draw­ings, check their docs for ex­am­ples here

It cur­rent­ly re­quires aafig­ure from bzr (0.3 won't work).

It's my plea­sure to an­nounce the re­lease of rst2pdf ver­sion 0.11, avail­able at http://­code.­google.­com/p/rst2pdf/­down­load­s/list

Rst2pdf is a tool to gen­er­ate PDF files di­rect­ly from re­struc­tured text sources via re­port­lab.

This ver­sion in­cludes many bug­fix­es and some new fea­tures com­pared to the pre­vi­ous 0.10.1 ver­sion, in­clud­ing but not lim­it­ed to em­bed­ding PDF im­ages, much im­proved im­age siz­ing, nicer list lay­out­s, bet­ter styling, page back­ground­s, and more than 15 bugs fixed. A full changel­og is in­clud­ed at the bot­tom of this mes­sage.

Rst2pdf aims to sup­port the full re­struc­tured text fea­ture set, and is very close to that goal, while al­so in­clud­ing some of the more ex­per­i­men­tal fea­tures, like a source code di­rec­tive with syn­tax high­light­ing and math no­ta­tion sup­port with La­TeX-­like syn­tax.

It sup­ports em­bed­ding ar­bi­trary fonts, both True Type and PS Type 1, both raster and vec­tor im­ages (in­clud­ing SVG), page tran­si­tion ef­fect­s, mul­ti­ple, flex­i­ble page lay­out­s, cas­cad­ing styles, and much, much more.

You can find more in­for­ma­tion about rst2pdf in its home page ( http://rst2pdf.­google­code.­com), and ask any­thing you want in the rst2pdf- dis­cuss mail­ing list (http://­group­s.­google.­com/­group/rst2pdf-dis­cuss)

Here are the changes in this ver­sion com­pared to 0.10.1:

• De­­grade more grace­­ful­­ly when one or more wor­­daxe hy­phen­a­tors are bro­ken (cur­ren­t­­ly DWC is the bro­ken one)

• Fixed is­­sue 132: in some cas­es, with user-de­fined fontAl­i­as, bold and ital­ic would get con­­fused (get­t­ing ital­ic in­­stead of bold in in­­­line markup, for in­­s­tance).

• New stylesheet no-­­com­­pact-lists to make list­s... less com­­pact

• SVG im­ages now han­­dle % as a width unit cor­rec­t­­ly.

• Im­­ple­­men­t­ed is­­sue 127: sup­­port im­ages in PDF for­­mat. Right now they are ras­ter­ized, so it's not ide­al. Per­haps some­thing bet­ter will come up lat­er.

• Fixed is­­sue 129: make it work around a prblem with Keep­­­To­geth­­er in RL 2.1 it prob­a­bly makes the out­­put look worse in some cas­es when us­ing that. RL 2.1 is not re­al­­ly sup­­port­ed, so added a warn­ing.

• Fixed is­­sue 130: use os­­.­­path­sep in­­stead of ":" since ":" in win­­dows is used in disk names (and we still pay for DOS id­io­­cy, in 2009)

• Fixed is­­sue 128: head­­ings lev­­el 3+ all looked the same

• Ug­­ly bug­­fix for Is­­sue 126: crash­es when us­ing im­ages in head­­er + TOC

• New tstyles sec­­tion in the stylesheet pro­­vides more con­­fig­urable list lay­outs and more pow­er­­ful ta­ble styling.

• Bet­ter syn­­tax high­­­light­ing (sup­­ports bold/i­­tal­ic)

• Work­around for is­­sue 103 so you can use bor­der­­Padding as a list (but it will look wrong if you are us­ing wor­­daxe <= 0.3.2)

• Added field­­­val­ue style for field lists

• Added op­­tion­list tstyle, for op­­tion lists

• Added col­lec­­tion of util­i­­ty stylesheets and doc­u­­men­t­ed it

• Im­proved com­­mand line pars­ing and stylesheet load­­ing (guess ex­ten­­sion like lat­est rst2la­­tex does)

• Fixed Is­­sue 67: com­­plete­­ly new list lay­out­ing code

• Fixed Is­­sue 116: crash­es caused by huge im­ages

• Bet­ter sup­­port for %width in im­ages, n2ow it's % of the con­­tain­er frame's width, not of the text area.

• Fixed bug in SVG scal­ing

• Bet­ter han­dling of mis­s­ing im­ages

• Added mis­s­ing styles ab­s­trac­t, con­­tents, ded­i­­ca­­tion to the de­­fault stylesheet

• Ta­bles style sup­­port space­Be­­fore and spaceAfter

• New top­ic-ti­­tle style for top­ic ti­­tles (ob­vi­ous ;-)

• Ver­ti­­cal align­­ment for in­­­line im­ages (:align: pa­ram­e­ter)

• Is­­sue 118: Sup­­port for :s­­cale: in im­ages and han­­dle re­­siz­ing of in­­­line im­ages

• Is­­sue 119: Fix place­­ment of head­­ers and foot­ers

• New back­­­ground prop­er­­ty for page tem­­plates (nice for pre­sen­­ta­­tion­s, for ex­am­­ple)

• De­­fault to px for im­age width spec­i­­fi­­ca­­tions in­­stead of pt

• Sup­­port all re­quired mea­­sure­­ment units ("em" "ex" "px" "in" "cm" "m­m" "p­t" "pc" "%" "")

• New au­­to­­mat­ed scripts to check test cas­es for "vi­­su­al dif­fer­­ences"

• Re­spect im­ages DPI prop­er­­ty a bit like rst2la­­tex does.

• Is­­sue 110: New --in­­line-­­foot­notes op­­tion

• Test­ed with re­­port­lab from SVN trunk

• Sup­­port for Dinu Gher­­man's svglib. If both svglib and uni­­con­ver­­tor are avail­able, svglib is pre­­ferred (for SVG, of course). Patch orig­i­­nal­­ly by rute.

• Is­­sue 109: Sep­a­rate styles for each kind of ad­­mo­ni­­tion

• For Is­­sue 109: mis­s­ing styles are not a fa­­tal er­ror

• Is­­sue 117: TOCs with more than 6 lev­­els now sup­­port­ed (raised lim­it to 9, which is sil­­ly deep)

Since the last re­lease, there have been many changes, im­prove­ments and fix­es in rst2pdf.

At the bot­tom of this post you will find (maybe in­com­plete) list, but I want­ed to share a cou­ple of rel­a­tive­ly large ad­vances.

Pre­sen­ta­tions

I have want­ed to make rst2pdf use­ful for pre­sen­ta­tions for quite a while. And now it's get­ting close.

I am writ­ing a small tu­to­ri­al about it, but you can see a de­mo al­ready.

The changes that make this pos­si­ble are:

• Fixed bugs re­­gard­ing page lay­out

• Added sup­­port for page back­­­grounds (in­­clud­ing SVG!)

This was in large part be­cause of César Ro­das, who want­ed some­thing sim­ple and tex­t-based to do his Zend­Con pre­sen­ta­tion, so he asked me about it, and I was ashamed to give him a bro­ken tool.

See how that work­s? I am driv­en by em­bar­rass­men­t. That's em­bar­ras­ing.

Ma­jor stylesheet im­prove­ments

The re­lat­ed changes are way too many (see be­low), but it al­so hap­pened for a rea­son: I want­ed to make pret­ti­er doc­u­ments.

So, since most peo­ple seems to like Sphinx's style, I want­ed to look sim­i­lar.

Did I achieve it? Yes and no, take a look:

But it's just a draft, I did­n't look at fonts, or weight of the head­ings, or even at what pyg­ments col­or scheme sphinx is us­ing.

But any­way, even this rough stylesheet made me find a dozen bugs or prob­lems in rst2pdf.

So, the main les­son here is, please tell me what you can and can't do with rst2pdf, be­cause there are whole ar­eas I am not even look­ing at, day-­to-­day.

The fi­nal thing is... the next re­lease is go­ing to be awe­some. But then again, I al­ways say that, don't I?

Changes as of to­day:

• Work­around for is­­sue 103 so you can use bor­der­­Padding as a list (but it will look wrong if you are us­ing wor­­daxe <= 0.3.2)

• Added field­­­val­ue style for field lists

• Added op­­tion­list tstyle, for op­­tion lists

• Added col­lec­­tion of util­i­­ty stylesheets and doc­u­­men­t­ed it

• Im­proved com­­mand line pars­ing and stylesheet load­­ing (guess ex­ten­­sion like lat­est rst2la­­tex does)

• Fixed Is­­sue 67: com­­plete­­ly new list lay­out­ing code

• Fixed Is­­sue 116: crash­es caused by huge im­ages

• Bet­ter sup­­port for %width in im­ages, n2ow it's % of the con­­tain­er frame's width, not of the text area.

• Fixed bug in SVG scal­ing

• Bet­ter han­dling of mis­s­ing im­ages

• Added mis­s­ing styles ab­s­trac­t, con­­tents, ded­i­­ca­­tion to the de­­fault stylesheet

• Ta­bles style sup­­port space­Be­­fore and spaceAfter

• New top­ic-ti­­tle style for top­ic ti­­tles (ob­vi­ous ;-)

• Ver­ti­­cal align­­ment for in­­­line im­ages (:align: pa­ram­e­ter)

• Is­­sue 118: Sup­­port for :s­­cale: in im­ages and han­­dle re­­siz­ing of in­­­line im­ages

• Is­­sue 119: Fix place­­ment of head­­ers and foot­ers

• New back­­­ground prop­er­­ty for page tem­­plates (nice for pre­sen­­ta­­tion­s, for ex­am­­ple)

• De­­fault to px for im­age width spec­i­­fi­­ca­­tions in­­stead of pt

• Sup­­port all re­quired mea­­sure­­ment units ("em" "ex" "px" "in" "cm" "m­m" "p­t" "pc" "%" "")

• New au­­to­­mat­ed scripts to check test cas­es for "vi­­su­al dif­fer­­ences"

• Re­spect im­ages DPI prop­er­­ty a bit like rst2la­­tex does.

• Is­­sue 110: New --in­­line-­­foot­notes op­­tion

• Test­ed with re­­port­lab from SVN trunk

• Sup­­port for Dinu Gher­­man's svglib. If both svglib and uni­­con­ver­­tor are avail­able, svglib is pre­­ferred (for SVG, of course). Patch orig­i­­nal­­ly by rute.

• Is­­sue 109: Sep­a­rate styles for each kind of ad­­mo­ni­­tion

• For Is­­sue 109: mis­s­ing styles are not a fa­­tal er­ror

• Is­­sue 117: TOCs with more than 6 lev­­els now sup­­port­ed (raised lim­it to 9, which is sil­­ly deep)

So, rst2pdf 0.10 was not ok. The set­up.py that worked on 0.9 sim­ply did­n't work for the new ver­sion.

Good thing is, Christoph ac­tu­al­ly un­de­stands se­tup­tool­s, so he could fix it and de­liv­er a neat 0.10.1 for your PDF-­gen­er­at­ing plea­sure.

Post 0.10.1, I have al­ready fixed one bug, Is­sue 117.