innoConv (mintmod) API documentation

What is innoConv (mintmod)?

This package converts mintmod-flavoured LaTeX into Markdown.

It can be seen as a shim for mintmod.tex and handles important mintmod commands by translating them to regular Pandoc elements.

Technically spoken it’s essentially a wrapper to Pandoc.

Read more about innoconv-mintmods architecture.

Table of contents

Installation

Prerequisites

innoconv-mintmod is mainly used on Linux machines. It might work on Mac OS, Windows/Cygwin/WSL. You are invited to share experiences in doing so.

Dependencies

The only dependencies you have to provide yourself is Pandoc and the Python interpreter.

All others can be installed into a Virtual environment.

Python interpreter

While other versions of Python might work fine, innoconv-mintmod was tested with Python 3.6. Make sure you have it installed.

Pandoc

You need to make sure to have a recent version of the pandoc binary available in PATH (Pandoc 2.2.1 at the time of writing). There are several ways on installing Pandoc.

Virtual environment

Setup and activate a virtual environment in a location of your choice.

$ python3 -m venv venv
$ source venv/bin/activate

Install innoconv-mintmod in your virtual environment using pip.

$ pip install --process-dependency-links -e git+https://gitlab.tubit.tu-berlin.de/innodoc/innoconv-mintmod.git#egg=innoconv-mintmod

If everything went fine you should now have access to the innoconv-mintmod command.

$ innoconv-mintmod
usage: innoconv-mintmod [-h] [-o OUTPUT_DIR_BASE]
                        [-f {latex+raw_tex,markdown}]
                        [-t {html5,json,latex,markdown,asciidoc}] [-l {de,en}]
                        [-d] [-i] [-r] [-s]
                        source
innoconv-mintmod: error: the following arguments are required: source

Congratulations!

How to use innoconv-mintmod

You can run the converter in your content directory.

$ innoconv-mintmod .

This will trigger the conversion for this folder.

Command line arguments

usage: innoconv_mintmod [-h] [-o OUTPUT_DIR_BASE]
                        [-f {latex+raw_tex,markdown}]
                        [-t {latex,html5,asciidoc,markdown,json}] [-l {de,en}]
                        [-d] [-i] [-r] [-s]
                        source

Positional Arguments

source

content directory or file

Named Arguments

-o, --output-dir-base
	output base directory Default: “./innoconv_output”
-f, --from	Possible choices: latex+raw_tex, markdown input format Default: “latex+raw_tex”
-t, --to	Possible choices: latex, html5, asciidoc, markdown, json output format Default: “markdown”
-l, --language-code
	Possible choices: de, en two-letter language code Default: “de”
-d, --debug	debug mode (output HTML and highlight unknown commands) Default: False
-i, --ignore-exercises
	don’t show logs for unknown exercise commands/envs Default: False
-r, --remove-exercises
	remove all exercise commands/envs Default: False
-s, --split-sections
	split sections Default: True

Converting legacy mintmod content

In this chapter some findings are documented on how to prepare content so it can be read by the innoconv-mintmod command.

Note

It’s not a complete list and there might be things missing that need to be done in your specific case.

First of all make sure all content is UTF-8 encoded. If not, tools like iconv can be helpful.

Adjust commands

There are some mintmod commands Pandoc is not able to parse. You need to manually replace them throughout your project.

Remove \ifttm…\else…\fi commands

mintmod_ifttm can get rid of all \ifttm commands.

Usage:

$ mintmod_ifttm < file_in.tex > file_out.tex

Automate on many files:

$ find . -name '*.tex' | xargs -I % sh -c 'mintmod_ifttm < % > %_changed && mv %_changed %'

Warning

The script cares only about \ifttm…\else…\fi with an \else command. There may be occurences of \ifttm…\fi (without \else). You need to remove them manually!

Unwanted LaTeX commands

A couple of commands are superflous or doesn’t make sense in a web-first content publishing platform like innoDoc. So remove any occurences of the following commands.

• \input{mintmod.tex}
• \input{english.tex}
• \begin{document} \begin{document}
• \MPragma{MathSkip}
• \Mtikzexternalize
• \relax
• \- (hyphenation)
• \pagebreak
• \newpage
• \MPrintIndex
• \relax

Automate:

find . -type f -name '*.tex' -or -name '*.rtex' | xargs perl -i -pe 's/\\input{mintmod(.tex|)}\w*\n//igs'

Including other modules

Pandoc doesn’t understand \IncludeModule. Change these statements to proper LaTeX commands.

\IncludeModule{folder}{file.tex} → \input{folder/file.tex}.

Replace strings

There are a couple of special characters you need to replace yourself.

• \"a → ä
• \"o → ö
• \"u → ü
• \"A → Ä
• \"O → Ö
• \"U → Ü

• \"s → ß
• \"s → ß
• {\ss} → ß
• \ss `` → ``ß
• \ss\ → ß
• \ss{} → ß
• \ss → ß

• "a → ä
• "o → ö
• "u → ü
• "A → Ä
• "O → Ö
• "U → Ü

• "` → „
• `` → „
• '' → “
• "' → “

Automate:

find . -type f -name '*.tex' -or -name '*.rtex' | xargs sed -i 's/\\"a/ä/g'

Clean up code

Remove unused files from your project and keep track of your changes using a VCS.

Architecture

This section gives an overview of innoconv-mintmods architecture.

The command line interface

The entry point is the command line tool innoconv-mintmod.

It calls panzer which is a Pandoc wrapper tool with the correct parameters.

Most of the magic happens in the package MintmodFilterAction.

It is implemented as a Pandoc filter and provides functions to deal with a number of special LaTeX mintmod commands Pandoc would otherwise just ignore.

All special commands are translated into primitives Pandoc knows already. Additionally information is encoded in attributes that are attached to the resulting elements.

The result of the MintmodFilterAction is a regular Pandoc AST that can be further processed by Pandoc output modules, thus be translated to Markdown, LaTeX, HTML and so forth.

panzer

panzer is a small wrapper script around Pandoc. It enriches Pandoc with serveral useful features that just happened to match this projects needs.

First of all it is possible to define profiles (called styles in panzer) that can already define parameters on how to run Pandoc.

Furthermore it can manage applied filters, run pre- and postprocessors etc.

You can find its configuration in the sub-directory .panzer.

A conversion run in a nutshell

TDB

Module overview

innoconv_mintmod.constants

Project constants are defined here.

innoconv_mintmod.constants.INDEX_LABEL_PREFIX

Element class for index labels

innoconv_mintmod.constants.COMMANDS_IRREGULAR

Math commands with irregular arguments, key=command-name, value=formatstring or value=dict (number of arguments, formatstring)

innoconv_mintmod.constants.REGEX_PATTERNS

Regular expressions

innoconv_mintmod.constants.ELEMENT_CLASSES

Element classes

innoconv_mintmod.constants.MINTMOD_SUBJECTS

Subjects as used in mintmod command \MSetSubject

innoconv_mintmod.constants.LANGUAGE_CODES

Supported language codes

innoconv_mintmod.constants.DEFAULT_LANGUAGE_CODE

Default language code

innoconv_mintmod.constants.DEFAULT_OUTPUT_DIR_BASE

Default innoconv output directory

innoconv_mintmod.constants.DEFAULT_OUTPUT_FORMAT

Default innoconv output format

innoconv_mintmod.constants.OUTPUT_FORMAT_EXT_MAP

mapping between output formats and file extensions

innoconv_mintmod.constants.OUTPUT_FORMAT_CHOICES

Output format choices

innoconv_mintmod.constants.ROOT_DIR

project root dir

innoconv_mintmod.constants.PANZER_SUPPORT_DIR

panzer support directory

innoconv_mintmod.constants.ENCODING

encoding used in this project

innoconv_mintmod.errors

Exceptions are defined here.

exception innoconv_mintmod.errors.ParseError

Raised when a mintmod command cannot be parsed.

innoconv_mintmod_mintmod.mintmod_filter

This module handles mintmod LaTeX commands.

Commands and environments are defined in the classes Commands and Environments.

innoconv_mintmod.mintmod_filter.commands

Handle mintmod LaTeX commands.

Note

Provide a handle_CMDNAME function for handling CMDNAME command. You need to slugify the command name.

Example: handle_msection method will receive the command \MSection.

class innoconv_mintmod.mintmod_filter.commands.Commands

Handlers for commands are defined here.

Given the command:

\MSection{Foo}

The handler method handle_msection receives the following arguments:

cmd_args: ['Foo'] elem: panflute.base.Element

handle_bigskip(cmd_args, elem)

Handle \bigskip command.

handle_clearpage(cmd_args, elem)

Handle \clearpage command.

handle_glqq(cmd_args, elem)

Handle \glqq command.

handle_grqq(cmd_args, elem)

Handle \grqq command.

handle_highlight(cmd_args, elem)

Handle highlight command.

This seems to be some sort of formatting command. There’s no documentation and it does nothing in the mintmod code. We just keep the information here.

handle_hspace(cmd_args, elem)

Handle \hspace and \hspace* command.

handle_jhtmlhinweiseingabefunktionen(cmd_args, elem)

Handle \jHTMLHinweisEingabeFunktionen command.

handle_jhtmlhinweiseingabefunktionenexp(cmd_args, elem)

Handle \jHTMLHinweisEingabeFunktionenExp command.

handle_mblank(cmd_args, elem)

Handle \MBlank command.

handle_mcontenttable(cmd_args, elem)

Handle \MContentTable command.

handle_mcopyrightcollection(cmd_args, elem)

Handle \MCopyrightCollection command.

handle_mdeclaresiteuxid(cmd_args, elem)

Handle \MDeclareSiteUXID command.

This command is used to embed IDs. This is not relevant anymore and becomes a no-op.

handle_medskip(cmd_args, elem)

Handle \medskip command.

handle_mentry(cmd_args, elem)

Handle \MEntry command.

This command creates an entry for the glossary/index.

handle_mequationitem(cmd_args, elem)

Handle \MEquationItem command.

handle_mextlink(cmd_args, elem)

Handle \MExtLink command.

This command inserts an external link.

handle_mformelzoomhint(cmd_args, elem)

Handle \MFormelZoomHint command.

handle_mglobalchaptertag(cmd_args, elem)

Handle \MGlobalChapterTag command.

handle_mglobalconftag(cmd_args, elem)

Handle \MGlobalConfTag command.

handle_mglobaldatatag(cmd_args, elem)

Handle \MGlobalDataTag command.

handle_mglobalfavotag(cmd_args, elem)

Handle \MGlobalFavoTag command.

handle_mgloballocationtag(cmd_args, elem)

Handle \MGlobalLocationTag command.

handle_mgloballogintag(cmd_args, elem)

Handle \MGlobalLoginTag command.

handle_mgloballogouttag(cmd_args, elem)

handle \MGlobalLogoutTag command.

handle_mglobalsearchtag(cmd_args, elem)

Handle \MGlobalSearchTag command.

handle_mglobalstart(cmd_args, elem)

Handle \MGlobalStart command.

handle_mglobalstesttag(cmd_args, elem)

Handle \MGlobalSTestTag command.

handle_mgraphics(cmd_args, elem, add_desc=True)

Handle \MGraphics.

Embed an image with title.

Example: MGraphics{img.png}{scale=1}{title}

handle_mgraphicssolo(cmd_args, elem)

Handle \MGraphicsSolo.

Embed an image without title. Uses filename as image title.

handle_mgroupbutton(cmd_args, elem)

Handle \MGroupButton command

handle_mindex(cmd_args, elem)

Handle \MIndex command.

This command creates an invisible entry for the glossary/index.

handle_minputhint(cmd_args, elem)

Handle \MInputHint command.

handle_mlabel(cmd_args, elem)

Handle \MLabel command.

Will search for the previous header element and update its ID to the ID defined in the \MLabel command.

The command can occur in an environment that is parsed by a subprocess. In this case there’s no last header element. The process can’t set the ID because it can’t access the doc tree. Instead it replaces the \MLabel by an element that is found by the parent process using function innoconv.utils.extract_identifier().

handle_mlcheckbox(cmd_args, elem)

Handle exercises defined by \MLCheckbox command

handle_mlfunctionquestion(cmd_args, elem)

Handle exercises defined by \MLFunctionQuestion command

handle_mlintervalquestion(cmd_args, elem)

Handle exercises defined by \MLIntervalQuestion command

handle_mlparsedquestion(cmd_args, elem)

Handle exercises defined by \MLParsedQuestion command

handle_mlquestion(cmd_args, elem)

Handle exercises defined by \MLQuestion command

handle_mlsimplifyquestion(cmd_args, elem)

Handle exercises defined by \MLSimplifyQuestion command

handle_mlspecialquestion(cmd_args, elem)

Handle exercises defined by \MLSpecialquestion command

handle_mmodstartbox(cmd_args, elem)

Handle \MModStartBox command.

This command displays a table of content for the current chapter. This is handled elswhere and becomes a no-op.

handle_mnref(cmd_args, elem)

Handle \MNRef command.

This command inserts a section link.

handle_modsemph(cmd_args, elem)

Handle modsemph command.

handle_modstextbf(cmd_args, elem)

Handle modstextbf command.

handle_mpragma(cmd_args, elem)

Handle \MPragma command.

This command was used to embed build time flags for mintmod. It becomes a no-op.

handle_mprintindex(cmd_args, elem)

Handle \MPrintIndex command.

Index will be printed automatically. It becomes a no-op.

handle_mpullsite(cmd_args, elem)

Handle \MPullSite command.

handle_mref(cmd_args, elem)

Handle \MRef command.

This command translates to \vref.

handle_msection(cmd_args, elem)

Handle \MSection command.

handle_msetsectionid(cmd_args, elem)

Handle \MSetSectionID command.

This command is used solely for tikz images. It becomes a no-op.

handle_msetsubject(cmd_args, elem)

Handle \MSetSubject{} command.

Command defines the category.

handle_msref(cmd_args, elem)

Handle \MSRef command.

This command inserts a fragment-style link.

handle_msubject(cmd_args, elem)

Handle \MSubject{title} command.

Command defines the document title.

handle_msubsection(cmd_args, elem)

Handle \MSubsection

handle_msubsubsection(cmd_args, elem)

Handle \MSubsubsection

handle_msubsubsectionx(cmd_args, elem)

Handle \MSubsubsectionx command. Which will generate a level 3 header.

handle_msubsubsubsectionx(cmd_args, elem)

Handle \MSubsubsubsectionx command. Which will generate a level 4 header.

handle_mtikzauto(cmd_args, elem)

Handle \MTikzAuto command.

Create a CodeBlock with TikZ code.

handle_mtitle(cmd_args, elem)

Handle \MTitle command.

This is an equivalent to \subsubsection

handle_mugraphics(cmd_args, elem)

Handle \MUGraphics.

Embed an image with title.

handle_mugraphicssolo(cmd_args, elem)

Handle \MUGraphicsSolo.

Embed an image without title.

handle_mvideo(cmd_args, elem)

Handle \MVideo.

Just return a Link Element.

handle_mwatermarksettings(cmd_args, elem)

Handle \MWatermarkSettings command.

handle_myoutubevideo(cmd_args, elem)

Handle \MYoutubeVideo.

Just return a Link Element.

handle_mzahl(cmd_args, elem)

Handle \MZahl command.

This is a math command but in fact occurs also in text.

handle_mzxyzhltrennzeichen(cmd_args, elem)

Handle \MZXYZhltrennzeichen command.

It is transformed to a \decmarker command and later substituted by MathJax. This is already in math substitions but as it occurs outside of math environments it’s defined here too.

handle_newline(cmd_args, elem)

Handle newline command.

handle_newpage(cmd_args, elem)

Handle \newpage command.

A display related command. It becomes a no-op.

handle_noindent(cmd_args, elem)

Handle \noindent command.

handle_quad(cmd_args, elem)

Handle \quad command.

handle_smallskip(cmd_args, elem)

Handle \smallskip command.

handle_special(cmd_args, elem)

Handle \special command.

This command is used to embed HTML in LaTeX source.

handle_vspace(cmd_args, elem)

Handle \vspace command.

A display related command. It becomes a no-op.

innoconv_mintmod.mintmod_filter.elements

Convenience functions and classes for creating common elements.

class innoconv_mintmod.mintmod_filter.elements.Exercise

Wrapper/Factory class that inherits from pf.Element and will return pf.Code instances, with special classes and attributes, depending on the given mintmod class.

innoconv_mintmod.mintmod_filter.elements.create_content_box(elem_content, elem_classes)

Create a content box.

Convenience function for creating content boxes that only differ by having diffent content and classes.

innoconv_mintmod.mintmod_filter.elements.create_header(title_str, doc, level=0, parse_text=False)

Create a header element.

Because headers need to be referenced by later elements, references to the last found header is remembered.

innoconv_mintmod.mintmod_filter.elements.create_image(filename, descr, elem, add_descr=True, block=True)

Create an image element.

innoconv_mintmod.mintmod_filter.elements.parse_ex_args(cmd_args, *names)

receive a list of argument names and a list of values and return a pandoc conformant argument array containing element’s arguments. In other words: take a list of arguments and make them named arguments for easier referencing.

innoconv_mintmod.mintmod_filter.environments

Handle mintmod LaTeX environments.

Note

Provide a handle_ENVNAME function for handling ENVNAME environment. You need to slugify the environment name.

Example: handle_mxcontent method will receive the \begin{MXContent}…\end{MXContent} environment.

class innoconv_mintmod.mintmod_filter.environments.Environments

Handlers for environments are defined here.

Given the environment:

\begin{MXContent}{Foo title long}{Foo title}{STD}
    Foo content
\end{MXContent}

The handler method handle_mxcontent receives the following arguments:

elem_content: 'Foo content' cmd_args: ['Foo title long', 'Foo title', 'STD'] elem: panflute.elements.RawBlock

handle_html(elem_content, env_args, elem)

Handle \html environment.

handle_itemize(elem_content, env_args, elem)

Handle itemize environments, that were not correctly recognized by pandoc. This e.g. happens if there are \MExerciseItems environments contained in the items.

handle_mcontent(elem_content, env_args, elem)

Handle \MContent environment.

handle_mcoshzusatz(elem_content, env_args, elem)

Handle \MCOSHZusatz environment.

handle_mexample(elem_content, env_args, elem)

Handle \MExample command.

handle_mexercise(elem_content, env_args, elem)

Handle \MExercise environment.

handle_mexercisecollection(elem_content, env_args, elem)

Handle \MExerciseCollection environment.

handle_mexerciseitems(elem_content, env_args, elem)

Handle \MExerciseitems environments by returning an ordered list containing the \item s defined in the environment. This is needed on top of handle_itemize as there are also mexerciseitems environments outside itemize environments.

handle_mexercises(elem_content, env_args, elem)

Handle \MExercises environment.

handle_mexperiment(elem_content, env_args, elem)

Handle \MExperiment environment.

handle_mhint(elem_content, env_args, elem)

Handle \MHint command.

handle_minfo(elem_content, env_args, elem)

Handle \MInfo environment.

handle_mintro(elem_content, env_args, elem)

Handle \MIntro environment.

handle_mquestiongroup(elem_content, env_args, elem)

Handle \MQuestionGroup environments. That are used to group together exercises, in order to allow synchronous validation. Especially used in checkbox grids. In mintmod, a button is also rendered below the contained exercises in the group. This function just returns a div with a class, in order to leave the validation logic, to client scripts

handle_msectionstart(elem_content, env_args, elem)

Handle \MSectionStart environment.

handle_mtest(elem_content, env_args, elem)

Handle \MTest environment.

handle_mxcontent(elem_content, env_args, elem)

Handle \MXContent environment.

handle_mxinfo(elem_content, env_args, elem)

Handle \MXInfo environment.

innoconv_mintmod.mintmod_filter.filter_action

Pandoc filter that transforms mintmod commands.

class innoconv_mintmod.mintmod_filter.filter_action.MintmodFilterAction(debug=False)

The Pandoc filter is defined in this class.

filter(elem, doc)

Receive document elements.

This method receives document elements from Pandoc and delegates handling of simple subtitutions, mintmod commands and .ments.

Parameters:

• elem (panflute.base.Element) – Element to handle
• doc (panflute.elements.Doc) – Document

innoconv_mintmod.mintmod_filter.math

Handle mintmod math commands.

innoconv_mintmod.mintmod_filter.math.handle_math(elem)

Handle mintmod text substitutions and some commands with irregular arguments.

innoconv_mintmod.runner

Runner module

class innoconv_mintmod.runner.InnoconvRunner(source, output_dir_base, language_code, ignore_exercises=False, remove_exercises=False, split_sections=False, input_format='latex+raw_tex', output_format='markdown', debug=False)

innoConv (mintmod) runner that spawns a panzer instance.

run()

Setup paths and options and run the panzer command.

Return type:str Returns:output filename

innoconv_mintmod.utils

Utility module

innoconv_mintmod.utils.block_wrap(elem, orig_elem)

Wraps an element in a block if necessary.

If the original element was block panflute expects the return value to be also block. In many places we need to detect this and wrap an inline.

Parameters:

• elem (panflute.base.Element) – Element to be wrapped
• orig_elem (panflute.base.Element) – Original element

Return type:

panflute.base.Element

Returns:

elem or elem wrapped in panflute.elements.Plain

innoconv_mintmod.utils.destringify(string)

Takes a string and transforms it into list of Str and Space objects.

This function breaks down strings with whitespace. It could be done by calling parse_fragment() but doesn’t have the overhead involed.

Example:

>>> destringify('foo  bar       baz')
[Str(foo), Space, Str(bar), Space, Str(baz)]

Parameters:

string (str) – String to transform

Return type:

list

Returns:

list of panflute.Str and panflute.Space

innoconv_mintmod.utils.extract_identifier(content)

Extract identifier from content and remove annotation element.

\MLabel commands that occur within environments are parsed in a child process (innoconv_mintmod.mintmod_filter.commands.handle_mlabel()). The id attribute can’t be set directly as they can’t access the whole doc tree. As a workaround they create a fake element and add the identifier. This function extracts the identifier and removes the annotation element.

Parameters:content (list) – List of elements Return type:(list, str) Returns:updated content list and identifier (might be None)

innoconv_mintmod.utils.get_panzer_bin()

Get path of panzer binary.

innoconv_mintmod.utils.get_remembered_element(doc)

Retrieve rememembered element from the document and forget it.

To remember elements use remember_element().

Parameters:doc (panflute.elements.Doc) – Document where the element is stored Return type:panflute.base.Element Returns:The remembered element or None

innoconv_mintmod.utils.log(msg_string, level='INFO')

Log messages when running as a panzer filter.

Parameters:

• msg_string (str) – Message that is logged
• level (str) – Log level (INFO, WARNING, ERROR OR CRITICAL)

innoconv_mintmod.utils.parse_cmd(text)

Parse a LaTeX command using regular expressions.

Parses a command like: \foo{bar}{baz}

Parameters:text (str) – String to parse Return type:(str, list) Returns:command name and list of command arguments

innoconv_mintmod.utils.parse_fragment(parse_string, as_doc=False, from_format='latex+raw_tex')

Parse a source fragment using panzer.

Parameters:

• parse_string (str) – Source fragment
• as_doc (bool) – Return elements as panflute.elements.Doc
• from_format (str) – Source format

Return type:

list of panflute.base.Element or panflute.elements.Doc

Returns:

parsed elements

Raises:

• OSError – if panzer executable is not found
• RuntimeError – if panzer recursion depth is exceeded
• RuntimeError – if panzer output could not be parsed

innoconv_mintmod.utils.parse_nested_args(to_parse)

Parse LaTeX command arguments that can have nested commands. Returns arguments and rest string.

Parses strings like: {bar}{baz{}}rest into [['bar', 'baz{}'], 'rest'].

Parameters:to_parse (str) – String to parse Return type:(list, str) Returns:parsed arguments and rest string

innoconv_mintmod.utils.remember_element(doc, elem)

Rememember an element in the document for later.

To retrieve remembered elements use get_remembered_element().

Parameters:

• doc (panflute.elements.Doc) – Document where to store the memory
• elem (panflute.base.Element) – Element to remember

innoconv_mintmod.utils.remove_empty_paragraphs(doc)

Remove empty paragraphs from document.

Parameters:doc (panflute.elements.Doc) – Document

innoconv_mintmod.utils.to_inline(elem, classes=[], attributes={})

Convert any given pandoc element to inline element(s). Some information may be lost.

Indices and tables

• Index
• Module Index
• Search Page