Skip to content

The format

Jump to bottom Edit New page
leafstorm edited this page Jan 7, 2011 · 10 revisions

#The Lua Cookbook Text Format

Source

We still have to pick one

Options, suggested in the Lua ML:

  1. Markdown + Pandoc + Some post-processing, like in ProGit book.

  2. RST + Sphinx.

  3. Raw LaTeX

What features/styles do we need?

  • Auto table of contents
  • Auto index
  • Part/Chapter/Section/Subsection etc
  • Bold text
  • Italic text
  • Inline code
  • Code blocks with highlighting
  • Console sessions
  • Footnotes
  • Header / footer
  • Auto page numbers
  • Images
  • Note, Warning, Caution, Tip
  • Bullet lists
  • Numbered lists
  • Definition lists
  • Quote/Quotation
  • Story

Output

Definitely we must have at least these formats as output:

  • Set of HTML files, as in ProGit
  • A PDF file
  • ePub

Opinions

mbalmer:

We should also think about the final output format. This could be html/css, ePub, PDF, or all of them.
Personally, I (mbalmer) prefer PDF and ePub, with table of contents etc.

My (mbalmer) preferred source format is LaTeX. Don't how sensible it is to use mixed formats, i.e. I use LaTeX and you use XML. Maybe we need an > editor that edits all the text documents.

leafstorm:

Definitely in favor of Sphinx + reST. reStructuredText supports all those formatting things, and it can output to HTML, LaTeX, and ePub. (I put an example at https://gist.github.com/769988)

Also, Sphinx has a lot of useful features for books like table of contents, index, and the like that we would have to write ourselves if we used a custom pipeline.

Add a custom footer
Add a custom sidebar
Clone this wiki locally