Manuel (doing all the work) and I (helping on the design) are working on the the following need:
Be able to provide numbering for content other than figures, tables and headings
Example of such content: Theorems, Lemmas, Definitions, etc
Have the LaTeX export support it and map it nicely to LaTeX syntax
We’ve already progressed a lot but wanted to provide visibility about what we’re doing, share that knowledge and also make sure we’re going in the right direction.
So here’s how we’re implementing this need:
Reuse the {{figure}} macro (now moved to a contrib project) to define all the types of content that can be numbered.
Extend the existing type parameter to support custom types that the user can define through configuration. Example usage: {{figure type="theorem"}}...
When the Numbered Content Extension is installed, number all the figure types (i.e. prefix the caption with the figure type + counter value, e.g. Theorem 1 ...caption content here...)
Be able to share counters between figure types. For example you may want to share the same counter between theorems and lemmas. The counter used by a figure type is defined in the type configuration.
Be able to support 2 layout styles: inline and block.
The figure style to use for a given figure type is also defined in the configuration.
Notes:
When the figure style is inline and a caption is defined, the rendering will be the following when Numbered Content is activated (based on a figure type of theorem): Theorem 1 (Pythagoras Theorem) ... content here...
Currently, the Numbered Content extension adds the figure type)(counter): prefix to the caption but we’ve realized that this is not going to work well for all languages (for French for ex, this is wrong as it should be figure type)(counter) : - notice the extra space). So we’re replacing the : with something else. We’ve not fully decided yet but it could be displaying the caption in bold, using a dot (as it’s often done in LaTeX) or using some other style like putting the caption into some box with some different background color. Ideally this could be configurable but FTM we’re going to provide only a single style (which will be overridable by the user with some SSX).
Manuel is still trying to figure out (pun intended ;)) if we can reconcile the CKEditor editing of an inline figure style with the fact that at the xwiki syntax/XDOM level, the {{figureCaption}} macro is standalone (and it should remain like since when exporting to HTML it’s generating a <figure> and <figcaption> elements which are block elements. Manuel thinks it could be done with some special CSS applied when editing with CK.
Let us know if you’re ok with this and/or if you see some problems with it.
Is it correct that “inline” mode just means that caption is kind of treated as a prefix of the first block, not that the whole figure content is inline? Treating the whole figure as inline content wouldn’t mirror what LaTeX supports (in LaTeX, a theorem can also consist of several paragraphs). In terms of CSS, wouldn’t it be sufficient to mark the caption as display: inline-block, so isn’t this more a caption style than a figure style?
What would happen if in an “inline” style figure, the caption is provided after the content?
Regarding the prefix with the number, isn’t that an example where the usual best practice that punctuation (and numbers) need to be part of the translated string should be applied?
similarly if the {{figureCaption}} macro is used not as the first or last block, the figure macro should generate an error.
Yes if there’s no other choice but it’s probably better to have a universal way of separating the elements visually that doesn’t involve punctuations. Seems that LaTeX does that by default. See Theorems and proofs - Overleaf, Online LaTeX Editor for example.
In order to apply the easily distinguish between the block/inline figure styles, I propose to introduce a new data-xwiki-rendering-figure-style parameter introduced by the figure macro according to the type of the figure. It’s value would currently be limited to block or inline.
Note that I currently have a working version supporting the localization of the separators.
The display is:
For block style: ${LABEL}${SEPARATOR}${NBSP}${CAPTION_CONTENT)
For inline style:
when the figure does not have a caption: ${LABEL}
when the figure has a caption: $LABEL${NBSP}${START_WRAPPER}${CAPTION_CONTENT}${END_WRAPPER}
where
${NBSP} is the non-breakable space
${LABEL} is resolved using the org.xwiki.rendering.macro.figure.FigureType.${figureType} translation key
${SEPARATOR} using the numbered.figures.caption.block.separator translation key (default being :)
${START_WRAPPER} and ${START_WRAPPER} respectively using the \numbered.figures.caption.inline.startandnumbered.figures.caption.inline.endtranslation keys (defaults being(and)`).
Note that by default, LaTeX is following is own norms and locales, it is possible to align them:
by customizing the translation keys to match what LaTeX outputs
by customizing the LaTeX templates to match what’s display the page content
I’d have preferred to not use localization but ok. Now I’m far from sure that what you’ve proposed is working for all languages. I think you need the full string as a localization key and you cannot separate the parts. What if in some language there’s no space after the separator and the caption content? You could include the NBSP inside the SEPARATOR but I’m not sure it’s enough, which is why I’d use a full translation key.
I agree a full translation key would be nicer but the way the label and counter are inserted (using ::before/::after css selectors) does not allow for the use of parameters, which would be required to insert the caption content inside the `${Label} ${Counter} (${Caption Content})) structure.
If we keep the translation key based approach, having the non-breakable spaces in the translation is not an issue.
The other option is to never use translation keys and to distinguish visually (e.g., using bold) but this makes it harder to have a consistent look between xwiki and latex results.
Not sure I’m following you. AFAICS LaTeX is using bold by default (see Theorems and proofs - Overleaf, Online LaTeX Editor). In this case I don’t see how the translation approach will allow consistency. Ofc if the LaTeX code is changed to use, say a dot, then yes the translation approach would work.
Personally I wouldn’t focus too much about keeping a consistency between both. I think we need to choose what makes the most sense for the XWiki Rendering in the figure/figureCaption macros. Then the LaTeX exporter can have its own customization if need be.
I guess we can use both approach, a translation key (including the spaces before and after) + the ability to have CSS to use bold (and possibly to override the translation to use an empty translation value for the separator).
+1, if the default separator does not fit, they can always be overridden.
Regarding CSS, the current style we have is to have a smaller font + slightly grey
I didn’t mean to use both at the same time! But to be able to use both, i.e. a character separator or some styling separator (bold or other). I’m fine to keep the current style + colon for now.
BTW couldn’t the separator also be defined as CSS? I guess we don’t have CSS that is language dependent, right?
