DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:caption

caption Plugin

Compatible with DokuWiki

  • 2024-02-06 "Kaos" unknown
  • 2023-04-04 "Jack Jackrum" yes
  • 2022-07-31 "Igor" yes
  • 2020-07-29 "Hogfather" yes

plugin Provide figure and table captions with reference and automatic numbering

Last updated on
2024-02-24
Provides
Syntax
Repository
Source
Conflicts with
bootswrapper, strata

Similar to latexcaption

Tagged with caption, figure, tables

Please refer to the plugin homepage for the original installation and documentation guide (note that instructions are only available in German).

Syntax

The plugin basically provides two different syntax elements, similar to the blockquote plugin, one for the outer block (figure, table, codeblock, fileblock), one for the caption:

<figure>
...
<caption>...</caption>
</figure>

Besides <figure>…</figure> as shown above, you can use <table>…</table>, <codeblock>…</codeblock>, and <fileblock>…</fileblock> as well.

<caption>…</caption> should only ever be used within one of the other two environments.

Note: Illustrations always have their captions set below the actual illustration, tables (and code/file blocks) always have their captions placed above. Place the caption accordingly.

Within the syntax elements, almost every other DokuWiki markup is allowed.

The caption environment provides for automatic numbering and the output of the string “Fig.” or “Figure” (and corresponding for the tables, code and file blocks).

Whether the abbreviated or spelled notation is to be used can be set via the configuration interface of the plugin. The respective strings are localized, localizations for German, English, Korean and Portuguese-Brazil are currently available, others can be easily installed if necessary1).

Note: In DokuWiki almost everything is allowed within a <caption>, but you should be aware that e.g. footnotes within a floating environment are not allowed in LaTeX.2)

Labels and references

Since the figures and tables are automatically numbered by the plugin, there is a need to be able to refer to these figures / tables automatically in the text without having to change all references by hand each time when regrouping the figures / tables.

The original restriction by the parser that only references to already defined figures / tables were resolved has been fixed3).

The syntax looks like this:

<figure label>
...
</figure>

...

{{ref>label}}

The same applies to the tables. This means that the (optional) label is defined in the opening tag of an image / table 4) and via the structure

{{ref>label}}

referred to. The reference does not differentiate between figures and tables; without exception (like the corresponding LaTeX command \ref{}) it outputs the corresponding number. This number is also a link to the corresponding figure / table.

Note: If a label / table has a label defined, this will be displayed as a “hover” text (“tooltip”), if you move the mouse over the respective beginning of the respective label (“Fig[ure] n” / “Tab[le] m”).

Changing numbering

Sometimes you would like to control the numbering of your figures/tables/… This is possible as well (new 2021-09-29). You can (re)set the counters everywhere on your dokuwiki page, and independently for all kinds of environments (figures, tables, code and file listings). Suppose you would want to set the counter for figures to 5:

{{setcounter figure=5}}

Note: You can only set the four defined types (figure, table, codeblock, fileblock), and you can only use integers.

Example

And that's how the DokuWiki markup could look like:

<figure>
{{:Stuff:kuschelpanzer.jpg|cuddle tanks}}
<caption>**The ultimate pink cuddly shell.** Now I finally have to get one
Create a caption, which also contains some // formatting //.
Basically, everything is allowed ((footnotes actually?))</caption>
</figure> 

And the result:

cuddle tanks

or analogously for a table:

<table>
<caption>And a table heading with some **bold text**.</caption>
 
^ Heading 1 ^ Heading 2 ^ Heading 3 ^
|  Some text |  some more text |  some less text |
|  no idea what to write in here |||
|  |  But still some idea for here ||
 
</table>

Styles

The individual elements are as far as possible separately addressable and adaptable via changes to the CSS file of the plugin.

The following is an example of the XHTML code generated by the plugin, specifying the appropriate classes.

<figure class="plugin_caption_figure">
    <figcaption class="plugin_caption_caption">
        <span class="plugin_caption_caption_number">Figure 2:</span>
        <span class="plugin_caption_caption_text">...</span>
    </figcaption>
</figure>

Basically, it is important to format the image subheadings and table headings so that they are as clear as possible from the surrounding body text (especially if they span multiple paragraphs, which may be less common, but may well occur).

Configuration

The DokuWiki configuration interface can be used to set whether the over / signatures begin with abbreviated or advertised “labels” (“Figure” vs. “Fig.” / “Table” vs. “Tab.”).

The “labels” are initially available in German and English via the standard localization of the plugins, but can also be supplemented for other languages ​​if required.

Installation

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

Development

Development takes place via git and GitHub.

Feel free to fork the repository, change it and submit pull requests.

Change Log

Known Bugs and Issues

Please report bugs or feature requests at the bug tracker.

1)
According to the guidelines and structures of DokuWiki for multilingualism.
2)
An appropriate automatic handling of footnotes within the scope of the dokulatex plugin within floating environments is (at least for the moment) beyond the possibilities and the reasonable amount of programming effort.
3)
The “trick” is a little rough as it is a search & replace in the already parsed part of the current page.
4)
Pay attention to short, concise but meaningful labels. Since the same labels are also used in the case of LaTeX export in LaTeX, all limitations of LaTeX labels apply: no special characters such as umlauts, no spaces
plugin/caption.txt · Last modified: 2024-02-24 17:06 by tbiskup

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki