Writing in OpenOffice

Writing PubTal content using OpenOffice.

PubTal supports the use of OpenOffice word processing files (.sxw) for authoring web page content.  An author does not need to know any HTML to use OpenOffice, and can take advantage of features such as spell checking.

PubTal supports enough of OpenOffice's features to allow web page content to be authored, but not enough to act as a generic OpenOffice to HTML converter (a function that OpenOffice already has). 

The following subset of OpenOffice document features are supported:

• Meta data (e.g. title, subject, keywords).
• Heading levels.
• Text styles (bold, italic, underline, strikeout, overline, superscript and subscript).
• Preformatted Text and Source Text (converted to <pre> and <code> respectively).
• Hyperlinks and Bookmarks (anchors).
• Images (both embedded and linked).
• Lists (both bullet lists and numeric lists).
• Footnotes and endnotes - All treated as endnotes.
• Tables, including nested tables.
• Left, right, centre and fully justified paragraph layout.

Tips on using OpenOffice

There are several tricks to making the best use of OpenOffice for editing PubTal content.  Bear these in mind and OpenOffice can provide an excellent environment for writing web content, certainly superior to writing pages in a text editor.

Using Styles

PubTal supports styles, such as bold and italic, by generating HTML that contains Cascading Style Sheet (CSS) code.  PubTal does not reproduce the styling of the original OpenOffice document.  Styling, for example on tables, should be done in CSS files that are linked from the template.  This allows a common styling to be used across all produced web pages, regardless of the styling used in the individual documents.

Note that advanced techniques like multiple columns, precise positioning of images, etc. are not supported.

Tables

Tables in OpenOffice provide optional support for a heading row.  PubTal will convert these into <th> HTML tags, which allows a different style to be applied to the heading cells and the body cells.  To instruct OpenOffice to use a heading row select the "Header" option in the Insert Table dialog.  If a table is generating only <td> tags then its headers have become disabled - highlight the whole table and select "Split Table" to enable them.

Links

To use a URL to link to another document on the same website (a relative link), the OpenOffice "Document" hyperlink option must be used, not the "Internet" option.  This is because OpenOffice treats all links entered using the "Internet" panel of the Hyperlink dialog as being absolute addresses (fine for external links).  To check that the correct type of link has been created, enable the Hyperlink Bar using "View -> Toolbars -> Hyperlink Bar".  If the hyperlink you have entered begins with "file://" then it is a relative link, otherwise it is an absolute link.

Images

OpenOffice supports two kinds of images: linked and embedded.

Linked Images

To add a linked image to a document select the "Insert -> Graphics -> From File..." menu option.  Select the "Link" option so that OpenOffice will create a relative link to the image; this is equivalent to using <img src="filename.ext"> in HTML.  It is best to keep the image files in the content directory, and use the Binary content-type to copy them into the destination directory (this is configured by default for .jpg, .png, and .gif files).  This ensures that the relative links generated in the resulting HTML are correct.

It is also possible to link to an image on an external system.  To do this use the "Link" option described above and select any image file on your system.  Once this has been inserted into your document, double click on the image to bring up the Graphics dialogue box.  Select the "Graphics" tab, and then put the URL of the image into the File name box.  Select the "Type" tab, and then press the "Original Size" button to make OpenOffice take the correct image size.

Embedded Images

If the "Link" option is not selected when an image is inserted, then OpenOffice will take a copy of it and embed it into the document.  When PubTal finds such an image it will extract it, and place it into a directory called "Pictures" in the destination directory.  The HTML output page will contain a <img> tag that links to the file inside the Pictures directory.

PubTal names the individual image files using a combination of the generated HTML page name, and the internal OpenOffice names.  This is to avoid embedded images from several documents over-writing each other in the Pictures directory.

Notes

Images can also be turned into Hyperlinks.  To do this, double click on the image, and select the "Hyperlink" tab.  The "alt" text for the image can be specified in the "Options" tab.

PubTal does not support any attempt to align images; they are always created inline in the HTML document.  If an image is in a paragraph with the "Preformatted Text" style then PubTal will not produce a corresponding <img> tag in the output HTML.  In HTML it is forbidden to have images inside preformatted text.

Template Properties

When publishing OpenOffice documents PubTal provides additional context to the template used:

• page/headers/keywords - This path will contain the list of keywords associated with this document.
• page/footers - This path will contain a list of footnotes and endnotes used in this document.

Both of these properties are lists, and so need to be iterated over to be useful.  The following template snippet demonstrates how this can be done:

<div>
  <span tal:repeat="keyword page/headers/keywords">Keyword: <b tal:replace="keyword"></b></span>
</div>
<div>
  <div tal:repeat="footnote page/footnotes" tal:replace="structure footnote">Foonotes go here.</div>
</div>

Note that the footnotes in the list contain HTML, and so the "structure" keyword must be used in the tal:replace command.

To specify which files are treated as OpenOffice documents please refer to the Configuration section.