I can produce OpenDocument files with Emacs … BUT I need documents with my own styles
An Org file like this
exports to the following OpenDocument file
What if you are a fiction writer, and want to produce your copy in
Manuscript format i.e., a document like this
Use ODT-specific export keywords like
The answer is you would create a custom OpenDocument Template, and use it as part of
#+odt_styles_file keyword. Or, if you are using the enhanced OpenDocument exporter, you will use inline XML style definitions using
Ultimately, your Org file will look like
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 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 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.
For the sake of this article, you will produce a OpenDocument file in
Manuscript format. 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 is self-explanatory.
Here is a overview of the steps
- Export your Org file to OpenDocument format
- Open the ODT file in LibreOffice, and customize it to your heart’s content.
- Save the customized file as a OpenDocument Template file
- Open your Org file, and point to the template file with
- Open the ODT file in Emacs. For each of your modified styles, collect it’s XML definition
- Inline the above XML style definitions in to your Org file
- Assign the above XML style definitions–they fall in to one of three types–in to the right keyword from among
#+odt_master_styles. When adding the ODT-specific export keywords to the styles, you will find the
rectangle commands handy.
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.
Produce OpenDocument files with custom styles using Emacs Orgmode
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 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
- 12 pt size for
- First line indent for
- Courier font for
- Capitalizing of
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. For the curious, this is how a sample document looks, once the above omissions are fixed.
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
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 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.