Skip to main content

Ralsina.Me — Roberto Alsina's website

Posts about programming (old posts, page 51)

AAFigure in rst2pdf

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):

/static/aafigure.png

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).

Rst2pdf 0.11 released!

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)

rst2pdf progress report

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:

web-sphinx rst2pdf-sphinx

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)

Sorry about rst2pdf 0.10, have some 0.10.1 instead.

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.

Released rst2pdf 0.10!

Af­ter 8 months (!) it's fi­nal­ly out: rst2pdf 0.10 ready for down­load­ing from its home­page.

If you don't know what I'm talk­ing about, rst2pdf lets you cre­ate PDF files from a sim­ple, very light­ly marked pure text for­mat called re­struc­tured text and is the eas­i­est way to cre­ate nice doc­u­men­ta­tion for your free soft­ware project and more!

Here is the man­u­al which is cre­at­ed us­ing rst2pdf it­self from this.

And here's a (maybe par­tial) list of the changes, which should con­vince you that you re­al­ly want this ver­sion:

  • Is­­sue 87: Ta­ble head­­ers can be re­­peat­ed in each page (thanks to Ya­­sushi Ma­­su­­da)

  • Is­­sue 93: Line num­ber sup­­port for code blocks (:­li­­nenos: true)

  • Is­­sue 111: Added --no-­­foot­note-back­­links op­­tion

  • Is­­sue 107: Sup­­port lo­­cal­ized di­rec­­tives/roles (ex­am­­ple: som­­maire in­­stead of con­­tents)

  • Is­­sue 112: Fixed crash when pro­cess­ing em­p­­ty list items

  • Is­­sue 98: No­break sup­­port, and set as de­­fault for in­­­line-l­it­er­als so they don't hy­phen­ate.

  • Slight­­ly bet­ter tests

  • Back­­­ground col­ors in text styles work with re­­port­lab 2.3

  • Is­­sue 99: Fixed hy­phen­a­tion in head­­er­s/­­foot­ers (re­quires wor­­daxe 0.3.2)

  • Is­­sue 106: Crash on de­­mo.txt fixed (re­quires wordxe 0.3.2)

  • Is­­sue 102: Im­­ple­­men­t­ed styles for bul­let­ed and num­bered lists

  • Is­­sue 38: De­­fault head­­er­s/­­foot­ers via op­­tion­s, con­­fig file or stylesheet

  • Is­­sue 88: Im­­ple­­men­t­ed much bet­ter book-style TOCs

  • Is­­sue 100: Fixed bug with head­­er­s/­­foot­ers and Re­­port­lab 2.3

  • Is­­sue 95: Fixed bug with in­­­den­t­ed ta­bles

  • Is­­sue 89: Im­­ple­­men­t­ed --ver­­sion

  • Is­­sue 84: Fixed bug with rel­a­­tive in­­­clude paths

  • Is­­sue 85: Fixed bug with ta­ble cell styles

  • Is­­sue 83: Fixed bug with nu­mer­ic col­ors in back­­­Col­or at­tribute

  • Is­­sue 44: Sup­­port for stdin and std­out

  • Is­­sue 79: Added --stylesheet-­­path op­­tion

  • Is­­sue 80: Send warn­ings to stder­r, not std­out

  • Is­­sue 66: Im­­ple­­men­t­ed "s­­mart quotes"

  • Is­­sue 77: Work around mis­s­ing mat­­plotlib

  • Prop­er tran­s­la­­tion of la­­bels (such as "Au­thor", "Ver­­sion" etc.) us­ing the do­cu­tils lan­guages pack­­age. (r473)

  • Fixed prob­lems with wrong or non-ex­ist­ing fonts. (r484)

  • Page tran­si­­tion ef­­fect sup­­port for pre­sen­­ta­­tions (r423)


Contents © 2000-2020 Roberto Alsina