Skip to main content

Ralsina.Me — Roberto Alsina's website

rst2pdf: What will be new tomorrow

Keep­ing with my new time-based re­lease sched­ule, to­mor­row is again rst2pdf re­lease day! What will be new in 0.7? Sev­er­al things!

  • Fixed sev­er­al se­ri­ous bugs, spe­­cial­­ly with the han­dling of lit­er­al blocks (pre­­for­­mat­t­eds and code block­­s).

  • Im­­ple­­men­t­ed a rather neat side­bar/float­ing block mech­a­nis­m. It on­­ly lets you go float-left or float-right but it looks bet­ter than what you get in HT­M­L, at least:

sidebar-beige

You can even use it to float al­most ar­bi­trary ob­ject­s, so you can have float­ing im­ages or float­ing fig­ures.

  • Fixed the look of hy­per­links. Re­­port­lab had a bug about mak­ing some hy­per­links un­der­­lined, and those with a black thick un­der­­line. Not when you use rst2pdf! Mon­key-­­patched the heck out of that.

  • Ta­ble styling. Let me show you:

rst2pdf-tablestyles

The first row is a head­er row. It au­to­mat­i­cal­ly takes the table-­head­ing style.

The fol­low­ing rows are reg­u­lar, and they take the ta­ble style, which has sup­port for ze­bra ta­bles with al­ter­nat­ing col­ors (white and gray here).

The lone red cell at the right is spe­cial. Its con­tent is this:

.. class:: red

red

If you don't know ReST, that means "red" is a para­graph with class red, so it will be styled what­ev­er way that means (here: red back­ground).

Usu­al­ly that would mean you have a white (or gray) cell with a red para­graph in it. That looks in­cred­i­bly ug­ly.

So, rst2pdf tries to be clev­er: If there is a sin­gle el­e­ment in a cel­l, it will try to guess the cell back­ground from it.

And as you saw above, it works :-)

rst2pdf: progress in smartframe branch

Yes, it is get­ting bet­ter. Now there are left­-float­ing or right-float­ing el­e­ments, and you can float pret­ty much any­thing (ex­cept lit­er­al block­s, that's a prob­lem) by us­ing the class di­rec­tive. Here's how it look­s:

sidebar-beige

rst2pdf: smartframes branch

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:

sidebar-html

And here's La­TeX:

sidebar-latex

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:

sidebar-pdf2

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

sidebar-wires

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

rst2pdf is going to be one day late. But there's a good reason.

Be­sides ev­ery­thing I men­tioned yes­ter­day, to­day I im­ple­ment­ed two rather im­por­tant fea­tures: cas­cad­ing stylesheet­s, and user-de­fined page lay­out­s. Here is a screen­shot:

montecristo-3

That neat two-­col­umn lay­out is done by adding this to the stylesheet:

"pageTemplates" : {
  "firstPage": {
      "frames": [
          ["0cm", "0cm", "49%", "100%"],
          ["51%", "0cm", "49%", "100%"]
      ]
  }
},

The name "first­Page" is mag­i­cal right now, and there's no way to change from one tem­plate to an­oth­er (yet), and un­til I do that, I won't be re­leas­ing.

Here's what cas­cad­ing stylesheets does. Sup­pose you want to use A5 pa­per and size 12 Times New Ro­man fonts? Here's all the stylesheet you need:

{
  "pageSetup" : {
    "size": "A5",
  },
  "fontsAlias" : {
    "stdFont": "Times-Roman",
  },
  "styles" : [
    ["base" , {
      "fontSize": 14,
      "leading": 16
    }]
  ]
}

Al­so, you can spec­i­fy as many stylesheets as you want in the com­mand line. So you can have one that sets the pa­per size, one for page lay­out as above, one for font "set­s", etc.

Neat, is­n't it?