To­day I start­ed a branch called Smart­Frames. The main goal is to achieve a bet­ter text flow in the doc­u­ment (for ex­am­ple, for side­bars), and it is start­ing to get there, slow­ly.

Let's con­sid­er how ReST side­bars are ren­dered in the dif­fer­ent writ­er­s.

We'll work with an or­di­nary lorem ip­sum that has a side­bar de­clared just be­fore it.

Here's HTM­L:

And here's La­TeX:

Each one has its good side and its bad side.

The HTML side­bar is a re­al side­bar, while the La­Tex one is some sort of in­sert.

OTO­H, the ragged text against the HTML side­bar is ... hor­rid.

So, I want­ed some­thing at least a bit bet­ter than that for rst2pdf. In the best of all pos­si­ble world­s, it would be the neat text align­ment of La­Tex with the float­ing HTML side­bar.

Here's how it looks now:

There are some mi­nor prob­lems with the cur­rent im­ple­men­ta­tion, such that the side­bar is al­ways aligned to the top of a para­graph, and some spac­ing is­sues.

How is it done? Let me tell you: it was not triv­ial :-)

In fact it's pret­ty evil, but here's a quick ex­pla­na­tion:

When I get a side­bar flow­able, I in­sert a new frame in the page tem­plate where the side­bar should go, then call a frame­break, in­sert the "re­al" side­bar, a "frame­cut­ter" and an­oth­er frame­break.

The frame­cut­ter is a flow­able that does noth­ing vis­i­ble, but in­serts an­oth­er two frames, one at the right of the side­bar with the same height, and an­oth­er be­low the side­bar, full width.

I need to use the frame­cut­ter be­cause I don't know the height of the side­bar un­til af­ter it's drawn.

So, we now have 4 frames in­stead of one:

1. The orig­i­­nal frame, cov­­ers the whole page, but has a frame­break above the side­bar.

2. The side­bar frame, which is very tal­l, but has a frame­break be­low the side­bar tex­t.

3. A beside-the-side­bar frame, short and wide, start­ing at the right of the side­bar.

4. A be­low-the-side­bar frame, wide and tal­l, start­ing be­low the side­bar.

The text should flow from 1 to 3 to 4 neat­ly and the seams should­n't show.

Here's a pic­ture that MAY make it clear (there are some odd dis­place­ments: those were bugs):

So, I'm not call­ing it a suc­cess yet, but it is look­ing de­cen­t.

Many new fea­tures. Cus­tom page lay­out­s! Mul­ti­ple frames per page! Mul­ti­ple lay­outs per doc­u­men­t! Cas­cad­ing stylesheet­s! Not very bug­gy! Get it at http://rst2pdf.­google­code.­com or via PyP­I.

How good? Let me tell you...

• Sup­­port for PDF ta­ble of con­­tents

• Sec­­tion names and num­bers in head­­er­s/­­foot­ers

• Com­­pressed PDFs (or not)

• Guess im­age sizes. Spe­­cial­­ly if you meant to use them in a web page and de­­clared just ":width: 50%"

• Gut­ter mar­­gin sup­­port

• Raw di­rec­­tive (in­sert page­breaks and ver­ti­­cal space man­u­al­­ly)

• Of­fers a do­cu­til­s-­­com­­pli­ant API (and an­oth­er API, too)

• In­­­clude full or par­­tial files for code-block. That means you can ex­­tract code and show it in your doc­u­­men­t!

• Huge code cleanup lead by Nico­las Lau­rance.

• Work­ing mul­ti­lin­gual hy­phen­a­tion. You can have a per-­­para­­graph lan­guage and hy­phen­ate it cor­rec­t­­ly.

I am a big Alexan­dre Du­mas fan. He's the di­rect an­ces­tor of Neal Stephen­son, so many of you should like him too. So I used one of his best books to try some au­to­mat­ic type­set­ting of project guten­berg texts.

No, the whole book did not con­vert with­out er­rors, and yes, there is some man­u­al work in what you are about to see, but hey, take a look.

Here's a far look of the first two pages:

And here's some de­tail of the typset­ting:

Yes, the type­set­ting is not re­al­ly La­TeX qual­i­ty, but it's not bad, ei­ther.

Com­pare it with the HTML ver­sion at project Guten­berg. The type­set­ting is a thing of beau­ty com­pared to that :-(

The im­age is a pic­ture of Chateau d'If from flick­r, re­leased un­der Cre­ative Com­mon­s. The ti­tle font is Scripti­na, I chose it be­cause it looks 19th cen­tu­ry but mod­ern.

I did a re­lease yes­ter­day, and an­oth­er to­day of my rst-­to-pdf-with­out-la­tex tool. What's new? Here's an in­com­plete list:

New in 0,4

• Fixed bul­let and item lists in­­­den­­ta­­tion/nest­ing.

• Im­­ple­­men­t­ed ci­­ta­­tions

• Work­ing links be­tween foot­notes and its re­f­er­ences

• Jus­ti­­fi­­ca­­tion en­abled by de­­fault

• Fixed ta­ble bug (de­­mo.txt works now)

• Ti­­tle and au­thor sup­­port in PDF prop­er­ties

• Sup­­port for doc­u­­ment ti­­tle in head­­er/­­foot­er

• Cus­­tom page sizes in stylesheet

New in 0.3

• Font em­bed­d­ing (use any True Type font in your PDF­s)

• Syn­­tax high­­­lighter us­ing Pyg­­ments

• User's man­u­al

• Ex­ter­­nal/­­cus­­tom stylesheets

• Sup­­port for page num­bers in head­­er/­­foot­er

Of course, since I said I would re­lease some­thing ev­ery fri­day, this means I need to find some­thing else to re­lease? ;-)