Blueprint improved export function

Use cases

(This section is a copy from the old wiki, by Johannes Reinhardt 2010/07/04)

• A scientist takes notes and exports a subset of them to a LaTeX document, as a base for a discussion with a colleague
• A writer uses zim to work on a script, using a note for each scenes (or variant of a scene). He wants to export some of them in a certain order to a continuos HTML document for printing.
• A blogger uses zim to manage his blog. Posts are notes, and comments are subpages to their corresponding posts. He wants to export each post and all corresponding comments to a single html file. Additionally, a page containing a overview over the 10 most recent posts, and overview pages for each of several tags shall be created.
• A book enthusiast keeps a list of books in zim, one note for each book . He wants to print an alphabetical index, using only the title of all notes.
• A notetaker wants to print out his shopping list, which is contained in a single note.

Required functionality The export mechanism should be able to do the following:

• Include child posts into the exported parent post (e.g. as a appendix, or the comments of a blog, or different div in a complex website)
• Access the content of all posts from a master document (e.g. the index page, or a latex beamer document which shall consist all selected notes)
• Different orders, as the order matters (e.g. Alphabetic for a glossary, chronological for a blog, user defined for a storyboard)

Requirements:

• allow sub tree export
• allow multiple pages wrapped into a single file (html / markdown / rst/ …)
• allow multipage project that compiles to a single file (latex)
• allow plugin output in export
  • e.g. calendar week / month summary
  • e.g. tasklist
• allow plugin/template to transform elements in format (html) (e.g. add classes etc.)

How:

• Split exporter / export layout from page selection → allow flexible selections like sub tree
• Make template able to handle multiple pages in single output
• For latex use multi-file export + special index page to do "include"s
• Robust error handling to skip over errors in template and in page reading / dumping

For error handling

• catch errors in template at various levels: block, iteration, page read / dump
• optional to catch and log versus log and raise again - in testing we want to see all as exception
• insert handler for logging - present errors to user at end of export

For single-file template

• Emit signals per page being added to update progress
• Want incremental write → filehandler that supports append + buffer of X bytes

Template vars

• “pages” one or more pages to be exported to single file - allow to inspect length etc.
• “next” / “prev” refer next / prev export file (not page, but maybe page)
• “links” dict with links to special pages (incl index and home)

For special pages (plugins / index) (later)

• Add them to Exporter by ExporterExtension
• Allow user to toggle on / off in dialog (default on)
• Allow generating based on page selection (e.g. index, subset tasks, ..)
• Export by same template as normal pages

For transform (later) -- see also notes below

• put hook in format to replace elements / attribs, e.g. in html identify tags + attribs before turning them into text -- ok if HTML is only format to support this
• set a transform option for a block in the template
• how to do the actual transform - embedded python ???

For theming (later)

• allow to select CSS for HTML separate in dialog, insert as template parameter

Dialog

What (input):

• all pages

• section

  • page

• single page

  • page

• select by query ?

  • query
  • button to show results

Advanced option to do manual selection on pages to be included ?? Alternative, use normal page as "manual index", query "links: page"

Include plugin pages, selection box:

• tasklist
• … ?

How (style):

• format

  • html, latex, markdown, rst, mhtml, epub, …

• layout

  • single file project
  • multi file project (grey out if NA, or if single page selected for export)

• template

  • template
  • style (CSS for html, else NA) -- set default from template ?

(Optional button “advanced” to fix e.g. sorting order, heading levels etc.)

Where (output):

File or folder

Link document root: absolute / URL -- //allow setting default from template//