DOM Converters, Item, and Macro TODOs from /docs/todo/todo.rst

[UlrichB22]

The latest readthedocs build log shows the following warning:

[...]docs/todo/todo.rst: WARNING: document isn't included in any toctree

The file docs/todo/todo.rst has not been updated for 5 years. Some descriptions are not self-explanatory. I can create 3 new issues about DOM converters, items and macros and remove todo.rst. The ideas get lost otherwise because we mainly work with issues in github. Please advise.

Duplicate to #722.

[RogerHaase]

With a couple of trivial edits to correct rst syntax errors, using the rst > markdown conversion tool, and copy and paste: the following is the complete content of the former /docs/todo/todo.rst. As some descriptions are not self-explanatory, this issue is likely to be open for some time. To minimize the mess, a suggestion is to open a new issue referencing this issue when working on a fix, and editing this entry to add comments in bold-italic when something is complete. If that doesn't work, improvise.

General

• verify if these TODO items are still valid
• move valid TODO items either to the respective code file or to the issue tracker and remove them from here

DOM Converters

General DOM

If someone adds a new type of node in the Moinmoin DOM tree:

TODO: add support of new types of node

Allow creation of unicode URIs for wiki links. This should also provide access to the query parameters.

Support for per-instance converters.

Include converter

• Handle URIs using the Uri class.

Macro converter

• Move macro definitions into different namespace.
• Footnote placing.

HTML output converter

• Footnote placing.

ReStructuredText

Some syntax of ReStructuredText is ignored because it can't be converted to the current DOM tree (like inline style/class/template replacement via directives). Moin needs some page about unsupported things or changes in DOM tree.

Mediawiki

Before trying to fix mediawiki>DOM parser take a look at https://www.mediawiki.org/wiki/Alternative_parsers. There may be a suitable python parser that could be used in a manner similar to markdown. Mediawiki->DOM converter based on moinwiki->DOM parsing model. Moinwiki parser has blocks (multiline markup) and inline markup, but Mediawiki has tags that are inline and can be extended to next lines (until closing tag or end of the file). This creates a problem, for some tags it can be solved by implemented preprocessor, but it doesn't work with tags that have multiline output (like <blockquote>).

There are two ways to fix it:

• preprocessor must input 'n' before <blockquote> and after </blockquote>
• parser must be able to start new block(multiline) element after inline lexem.

Item

• Support different output types again.
• Converter-aware quickhelp.
  • Possibilities:
    • Use help from converter $type -> application/x-moin-document.
    • Use a different converter $type -> application/x-moin-document;quickhelp which always returns the help.
    • Use another registry for the quickhelps within the converter framework.
• Fix GUI editor.
  • Don't expand macros and links(?) in HTML.
  • Replace html -> moin wiki converter.

Macros

Macro handling

• Handle errors. Done
• Merge Macros and Converters

Include macro

• Argument parsing. The argument parsing through wikiutil.invoke_extension_method is currently incompatible with several examples of the macro usage. Done - each macro must parse its own arguments, perhaps using an existing parser
• Normalization of heading levels - e.g. if the tree has h1->h2->h4 (h3 is missing). For simple pages, we could just ignore this problem and require correct heading levels in input markup. But if you use Include much, this can get either a pain (esp. if you change levels) or even impossible (if same content is included on different pages into different levels). Would also fix broken looking TOC if levels are missing. Currently, the code has only 1 normalization: that the biggest heading on a rendered page starts at h1.
• For generation of a single output document (that can be either used as a single html file or transformed to a PDF), page links need to be changed: Usually page links just link to another page url. But if one assembles one large document using Include, one wants the links to the pages that got included point to some anchor where the page inclusion starts. For normal anchor links to / within included pages, it should be #Pagename-anchorid.