figures

Background and rationale

Figures (attachments) in technical report style pages need to be numbered and have associated captions. The best way to do this is with tables, but the complex markup for tables distract from the the flow of the raw text, and looks daunting, if not impenetrable, to new users. Therefore, a simple section parser that can read a list of attachment names and figure captions would provided a cleaner flow, assuming a standard to limited range of formatting options is acceptable.

A simple parser cannot provide for all contingencies, so having the parser display the wiki markup for re-use with modification could take some of the chore out off constructing a more suitable table.

Description

A simple parser that reads key:value pairs from a listing of figures (attachments) and captions then formats these for display in as tables. Defaults to three column table with captions below centred figures (centred if less than three in the row). If more than three key:value pairs are provided additional rows are added to the table. The user can set options to (1) force a single or double column table, (2) place captions to the left or right of the figures, (3) set figures left or right justified, (4) give figures a width other than the default of 33% (a value from 25 to 100% is permitted), and (5) show only the markup for re-use with modifications, if desired, or for debugging purposes. The number of columns is set dynamically, if specified widths are two wide for 3 columns (ie if 34-50% then two columns forced and if >50% a single column is forced).

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

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

anchors: Create anchors from the captions, if they contain 'Fig. nnn', 'Figure nnn' or 'Plate nnn', where n is any digit. Any bold or italic emphasis markup is removed from the caption first. The anchors are placed before all figures in a horizontal group.
c-1: forces single column only. Overides c-2, if both options given, as single column takes precedence.
c-2: forces double column only, if the requested width 50% or less. Default is three columns, so no col-3 option is needed.
c-left: caption to left of image. Overides c-none or c-right, if more than one option given, as left takes precedence.
c-none: ignore captions.
c-right: caption to right of image. Overides c-none, if both options given, as right takes precedence over none.
f-left: figures set left. Overides f-right, if both options given, as left takes precedence.
f-right: figures set right.
nnn%: requested width of figure (including caption if set to left or right), where n is digits from 25 to 100. If outside this range, the default 33% is appled and no warning is given. If two or more width options are given, the first takes precedence and others are ignored (even if the first is invalid and the default widith applied). The value is checked and if 34-50% two columns are forced, and if >50% then a single column is forced.
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.
#: inserted at the beginning of the caption overrides caption inclusion and any associated padding. Inclusion of caption text is therefore optional and if included it effectively acts as a comment. Overidding captions can result in uneven multiple row layout where rows have different number of images and/or overidden captions. Therefore, this feature in recommended only for single row layouts. Also, caption and padding cells are not generated, so the sum of the cell widths is less than the table width and the figures and remaining captions will increase in size proportionally. Values set by the nnn% argument therefore become nominal only.

Defaults are caption and figure centred, width 33%, three columns (so no options for these are needed).

Keywords can appear in any order, other than as indicated above for conflicting choices.

Usage

As parser section

{{{#!figures [anchors ][c-1|c-2 ][c-left|c-none|c-right ][f-left|f-right ][nnn% ][markup ]
 figure_file:: [#]caption
 figure_file:: [#]caption
 ...
}}}

Download & Release Notes

Download	Release Version	Moin Version	Release Notes
figures-1.6.py	1.6	1.9.2

Examples

History

Version 1.6 - 15.10.2012: included automatic anchor insertion

Version 1.5 - 14.10.2012: included time dependency to properly handle Ref macro in captions

Version 1.4 - 22.01.2011: ffixed dynamic column allocation; minor edits

Version 1.3 - 15.01.2011: fixed the wiki formatting by setting inhibit_p to True

Version 1.2 - 13.01.2011: allowed for caption to overridden; right justified left positioned captions; other minor fixes

Version 1.1 - 11.01.2011: reverted to Python 2.5 string formatting

Version 1.0 - 11.01.2011: initial version

Developed with inspiration and code from:

Copyright

License

GNU GPL, see COPYING for details.

Known issues and limitations

For multi-figure layouts, optimal appearance might depend on pre-processing the figures to consistent dimensions.
Being formatted for display as tables, text cannot wrap around the figures (say if left or right justified). For this, an implementation using frames would be needed.
Overriding caption inclusion makes results in the sum of cell widths being less than the table widths, so cells are expanded proportionally, which makes the nnn% argument specified width inaccurate.

Possible improvements

Allow for 4 column rows of figures 25% wide.
It would be good to extract the figure name and number (e.g. "Fig. 1", "Figure 1", "Plate 1", or the like) and automatically create an anchor for each, ready for use for linked references from the text.
- Done in version 1.6.

Hits: 309

figures.py