Project tools

Wiki

How do I...

For the following instructions to work, ensure that the DocBook stylesheets have been enabled. See the User Guide if this has not already been done. Currently the stylesheets only support <article> and <chapter> as top-level elements.

The Stylist and Navigator also need to be displayed:

Press F11 to display the Stylist
Depending on the DocBook tag to be used, the following options are available:

Select either Custom Styles or All Styles in the Stylist combo-box
Click either the Paragraph Styles icon (first in the left on the Stylist) or the Character Styles icon (second from the left on the Stylist)

Press F5 to display the Navigator
The Headings tab can be expanded to navigate through the DocBook sections of the document.

1. Top-Level Elements

To import an existing Article or Chapter

In the File Open dialog select the appropriate DocBook filter (Article or Chapter) in the File Type combo-box. An existing DocBook document can then be imported to OpenOffice.org.

To export an Article or Chapter

Similarly, in the File Save As dialog select the appropriate DocBook filter in the File Type combo-box.
NOTE: It is possible with the current filter to import an article and export it as a chapter, or go from chapter to article.

Creating an Article or Chapter

It is possible to create and save a new DocBook document in OpenOffice.org.

Go to File -> Open
Select OpenOffice Text Document Template (*.stw) as the File Type
Open the DocBookTemplate.stw (downloaded when enabling the DocBook stylesheets)
Begin entering DocBook content as described in the sections below.
Export the document as either a DocBook Chapter or Article

2. Meta Information

The info sections currently supported match the top-level elements: <articleinfo> and <chapterinfo>

Creating an Articleinfo

The ArticleInfo can contain the meta information about the Article, such as author details and copyright.

The cursor should be at the top of the document
Open the Insert Section dialog.
Set the name of the new section to ArticleInfo and Insert
Go to Custom Paragraph styles in the Stylist and select Document Title
Enter the document title
Create the Authorgroup (this is an example of using nested elements):

Go to All Character styles in the Stylist and select Default
Press return to create a new line and enter the first author's name
Highlight the author's name
In the Insert Bookmark dialog enter author_0
Repeat the above 3 lines to create the second author's name, this time using author_1
Create a new line above the author names
Highlight both the names and the empty line above them
In the Insert Bookmark dialog enter authorgroup_0

In the File Save As dialog, export the document as a DocBook Article.

The above steps can also be followed to create a Chapterinfo, replacing Chapter for Article were necessary.

3. Nested Elements

Early in the DocBook project there were difficulties mapping nested DocBook XML elements to the internal OpenOffice.org XML format. An example of how nested tags are now supported is the menuchoice element that can contain several guimenu elements.

NOTE: This is the initial fix for the problem of nesting DocBook XML tags in OpenOffice.org. The main purpose was to retain the information on a round-trip import and export of a DocBook document. It is not ideally suited to creating DocBook content in OpenOffice.org.

Nesting Guimenus and Guimenuitem inside a Menuchoice

Press return to create a new paragraph
Go to Custom Character styles in the Stylist and select Guimenu
Enter the Guimenu text
Select Guimenuitem in the Stylist
Enter the Guimenuitem text
Highlight the Guimenu and Guimenuitem text
In the Insert Bookmark dialog enter the text menuchoice_0 and click OK

OpenOffice.org bookmarks with reserved names are used to represent the parent element when nesting tags. The convention used is to follow the element name by an underscore and a number. The first element in the document will be numbered 0 (e.g. menuchoice_0) and subsequent elements of the same type will increment this number (e.g. menuchoice_1 menuchoice_2 etc.). For another example of how to use nested tags, see Meta Information where an Authorgroup is used to contain Author's.

4. In-Line Elements

DocBook in-line elements are, in general, mapped to OpenOffice.org Custom Styles.

The following instructions show how to create a DocBook subscript element.

Go to Custom Character styles in the Stylist and select Subscript
Enter the subscript text

The same procedure can be used for all of the DocBook Custom Character styles.

5. Sections

Initially the DocBook project used OpenOffice.org sections to enforce the nesting of DocBook sections. Feedback has shown that authors wish to use the common word processing styles such as Heading1, Heading2, etc. The following instructions describe how to create a <sect1> that contains a <sect2>

Select All Styles in the Stylist combo-box
Click the Paragraph Styles icon (first in the left on the Stylist)
Double-click the Heading 1 style
Enter the text to be the <sect1> title
All the text below this heading will now be the content of the DocBook <sect1>
Enter other DocBook styles, tables, etc.
Enter other DocBook styles, tables, etc. to be included in <sect1>

Double-click the Heading 2 style
Enter the text to be the <sect2> title
All the text below this heading will now be the content of the DocBook <sect2>
Enter other DocBook styles, tables, etc. to be included in <sect2>

This nesting of DocBook sect's using OpenOffice headings can go as far as <sect4> / Heading 4

6. Tables

Formal and Informal DocBook tables are represented by a standard OpenOffice.org tables.

Creating a Table

Go to Insert -> Table...
Set the table properties using the Insert Table dialog
The table name will become the table's id
Fill in the content of the table
Right-click on the table, and enter the table's <title> as the Caption

Creating an Informaltable

An <informaltable> is constructed in the same fashion as the formal table above, the only difference is that the table Caption is not specified.

7. Lists

The various DocBook lists are represented by custom and standard OpenOffice.org list styles.

Creating a Varlist containing Varlistentrys

Select Custom Styles in the Stylist combo-box
Click the Paragraph Styles icon (first in the left on the Stylist)
Double-click the VarList Term style
Enter text to be contained in the varlist term
Press the return key to enter text in the next varlist term

Creating an Orderedlist containing Listitems

Toggle the numbering to on by clicking the Numbering On/Off icon
Enter text to be contained in the listitem
Press the return key to enter text in the next listitem

Creating an Unorderedlist containing Listitems

Toggle the bullets to on by clicking the Bullets On/Off icon
Enter text to be contained in the listitem
Press the return key to enter text in the next listitem

8. Links

The different methods of linking available in DocBook are supported in OpenOffice.org

How to create a Footnote

Format the properties of the footnote in the Insert Footnote dialog.
Press OK and enter the footnote text at the bottom of the OOo page.

TBD

How to create a Note

Go to Insert -> Note...
Enter the text and click OK.
The text will be exported as <note> <remark> your text here </remark> </note>

How to create an Xref

There is support for <xref> with a linkend attribute. If the element to be referenced does not already have an id attribute then an id can be created with an OpenOffice.org cross-reference.

Create an id attribute for a <sect1>

Highlight the sect1 title
Go to Insert -> Cross-reference...
Set Type to Set Reference
Set Name to the desired value of the id attribute
Click Insert

Create the <xref>

Place cursor where the <xref> is to be located
Go to Insert -> Cross-reference...
Set Type to Insert Reference
From Selection choose the id for the <sect1> (this corresponds to the linkend attribute)
Choose Reference from the Format list.
Click Insert

Link, Ulink and Olink

The filter has round trip support for importing and exporting DocBook links.

9. Graphics

How to create a MediaObject