Create a stylesheet for your OpenDocument files, and inline the XML definitions right in your Org file–Think HTML_HEAD, or HTML_HEAD_EXTRA but for ODT / DOCX files


A Problem

I can produce OpenDocument files with Emacs … BUT I need documents with my own styles

An Org file like this

oxodt-001

exports to the following OpenDocument file

oxodt-002

What if you are a fiction writer, and want to produce your copy in Manuscript format i.e., a document like this

oxodt-004

The solution

Use ODT-specific export keywords like odt_styles_file, odt_extra_styles, odt_extra_automatic_styles and odt_master_styles

The answer is you would create a custom OpenDocument Template, and use it as part of #+odt_styles_file keyword.[1]   Or, if you are using the enhanced OpenDocument exporter[1], you will use inline XML style definitions using #+odt_extra_styles, #+odt_extra_automatic_styles, and #+odt_master_styles keywords.

Ultimately, your Org file will look like

oxodt-003

Why this article?

This article brings to fore all aspects that go in to producing a custom OpenDocument file

The man page of the official OpenDocument exporter[1] says only so much

Open the above ‘example.odt’ using LibreOffice. Use the Stylist to locate the target styles, which typically have the “Org” prefix. Open one, modify, and save as either OpenDocument Text (ODT) or OpenDocument Template (OTT) file. To apply an ODT style to a particular file, use the ‘ODT_STYLES_FILE’ keyword as shown in the example below: #+ODT_STYLES_FILE: “/path/to/example.ott”

The man page of the enhanced OpenDocument exporter[1]  goes a little step further–just a very little step further–and gives examples on how to inline the XML style definitions within your Org file.  A typical example goes like this:

#+ODT_EXTRA_STYLES: <style:style style:name="Text_20_body_large"
#+ODT_EXTRA_STYLES:              style:family="paragraph"
#+ODT_EXTRA_STYLES:              style:parent-style-name="Text_20_body">
#+ODT_EXTRA_STYLES:   <style:text-properties fo:font-size="150%"/>
#+ODT_EXTRA_STYLES: </style:style>

*** A regular paragraph

Nunc eleifend leo vitae magna.  Nunc eleifend leo vitae magna.
Curabitur lacinia pulvinar nibh.  Donec posuere augue in quam.
Aliquam posuere.  Nullam rutrum.  Aliquam posuere.

*** Same paragraph, in a larger font

#+ATTR_ODT: :style "Text_20_body_large"
Nunc eleifend leo vitae magna.  Nunc eleifend leo vitae magna.
Curabitur lacinia pulvinar nibh.  Donec posuere augue in quam.
Aliquam posuere.  Nullam rutrum.  Aliquam posuere.

Neither of the official manuals offers you practical help on how to tweak existing OpenDocument styles to create new styles, or how to cook the XML definitions.  If you hunt the internet, you will find plenty of information on how to style HTML documents using CSS, and sample snippets but you will NOT find information on how to style OpenDocument files with XML style definitions.  This article fills these gaps, and helps you  create OpenDocument files with custom styles.

About the Manuscript format

For the sake of this article, you will produce a OpenDocument file in Manuscript format[1].  This format is used by the fiction writers for producing their manuscripts.

For the sake of completeness, here is a quick summary of the above format

  • Use Courier or Times New Roman.
  • Set your font size to 12 points.
  • At least 1″ to each side of the text–top, bottom, left, and right.
  • Use double-space between lines.
  • In the first page of your manuscript,
    • in the upper left corner, place your name, address, telephone number, and e-mail address.  Place your professional membership beneath this information
    • In the upper right corner,  place an approximate word count
  • Place the title of your story ⅓ or ½ of the way down the first page. Center it between the margins.  Optionally, use all capitals
  • One double space below your title, center your byline.
  • Begin the text of your manuscript two double spaces below your byline.
  • Indent the first line of every paragraph by ½”.
  • No extra line spaces between paragraphs
  • In the upper right corner of every page (except the first),  place your surname, the title of your story, and the page number.
  • Left margin, except for paragraph indentations, should be ruler-straight. Right margin, should be ragged, not justified.
  • Emphasize a word or phrase with underline
  • If you want to indicate an em dash–the punctuation that sets off a phrase like this one–use two hyphens to do so.
  • Signal the end of a break,  by centering the character “#” on a line by itself.
  • Signal the end of a story, by centering the word “END”

Why the Manuscript format?

I have chosen the Manuscript format not only for it’s simplicity and practical usefulness, but for it’s technical merits.   This format requires that you be proficient in defining a broad class of OpenDocument styles.  You need two different types of pages: a first page and the rest.  Each type of page has it’s own header and footer content.  You also need multiplicity of paragraph styles: one each for the title, the byline, the headings, and body content.

A summary of steps

The GIF[1] is self-explanatory.

Here is a overview of the steps

  1. Export your Org file to OpenDocument format
  2. Open the ODT file in LibreOffice, and customize it to your heart’s content.
  3. Save the customized file as a OpenDocument Template file
  4. Open your Org file, and point to the template file with #+odt_styles_file
  5. Open the ODT file in Emacs.  For each of your modified styles, collect it’s XML definition
  6. Inline the above XML style definitions in to your Org file
  7. Assign the above XML style definitions–they fall in to one of three types–in to the right keyword from among #+odt_extra_styles, #+odt_extra_automatic_styles and #+odt_master_styles.  When adding the ODT-specific export keywords to the styles, you will find the rectangle commands[1] handy.
  8. Profit

Steps 5-7 apply only if you are using the enhanced OpenDocument exporter.  They do not make sense for the plain vanilla Emacs.

The most crucial step

But the most crucial step is the one that precedes step 1 above.  Here you tell LibreOffice to create pretty XML files.  If you skip this step, you will not be able to inspect or edit the component XML files of your OpenDocument file.  This is because, LibreOffice will produce XML file with a single long line, and when you  open such files Emacs will choke and refuse to budge any further.[1]

oxodt-015

oxodt-016

The Details

[CLICK HERE FOR UNSCALED GIF]

Produce OpenDocument files with custom styles using Emacs Orgmode

oxodt 2020-06-20

[CLICK HERE FOR UNSCALED GIF]

Conclusion

Producing a custom OpenDocument file using Emacs is a stressful … for a newbite

Producing a custom OpenDocument file using Emacs is a stressful for a couple of reasons:

  •  Very little OpenDocument know-how within the Emacs community: The Emacs community is technically-minded and has surfeit of LaTeX experts, but little to  no OpenDocument users.

While researching for this article, there was a lone article[1] that talked about custom styles  for OpenDocument export.  Strangely enough, the solution involved using something other than Emacs.

  • A culture of using UIs–as opposed to XML markups–to produce OpenDocuments:  OpenDocument files are popular with enterprise users, and in case of academia among the Humanities and Social Sciences discipline.  These users prefer UIs and stay mile away from hand-crafting of their documents with XML

  • XML style definitions are verbose and their options are elaborate:  Just compare the labour involved in producing the above custom OpenDocument file, with an equivalent custom HTML file.  There are too many  styles, and each style has too many knobs.  For example, in producing the above video tutorial, I have missed out on the following:
    • Capitalizing of OrgTitle
    • 12 pt size for Heading 1
    • First line indent for Text Body
    • Courier font for Footer

The above omissions are in spite of the care I exercised in producing the video tutorial.  It would be stupid of me to redo my GIF with the above omissions fixed: the point of this article was never to produce a first-class stylesheet for Manuscript format, but to talk about nitty-gritties of producing a custom stylesheet.  If you are a fiction writer, and you want to produce a document in Manuscript format using Emacs Orgmode, you can download the updated styles from my repository.[1] For the curious, this is how  a sample document looks, once the above omissions are fixed.

oxodt-manuscript-format

 

There seems to be no need for OpenDocument files among technically-minded plain-text enthusiasts.  To understand the gravity of situation, ask any ardent Microsoft Word or even a LibreOffice user this question:  “Do you use OpenDocument formats?”  You  will be invited with a blank stare, as if the user stumbled upon an alien, and lost all his senses.  This is despite the fact that they already use the format for their document-needs day-in and day-out.

Two Thumbs-Up for the enhanced OpenDocument Exporter[1]

That said,  I re-iterate my enthusiasm for the enhanced OpenDocument exporter.  If you produce OpenDocument Text files on a regular basis, I strongly recommend that you start using the enhanced OpenDocument exporter.  I base this recommendation on it’s ability to use inline XML styles.

The inline XML styles  offers the following advantages:

  • I can share my Org file with my LibreOffice-averse, OpenDocument-challenged co-workers, and expect them to produce good-looking, custom OpenDocument files right from the word go.  To appreciate what I say, try exporting the Org file in my repository[1] to OpenDocument format and see what you get.
  • Tweaking an existing style is a breeze.  Adding or removing an inch from the margins, or adding or reducing the font-size is just few key-strokes away.
  • The styles file i.e., the OpenDocument Template file is made redundant.  One less dependency, implies a quicker  and robust workflow.

Apart from offering inlining of OpenDocument XML style definitions, the enhanced OpenDocument exporter offers many new features.[1] In fact, my previous article explored List Tables.[1].

Categories gnu

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this:
search previous next tag category expand menu location phone mail time cart zoom edit close