Blueprint improved export function

jaap-karssenberg edited this page Nov 20, 2013 · 1 revision
Clone this wiki locally

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//