@@ -14,6 +14,46 @@
1414
1515Flatten sequences of elements.
1616-}
17+
18+{-
19+The purpose of this module is to combine the formatting of separate
20+runs, which have *non-nesting* formatting. Because the formatting
21+doesn't nest, you can't actually tell the nesting order until you
22+combine with the runs that follow.
23+
24+For example, say you have a something like `<em><strong>foo</strong>
25+bar</em>`. Then in ooxml, you'll get these two runs:
26+
27+~~~
28+<w:r>
29+ <w:rPr>
30+ <w:b />
31+ <w:i />
32+ </w:rPr>
33+ <w:t>Foo</w:t>
34+</w:r>
35+<w:r>
36+ <w:rPr>
37+ <w:i />
38+ </w:rPr>
39+ <w:t> Bar</w:t>
40+</w:r>
41+~~~
42+
43+Note that this is an ideal situation. In practice, it will probably be
44+more---if, for example, the user turned italics
45+off and then on.
46+
47+So, when you get the first run, which is marked as both bold and italic,
48+you have no idea whether it's `Strong [Emph [Str "Foo"]]` or `Emph
49+[Strong [Str "Foo"]]`.
50+
51+We combine two runs, then, by taking off the formatting that modifies an
52+inline, seeing what is shared between them, and rebuilding an inline. We
53+fold this to combine the inlines.
54+
55+-}
56+
1757module Text.Pandoc.Readers.Docx.Combine ( smushInlines
1858 , smushBlocks
1959 )