Changes to template function documentation processing

[chaley]

For the past many years we have had 2 and sometimes 3 simultaneous different versions of documentation for template functions. These versions weren't kept in sync. Some versions were wrong. The multiple versions created extra work for translators. In addition, the version visible in the template tester was unformatted so complex documentation such as for format_date() was hard to read.

We have now completed the changes so that:

• the one-true version of the documentation is the one shown in the template tester.
• the web documentation is generated from the documentation in the template tester.
• the template tester shows formatted documentation, with for example code samples and bulleted lists.
• a document browser dialog is available from the template tester via a "Documentation" button.

The documentation will be checked and corrected over time. It documents how the functions are used in General Program Mode where the "value" parameter is explicit, as opposed to being implicit in Single Function Mode. People are welcome to participate, but we ask that you ensure that changes you make are correct.

The documentation on the web won't be updated until the next calibre release (not preview).

Translators and documentation editors:
The documentation uses an invented markup language "Formatter Function Markup Language" (FFML), a subset of BBCODE (used by MobileRead) and RST (sphinx web documentation). Both HTML and RST can be generated from FFML. It is documented in the FFML processing code (calibre.utils.ffml_processor.py), and inside calibre by pushing the (new) "General Information" button in the template tester.

A simple editor/viewer is available in calibre for documentation either while editing or translating. There is no requirement to use it, but doing so might help avoid formatting errors. This viewer/editor is available in two ways:

• Using a shell with the command
  

  calibre-debug -c "from calibre.gui2.dialogs.ff_doc_editor import main; main()"

  all on one line. For the moment this works if you are running from source. It will work with calibre binaries after the next release/preview.
• By defining a keyboard shortcut in calibre for the action "Open the template documenation editor" in the Miscellaneous section of Preferences / Keyboard shortcuts. There isn't a default shortcut. For my use I set the shortcut to Ctrl+Alt+D.

The editor lets you enter and edit text in FFML, immediately seeing the formatted result. You can also see the original English documentation for existing template functions. However, I reiterate that the editor is low function. You can edit, copy and paste but not much more, which is sufficient for short documents. For longer documents I use a separate editor and use the built-in editor as a viewer to verify the result. That way while editing I get line wrapping and spell checking, for example.

[Comfy.n]

Is it possible to save a documentation "note" for a stored template such as "books with notes containing text"?

[chaley]

Originally Posted by Comfy.n

Is it possible to save a documentation "note" for a stored template such as "books with notes containing text"?

I don't understand the question. You appear to have successfully entered some documentation for that template. Do you want to do something more than that?

EDIT: Or perhaps you entered it but it isn't being saved? If this is the problem then press the Replace button.

[Comfy.n]

Originally Posted by chaley

EDIT: Or perhaps you entered it but it isn't being saved? If this is the problem then press the Replace button.

that was it.

[ownedbycats]

I now wonder if, in the future, there might be a way to export specific stored templates/functions and their documentation for other users to import (similar to Action Chains). Likely limited in its usefulness admittedly.

[chaley]

Originally Posted by ownedbycats

I now wonder if, in the future, there might be a way to export specific stored templates/functions and their documentation for other users to import (similar to Action Chains). Likely limited in its usefulness admittedly.

I've wondered about that. It would be useful for the recipes, especially now that the template's documentation is available and can be formatted. I'll look at it at some point.

[Comfy.n]

On a quite unrelated note, I've recently wondered about a common repository for author notes...