Blueprint improved export function

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

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

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.