Documentation/Understanding, Authoring and Editing Openoffice.org Help/4

Author: Frank Peters, Sun Microsystems (fpe@openoffice.org) Version: 2.0_16 Date: Feb 3, 2006

Public Documentation License Notice The contents of this Documentation are subject to the Public Documentation License Version 1.0 (the "License"); you may only use this Documentation if you comply with the terms of this License. A copy of the License is available at https://www.openoffice.org/licenses/PDL.html. The Initial Writer of the Original Documentation is Sun Microsystems Inc. Copyright (C) 2005. All Rights Reserved. (Initial Writer contact(s): fpe@sun.com). Contributor(s): ______________________________________.

= Authoring Help With OpenOffice.org =

(Deprecated) You need OpenOffice.org 1.1.x to use the help authoring environment. The authoring environment also is not yet compatible with OpenOffice.org 2.0.

Setting Up the Environment
There is an import/export filter available that allows for direct editing of OpenOffice.org help files without the need of extra conversion steps. The following describes how you set up the filter.

The filters are xsl files that are used in conjunction with an import template and takes advantage of OpenOffice.org xsl filter functionality.

Directory Hierarchy
The correct function of the help authoring environment with OpenOffice.org relies on the CVS module directory layout. Since all help file and image references are expressed relatively, the environment needs to know the absolute paths to be able to assemble and disassemble the references correctly for display in OpenOffice.org.

Us the following directory structure when checking out the modules from CVS. If you work in a Child Workspace, this is the default directory layout:

$root |__default_images                <-- check out from CVS |__helpcontent2                  <-- check out from CVS |__helpers |__util |__prj |__source |__text |__auxiliary

Before you set up the environment you need to select and create a root directory for working on the help files ( $root ), for example: /opt/ooohelp or D:\ooohelp

Creating the image directory

The CVS module default_images contains all images thatare used by the help.


 * Check out the module default_images from OpenOffice.org CVS into the help root directory (as described above).

Creating the help files directory


 * Check out the module helpcontent2 from OpenOffice.org CVS into the help root directory (as described above).

Installing The Import/Export Filters
Ensure that the XML Filter option is installed in OpenOffice.org. If this option is not installed, install it using the option from the the OpenOffice.org setup.# Get the filter package from the helpers/helpauthoring directory of the helpcontent 2 CVS module. There is one common package for Windows and Unix.
 * 1) The packages contain the XSLT Import/Export filters and the template.
 * 2) Open a text document in OpenOffice.org. The menu item for the XML Settings will only be visible if a document is loaded.
 * 3) Choose
 * 4) Click
 * 5) Browse to the filter package and click.
 * 6) Click

You can now open and save files in OpenOffice.org help format.

Note that occasionally, OpenOffice.org seems to corrupt the packaged files while unpacking. If you are unable to load or save help files, check the xsl files in the user/xslt/Help directory and the template in the user/template/Help directory. You can also, extract the file manually from the package using a zip file utility.

Installing The Supporting Macros
The macro set is used to perform tasks inside the help files.


 * 1) Get the macro archive HelpAuthoring.tar.gz from the helpers/helpauthoring directory of the helpcontent 2 CVS module.
 * 2) Unpack it to a temporary directory.
 * 3) Choose


 * 1) Click
 * 2) Click the  tab
 * 3) Click  and browse to the temporary directory with the unpacked macros
 * 4) Select the file script.xlb inside the macro directory and click
 * 5) Select  and click
 * 6) Close the macro dialogs

You can now use the macros for help authoring. The macros create a configuration file helpauthoring.cfg to store various information and settings in your user/config directory.

Installing The Help Authoring Menu
The Help Authoring menu allows easy access to the macros to perform standard tasks with the help files.* This procedure overwrites any menu customization that you have made!
 * Get the menu archive helpauthoring_menu.zip from the helpers/helpauthoring directory of the helpcontent 2 CVS module.
 * Choose and select the  tab
 * Click
 * Locate the helpauthoring_menu.zip file
 * Select the file and then click

If all steps were performed successfully, you should now be able to use the menu.

Editing Help Files - Basics
Since OpenOffice.org cannot simply be used as an XML editor we need to make some effort to map elements and attributes in the help file to elements that are recognized by OpenOffice.org.

Paragraphs And Paragraph Formatting
Paragraphs are the central content carrying element in a help file. A paragraph in the help file maps to a paragraph in OpenOffice.org. The role attribute of a paragraph maps to a paragraph style in OpenOffice.org.

For every paragraph role in the help file there is a paragraph style beginning with hlp_ and ending with the role name, e.g. the role paragraph maps to a style named hlp_paragraph.

There are also special paragraph styles that start with hlp_aux_. These are used for identifying special elements and should never be used for paragraphs.

The default paragraph styles for a help file (that is, the default roles of a paragraph) are already pre-defined in the help authoring template ( xmlhelptemplate.stw ) that is used for loading the help files in OpenOffice.org. This template is part of the import/export package and automatically installed in your user/template directory.

You can define new paragraph styles that are transformed to roles in the help files on export by creating a custom style beginning with hlp_ and ending in the role name. This new style will be recreated on loading that file in OpenOffice.org next time. However, there will be no formatting information for OpenOffice.org associated with it. For that, the style needs to be added to the template.

Note, that these styles don't have any effect on the help as it is displayed as such. In order to adjust the help appearance the roles that are created from the paragraph styles must be transformed by the main transformation style sheet and/or assigned to formats using the cascading style sheets of the help.

Sections
A section in the help file maps to a section in OpenOffice.org. You can use the navigator to get an overview of existing sections or use the Insert - Section and Format - Sections  menus to modify existing sections. The section   ID   maps to the section name in OpenOffice.org. Nested sections are supported.

Tables
A table in an OpenOffice.org help file transforms to a visible table in the OpenOffice.org file. The table name holds all attributes for that table. If the table has a caption defined in the help file, a paragraph is created directly after the table that contains the caption. It is important that this sequence is not modified since the export filter relies on that sequence.

Tables should no longer be used for formatting purposes, for instance, to place images or to mimic numbered lists. Nevertheless, there still is a considerable amount of legacy help files that do that.

Images
Images are mapped to image objects in OpenOffice.org that are linked (not embedded) to the OpenOffice.org file and anchored as character. The alternative text is defined in the Alternative property of the image object that can be accessed through the Graphics properties dialog (by double-clicking the image) on the Options  tab page. The   ID   of an image is stored in the name of the image object and should not be altered manually.

Lists
There are two types of lists in the help (unordered and ordered) that match to the corresponding list type in OpenOffice.org.

Embedding
The embedding technique is unique to the help. Therefore, we use some workarounds to implement embedding when editing the help files in OpenOffice.org:


 * Sections to be embedded are represented as sections.
 * Paragraph parts to be embedded are surrounded by a  variable  tag pair.
 * Places where sections are embedded are designated by an  embed  tag.
 * Places where parts of paragraphs are embedded are designated by an embedvar tag.

Character Formatting
Direct (hard) formatting is not supported. Any character with a direct format will lose its format definition on export. Instead, character formatting is achieved using character styles. The importing template already contains a list of pre-defined character styles. All styles that begin with hlp_ can be used for character formatting except for the styles beginning with hlp_aux_ because those are used for internal purpose.

Similar to the paragraph styles, you can define new character styles that are transformed to type attributes of item elements in the help files on export. To do this, create a custom character style beginning with hlp_ and ending in the type name (e.g., hlp_dialogname ). This new style will be recreated on loading that file in OpenOffice.org next time. However, there will be no formatting information for OpenOffice.org associated with it. For that, the style needs to be added to the help authoring template.

Creating A Help File
The help authoring menu is only available in the Writer context. So you need to have a Writer window open. You should always create a new file this way to ensure that all settings are made correctly. The directory structure is described in this section. You will be automatically prompted to save the file. You need to save it before you can actually work on it.
 * 1) Start OpenOffice.org and open a new empty Writer window.
 * 1) Choose Help Authoring - Create New Help File.
 * 1) Select a file name inside the help directory structure
 * 1) Insert an initial comment (optional)

You will be prompted to insert a comment on file creation. This comment will be stored in the file metadata and cannot be changed using OpenOffice.org.

Now you have created a fresh empty help document. The file title is set to the generic term . To adjust the topic title see Meta Data.

Switch the Stylist to show Custom styles to view a list of all styles that are allowed in the help file. None but these (and the ones created by you following the guidelines above) can be used.

Opening A Help File

 * 1) Choose
 * 2) Browse to the file you want to open and select Help (*.xhp) as the file type
 * 3) Click

Removing A Help File
Since a help file is referenced from multiple locations, simply deleting a file from disk is not sufficient for removing a help file from the set of help files.

To remove a help file from the set of help files that are compiled, you need to remove it from the makefile of its directory. In this way, it will not be included in the index, or the full text search. However, it will still be included in the help files archive *.jar.

To delete a help file completely, you need to remove it from your local disk and remove its entry in the makefile of its directory. If you work on the CVS you also need to remove it from the CVS repository.

You also need to remove all dependency files in the output tree that are created during a help build that refer to the deleted file. See also Building the Help Set. If you haven't built the help set before you don't need to worry about this. If you have changed multiple files it is safer to remove the output tree completely and rebuild the help from scratch.

Finally, you need to ensure that the deleted file is not referenced by other help files or by the content files *.tree in the auxiliary directory.

To remove a help file

This step is not required if you use the createmakefile.pl script from helpcontent2/helpers to update all makefiles before building the help.
 * 1) If this change will be committed back to the CVS, remove the help file from the CVS repository, for example, using the cvs remove command.
 * 2) Delete the help file on your local disk.
 * 3) In the makefile.mk of its directory, locate the help file's entry (it has the extension .hzip instead of . xhp ) and delete the corresponding line.
 * 1) Check if the help file is referenced in on of the *.tree  files in helpcontent2/source/auxiliary and delete its reference there, if required.
 * 2) If you have built the help before and you have an existing output tree with dependency files *.dphh , delete any dependency files that reference the deleted help file. A dependency file lists all files that it depends on.

Moving A Help File
From the build environment's view, moving a help file from one directory to another is equivalent to removing a file from one directory and creating a file in another directory.
 * 1) Copy the help files to the new directory.
 * 2) Follow the procedure described previously for removing a help file.
 * 3) Ensure that all links inside the moved help file to itself have been adjusted.
 * 4) Add the file to the makefile of the new directory.

This step is not required if you use the createmakefile.pl script from helpcontent2/helpers to update all makefiles before building the help.

Sections and Paragraphs
Sections are used to specify parts of help files that are used for referencing purpose in other files. Sections can be embedded and linked.

Where Are The Sections?
Since OpenOffice.org natively supports sections, we make use of them to represent sections in help files. The ID attribute of a section in the help is represented by the name property of the section in OpenOffice.org.

All other properties of sections inside OpenOffice.org have no influence on the help sections. Any layout settings made to sections (background, visibility...) are lost on next reload.

You can use the navigator to view and navigate sections. Nested sections are also supported ,both by the help and by OpenOffice.org.

Sections start and end with a section tag that is placed in the first paragraph directly after the section starts, and in the last paragraph before the section ends:



Fig. 6: Section tags and section areas

If you want to insert something before or after a section, ensure that you place it before or after the section delimiter line, not just before or after the section tag.

If the section starts at the top of the document and you want to insert something before that section, go to the top of the section and press Alt+Return to create a paragraph in front of the section.

If the section ends at the bottom of the document and you want to insert something after that section, go to the bottom of the section and press Alt+Return to create a paragraph after the section.

Adding A Section

 * 1) Depending on whether you want to insert a new empty section or build a section around existing text, do one of the following:
 * 2) * Place the cursor where you want to insert the new empty section.
 * 3) * Mark the piece of the document that you want to include in a section.
 * 4) Choose Help Authoring - Insert Section
 * 5) Insert an identifier for the section in the text box.

This section identifier will be used as ID attribute for the section in the help file. It must be unique within the file. It is advisable to use some kind of descriptive name. Use only letters, numbers and the underscore.

Adding A Subsection
A subsection is a section that is the child of another section. OpenOffice.org supports nested sections. The procedure to insert a subsection is the same as inserting a section, except that if you insert a section with the cursor inside an existing section you will create a subsection.

You cannot create overlapping sections. Neither the help format nor OpenOffice.org support this.

Removing A Section

 * 1) If you want to remove a section including its content, delete the section content first.
 * 2) Choose Format – Sections.
 * 3) Select the section you want to remove from the list of sections and click Remove .  

If you remove a section that has subsections only, the selected section will be removed while the subsections will be preserved.

Linking To A Section
You can create a link to a section by specifying the section ID as the target in the hyperlink URL when creating a link, for example



For details, see Linking.

Embedding A Section
You can embed a section using the embed element. You need the file name and the ID of the section that you want to embed. The embedded section preserves its structure. For details on embedding, see Embedding Content.

Adding A Paragraph
Paragraphs in the Help have some attribute values that cannot be represented in OpenOffice.org without using certain workarounds. Therefore, you need to follow the following instructions to create valid paragraphs.

You can write the paragraph content in the usual way. You only have to ensure that


 * the paragraph has meta information associated with it
 * the paragraph has a valid paragraph format assigned

The paragraph meta information consists of the paragraph ID, the language (which in the source files is always en-US ), the localize attribute, and some other attributes that are not relevant in this context.

All of these values are stored in a variable field at the beginning of the paragraph. The paragraph ID identifies the paragraph contents in the localization database.

Before saving the final file, each paragraph must have a valid and unique ID. The easiest way to do this is to place the cursor somewhere in the paragraph and to choose Help Authoring - Paragraph - Set Paragraph ID. If the paragraph does not have the correct style associated (see below) ID creation will be denied. Paragraph IDs are also be assigned when the file is validated using HelpAuthoring – Validate.

Not all paragraphs get IDs. Some paragraphs only contain structural information, such as opening and closing tags, or bookmarks, and don't need an ID because they don't transform back to content paragraphs in the help file. All these paragraphs have a paragraph style assigned that starts with hlp_aux_.

If you forget to assign IDs to all corresponding paragraphs, the application will do that for you on saving, provided the template was correctly installed.

Editing A Paragraph
Editing the contents of a paragraph does not need any further action. The localization process finds out for itself when in the content of a paragraph has changed.

This has two consequences for the writers:


 * 1) You do not need to worry about whether a change has an influence on the localization.
 * 2) You cannot force re-translation of a paragraph by just setting any editing flag.

For basic content management purposes, the l10n attribute of a paragraph can be used for setting paragraph status values, since this attribute was only relevant for the migration phase.

For instance, you can set the paragraph status to NEW or CHG (changed) to allow reviewers to easily spot these paragraphs for content review. Any other values come from the migration phase and are no longer relevant. Paragraphs that have been reviewed don't carry an l10n attribute (or carry an empty one).

Paragraph Formatting
All paragraphs in a help file are formatted using paragraph styles. Direct formatting (borders, indentation, etc.) is strictly unsupported. In fact, all direct formatting will simply be lost on export.

Use the predefined styles to format the paragraphs. The following styles are available in the help authoring template (switch to the Custom view in the Stylist):


 * hlp_default


 * This is the parent style for all hlp_* styles and only used as a fallback. It translates to a paragraph@role="paragraph" in the help file.


 * hlp_paragraph


 * This is the standard style to be used for paragraphs. It translates to a paragraph@role="paragraph" in the help file.


 * hlp_head, and hlp_head1...hlp_head5


 * The hlp_head style is the parent style for the other hlp_head* styles and should never be used as such. The hlp_head* styles designate heading elements of different levels. They translate to paragraph@role="heading"@level="x" in the help file with x corresponding to the heading level.


 * hlp_listitem


 * This is the style to be used for list items. Its use is optional, as paragraphs inside list items can also have the paragraph style. It translates to a paragraph@role="listitem" in the help file.


 * hlp_tablehead


 * This is the style to be used for table header cells. It translates to a paragraph@role="tablehead" in the help file when the main_transform.xsl stylesheet is used.


 * hlp_tablecontent


 * This is the style to be used for table content cells. It translates to a paragraph @role="tablecontent" in the help file.


 * A couple of hlp_aux_* styles


 * These are not meant to be used by the writers. These styles designate paragraphs that contain structural information rather than content.

Creating New Styles
If the styles in the pre-defined set are not sufficient for your purpose you can create new styles as long as they follow these rules:
 * A new paragraph style must be based on the hlp_default style
 * The style name must begin with hlp_
 * The style name must not begin with hlp_aux_

You can use these styles in the help document. They will be transformed to values of the role attribute for a paragraph in the help file, for instance, hlp_mystyle will result in a paragraph with the role set to mystyle.

This style will be reconstructed when the help file is loaded. But any formatting information for OpenOffice.org will be lost. Also, the style will only be available in that file. If you want the style to be available for all documents and have a defined appearance it must be added to the help authoring template.

In order to have a special appearance in the final help, the role must also be addressed in the stylesheets that are delivered with the help and define its appearance.

Changing A Paragraph Style
Changing the style of a paragraph has no impact on the localization process. Only the contents of a paragraph (including inline elements) are subject to localization.

Changing A Character Style
Changing the style of a character inside a paragraph does have an impact on the localization of that paragraph since the character style transforms to an inline element.

Moving A Paragraph Inside A Help File
You can safely move a paragraph in a help file without the need of further action. The paragraph styles might need adjustment if the paragraph is moved to a different context in a help file.

Moving A Paragraph To A Different Help File
Moving a paragraph from one file to another is a sequence of deleting and creating that can be accomplished by cutting and pasting the paragraph without its meta data.

Excluding A Paragraph From Localization
Paragraphs can be excluded from localization. In this case, the localized help files contain the English source for the corresponding paragraph. This is controlled by the localize attribute of a paragraph. If it is set to false the paragraph will not be localized, in all other cases it will.

To exclude a paragraph from localization choose Help Authoring - Paragraph - Exclude from L10N.

Adding A Table

 * 1) Choose Help Authoring - Table - Insert Table
 * 1) Insert the initial number of rows and columns in the corresponding text boxes.
 * 2) You can change the table layout after creation, if required.
 * 3) The width and height values are currently unsupported.
 * 4) If required, insert a table caption in the Caption text field.
 * 5) You can exclude the caption from localization by clearing the Localize check box.
 * 6) Click Ok

The created table is followed by a paragraph containing the caption, if a caption was defined.

Modifying The Table Layout
After creation of the table you can change the table layout to suit your needs. You can add or remove rows or columns.

Initially, the column widths will be distributed equally. You can manually resize the column widths but for now this will be lost on next reload.

▷ Never ever merge cells. Complex layouts are untested and  can  lead to unexpected results.

Deleting A Table
Delete a table as usual in OpenOffice.org. Make sure that the trailing paragraph with the caption is also removed.

Using A Table For Formatting Purposes
Don't do that.

There are still many places in the help files that use tables for formatting. We will try to get rid of these occurrences over time.

Adding A Caption To An Existing Table
When you have created a table and want to add a caption to it proceed as follows:


 * 1) Place the cursor after the paragraph containing the table attributes. In any other place the script will reject adding a caption.
 * 2) Choose Help Authoring - Table - Insert Table Caption
 * 3) Specify the caption text and click Ok.

Inserting, Removing, Modifying Lists
You can work with lists as you would usually do in OpenOffice.org if you note the following:

Interrupting A List
A list that is interrupted by a paragraph that is not part of the list, and then continued with the next number as displayed below on the left, is unsupported. If you create such a list in OpenOffice.org it will transform to the list below on the right after the reload. You will end up with two separate lists both starting with 1 (see Fig. 7).

Images in lists can be placed in such paragraphs. There is no need to mimic lists using table constructions.

Help Image Repository
Help images are stored inside the res/helpimg subdirectory of the default_images CVS module. Images that are used by the help need to be added to this repository module. See tools.openoffice.org for details on working with the OpenOffice.org CVS repository.

The helpimg directory contains all help images in English. Subdirectories for each language (except for the source language which is en-US ) contain the localized images. If an image does not need localization it only needs to be present in the helpimg directory. The subdirectories are named using the ISO codes for language and country as described on page 13.

To add an image to the repository You must mark the image as to be localized using the Help Authoring - Image – Image needs L10N  menu. An image that needs localization will appear with a red border in OpenOffice.org (not in the final help, of course). You can use Help Authoring - Image – No L10N for Image to clear the localization mark.
 * 1) Place the English image inside the res/helpimg directory of the default_images module.
 * 2) Place the localized images inside the corresponding language subdirectories of res/helpimg, for example zh-CN for simplified Chinese.


 * 1) Open the file helpimg.ilst in the util directory of the helpcontent2 module and add the English and all localized variants to the file. Keep the file entries sorted.

To Remove an Image from the Repository


 * 1) Remove the English and localized files from the CVS
 * 2) Open the file helpimg.ilst in the util directory of the helpcontent2 module and remove the corresponding file entries.

Inserting A Block Image
A block image is an image that is located in a paragraph of its own. It can contain a caption.

The image must be located inside the help file hierarchy as described in Setting Up the Environment.
 * 1) Choose HelpAuthoring - Image - Insert Image.
 * 2) Select an image file to insert and click Open.
 * 1) Specify an alternative text for the image (mandatory). This text is needed to comply with accessibility regulations.
 * 2) Specify a caption text for the image (optional).

The image will be added on a paragraph of its own surrounded by img tags. If you have specified a caption this caption text will appear inside imgcaption tags.

Inserting An Inline Image
An inline image is an image that is displayed inline in between paragraph text. It can not contain a caption.

The image must be located inside the help file hierarchy as described in Setting Up the Environment.
 * 1) Choose HelpAuthoring - Image - Insert Inline Image.
 * 2) Select an image file to insert and click Open.
 * 1) Specify an alternative text for the image (mandatory).

This text is needed to comply with accessibility regulations. The image will be added to the paragraph surrounded by img tags.

Adding An Image Caption
You can add a caption to an existing block image.


 * 1) Choose HelpAuthoring - Image - Insert Caption.
 * 2) Specify a caption and click Ok.

Embedding A Section Or Variable

 * 1) Choose Help Authoring - Embed Sections or Variables
 * 1) Enter the name of the file that contains the section or variable to be embedded in the File Name text box or click Browse to browse for a file. The path starts with the text directory in the help directory hierarchy (see this section).
 * 2) Select whether a variable (text block in a paragraph or the complete contents of a paragraph) or a section is to be embedded.
 * 3) Insert the section or variable ID or click Browse to browse all sections, variables, and paragraphs in the selected file.

Linking To Another Help File

 * 1) Mark the text that you want to appear as hyperlink.
 * 2) Choose Help Authoring - Insert Link
 * 3) Enter the name of the file to link to in the Link target box. The path starts with the text directory in the help file hierarchy. The path can contain a target anchor, for example, text/swriter/01/01020304.xhp#anchor
 * 4) Click Ok

Linking To The WWW
Proceed as with links to help files, but instead specify a WWW URL as link target.

Meta Data
The meta data are available through the Help Authoring - Meta Data menu that calls the Meta Data dialog:



Setting The Topic Title
On help file creation, the topic title is set to a generic string. This must be changed before finally saving the file.


 * 1) Choose Help Authoring - Meta Data
 * 2) Insert a topic title in the corresponding text box or click Fetch to fetch the topic title from the first heading in the document.

Setting The Topic ID
On document creation, the topic ID will be set from the file name. There is usually no need for setting the topic ID manually but you can do so by entering the ID in the corresponding text box. Characters that are not allowed are automatically stripped from the ID. Clicking Suggest creates an ID based on the filename (like when the file is created).

Excluding A File From The Search Index
By default, all files are included in the full text search index creation. You can exclude files form this search index by selecting the exclude option in the Indexing section.

Changing The Initial File Creation Comment
If you are do not like your initial comment you need to patch the xhp file.

Changing The Last Edited Comment
You can insert a comment when you edit and save a help file. This comment can be used to describe why a change was made and what changes were performed. A new comment overrides existing comments.

Bookmarks
Bookmarks host index entries, help IDs, and entries for the table of contents (TOC)

Adding A New Bookmark Set With Index Entries
Remember that an index entry transforms to an anchor target in the help file. Therefore, an index entry should always be placed directly above the text it refers to. Index entries that refer to the complete help topic should be placed at the top of the file. Enter the first and second level of the index entry in the Index Entry text boxes and click Add or press the Ins key to add it to the list of index entries. You can remove index entries from the list by selecting them and clicking Remove Selected.
 * 1) Place the cursor where you want the index entry to appear.
 * 1) Choose Help Authoring - Bookmarks - Insert Index Entries.
 * 1) Select Add parent bookmark tag to create a new set of index entries. If you want to add index entries to an existing set you need to clear this box (see next procedure).
 * 2) Click Ok.

Adding Index Entries To An Existing Bookmark Set

 * 1) Place the cursor inside the set of index entries where you want to add index entries.
 * 2) Choose Help Authoring - Bookmarks - Insert Index Entries.
 * 3) Compile the list of index entries that you want to add to the bookmark set like described in the previous procedure.
 * 4) Clear the Add parent bookmark tag box.
 * If the box is checked a new bookmark set with the specified index entries will be created after the set at the cursor position.
 * 1) Click.

Modifying Index Entries In An Existing Bookmark Set
If you need to modify an existing index entry (for instance, to correct a typographical error) delete and recreate this index entry as described previously.

Adding A New Bookmark Set With TOC Entries
TOC entries that refer to the complete help topic must be placed at the start of the help topic.
 * 1) Place the cursor where you want the TOC entry to appear.
 * 2) Remember that a TOC entry transforms to an anchor target in the help file. Therefore, a TOC entry should always be placed directly above the text it refers to.
 * 1) Choose Help Authoring - Bookmarks - Insert TOC Entries.



Enter the TOC entry string in the TOC Entry text box and click Add to add it to the list of TOC entries.

The TOC levels are separated using a slash /, for details see page 25.

You can remove TOC entries from the list by selecting them and clicking Remove Selected.
 * 1) Select Add parent bookmark tag to create a new bookmark set of TOC entries. If you want to add TOC entries to an existing bookmark set you need to clear this box (see next procedure).
 * 2) Click Ok.

Adding TOC Entries To An Existing Bookmark Set

 * 1) Choose Help Authoring - Bookmarks - Insert TOC Entries.
 * 2) Compile the list of TOC entries that you want to add to the bookmark set, as described previously.
 * 3) Clear the Add parent bookmark tag box.
 * 4) If the box is checked a new bookmark set with the specified TOC entries will be created after the set at the cursor position.
 * 5) Click Ok.

Determining A Help ID
The help ID inserted into the help file must either be the symbolic ID or an UNO command (see "hid" Branch on page 26). You can determine the numerical ID or the UNO command from the UI by setting an environmental variable  HELP_DEBUG  and setting it to TRUE before you start OpenOffice.org.

If the variable is set you will see the help ID of an element together with its extended tip whenever you rest the mouse over it (provided the extended tips are enabled). This help ID can either be


 * a numerical ID, in this case it must be converted to the symbolic ID before inserting it into the help file (see below)
 * an UNO command. This can be inserted into the help file without need for conversion

Adding A Help ID
Remember that a Help ID transforms to an anchor target in the help file. Therefore, the Help ID must be placed directly above the text it refers to and above any extended tip that it corresponds to. Help IDs that refer to the complete help topic must be placed at the beginning of the help topic. # Choose Help Authoring - Bookmarks - Insert Help ID.
 * 1) Place the cursor where you want the Help ID to appear.
 * 1) Insert the Help ID in the Help ID text box
 * 2) If you only have the numerical help ID, click Convert to Symbol to convert it to the symbolic Help ID. If this button is disabled you need to place a help_hid.lst file into the user/configuration directory of your OpenOffice.org installation.
 * 3) Click Ok.

Inline Switching
Inline switching uses conditional tags to switch parts of a paragraph for different context situations. An inline switch consists of an outer switchinline element that encloses one or more caseinline elements that define the conditions and optionally one defaultinline element. The complete switch must be in one paragraph.

   ...


 * 1) Place the cursor where you want the inline switch to start or select the text passage that you want in the first condition.
 * 2) Choose Help Authoring - Switching - Open Switchinline


 * 1) Select a switch type from the dialog. Currently, there are three switch types available:
 * 2) * System switches are used to switch between different platforms (Windows, Unix,...).
 * 3) * Application switches are used to switch between different applications (Writer, Calc, Draw,...)
 * 4) * Distribution switches are used to switch between open source and commercial distributions (OpenOffice.org, StarOffice,...)


 * 1) Click Ok
 * 2) Select the first condition ( caseinline ).

You can either select one of the pre-defined conditions from the list or specify your own condition string.




 * 1) Enter further conditions by selecting text and choosing Help Authoring - Switching - Insert Caseinline  for the corresponding switch type.  

There is no text allowed (including spaces or line breaks) between a closing and an opening tag inside an inline switch, e.g.

 wrong:   correct:    If you have inserted a default condition as described above, the switchinline element will automatically be closed.
 * 1) Optionally, insert a default condition by selecting text and choosing Help Authoring - Switching - Insert Defaultinline.
 * 2) Insert a closing switchinline element directly after the last caseinline element by choosing Help Authoring - Switching - Close Switchinline.

If you are not sure if you have actually created a valid switch choose Help Authoring - Validate  and you will be notified of any errors.

Switching Complete Sections Or Paragraphs
Other than inline switches, this type of switches encloses one or more paragraphs including graphics and tables. Similar to inline switches, they consist of an outer switch element that encloses one or more case elements that define the conditions and optionally one default element. Each of those elements must be in a paragraph of its own that is assigned the hlp_aux_switch style. The macros handle all that for you.

If you are in a non-empty paragraph the switch will start before that paragraph.
 * 1) Place the cursor where you want the switch to start.
 * 1) Choose Help Authoring - Switching - Open Switch



You can either select one of the pre-defined conditions from the list or specify your own condition string.
 * 1) Select a switch type from the dialog. Currently, there are three switch types available:
 * System switches are used to switch between different platforms (Windows, Unix,...).
 * Application switches are used to switch between different applications (Writer, Calc, Draw,...)
 * Distribution switches are used to switch between open source and commercial distributions (OpenOffice.org, StarOffice,...).
 * 1) Select the first condition ( case ).



If you are in a non-empty paragraph the condition will end after that paragraph. # Choose Help Authoring - Switching - Close Case to close a condition.
 * 1) Place the cursor where the condition ends.
 * 1) Now insert further conditions by
 * placing the cursor in the first paragraph of the condition
 * choosing Help Authoring - Switching - Open Case
 * placing the cursor in the last paragraph of the condition
 * choosing Help Authoring - Switching - Close Case.

There are no paragraphs allowed between a closing and an opening tag inside an switch, for example:

Wrong:

{Some other text, even an empty paragraph}

Correct:

If you have inserted a default condition the switch will automatically be closed.
 * 1) You can optionally enter a default condition as follows:
 * place the cursor in the first paragraph of the default condition
 * choose Help Authoring - Switching - Open Default
 * place the cursor in the last paragraph of the default condition
 * choose Help Authoring - Switching - Close Default.
 * 1) Close the switch by placing the cursor directly behind the last case element and choosing Help Authoring - Switching - Close Switch.

If you are not sure if you have actually created a valid switch, choose Help Authoring - Validate  and you will be notified of any errors.

Extended Tips
Extended tips come in two flavors, visible and hidden. Visible extended tips are part of the normal help text while hidden extended tips are hidden from the normal help content. Each extended tip is assigned a help ID to which it responds.

If you enclose text by a hidden extended tip this text portion will no longer be visible in the help viewer. 
 * 1) Select the part of the paragraph that you want to use as extended tip. An extended tip must not be spread over multiple paragraphs.
 * 2) Choose Help Authoring - Insert Visible Extended Tip or Help Authoring - Insert Hidden Extended Tip.
 * 1) Insert a help ID to be assigned to the extended tip. Note the comment about help IDs above.

Sorting
Sorting is a new feature in OpenOffice.org Help. It can be used to sort sections based on their content. This is useful, for example, for glossaries or other sorted lists that are localized and would otherwise lose their correct sort order.

In the current implementation the sort element sorts the content of sections. The sort element must not have any other child elements than section s.
 * 1) Place the cursor before the first section to be sorted.
 * 1) Choose Help Authoring - Sorting - Open Sort
 * 2) Place the cursor after the last section to be sorted.
 * 3) Choose Help Authoring - Sorting - Close Sort

Validating
There is a basic validation procedure available that tests the help files before they are exported from OpenOffice.org. To call it, choose Help Authoring - Validate.

Note that this procedure catches some of the most common and severe errors but it is not fool-proof. It does not perform an XML validation on the file.

It is, however, recommended to validate a file before saving.

A Help File Cannot Be Opened
The reason is probably an invalid help xhp file. To verify this, open the help file in any XML or text editor and check its validity. Fix any invalid syntax and reload the file.

If the XML file is valid and you cannot open any help file, see below.

A Help File Cannot Be Saved
The reason could be insufficient access rights to the directory or file you want to save to. Change the access rights accordingly.

If you cannot save any help file, see below.

No Help File Can Be Opened Or Saved
The reason is probably a corrupted XSLT export/import filter. Occasionally, installing the help authoring filter produces an error in the xsl files. To repair this proceed as follows:

If you are familiar with XSLT


 * 1) Change to the user/xslt/Help directory of your OpenOffice.org installation.
 * 2) Open the import and/or export xsl file.
 * 3) Got to the end of the file and check if there is any obvious duplicated content. Occasionally, the last lines of the stylesheet get duplicated. There must only be one single  tag in the file.

If you are unfamiliar with XSLT


 * 1) Get the help authoring filter package (see Installing the Import/Export Filters'' on page 76) and unpack it to a temporary directory.
 * 2) Copy the *.xsl  files from the Help subdirectory of the files that you just unpacked to the user/xslt/Help directory of your OpenOffice.org installation overwriting the existing files.

Paragraph Content Has Vanished On Reload
The reason is probably the use of a wrong paragraph format. Remember, that for paragraphs with content you must use one of the predefined hlp_* paragraph styles. See also Paragraphs and Paragraph Formatting on page 78.