Advice on replacing one document's content.xml with another?

English
, , , , , ,
#1

I’d like to produce variant versions of my book from a single master version, where the main differences are just in the formatting.
The simplest example is creating a 4"x7" edition by just unzipping a 4x7 template .odt and the book’s master 5"x8" edition, copying the 5"x8" edition’s content.xml file into the unzipped template, editing the ISBN and then re-zipping.
I use the same name paragraph styles in all variants.
To make the document amenable to diff tools like meld and human editing, I can break up the XML into something semantically identical (I believe!) by only folding lines after an end-text XML tag

</text...>

(I can also safely fold lines at any right angle-bracket before the XML for any element starts.)

AN advice on what I should be alert to?

One thing I’ve noticed comparing my manually constructed (by cutting and pasting the whole master text into the 4x7 template and then fixing all the formatting errors), is that the two documents have

<text:soft-page-break/>

sprinkled through in the middle of the text of paragraphs for no reason I can imagine. I certainly didn’t intend yo make any kind of page break in the middle of a paragraph.
I also observe that the names of the XML tags used for paragraphs and text styles differ (e.g. P20 in one is P15 in the other, T5 is T3, and so on, and there are about ten times the number I expected).

I also see things I don’t understand in the paragraph styles XML, like names that seem to reference page styles I have (like Body_N_HdrFtr for body pages with no header or footer), and entities like a paragraph-rsid.

<style:style style:name="P63" style:family="paragraph" style:parent-style-name="Text_20_body" style:master-page-
name="Body_5f_N_5f_HdrFtr">
<style:paragraph-properties style:page-number="auto"/>
<style:text-properties fo:language="en" fo:country="US"/>
</style:style>
<style:style style:name="P64" style:family="paragraph" style:parent-style-name="Text_20_body" style:master-page-name="Body_5f_N_5f_HdrFtr">
<style:paragraph-properties fo:text-align="center" style:justify-single-word="false" style:page-number="auto"/>
<style:text-properties fo:language="en" fo:country="US"/>
</style:style>
<style:style style:name="P65" style:family="paragraph">
<style:text-properties fo:language="en" fo:country="US"/>
</style:style>
<style:style style:name="P66" style:family="paragraph" style:parent-style-name="Chapter_20_Title" style:list-style-name="">
<style:paragraph-properties fo:text-align="center" style:justify-single-word="false" fo:hyphenation-ladder-count="no-limit">
<style:tab-stops/>
</style:paragraph-properties>
<style:text-properties fo:language="en" fo:country="US" fo:hyphenate="false" fo:hyphenation-remain-char-count="2" fo:hyphenation-push-char-count="2"/>
</style:style>
<style:style style:name="P67" style:family="paragraph" style:parent-style-name="Chapter_20_Title">
<style:paragraph-properties fo:margin-top="36pt" fo:margin-bottom="10.01pt" loext:contextual-spacing="false" fo:break-before="page" style:writing-mode="page"/>
</style:style>
<style:style style:name="P68" style:family="paragraph" style:parent-style-name="Chapter_20_Title">
<style:paragraph-properties fo:margin-top="100.01pt" fo:margin-bottom="10.01pt" loext:contextual-spacing="false" style:writing-mode="page"/>
<style:text-properties style:font-name="Times New Roman3" officeooo:paragraph-rsid="00438e2a"/>
</style:style>

So: any advice, such as some reading about the workings of the .odt XML I should be careful of?

I only vaguely understand direct formatting - just enough to know that it’s likely to trip me up. I’m not aware of any description of what it is, in detail. (Like, how you create it, and how you would create documents that avoid it.)

#2

I strongly advocate against trying to fool Writer with such a trick. You’ll end up with a damaged document.

As you have seen, Writer assigns “indirect” style names when it uses your defined styles ( like P99 for a paragraph style). This allows to handle direct formatting in a unified manner. But the indirection depends on the document history. The same named style may receive a different indirect name in two documents with the same set of styles if the styles were referenced in a different order (due to insertion, deletions and editing). Consequently, don’t try to paste a content.xml from one file to the other.

What is direct formatting?

In simple words, this formatting made outside styles. Whenever you push a tool bar button, use a Format menu command or a keyboard shortcut, you are direct-formatting. In XML, this translates to another of these intermediate strange styles but without reference to one of the named styles (anonymous style). Taking the example of Ctrl+B for bolding characters, a new character style is created for every occurrence. You easily understand you can’t rely on the numeric id of the style to characterise “bold” in a document and another one.

How to avoid direct formatting?

Use exclusively styles. Contrary to M$ Word, LO Writer provides many more style categories to cover nearly all aspects of document authoring:

  • paragraph styles (the most known category because it is shared by all document suites),
  • character style (to apply a formatting variant inside a paragraph),
  • frame styles (for positioning properties of inserts),
  • page styles (for general aspect of pages),
  • list styles (in fact the properties of a numbering sequence and how it affects a paragraph style).

I don’t mention here the recent table “styles” because they are not styles like the others but templates operated by macros.

Your job, as an author and document maintainer, is to ensure that absolutely everything in your book is controlled by styles. The only exceptions are some manual page breaks to force a new page style after the break when the break can’t be included in a paragraph style and the restart of numbering for lists. I repeat, everything else must be style-formatted.

Also, wherever possible, if some information depends on a paragraph content, use fields to duplicate the information. For example, to copy the chapter title into the header; thus, the same page style may be used for several chapters.

Also, never position your text with empty paragraphs or non-semantic page break (in my wording, a “semantic” page break is associated with a break in the discourse, not a clumsy attempt to avoid orphan/widow lines). Tuning your styles should fix all formatting issues, eventually accepting a very few numbers of “approximations”.

The set of styles so defined and tuned should go into a template file (.ott extension).

If you have not yet based your book on a template, don’t worry. Install the DocumentTemplateChanger extension. You’ll then be able to assign a template to your document. But make sure that the styles in the templates take precedence on those in the document. Afterwards, never modify the styles in the document (unless you experiment and immediately transfer the modification into the template) otherwise they will override those in the template and you’ll have discrepencies.

5"x8" and 4"x7" variants

The main difference is in the page styles. Perhaps, you may need to adjust some tabs in the paragraph styles (by the way, I forgot to mention: don’t rely on the default evenly spaced tabs; they are not specific to your book. Prefer specific tab stops. Spacing in your paragraph should be set with a single tab character; if you use two or more to get your formatting, this is a hint that your document is not correctly structured: missing specific tab stops or data to be put in a table).

Create a second template with the adjusted styles.

To switch from one formatting to the other, use the DocumentTemplateChanger to switch the template. If the styles are well designed and your document correctly structured, this should do the trick without further adjustments.

I also recommend you don’t save two copies of your book (one in 5x8, the other in 4x7) at least in .odt because you’ll risk to forget to forward content edits into the other copy. But you can save the result as PDFs without adverse effects.

To show the community your question has been answered, click the ✓ next to the correct answer, and “upvote” by clicking on the ^ arrow of any helpful answers. These are the mechanisms for communicating the quality of the Q&A on this site. Thanks!

In case you need clarification, edit your question (not an answer) or comment the relevant answer.

#3

Thanks for explaining all that, especially the clear explanation of direct formatting.

Is there an extension which will distil a document down to a set of minimum styles?
E.g. define a single style for all text of a specific set of properties (Font, size, style), e.g. define an EmphasisTR12 style for all TimesRoman italic 12pt?

Or I suppose I could analyse the XML to work this out myself.

I imagine the reason Writer creates a new style each time you make some text italic (which is great ergonomics, a single key stroke or button press), is just in case the user wants each piece of text they directly set to italic a possibly different italic? (I’m trying to guess why Writer would create a new style rather than reuse an existing one.)

In any case, I’ll definitely try out what you’ve described here.

I confess there would be a massive amount of work in finding and changing all directly formatted italics to use a style.
But you’ve given me heaps of great information, thank you!

#4

The reason why Writer assigns a different style every time you press Ctrl+B is it can’t guess whether you consider that bold to have the same meaning as the previous one. This is where styles come in. Consider styles to be author annotations for the text: this sequence is “important”, that sequence is “sarcastic”. You chose that both “important” and “sarcastic” are displayed as bold. They look the same, but the meaning, the semantics is different. Afterwards, you can turn “important” red so that there is no longer ambiguity for the reader. You only change the style and all occurrences are simultaneously updated. This is great but you must be disciplined from the start.

Minimal set of styles: only you can tell. Think of styles as semantic markup, not as typographical effect. Your example of TimesRoman Italic 12 pt is wrong. Why did you choose so? An emphasis? A foreign word? Then there are 2 semantic markups. Later, you map the styles to visual effects.

#5

And since visual effects are rather limited in number, you inevitably end up with several styles looking the same. This is not important if context allows to make the difference. But, you, as an author, can change the look of a specific sequence of TR ital 12 to something else because you carefully markep up the document.

The big task is to correctly mark up the text. Don’t rely on any automatic tool. Don’t even try to scan the XML. It may exhibit non significant style changes because of technical limitations. This is a manual task because you bring added value to it.

You’ll know you have eliminated all direct formatting when Ctrl+M on any selection do not show any formatting change.

Styles may be as handy as the shortcuts you already know because you can assign shortcuts to your favourite styles with Tools>Customize.

#6

That’s exactly what I thought, thanks.
It’s a pity there’s not a mode you can choose for Writer to select between in ‘every markup may be unique’ mode or ‘every markup is the same’. I strongly believe the latter is far more common than the former.
Because I know I only use a specific style change for a single purpose, I know that distilling my document to a minimal set of styles is what I want. There is no other semantic markup: the visible changes represent exactly the semantic differences, and if they look the same they are the same.
Even if only a majority of my uses of italics were for a single semantic purpose, it would be far easier to manually find and split those apart into separate styles than the current implementation, where searching for italic text isn’t reliable
If you’re saying though that I can use Tools>Customise to set CTRL-I as a shortcut for emphasis character style, then that would solve the usability issue I see in the current design.

#7

I’ve also installed DocumentTemplateChanger and have restarted Writer, but can’t find any documentation on how to use it, nor any change to the Writer UI that would let me experiment with it.
No, wait: by looking at the TemplateChanger extension I found the functionality is accessed via a File>Templates item.

#8

I’m currently drawing a blank in trying to find what you mean by
“make sure that the styles in the templates take precedence on those in the document.”

I take your point about the danger of setting myself for a trap in saving a .odt version. I’ll think about that. The opposing risk is forgetting to change a (probably small set) of text items that must be changed, such as the ISBN. Maybe I could manage that risk by marking such items with a comment with some marker text.
OTOH, I’d need to save a .docx for the epub and the mobi versions too, and they have more substantive changes that would need to be reapplied each time, so I think on balance a .odt version for each version would be less likely to lead to errors.
Ideally I could have a front and back section for each version of each book (since these are version specific, with different ISBN, links), saved as .odt, so that when using styles exclusively, copy and paste the large bulk of the text might be reliable instead of unusable.

#9

Style conflicts: without entering into details, make any style adjustment only in the template. The inconvenient is that you must close the document and reopen it for the changes in the template to take effect. When you edit your template, use the Open Template command, not the other usual ones otherwise you get a new document based on the template and you must go through the full procedure to reinstall it.

Multiple versions: I forgot the ISBN issue which means your books show differences, then you need different documents. You end up with 4 files (at least): template .ott, common content .odt and 2 master documents .odm. The master documents will contain the front and back covers plus the “directive(s)” to import the common content. In this case, the page styles will be in the master document and you need no longer change the template.

Caution! If you’re not familiar with templates and master documents, experiment on copies first.

#10

ODF/docx: there are differences between the formats. If your keep a simple structure for your content (template/master/sub-document is not important when exporting), there should not be problems. By simple structure, I mean a linear sequence of paragraphs, few inserted objects (tables are the most problematic), few or no nested frames/objects (avoid tables within tables), simple numbering scheme.

Be aware that exporting to PDF and saving as .docx are not the same and may show differences. I have no experience with ePub.

#11

Many thanks regarding the master documents: that sounds like the solution I need long term, in combination with rigorous use of styles.

Regarding ODF/docx: yes, they’re just fiction books, so they’re a simple structure.
The most complex thing is a small table right at the end, in the ebook editions.

Thanks again, you’ve been a great help. I’ll be doing all this over the next few days.

#12

Thanks also for the note about File>Templates>Open Template. I was doing the wrong thing until you pointed that out, too.
Ah, wait, maybe it’s too late: now, when I open the template file it warns me

“The template ‘Book-5x8’ on which this document is based, has been modified. Do you want to update style based formatting according to the modified template?”

But even if I choose Update styles and then Save, next time I Open Template I still get the same warning.

Ah, maybe fixed it myself: I see there’s also a File>Templates>Save as Template. By doing that, and then choosing to ignore the warning when I close the file that I need to save the document or my changes will be lost, it seems to be okay.

#13

Being rigorous about styles though will probably take a day or two per book, because Writer can’t reliably find italic text. So finding all cases of direct format italics will have to be manual, and error prone.

#14

Then be kind enough to check my answer as satisfactory (click only once on the gray check mark. It may take a while before it turns green).

#15

I’m getting close now to correcting all the problems for all four editions of my first book. (That is, 5"x8" and 4.24"x7" paperback editions, epub edition, and kindle edition).
The problem I’m facing now is that when I tidied up all the page styles in the .docx file (which was all I had for the epub edition), I now have random page breaks in the HTML produced by Calibre after importing the .docx file.
I’m still trying to work out why.
I notice in the XML (I got desperate and saved as .odt and then looked inside that), that there are lots of places where a text:soft-page-break/ appears in the middle of a paragraph. I certainly would not have inserted them, and I can’t find any information about them. What are they for? Are they relevant to my random page-breaks problem? They don’t seem to match up with the page breaks Calibre generates in the HTML for the epub.
The old version of the .docx used to convert correctly using Calibre; the new version has these random page breaks inserted.

#16

Tomorrow I plan to convert the older version of the .docx file to .odt and look inside that, to see if I can see what’s different to the new (supposedly clean and greatly fixed) .docx version.

But this bug sounds highly relevant:
https://bugs.documentfoundation.org/show_bug.cgi?id=43692

If so, maybe the solution will be for me to edit the contents.xml and remove all the soft-pagebreaks.
I can try that tomorrow, too.
(1am here now.)

#17

I try to avoid tweaking the XML: my strategy is to use the styles to express my formatting goal, extracting maximum juice out of them. Then I don’t try to figure out how the style applications will be translated into ODF and its incarnation as XML. I prefer to stay with a single paradigm and not be bothered with the interactions between two.

One point you should consider: apparently your original book is .docx. This is very important and might explain some anomalies. Writer is much richer style-wise than Word and exact conversion cannot be achieved. Notably, Word has no notion of page style. I suspect that part of your problems are probably a consequence of the conversion.

I had a look at one of my complex documents. <text:soft-page-break/> seem to be reminders set by Writer where page breaks occur. When met, the current page style footer and header are laid out on the page. They are “soft” in the sense that Writer …

#18

… has full freedom to move them as opposed to your manual page break which must inflexibly remain where you put it to respect your formatting. My advice: don’t remove them or Writer will need to recompute the page breaks. More generally, don’t play with the XML; this is Writer playground. Yours is the document in plain English. Concentrate on the styles (all of them, paragraph, character, page). They are made to represent your expected formatting. Avoid conversions; always save .odt. Convert only if an addressee requires it And double-check formatting to make sure.

#19

I’m using the XML for diagnosis and understanding.
The original format was .odt; I write my books in LibreOffice. I can’t remember exactly the problem that made me lose the version source .odt file for the epub edition of my book. But because Calibre works much better with .docx files than .odt (the developer, Kovid Goyal advised me back in 2019), I convert the .odt to .docx to make a Word file for Calibre to import.
I insert a manual page break before each new chapter.
If Writer only uses soft-pagebreak in docs converted from Word, why leave them in? Doesn’t Writer normally have to work out where the page breaks go anyway? The soft-pagebreaks are all in stupid places where the page shouldn’t break, so I can’t see how they help Writer.
I’ve now looked inside the .docx too: each spurious page break has moderate-sized slab of xml including an <w:sectPr> section; these also occur just before genuine chapter starts.
The text:soft-page-breaks are more frequent in the .odt and more random.

#20

I’ve also just now looked inside the .docx for the previous version, that doesn’t get the spurious page breaks added by Calibre during the conversion process.

In that .docx file, the <w:sectPr>…</w:sectPr> always encloses the paragraph before a section break (i.e. before each chapter). There are none sprinkled elsewhere. NB: there was always exactly one extra added, on the Ch 1st page

So it seems during my edits or round trips between .docx and .odt, something introduced a whole bunch of these.

I’m going to try deleting them from the problematic .docx file’s XML and see how I go.

Fascinating:

When I simply re-zipped the .docx from the unzipped elements and opened that new file in Writer, it showed me each of the spurious page breaks: they’re visible as page breaks in Writer!

When I re-zip to create a .docx from my edited word/document.xml and reconvert in Calibre, it’s perfect.

In writer the conversion messed up many headers and footers, but they’re ignored in the epub anyway.

Impressum (Legal Info) | Datenschutzerklärung (Privacy Policy)   Content on this site is licensed under a Creative Commons Attribution Share Alike 3.0 license.