1. chunks

1.1. Background and rationale

Being able to embed attachment content into wiki pages is a useful feature. In MoinMOin, this is usually achieved with {{attachment:filename.ext}}, and the way it is included depends on the file type (mimetype). For text mimetypes, the content is displayed as code boxes (.txt), tables (.csv), marked-up wiki text (.moin) and others, but this is usually followed by a link to the attachment (which might not be desirable, and there is no way to override this). If included as marked-up wiki text, it is not possible to control the impact this has on heading numbering, and the generation of the a table of contents. So a section parser that embeds attachment content with an increase level of control could be useful, especially as this would des not direct read-only users to the file attachment page, without preventing this for experienced users.

1.2. Description

A simple parser that reads key:value pairs, a listing of chunks (sections of MoinMoin markup stored in attached files) and headings, then inserts them into the page either inline or with a parser section. The latter option allows for borders and background colours, with multiple key:value pairs being allocated to separate sections (with the same properties). The user can set options to (1) insert the chucks in parser section, (2) set chunk heading level, (3) prevent chunk heading insertion, (4) bump headings in chunks by a specified number of levels, (5) control heading numbering within the chunk, and (6) show only the markup for re-use with modifications, if desired, or for debugging purposes.

The key:value list must be in the form attachment:: heading with a leading space (as MoinMoin dictionary entries). All non-conforming lines are ignored without warning.

If the file is not a text mimetype, it is inserted using the in-built methods, either in-line or with a parser section.

The parser is intended for page section use only. The parser name is followed by a list of keywords separated by spaces to specify any options required.

Keywords and numerical arguments

section: requests the chunks be inserted as parser sections. The default will be a section specified as {#!wiki}. Other sections specfication can be requested as {{{specs}}}, where specs is the requires section specifications (e.g. {#!highlight python} or {#!wiki blue/solid}). Headings in sections are not found by the TableOfContents macro.
h-[0-6]: set chunk level heading. Default is level 2. A value of 0 is equivalent to "nohead" (if "nohead" is give it will take precedence).
nohead: request that no headings be inserted even if they are given in the pair:value list.
b-[0-5]: requests all headings in the chunk be bumped up one or more levels (as indicted by the number). Headings will not be bumped to a value above level 6. A value of 0 means no headings will be bumped (the default, if not requested)
n-[on,off,0-7]: requests a temporay change in the state of the page pragma value for section -numbers.
markup: shows the markup if you wish to re-use this with modification (assuming the default tabulation does not suit a specific purpose) or for debugging purposes.
#: when inserted at the beginning of the heading, it overrides insertion as a heading, and instead it is inserted as a comment.

Defaults are inline insertion with headings with headings within the chunks unchanged.

Keywords can appear in any order, however, the first instance of any option will used if the option is repeated with conflicting choices.

1.3. Usage

As parser section

{{{#!chunks [section ][`{specs}` ][h-[0-6] ][nohead ][b-[0-5] ][n-[on,off,0-7] ][markup ]
 chunk_file:: [#][heading]
 chunk_file:: [#][heading]
 ...
}}}

1.4. Prerequisites

When the TableOfContents macro collects information on headings, it runs macros that are declared to generate headings, but does not facilitate the same option for parsers. Therefore, a modified TableOfContents macro is needed for the chucks parser to work correctly.

The following function needs to be added to the TOCFormatter class in the TableOfContents.py, and this modified various is most appropriately saved in wiki.data.plugin.macro.

   1     def parser(self, parser_name, lines):
   2         from MoinMoin.formatter import FormatterBase
   3         self._get_bang_args = FormatterBase(self.request)._get_bang_args
   4         try:
   5             gen_headings = wikiutil.importPlugin(self.request.cfg, 'parser',
   6                                                   parser_name, 'generates_headings')
   7             if gen_headings:
   8                 return FormatterBase.parser(self, parser_name, lines)
   9         except (wikiutil.PluginMissingError, wikiutil.PluginAttributeError):
  10             pass
  11         return ''

Also the following line, in the latter part of the TOCFormatter class definition, needs to removed or changed into a comment.

   1 -    parser = _anything_return_empty
   2 +    #parser = _anything_return_empty

1.5. Download & Release Notes

Download	Release Version	Moin Version	Release Notes
chunks-1.0.py	1.0	1.9.8
TableOfContents.py	-	1.9.8	Modified to include collection of headings from a parsed section

1.6. Examples

See Example

1.7. History

Version 1.0 - 24.02.2019: initial version

Developed with inspiration and code from:

1.8. Copyright

1.9. License

GNU GPL, see COPYING for details.

1.10. Known issues and limitations

None identified, other than that attachments need to come from a page readable for the current user (which is appropriate, but needs to be considered for chunks not attached to the current page).

1.11. Possible improvements

Currently, only the heading given to the inserted chuck is accessible to the TableOfContents macro, but not headings in the imported chuck (i.e. if the chuck is moin mark up). This is consistent with the current behaviour with embedded attachments of type .moin and in parser sections formatted by #!wiki, however, it might be useful to provide for imported heading to included in the table of contents and to be numbered consistently with the rest of the page.

Hits: 201

chunks.py