Skip to main content

Ralsina.Me — Roberto Alsina's website

Coding in anger: not-gitbook

I have, in­ter­mi­tent­ly, for the past few month­s, been writ­ing a book. You can see it here and I am fair­ly hap­py with how it's go­ing.

I am not so hap­py with the tool­ing.

When I start­ed writ­ing it, I did­n't want to write a tool, I just want­ed to write a book. So, I looked for "things to make a book out of mark­down" and found a few, in­clud­ing md­Book and git­book and tried them both, then de­cid­ed to go with git­book be­cause it seemed more de­vel­ope­d.

But, you know how this work­s. Things start­ed drift­ing.

One ini­tial ob­sta­cle was that I want­ed the code in the book to come from the ac­tu­al work­ing code, not be a copy. I al­so want­ed to "ex­e­cute" the chap­ters and make the out­put of the chap­ter's code part of the chap­ter itelf.

I found a nice tool for this called pyLit­er­ate which... I end­ed up ex­tend­ing to al­low for things such as "in­clude this piece of code from that file but do not ex­e­cute it" and what­ev­er, and in­te­grat­ing it in­to git­book in­volved ... a lot of Make­files.

And then wen the out­put ap­peared in git­Book ... I re­al­ly did­n't like how syn­tax high­light­ing worked. I want­ed pret­ti­er and specif­i­cal­ly to be able to high­light some lines, and to have line num­bers match­ing the file con­tents and not start­ing from 1 ... and I end­ed up writ­ing a Git­book Ex­ten­sion

And I added sup­port for graphviz in pyLit­er­ate be­cause I want­ed SVG di­a­grams as part of the code and not as sep­a­rate things.

And I wrote and I wrote.

And then life hap­pened and I stopped writ­ing. And when­ev­er I want­ed to start writ­ing again in a new set­up some­thing broke.

  • Maybe the git­book ver­sion in­stalled or its de­pen­den­cies had a se­cu­ri­ty is­sue and need­ed up­dat­ing.
  • Maybe the up­dat­ed git­book broke my plug­in
  • Maybe things just were "of­f" and I had to track it down*

And a cou­ple of days ago, I just got an­gry. And what the hell this is just a lame stat­ic file gen­er­a­tor and I know those suck­er­s.

So, I de­cid­ed to see how much work would it be to reim­ple­men­t, some­what dumb­ly, git­book.

Well, re­al­ly, it's about a day's work (for a low qual­i­ty ver­sion)

  • Sup­ports all I want
  • Sup­ports plug­ins
  • Sup­ports ar­bi­trary mark­down pre­pro­cess­ing
  • Sup­ports ar­bi­trary mark­down ren­der­er hack­ing
  • Us­es mis­tune for mark­down, which kicks ass
  • Us­es jin­ja2 for tem­plates and they are 10x sim­pler than in git­book AND THE OUT­PUT LOOK THE SAME. I mean, there is one tem­plate

I logged the work, which was at a very re­laxed pace over a cou­ple of days here and pub­lished not-git­book in git­lab

I could mi­grate my book to the new toolchain in a day more work, most­ly in­volv­ing im­ple­ment­ing things git­book does­n't do and I am hack­ing via Make­files.

It's sure­ly not ready for any re­al us­age but feel free to poke around and con­tact me if you want to use it.

AlbertMietus / 2019-01-06 22:55:

I agree; writing a book shouldn’t involve writing tools ... it should be about parts, chapters and paragraphs. About structure en order.
Unfortunately, that are things ‘md’ isn’t good at; md is about 1 page, an article to be published online.

The alternative —rst (restructured text)— can handle that better; specially when using Sphinx-doc. http://ReadTheDocs.org contains many nice examples- most in html/online and pdf/download, and more. That why i’m always using it; privately and professionally

Recently, it started to support md too. I haven’t used it.. But it may lower the porting.. writing a book shouldn’t be about code ...:-)

Roberto Alsina / 2019-01-06 23:39:

I am very, very familiar with reStructured text. I am, after all, the main author of https://rst2pdf.org/ :-)

None of the problems I had while writing this book were caused by Markdown, and none of them would have been solved by using Sphinx, except if I considered PDF via LaTeX as an important target for the book (which I really don't)

Jason Braganza / 2019-01-07 03:17:

This is literate programming in python?

Roberto Alsina / 2019-01-07 10:04:

It supports pyliterate, so, in a very limited sense it is.


Contents © 2000-2023 Roberto Alsina