Improving LibreOffice’s list numbering feature

Numbering and bullet list are a core feature of every word processing application, and naturally LibreOffice Writer has gazillion options in that area. Of course, Writer can also handle multilevel lists:

First line, first level
1. Second line, second level
2. Third line, second level
  1. Fourth line, third level
  2. etc etc

Now, how are these lists stored in ODF? Each level defines a num-prefix (what will be written before numbering), a num-suffix (same as prefix, but appended after the number), and display-levels – determining how many previous levels will be in list:

<text:list-level-style-number
text:level="3"
style:num-prefix=">>"
style:num-suffix="<<"
style:num-format="1"
text:display-levels="3">

In this example, we define a format for the third list level (in a numeric format), with displaying of all 3 levels and >> & << as a prefix/suffix. The output in Writer then looks like this: “>>1.2.3<<”

This is a nice and concise representation for many Western use-cases. But what can we do in this example:

Or in this case (https://bugs.documentfoundation.org/show_bug.cgi?id=116883):

One possible simple solution: we add a configurable number delimiter. In most cases, we would separate level numbers by “.” (and this was hard-coded in LO previously). For other cases, we should use “-” or “/”.

But before getting ahead of ourselves, lets first take a look what Word and DOCX does here:

Hmm, so Word does something completely different here: instead of a prefix/suffix, it uses an elaborate formatting string for numbers, where we can define any random prefix and suffix, plus arbitrary delimiters between different level numbers! We can even omit some numbers or worse, change their order of appearance (it is unclear how much sense that makes, but surely someone is now (mis)using that feature out there in documents).

And this is stored in DOCX in a rather simple xml attribute:

<w:lvlText w:val="%1-%2-%3-%4-"/>

Instead of prefix, suffix, display-levels and some additional separators, this has just one property, which at the same time provides much more flexibility.

Since LibreOffice 7.0, we are now using this lvlText (list format string) as an internal representation for documents (https://git.libreoffice.org/core/+/7459b9ecb54a298f02d19089620149718f8d8d48). This is enough to correctly load and save DOCX/DOC/RTF files, like the one from the screenshot above.

But we need to go further. If we save such DOCX files to ODT, more complex list level formattings will be lost.

Starting with LibreOffice 7.2, and with commit https://gerrit.libreoffice.org/c/core/+/117156/16, LibreOffice now features something quite similar to the DOCX properties: a new loext:num-list-format, which is obsoleting the older, less expressive num-prefix, num-suffix and text:display-levels attributes.

Unlike in DOCX instead of placeholders like “%1”, “%2”, this new ODF property is using “%1%”, “%2%”, etc. So why is that? Well in Word you can define up to 9 levels of list numberings, and %1 – %9 are enough for this representation. In LibreOffice, there are at least 10 levels, but even more ODF strives to be implementation-independent – so any hard limits here are anathema. Since format strings like “%10” are ambiguous (is it the “%1” placeholder with a “0” suffix, or is it the “%10” placeholder?) – the ODF specification uses the “%” delimiter on both sides of the placeholder.

Further improvements here include incorporating also style:num-format, to define numbering types for each level independently, in a way similar to the classical printf() format strings, in use with many programming languages.

The new num-list-format property is proposed for inclusion in ODF 1.4, but while this standard update slowly proceeds towards ratification, LibreOffice is meanwhile using its own namespace for it.

Work in this area is ongoing. Further efforts are needed:

LibreOffice’s UI need an update, to at least optionally allow list format string editing. Right now it is still using the old prefix/suffx edit boxes, where values are extracted from the list format string.
more refactoring of the Writer model – list format strings are still an optional element in list level definitions, and there are scenarios that need fallbacks if it is missing
more bugfixing of course – although the newest LibreOffice 7.4 / 7.5 beta are in fairly good shape, also thanks to the work of many other contributors
for reference, there’s a wiki page now to collect ToDo items around improving numbering support