Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Writing a Book with Pandoc, Make, and Vim

keleshev.com

Post reply on HN
Print view View original

41–50 of 61 posts

Re: Writing a Book with Pandoc, Make, and Vim

#41

Post by leephillips »

ddrt wrote: post #36
leephillips wrote: post #23

I’m always interested in reading articles like this, as I like to see the setups that people come up with to produce books and documents. I didn’t know about set virtualedit=all in vim! If you learn how to extend Pandoc with your own filters, which you can write in several languages, there is no limit to what you can do. Here’s the description, published in the sadly defunct Linux Journal , of the system I created to…

Everything in that link can be done with inDesign and having data. Finding a way to complete using console or alternative applications would take hacking the inDes app or finding some sort of IFTTT sort of automation when needed, then saving as a high res image, and referencing as a link in your console layout doc. At the end it would have to compile as an image into something (might as well be inDesign) and at that…

I’m not sure I understand your comment, but I believe inDesign is a proprietary, closed-source product, probably driven mainly through a GUI. My goal was to write my book in vim. All I need to do is type, and the book comes out, including a visual index of all the plots in the book. Every link in the chain, and every tool I used, is open source (and free). The result is exactly what I want. To each his own, but the project, described in my article, is to create an interface for me as an author. That interface is typing in vim, using a set of tags I created for the purpose.

Re: Writing a Book with Pandoc, Make, and Vim

#42

Post by ggerules »

marvindanig wrote: post #37
airstrike wrote: post #35

I know this is tangential, but I would love for someone to talk about writing a more visual type of book, full of images, tables and charts for the business world. A table like the one in the first screenshot of this post works well because the author is not repeatedly iterating on it, there's very little text and information flows top-to-bottom very neatly. That's great, but it's also extremely basic. Take a look at…

You mean https://bubblin.io/book/bookiza-documentation-by-marvin-dani... ?

Learning LaTex and tiKz help out with this. It looks like a presentation. So latex beamer package with some custom templates. The downside is that latex and tikz has a little bit of a learning curve. But it is worth it in the long run.

Re: Writing a Book with Pandoc, Make, and Vim

#43

Post by ggerules »

A couple of things that might be of interest:

1) pandoc is awesome. 2) There are integrated development environments that allow you to write in markdown and output to pdf, html, and word with the flick of a switch. Rstudio with knitr, bookdown, and markdown has some nice functionality. Plus you can do graphs and drawings and embed them in the the rmd (r markdown) text. 3) There is an earlier post in HN from Gilles Castel on how to speedily write text through the ultisnips package. Very much a game changer on how I use vim to work with anything text related.

https://castel.dev/post/lecture-notes-1/

Nice post!

Re: Writing a Book with Pandoc, Make, and Vim

#44

Post by marvindanig »

ggerules wrote: post #42
marvindanig wrote: post #37

Earlier quoted context omitted.

You mean https://bubblin.io/book/bookiza-documentation-by-marvin-dani... ?

Learning LaTex and tiKz help out with this. It looks like a presentation. So latex beamer package with some custom templates. The downside is that latex and tikz has a little bit of a learning curve. But it is worth it in the long run.

Have you used Katex in place of Latex? The latter is much lighter, especially if you're trying to publish a tome for the web.

Re: Writing a Book with Pandoc, Make, and Vim

#45

Post by Symbiote »

airstrike wrote: post #35

I know this is tangential, but I would love for someone to talk about writing a more visual type of book, full of images, tables and charts for the business world. A table like the one in the first screenshot of this post works well because the author is not repeatedly iterating on it, there's very little text and information flows top-to-bottom very neatly. That's great, but it's also extremely basic. Take a look at…

Those aren't books, they are presentation slides.

Using Powerpoint, for every slide the author chose (potentially) a different Powerpoint template (2×1 columns, 2×2 etc). They have complete freedom to "break" the structure, such as with callouts pointing to the "other" column, images going beyond the margins.

A automatic template removes this flexibility, but allows scripting or rebuilding the document with different text/data. That's the compromize.

Remark.js achieves some of the most basic parts of this, but would need some fiddling to add some CSS grid support and/or default templates: https://remarkjs.com/ (Except for being ugly, http://mobmad.github.io/js-tdd-erfaringer/ shows some possible structure with Remark.js).

Re: Writing a Book with Pandoc, Make, and Vim

#46

Post by yiyus »

leephillips wrote: post #33
j88439h84 wrote: post #32

Earlier quoted context omitted.

I cant tell the difference between this layout quality and latex. What are you noticing?

The first things that jump out are the large and uneven gaps between words and the “color” variations among paragraphs. What I mean by the “word-processing layout strategy” is the algorithm where, when you run out of space on a line, you simply break the line at the end of the previous word, fill up the space (for justified text) by expanding the spaces between words, and begin the next line. When you get to the end…

Maybe you already knew about it, but the microtype package improves the aspect of your documents even more: https://ctan.org/pkg/microtype

Re: Writing a Book with Pandoc, Make, and Vim

#47

Post by frozenlettuce »

After reading a couple posts here on HN about building a "second brain", I found a surprisingly effective setup to do that:

- Vim with vimwiki (https://github.com/vimwiki/vimwiki)

- A private Gitlab repo

- A simple cron job to commit all changes in `~/.vimwiki` to my private repo

And this is it! It would be possible to publish the wiki on the web using Gitlab pages, but so far it is working nice to me.

Re: Writing a Book with Pandoc, Make, and Vim

#48

Post by MattBlissett »

Here's a result [1] from a system I've put together, primarily using AsciiDoc(tor) and PO4A[3], to allow us to write a source document then translate it into multiple languages. It produces HTML and PDF, but ePUB is an option too.

Using AsciiDoc rather than Markdown has several benefits. The language supports many common book features, especially for technical books, like those "! Warning here" callouts, cited quotes, captioned figures/tables/codeblocks, internal links, I think even an index. It's also a lot more stable; I'm not concerned that there will be significant syntax changes in 5 years time. The user manual [2] is the quickest way to see what AsciiDoc can do.

PO4A is an adaptation of GNU GetText to use on prose. PO4A's output can input into a typical translation workflow -- distributing the files, or using online translation services. It mostly supports AsciiDoc, though there are some bugs, and outputting a PO file directly from AsciiDoctor (with a plugin) might be better -- PO4A parses AsciiDoc itself.

The code is at [4]. It's in slow development when necessary for new documents; I don't particularly intend to polish it for release or wider use.

KiCAD's documentation was the best example of something similar (AsciiDoc + PO4A) to what I've put together.

The missing pieces, which are closely related, are translatable and flexible diagrams. AsciiDoctor supports plenty of diagram tools, but none of them can do this. For example, the diagram at [6] is an SVG, which (since it's XML) can be translated using PO4A. However, in French the longer text spills out of the boxes. The previous diagram is an image, for this reason.

Is there an open-format (preferably open source) diagramming tool, which supports wrapping text, and even resizing "too long" text? I would be very interested!

[1] https://docs.gbif.org/collections-idea-paper/ or (in progress) https://docs.gbif.org/effective-nodes-guidance/1.0/

[2] https://asciidoctor.org/docs/user-manual/

[3] https://po4a.org/

[4] https://github.com/gbif/gbif-asciidoctor-toolkit/

[5] https://gitlab.com/kicad/services/kicad-doc

[6] https://docs.gbif.org/effective-nodes-guidance/1.0/en/#box-e...

Re: Writing a Book with Pandoc, Make, and Vim

#49

Post by marvindanig »

Symbiote wrote: post #45
airstrike wrote: post #35

I know this is tangential, but I would love for someone to talk about writing a more visual type of book, full of images, tables and charts for the business world. A table like the one in the first screenshot of this post works well because the author is not repeatedly iterating on it, there's very little text and information flows top-to-bottom very neatly. That's great, but it's also extremely basic. Take a look at…

Those aren't books, they are presentation slides. Using Powerpoint, for every slide the author chose (potentially) a different Powerpoint template (2×1 columns, 2×2 etc). They have complete freedom to "break" the structure, such as with callouts pointing to the "other" column, images going beyond the margins. A automatic template removes this flexibility, but allows scripting or rebuilding the document with different…

Going by the strict definition of a book [1] a file, a webpage or a website isn’t a book either.

[1] https://en.m.wikipedia.org/wiki/Book

Re: Writing a Book with Pandoc, Make, and Vim

#50

Post by airstrike »

Symbiote wrote: post #45
airstrike wrote: post #35

I know this is tangential, but I would love for someone to talk about writing a more visual type of book, full of images, tables and charts for the business world. A table like the one in the first screenshot of this post works well because the author is not repeatedly iterating on it, there's very little text and information flows top-to-bottom very neatly. That's great, but it's also extremely basic. Take a look at…

Those aren't books, they are presentation slides. Using Powerpoint, for every slide the author chose (potentially) a different Powerpoint template (2×1 columns, 2×2 etc). They have complete freedom to "break" the structure, such as with callouts pointing to the "other" column, images going beyond the margins. A automatic template removes this flexibility, but allows scripting or rebuilding the document with different…

I'm not so sure... I make them pretty much daily, and we print them and call them "books".

I'm not saying you shouldn't be able to tweak them manually, but there's got to be a more ergonomic language for drafting pages than literally dragging objects pixel by pixel, especially when most of the content comes in four forms: tables pasted in from Excel, charts pasted in from Excel, bullet lists and simple graphics around text like circles and squares

Post reply on HN