Calligra/Words/Tutorials/OdfStyles

Thomas' notes on QTextFormat

The thing is, there is no 1-to-one mapping between formats and styles. Formats are just a data object in Qt and styles indeed copy their data into it. But the formats store data from various other sources as well. In effect a format is just a added document-data structure.

Roop's mail on Headings

It looks like headings need not be part of a list at all. This is how simple headings are to be handled. They should only become part of a qtextlist (or a koliststyle) if they're enclosed within <list> tags.

This revelation :) was brought about with ODF1.1 section 14.1 'List style', which says: "A paragraph style and styles of other families that may contain paragraph properties can have an associated list style. This applies to automatic and common styles. The list style specified by the style:list-style-name attribute is only applied to headings and to paragraphs that are contained in a list, where the list does not specify a list style itself, and the list has no list style specification for any of its parents."

This implies that: <text:h>Heading</text:h> should not have any list style applied on it (it consequently will have no numbering), but <text:list><text:list-item><text:h>Heading</text:h></text:list-item></text:list> will be part of a qtextlist. The list style of this qtextlist will be derived as it's done for paragraphs (check if there's a list style specified on the <text:list> itself, or maybe it's parent list? Else the paragraph's list style. Barring all, look at default list style.)

However, ODF1.1 section 14.11 'Outline style' says (quoted earlier): "The outline style is a list style that is applied to all headings within a text document where the heading's paragraph style does not define a list style to use itself."

In my understanding, this means that if there's an outline level specified, all headings not within a <text:list> (which would otherwise have been without a qtextlist), will have to be added to the qtextlist corresponding to the outline style's qtextlist (for the heading's outline level).

So my take aways from these two snips from the specs (which are completely different from what I was thinking of headings before) are:

 a) there can be headings which are associated with no list style - in kword terms, they need not be part of any qtextlist
 b) heading blocks should be part of a qtextlist if and only if
    either (b1) the heading is part of a <text:list>
        or (b2) the styles.xml specifies an outline-style
 c) user can change association of list styles to headings using the stylemanager ui in the same way as is done for paragraphs.

In fact, this implies that headers are really a lot like paragraphs (the only difference being they need to be included in the TOC) and not at all like lists.

When I tried OO.o, just making a text heading and saving it results in just the <text:h> tag, but when you add numbering to it (by modifying the Heading1 paragraph style' list style from empty to some numbering style), it is written out as a list.

I just wanted to make sure everyone else is in agreement to this understanding of the spec.

Girish's explanation

The reason for the confusion is that when we write out the ODF, we do a diff between the format (QTextBlockFormat, QTextCharFormat) and the style (KoParagraphStyle, KoCharacterStyle). This diff just does a blind compare of each and every key of the QMap of the format and the QMap of the style. Whatever is the diff, we generate as the automatic style. It could very well be that we have not explicitly ignored properties when comparing the QMaps above because the need has not arisen. But because of the way the code is right now, it leads to an understanding that a format and the ODF style have a one-one mapping. That's what I was mentionning... Sorry for being really messy, close to unreadable...

A reason to have it in the block format is copy/paste. When you copy the block, we want all the block properties - the fact that it is a heading too. Currently, this is not a problem since we save/load odf on copy/paste which is extremely inefficient when pasting with kword itself. A solution that is faster for internal copy/paste would involve just copying the format of the block (and we don't need to write any special code to save extra properties in block data).