MobileRead Forums - View Single Post - Changes to template function documentation processing

chaley · 11-14-2024, 01:08 PM

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
Code:
```
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.

11-14-2024, 01:08 PM	#1
chaley Grand Sorcerer Posts: 12,449 Karma: 8012886 Join Date: Jan 2010 Location: Notts, England Device: Kobo Libra 2	Changes to template function documentation processing 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 Code: 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.