Authoring Help With OpenOffice.org

TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate

• Wiki Home
• Development
• Design
• QA
• Events
• Documentation
• Website
• Localization
• Accessibility
• Marketing
• Diversity
• Wiki Help

• Documentation Home
• Official Publications
• Other Resources
• FAQ
• HowTo
• Macros
• Docs Development

Content on this page is licensed under the Public Documentation License (PDL).

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): ______________________________________.

Note: Original document stored at Apache OpenOffice Website

Authoring Help With OpenOffice.org

Obsolete A lot of the contents of this page is obsolete. To contribute to LibreOffice's Help pages, please refer to Documentation/Help. The information below stays here for legacy purposes.

Note The Help Authoring macros and templates were updated and packed in a LibreOffice extension. You can download the latest version in this page: http://dev-www.libreoffice.org/helpauthoring/

(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.

Note The help files use the extension xhp.

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.

Use 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 that are 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 Tools ▸ XML Filter Settings
4. Click Open Package
5. Browse to the filter package and click Open.
6. Click Close

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.

Note The macros are only tested with OpenOffice.org versions 1.1.x Feel free to contact fpe@openoffice.org if you want to port them to OOo 2.0!

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 Tools ▸ Macros ▸ Macro

1. Click Organizer
2. Click the Libraries tab
3. Click Append and browse to the temporary directory with the unpacked macros
4. Select the file script.xlb inside the macro directory and click Open
5. Select Replace existing libraries and click Ok
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.

Note For some tasks, the macro set needs to recognize the paths to your help files and images as described on this section. You will be asked to provide these paths once a macro needs it. The paths will then be stored inside your user/config directory in the file helpauthoring.cfg. You need to delete this file when the paths to your help files or images change.

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!

• 1. Get the menu archive helpauthoring_menu.zip from the helpers/helpauthoring directory of the helpcontent 2 CVS module.
  2. Choose Tools ▸ Configure and select the Menu tab
  3. Click Load
  4. Locate the helpauthoring_menu.zip file
  5. Select the file and then click Ok

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.

Note For now, not all attributes for the elements are supported for editing in OpenOffice.org. The major ones, however, are available.

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.

Note Any paragraph that does not have a paragraph style starting with hlp_ will be disregarded on export by the export filter. Its content will be lost on the next reload of that file.

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.

Note The images will only be displayed in OpenOffice.org correctly if the path to the image files was correctly specified in the import and export filters (see on page ).

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.

Note 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 item types that are created from the character styles must be transformed by the main transformation style sheet and/or assigned to formats using the style sheets of the help.

Working With the Help Files

Note Ensure that you have set up your work environment correctly as described in Setting Up the Environment.

Creating A Help File

1. Start OpenOffice.org and open a new empty Writer window.

The help authoring menu is only available in the Writer context. So you need to have a Writer window open.

1. Choose Help Authoring - Create New Help File.

You should always create a new file this way to ensure that all settings are made correctly.

1. Select a file name inside the help directory structure

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. 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 <Set Topic Title>. 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.

Note After the file is finished it needs to be added to the list of files to be processed by the help compiler.This is done by adding the file to the makefile of its directory. You can either do that manually or run the createmakefiles.pl script when you have finished working on the help files. For details, see Building the Help Set.

Opening A Help File

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

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

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.

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

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.

Note Note that moving a help file can create new localization effort since the moved help file looks like a brand new file to the localization process. However, translation memory systems should be able to automatically translate it because the content did not change - except for internal links.

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:
   • Place the cursor where you want to insert the new empty section.
   • Mark the piece of the document that you want to include in a section.
2. Choose Help Authoring - Insert Section
3. 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.

Note If you remove a section, ensure that no other file references it to avoid broken links.

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

<link href="text/shared/guide/file_name.xhp#section_id">

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.

Note If the ID of a paragraph gets lost or is changed it is regarded as new for the database and needs to be localized again. So tampering with IDs must be strictly avoided.

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).

Note Note that this attribute is evaluated nowhere. It only influences the display of the paragraph in OpenOffice.org (the meta data appear with yellow background). If you want to use it, you will have to take care of its evaluation in the context of content management yourself.

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 <item type=""> 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.

Note Ensure that you also move the paragraph meta data that are stored in the variable field at the start of the paragraph. If you copy a paragraph, however, never copy the meta data. The ID of a para-graph must be unique within 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.

Note For localization purposes, this will be recognized as a new paragraph.

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.

Tables

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

Note Nested tables are unsupported. You cannot insert a table in another table.

Note The meta data of the table are stored "encoded" in the Name property of the table in OpenOffice.org. This must be left untouched.

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.

Lists

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).

• Fig. 7: Incorrect list design
• 

  before

• 

  after reload

A list where the paragraph is unnumbered but is still part of the list item is supported and will work fine. In OpenOffice.org you achieve this by pressing the Backspace key once to get rid of the list number.

• Fig. 8: Correct list design
• 

  before and after reload

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

Working with Images

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

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.

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.

Note If the image is not marked as to be localized, the help will always display the English image regardless whether there are localized images available.

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.

1. Choose HelpAuthoring - Image - Insert Image.
2. Select an image file to insert and click Open.

The image must be located inside the help file hierarchy as described in Setting Up the Environment.

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.

1. Choose HelpAuthoring - Image - Insert Inline Image.
2. Select an image file to insert and click Open.

The image must be located inside the help file hierarchy as described in Setting Up the Environment.

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 Content

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

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.

Note The topic title must not be empty.

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

1. Place the cursor where you want the index entry to appear.

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.

1. Choose Help Authoring - Bookmarks - Insert Index Entries.

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. 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

Note You cannot mix different types of bookmarks (index entries, help ids, and TOC entries).

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.

5. Click Ok.

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

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.

TOC entries that refer to the complete help topic must be placed at the start of the help topic.

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

Note You cannot mix different types of bookmarks (index entries, help ids, and TOC entries).# Place the cursor inside the bookmark set of TOC entries where you want to add TOC entries.

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

Using an environmental variable

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

Note To convert the numerical help ID into a symbolic help ID you need a matching table called help_hid.lst that can be found in the helpers directory of the helpcontent2 module (see [[#page18|]]Structure of the CVS Help Module on page 18).

Note You can either use this mapping table to look up a symbolic help ID yourself, or you can place it into your local user/configuration directory of OpenOffice.org to allow the corresponding help authoring macro convert it for you.

Using dialog screenshots

An alternative method for help IDs identication is LibreOffice dialog screenshot enablement. Clicking selected parts of captured dialogs provides bookmarking assistance for help IDs.

Adding A Help ID

1. Place the cursor where you want the Help ID to appear.

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. 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.

Switching Content

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.

<switchinline select="switch_type">
<caseinline select="condition_1"></caseinline>
<caseinline select="condition_2"></caseinline>
...
<defaultinline></defaultinline>
</switchinline>

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:
   • 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. 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: </caseinline> <caseinline> correct: </caseinline><caseinline>

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 have inserted a default condition as described above, the switchinline element will automatically be closed.

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.

Note The pre-defined conditions are processed when the help is displayed. If you want to specify your own condition string, you will have to ensure that the condition is processed when the help is compiled (see this page) and displayed. Usually, you will only use the pre-defined conditions.

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.

1. Place the cursor where you want the switch to start.

If you are in a non-empty paragraph the switch will start before that paragraph.

1. Choose Help Authoring - Switching - Open Switch

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).

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

1. Place the cursor where the condition ends.

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. 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:

</case>
{Some other text, even an empty paragraph} <case>

Correct:

</case>
<case>

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 have inserted a default condition the switch will automatically be closed.

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.

Note The pre-defined conditions are processed when the help is displayed. If you want to specify your own condition string you will have to ensure that the condition is processed when the help is compiled (see this page) and displayed. Usually, you will only use the pre-defined conditions.

Miscellaneous

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.

Note In the current implementation, the hid attribute of the extended tip elements AVIS and AHID are not evaluated. The corresponding Help IDs must be placed as bookmarks in a paragraph before the extended tip. The extended tip will be shown for all help IDs specified as bookmarks after the last extended tip in the file.

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.

If you enclose text by a hidden extended tip this text portion will no longer be visible in the help viewer.

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.

Note Note that sorting does not work for embedded sections.

1. Place the cursor before the first section to be sorted.

In the current implementation the sort element sorts the content of sections. The sort element must not have any other child elements than sections.

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.

Troubleshooting

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 </xsl:stylesheet> tag in the file.

If you are unfamiliar with XSLT

1. Get the help authoring filter package (see [[#page76|]]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 [[#page78|]]Paragraphs and Paragraph Formatting on page 78.