Code Blocks (Listings)

[bennyboer]

For the documentation we will need code blocks.

[bennyboer]

New ideas:

Thingy name: #CODE#,
with options:

• src: The source file to read code from
• caption: Caption for the code/listing
• label: Internal document reference label (We don't have to implement it, as this works for all Thingys already)
• language: May be used for syntax highlighting (Not to be developed now, as this will be a lot of work, we have to find a good library in the best case). If the src file is an *.rtf (Rich Text Format) file we can try to use the formatting from that file?

Code block specific styles should be entered in the Thaw document style file:

• Show line numbers
• Line numbering style
• Background color
• Font size and settings (what monospaced font to use)
• Alternating line background colors
• ...

[bennyboer]

For syntax highlighting we could use something like Pygments which requires a python interpreter.
But we can call it from Java (https://pygments.org/docs/java/).

The resulting HTML could be parsed and typeset properly.

[bennyboer]

Created branch codeblocks

[bennyboer]

After researching quite a bit I found out that Pygments does no more support Python 2.x, thus we cannot use Jython if we want to be able to update Pygments (new languages, ...).

Therefore the following plan:

• Either provide the code in an preformatted RTF-file (For example by copying code from your favorite IDE and pasting it in word and then saving it as RTF file). The file will be read by Thaw and displayed as listing without any syntax highlighting needed.
• When wanting to syntax highlight code files, the user should be prompted to install python first (when not installed) as well as a instructions to install pygments. Afterwards pygments will be called from Thaw to do syntax highlighting. Advantage is that we don't have to care for updating pygments. Although breaking changes in pygments updates might break our logic.

[bennyboer]

If python is not installed on the machine print:

In order to syntax highlight code blocks you need to install python on your machine (https://www.python.org/).
Afterwards you will need to install Pygments using `pip install pygments`.

If only Pygments is not installed print:

In order to syntax highlight code blocks you need to install Pygments using `pip install pygments`.
Afterwards please try again.

[bennyboer]

TODO

• Call Pygments pygmentize over the command line using Java
  • Print 'please install' messages (see last comment) when either Python or Pygments is not installed
  • Output Pygments result as RTF (Rich-Text-Format) to a temporary file (For example pygmentize -f rtf -l java -o test.rtf MyClass.java) - File should be deleted after use
• Parse RTF file to a code block (DocumentNode), that can be directly typeset by Thaw
  • Should use the code font (monospaced font) set in the style file
  • Honor new settings in style file (to be created) - code style block
    • Show line numbers - "showLineNumbers": "true" (Default = true)
  • Break lines when line is too long to be displayed completely!
• Create #CODE# thingy
  • Create Options:
    • src - Path to the source file that contains the code to show (Required) - Either first argument or src-option!
      • Can be a RTF file directly -> No syntax highlighting -> lang option will be ignored (if specified)
      • Other file (*.java, *.c, ...) -> any file ending -> Pygments will be used to syntax highlight
    • language - Name of the language to use (Optional - when not specified will be guessed)
    • style - Style to use (See pygmentize -L for a full list or https://help.farbox.com/pygments.html for an overview) - User will be able to specify the style name that should be used
    • startLine defining the first line to display
    • endLine defining the last line to display
• Write lexer for Pygments to syntax highlight Thaw *.tdt code
• (To be reconsidered when all the above things are done) Cache already processed (unchanged - based on hash) syntax highlighting results in the ~/.thaw/cache directory to save some time while rebuilding the document

[bennyboer]

Captions will be done in #19

[bennyboer]

codeblocks branch has been merged. Done.