Help File XML Reference

From The Document Foundation Wiki
Jump to: navigation, search


Heckert GNU white.svg

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
http://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): ______________________________________.
Im-jabber.svg

Note:
Original document stored at Apache OpenOffice Website

Help File XML Reference

This chapter lists all elements of the XML help file DTD in alphabetical order as presented in the Document Type Definition in the Appendix.

The element sections presented here all share a common structure. The name of the element serves as a heading and is followed by element details:

  • Element Description and Purpose
  • Attributes
  • Parent Elements
  • Child Elements
  • Element Definition
  • Element Example


Examples for elements can show an element within its parent or child context.

Common Attributes

The following attributes are common to several elements.

xml-lang

The xml-lang attribute designates elements that need localization. The localization process identifies elements to be localized by this attribute. It contains the language of the element it belongs to as a combination of language ISO code (ISO 639-1) and country ISO code (ISO 3166), separated by a dash.

xml-lang="en-US"

All elements containing text to be translated have an xml-lang attribute: alt, bookmark, caption, paragraph, and title.

You can use the comment element to insert comments into the help file. But if they are outside an element that will be localized they will not be recognized by the localizers.

localize

The localize attribute can only take the value false and designates elements that are excluded from the localization process. If an element contains the localize attribute set to false, its contents and the contents of all child elements should not be translated[1]. If the attribute contains any other value than false it will be ignored. The attribute is optional.

localize="false"

All elements containing text to be translated or subelements with text to be translated have an optional localize attribute: alt, body, bookmark, bookmark_value, caption, list, listitem, paragraph, section, switch, table, tablecell, tablerow, and title.

id

The id element contains a unique string used to identify the element for localization and referencing purposes. The ID must be unique within a help file so that referencing across files and relocating sections and paragraphs across files is possible.

id="some_unique_value"

All elements that can be embedded or have to be translated contain a mandatory id attribute: image, bookmark, paragraph, section, table, title, topic, and variable.

Valid characters for the id value are capital or small letters from a-z, numbers from 0-9, and the underscore, in any combination. Other characters are not allowed[2].

Help File (*.xhp) Elements

ahelp

This element designates text that is to be used as extended tips (for instance, tool tips or active help). It can contain text (PCDATA) and child elements. It can only be used as a child of a paragraph.

Attributes

Attribute Required Contents Values allowed Description
hid yes CDATA The symbolic help ID for which the content is to be displayed.
visibility no fixed value "hidden", "visible" The visibility of the ahelp content inside the help viewer. If set to "hidden" the content is only visible in the extended tips popup.

Table 1: Attributes of the ahelp Element

Parent Elements

caseinline, defaultinline, paragraph, variable

Child Elements

comment, embedvar, br, emph, item, link, variable

Element Definition

<!ELEMENT ahelp (#PCDATA | embedvar | br | comment | emph | item | link | switchinline | variable)*>
<!ATTLIST ahelp
hid CDATA #REQUIRED
visibility (hidden | visible) #IMPLIED
>

Example

<ahelp hid="HID_SOME_HID" visibility="hidden">
You will only see this text in the extended tips for the ui control with the help id HID_SOME_HID.
</ahelp>

alt

This element is used to specify an alternative text for an image. It corresponds to the HTML attribute of the same name and can only contain PCDATA that is localized (no markup).

Attributes

Attribute Required Contents Values allowed Description
xml-lang yes CDATA See #Common Attributes.
id yes CDATA A unique ID to identify the element, see #Common Attributes.
localize no fixed value "false" See #Common Attributes.

Table 2: Attributes of the alt element

Parent Elements

image

Child Elements

none

Element Definition

<!ELEMENT alt (#PCDATA)> <!ATTLIST alt
xml-lang CDATA #REQUIRED id CDATA #REQUIRED localize CDATA #IMPLIED
>

Example

<image src="img/imagefile.png" id="img_id1235">
<alt xml-lang="en-US" id="alt_id1235">Dialog File Open</alt> </image>

bascode

This element starts a Basic code sintax highlight

Im-jabber.svg

Note:
This element was introduced in LibreOffice

Attributes

None

Element Definition

<!ELEMENT bascode (paragraph+)>

Example

<bascode>
<paragraph role="bascode" id="par_id3156443" xml-lang="en-US" localize="false">Sub Dialog1Show</paragraph>
<paragraph role="bascode" id="par_id3148575" xml-lang="en-US" localize="false">    BasicLibraries.LoadLibrary("Tools")</paragraph>
<paragraph role="bascode" id="par_id3152463" xml-lang="en-US" localize="false">    oDialog1 = LoadDialog("Standard", "Dialog1")</paragraph>
<paragraph role="bascode" id="par_id3148646" xml-lang="en-US" localize="false">    oDialog1.Execute()</paragraph>
<paragraph role="bascode" id="par_id3147349" xml-lang="en-US" localize="false">End Sub</paragraph>
</bascode>


body

This element contains all help content information. It cannot itself contain any PCDATA, but rather only child elements.

Attributes

Attribute Required Contents Values allowed Description
localize no fixed value "false" See #Common Attributes

Table 3: Attributes of the body element

Parent Elements

helpdocument

Child Elements

section, paragraph, table, comment, bookmark, switch, embed, list, sort

Element Definition

<!ELEMENT body (section | paragraph | table | comment | bookmark | switch | embed | list | sort)*>
<!ATTLIST body
localize CDATA #IMPLIED
>

Example

<body>
<paragraph>This is the content of a help file</paragraph> </body>

bookmark

This element contains information about a bookmark used in the help files. The bookmark type is specified inside the branch attribute of the bookmark element while the bookmark value is defined in the child element bookmark_value. For more information about the bookmarking system in the help please refer to Defining Index, Contents, and Context Sensitivity on page 25.

Attributes

Attribute Required Contents Values allowed Description
branch yes CDATA “contents", “index", "hid" The bookmark type specified by the branch inside the unified bookmarks tree. See Defining Index, Contents, and Context Sensitivity on page Defining Index, Contents, and Context Sensitivity25]].
id yes CDATA A unique ID to identify the element, see #Common Attributes.
xml-lang yes CDATA See #Common Attributes.
localize no fixed value "false" See #Common Attributes.

Table 4: Attributes of the bookmark element

Parent Elements

body, case, default, section, topic, tablecell, listitem

Child Elements

bookmark_value

Element Definition

<!ELEMENT bookmark (bookmark_value)*> <!ATTLIST bookmark
branch CDATA #REQUIRED xml-lang CDATA #REQUIRED id CDATA #REQUIRED localize CDATA #IMPLIED
>

Example

<bookmark branch="contents" xml-lang="en-US" id="bm_id1234"> <bookmark_value>
StarOffice Writer Help/Working with Fields/Editing Field Contents </bookmark_value>
</bookmark>
<bookmark branch="index" xml-lang="en-US" id="bm_id9876"> <bookmark_value>
Formulas/Exporting </bookmark_value>
</bookmark>
<bookmark branch="hid/12345"/>

bookmark_value

This element contains the value of a bookmark. See Defining Index, Contents, and Context Sensitivity on page |25 for details.

Parent Elements

bookmark

Child Elements

embedvar

Element Definition

<!ELEMENT bookmark_value (#PCDATA | embedvar)*>

Example

<bookmark branch="contents" xml-lang="en-US" id="bm_123"> <bookmark_value>
StarOffice Writer Help/Working with Fields/Editing Field Contents </bookmark_value>
</bookmark>
<bookmark branch="index/scalc" xml-lang="en-US" id="bm_543"> <bookmark_value>
Formulas/Exporting </bookmark_value>
</bookmark>
<bookmark branch="index/scalc" xml-lang="de-DE" id="bm_543"> <bookmark_value>
Formeln/Exportieren </bookmark_value>
</bookmark>

br

This element can be used to place a manual line break. It works like the corresponding HTML <br> element. The element itself is empty.

Parent Elements

ahelp, caption, caseinline, defaultinline, paragraph, variable

Child Elements

none

Element Definition

<!ELEMENT br EMPTY>

Example

<paragraph>This line must have a <br/>'''manual'''<br/>line break.</paragraph>

caption

This element specifies the (optional) caption of an image or a table.

Attributes

Attribute Required Contents Values allowed Description
xml-lang yes CDATA See #Common Attributes.
id yes CDATA A unique ID to identify the element, see #Common Attributes.
localize no fixed value "false" See #Common Attributes.

Table 5: Attributes of the caption element

Parent Elements

image, table

Child Elements

embedvar, br, emph, item, link, switchinline, variable

Element Definition

<!ELEMENT caption (#PCDATA | embedvar | br | emph | item | link | switchinline | variable)*>
<!ATTLIST caption
xml-lang CDATA #REQUIRED id CDATA #REQUIRED localize CDATA #IMPLIED
>

Example

<table>
  <caption xml-lang="en-US" id="cp_1234">
 List of all <item type="productname">StarOffice</item> slots. </caption>
</table>

case

This elements holds the cases of a switch statement.

Attributes

Attribute Required Contents Values allowed Description
select yes CDATA Contains the value that is to be evaluated. See Switching Content on page 27 for more information.

Table 6: Attributes of the case element

Parent Elements

switch

Child Elements

paragraph, table, comment, bookmark, embed, list, switch, section

Element Definition

<!ELEMENT case (paragraph | table | comment | bookmark | embed | link | list | switch | section)*>
<!ATTLIST case
select CDATA #REQUIRED
>

Example

<switch select="sys">
<case select="WIN">
<paragraph>This appears in Windows.</paragraph> </case>
<case select="UNIX">
<paragraph>This appears in Unix.</paragraph> </case>
<default>
<paragraph>This appears in all other cases</paragraph> </default>
</switch>

caseinline

This element holds the cases for an switchinline statement.

Attributes

Attribute Required Contents Values allowed Description
select yes CDATA Contains the value that is to be evaluated. See Switching Content on page 27 for more information.

Table 7: Attributes of the caseinline element

Parent Elements

switchinline

Child Elements

image, embedvar, br, emph, item, link, switchinline, variable, ahelp, object

Element Definition

<!ELEMENT caseinline (#PCDATA | image | embedvar | br | emph | item | link | switchinline | variable | ahelp | object)*>
<!ATTLIST caseinline select CDATA #REQUIRED
>

Example

<paragraph>Press the
<switchinline select="sys">
<caseinline select="WIN">Ctrl</caseinline> <caseinline select="MAC">Apple</caseinline>
<defaultinline>any</defaultinline>
</switchinline> key to start.
</paragraph>

comment

This element is used for inserting comments into the help files used by the author/editor/translator. They are to be removed when the help files are compiled.

Attributes

none

Parent Elements

body, case, default, list, listitem, section, switch, tablecell

Child Elements

none

Element Definition

<!ELEMENT comment (#PCDATA)>

Example

<section>
<comment>FPE: This section is in a draft state!</comment>
</section>

created

This element holds the date of document creation and additional information (author or comment).

Attributes

Attribute Required Contents Values allowed Description
date yes CDATA
Contains the date of document creation in the format YYYY-MM-DDThh:mm:ss where:
YYYY = four-digit year
MM = two-digit month
DD = two-digit day of month
hh = two digits of 24 hour
mm = two digits of minute
ss = two digits of second

Table 8: Attributes of the created element

Parent Elements

history

Child Elements

none

Element Definition

<!ELEMENT created (#PCDATA)> 
<!ATTLIST created
date CDATA #REQUIRED
>

Example

<meta>
<history>
<created date="2002-05-20T15:15:00">New topic created</created>
<lastedited date="2002-06-20T15:15:00">Made changes</lastedited> </history>
</meta>

default

This elements holds the default values for a switch. It is evaluated if all case elements of a switch element evaluate to false.

Attributes

none

Parent Elements

switch

Child Elements

paragraph, table, comment, bookmark, embed, list, section

Element Definition

<!ELEMENT default (paragraph | table | comment | bookmark | embed | link | list | switch | section)*>

Example

<switch select="sys"> <case select="WIN">
<paragraph>This appears in Windows.</paragraph> </case>
<case select="UNIX">
<paragraph>This appears in Unix.</paragraph>
</case>
<default>
<paragraph>This appears in all other cases</paragraph> </default>
</switch>

defaultinline

This elements holds the default values for an inline switch. It is evaluated if all caseinline elements of a switchinline element evaluate to false.

Attributes

none

Parent Elements

switchinline

Child Elements

image, embedvar, br, emph, item, link, switchinline, variable, ahelp, object

Element Definition

<!ELEMENT defaultinline (#PCDATA | image | embedvar | br | emph | item | link | switchinline | variable | ahelp | object)*>

Example

<paragraph>Press the <switchinline select="sys">
<caseinline select="WIN">Ctrl</caseinline>
<caseinline select="MAC">Apple</caseinline>
<defaultinline>any</defaultinline>
</switchinline> key to start.
</paragraph>

embed

This element is used to embed content from a different source at the current position. The only elements that can be embedded from somewhere else are sections or paragraphs, which are identified by their URL. For smaller text fragments, embedvar can be used. See Embedding Content on page 28.

The optional role attribute can override the role of a paragraph. For embedded sections, the role attribute has no effect.

Attributes

Attribute Required Contents Values allowed Description
href yes URL A URL pointing to the content to be embedded. The URL has the form filepath#id. Filepath is the path of the file as contained in the jar archive.
role no see [[#page24|]]Paragraph Roles on page 24. The role in which the embedded paragraph will appear. If this attribute is specified the paragraph is displayed with this role overwriting its original role (not applicable for sections).
level no fixed values numerical value The heading level if the role attribute is set to "heading"

Table 9: Attributes of the embed element

Parent Elements

body, case, default, listitem, section, tablecell

Child Elements

none

Element Definition

<!ELEMENT embed EMPTY> <!ATTLIST embed
href CDATA #REQUIRED role CDATA #IMPLIED level CDATA #IMPLIED
>

Example

<embed href="text/swriter/guide/editing#4711"/>
<embed href="text/scalc/01/0123456#9876" role="warning"/>

embedvar

This element is used to embed smaller text fragments with and without markup, which were previously declared as being variables. See also [[#page28|]]Embedding Content on page 28.

Attributes

Attribute Required Contents Values allowed Description
href yes URL A URL pointing to the content to be embedded. The URL has the form filepath#id. Filepath is the path of the file as contained in the jar archive.
markup no fixed values "keep" "ignore" Specifies whether markup contained in the variable to be embedded is ignored or kept in the target position. The default is to keep markup within the text fragment.

Table 10: Attributes of the embedvar element

Parent Elements

ahelp, caption, caseinline, defaultinline, link, paragraph, variable

Child Elements

none

Element Definition

<!ELEMENT embedvar EMPTY> <!ATTLIST embedvar
href CDATA #REQUIRED
markup (keep | ignore) #IMPLIED
>

Example

<paragraph>This element can be found on the <embedvar href="text/swriter/01/dialogs#fileopen" markup="ignore"/>
dialog.</paragraph>

emph

This element is used to mark emphasized content. It can only contain PCDATA.

Attributes

none

Parent Elements

ahelp, caption, caseinline, defaultinline, link, paragraph, variable

Child Elements

item, comment, help-id-missing

Element Definition

<!ELEMENT emph (#PCDATA | item | comment)*>

Example

<paragraph><emph>Never</emph> delete the paragraph</paragraph>

filename

This element contains the path and name of the help topic file as included in the jar file, for example, text/swriter/01/1234567.xhp.

Attributes

none

Parent Elements

topic

Child Elements

none

Element Definition

<!ELEMENT filename (#PCDATA)>

Example

<filename>text/swriter/01/08154711.xhp</filename>

helpdocument

This is the root element of a help document and contains the meta and body part of the help topic.

Attributes

Attribute Required Contents Values allowed Description
version yes CDATA Contains the Help XML format version number currently 1.0) for compatibility to future versions.

Table 11: Attributes of the helpdocument element

Parent Elements

none

Child Elements

meta, body

Element Definition

<!ELEMENT helpdocument (meta, body)> <!ATTLIST helpdocument
version CDATA #REQUIRED
>

Example

<helpdocument version="1.0">
<meta></meta>
<body></body>
</helpdocument>

help-id-missing

This element is only used to display the help ID for a help file that cannot be found. It is only used in the help error page and replaced by the missing help ID.

Parent Elements

Child Elements

None

Element Definition

<!ELEMENT help-id-missing EMPTY>

history

This element contains information about the author and the date of creation, as well as the same information about the last editing cycle.

Attributes

none

Parent Elements

meta

Child Elements

created, lastedited

Element Definition

<!ELEMENT history (created, lastedited)>

Example

<meta>
<history>
<created date="2002-05-20T15:15:00">New topic created</created>
<lastedited date="2002-06-20T15:15:00">Made changes</created>
</history>
</meta>

image

This element carries information about images in the document.

Attributes


Attribute Required Contents Values allowed Description
src yes URL A URL pointing to the image as included in the picture archive picture.jar.
width no CDATA The image width. If missing, it is set to 100%.
height no CDATA The image height. If missing, it is set to 100%.
id yes CDATA A unique ID to identify the image, see #Common Attributes.
localize no CDATA Used to designate images that need localization. Used by the transformation style sheet. Only the value true is recognized.

Table 12: Attributes of the image element

Parent Elements

caseinline, defaultinline, paragraph, variable, tablecell

Child Elements

caption, alt

Element Definition

<!ELEMENT image (caption* | alt+)?> <!ATTLIST image
src CDATA #REQUIRED width CDATA #IMPLIED height CDATA #IMPLIED id CDATA #REQUIRED
>

Example

<image src="picture/win/common/writermainwin.xhp" id="img4711" width="75" height="75">
<caption xml-lang="en-US" id="cp4711">
The <emph>main writer windows</emph> showing all writer toolbars.
</caption>
<alt xml-lang="en-US" id="alt4711">Main program window</alt>
</image>

item

This generic element is used to mark up objects that are to be formatted in a unique way. The attribute type is used to specify the item type (a keystroke, a menu item, a dialog title etc). This element resembles the element in HTML.

Attributes

Attribute Required Contents Values allowed Description
type yes The item type that is used to format the data, for example "menuitem".

Table 13: Attributes of the item element

Parent Elements

ahelp, caption, caseinline, defaultinline, link, paragraph, variable, emph

Child Elements

none

Element Definition

<!ELEMENT item (#PCDATA)> <!ATTLIST item
type CDATA #REQUIRED
>

Example

<paragraph>You see the <item type="dialog">File Open</item> dialog. </paragraph>

lastedited

This element contains the date when the document was last edited inside the date attribute. Additional information can be specified as PCDATA.

Attributes

Attribute Required Contents Values allowed Description
date yes CDATA
Contains the date when the document was last edited, in the format
YYYY-MM-DDThh:mm:ss
where:
YYYY = four-digit year
MM = two-digit month
DD = two-digit day of month
hh = two digits of 24 hour
mm = two digits of minute
ss = two digits of second

Table 14: Attributes of the lastedited element

Parent Elements

history

Child Elements

none

Element Definition

<!ELEMENT lastedited (#PCDATA)> <!ATTLIST lastedited
date CDATA #REQUIRED
>

Example

<meta>
<history>
<created date="2002-05-20T15:15:00">New topic created</created>
<lastedited date="2002-06-20T15:15:00">Made changes</lastedited>
</history>
</meta>

link

This element contains a link to another document inside or outside the help system. For links to other help files, the URL syntax is

filename#anchor_target

with

  • filename

Path and name of the help file as contained in the help jar archive, for instance text/swriter/01/123345.xhp.

  • anchor_target

Anchor target to jump to (optional). These can be the IDs of bookmarks, sections, or paragraphs.

Attributes

Attribute Required Contents Values allowed Description
href yes URL
This contains the link address as
URL.
name yes This is the link name, needed to fulfill accessibility requirements.
type no This specifies the link type, for example, a popup. Currently not evaluated.
target no Can be used to specify a target frame.

Table 15: Attributes of the link element

Parent Elements

ahelp, caption, caseinline, defaultinline, paragraph, variable

Child Elements

emph, item, variable, embedvar, switchinline

Element Definition

<!ELEMENT link (#PCDATA | embedvar | emph | item | variable | switchinline)*>
<!ATTLIST link
href CDATA #REQUIRED name CDATA #REQUIRED type CDATA #IMPLIED target CDATA #IMPLIED
>

Example

Please refer to <link href="http://www.openoffice.org" name="Link to the OpenOffice.org Website">the <emph>OpenOffice.org</emph> website</link> for further details.
More details can be found in <link href="text/common/guide/overview.xhp" name="Link to the overview">the overview</link>.

list

This element represents ordered (numbered) and unordered (bulleted) lists. The element itself does not contain any PCDATA, but only child elements that carry the content or comments.

Attributes

Im-jabber.svg

Note:
Note that not all attributes are currently evaluated in the transformation style sheet (see also The Main Transformation Style Sheet on page 16)


Attribute Required Contents Values allowed Description
type yes
fixed
values
"ordered" or
"unordered"
Describes the list type as either being
ordered (numbered) or unordered
(bulleted).
startwith no CDATA The starting number of an ordered list; if omitted, the list starts with 1.
format no Fixed values "1", "i", "I", "a", "A"
The number format used in numbered (ordered) lists:
"1": arabic numerals
"i": small roman numerals
"I": capital roman numerals
"a": small letters
"A": capital letters
If omitted the list uses "1".
bullet no Fixed values "disc", "circle", "square" The bullet to be used in bulleted (unordered) lists.
localize no fixed value "false" See #Common Attributes
sorted no
fixed
values
“asc", “desc" Specifies whether the list should be sorted, either ascending or descending. If this attribute is not given, the list is not sorted. If it is given, the listitem child elements are sorted according to the current locale.

Table 16: Attributes of the list element

Parent Elements

body, case, default, section, tablecell

Child Elements

listitem, comment

Element Definition

<!ELEMENT list (listitem | (comment)*)+> <!ATTLIST list
type CDATA #REQUIRED startwith CDATA #IMPLIED
format (1 | i | I | a | A) #IMPLIED bullet (disc | circle | square) #IMPLIED localize CDATA #IMPLIED
sorted (asc | desc) #IMPLIED
>

Example

<list type="ordered" startwith="5" format="a">
<listitem>...</listitem>
</list>

listitem

This element holds the contents of a list in child elements.

Attributes

Im-jabber.svg

Note:
Note that not all attributes are currently evaluated in the transformation style sheet (see also The Main Transformation Style Sheet on page 16)


Attribute Required Contents Values allowed Description
format no fixed values "1", "i", "I", "a", "A"
The number format used in numbered (ordered) list items:
"1": arabic numerals
"i": small roman numerals
"I": capital roman numerals
"a": small letters
"A": capital letters
If omitted the list item uses the value set in the list.
bullet no fixed values "disc", "circle", "square" The bullet to be used in bulleted (unordered) list items.
localize no fixed value "false" See #Common Attributes
class no

Table 17: Attributes of the listitem element

Parent Elements

list

Child Elements

comment, section, paragraph, table, switch, embed, bookmark

Element Definition

<!ELEMENT listitem (comment | section | paragraph | table | switch | embed | bookmark)*>
<!ATTLIST listitem
format (1 | i | I | a | A) #IMPLIED bullet (disc | circle | square) #IMPLIED localize CDATA #IMPLIED
class CDATA #IMPLIED
>

Example

<listitem bullet="disc">
<paragraph>Insert the CD.</paragraph>
</listitem>

meta

This element contains sub-elements with data used to organize the help.

Attributes

None

Parent Elements

helpdocument

Child Elements

topic, history

Element Definition

<!ELEMENT meta (topic, history?)>

Example

<helpdocument>
<meta>
<history>...</history>
</meta>
<body>
</body>
</helpdocument>

object

This generic element contains information about objects to be embedded into the help page like audio or video files. It is reserved for future use.

Attributes


Attribute Required Contents Values allowed Description
type yes CDATA Specifies the mime type of the embedded object data.
id yes CDATA A unique ID to identify the image, see #Common Attributes.
data yes CDATA Specifies the object file.
height no CDATA Specifies the width of the object.
width no CDATA Specifies the height of the object.

Table 18: Attributes of the object element

Parent Elements

paragraph, caseinline, defaultinline, variable

Child Elements

none

Element Definition

<!ELEMENT object EMPTY> <!ATTLIST object
type CDATA #REQUIRED id CDATA #REQUIRED data CDATA #REQUIRED height CDATA #IMPLIED width CDATA #IMPLIED
>

Example

<object data="clock.svg" id="objClock" type="image/svg+xml" width="200" height="200">

paragraph

This element is the standard element holding content. The role attribute defines its context in greater detail. See also Paragraph Roles on page 24.

Attributes

Attribute Required Contents Values allowed Description
role yes CDATA Describes the current role of the paragraph, for example a simple paragraph or a heading or an example or a note. See also Paragraph Roles on page 24.
level no Defines the heading level if the paragraph role is set to "heading".
id yes See #Common Attributes.
l10n yes Contains the localization status of the old help files and is only used for migration purposes.
xml-lang yes CDATA See #Common Attributes.
oldref no CDATA This contains the reference number used by the old help files and is only used for migration purposes.
localize no fixed value "false" See #Common Attributes

Table 19: Attributes of the paragraph element

Parent Elements

body, case, default, listitem, section, tablecell

Child Elements

image, embedvar, br, emph, help-id-missing, item, link, switchinline, variable, ahelp, object, bookmark

Element Definition

<!ELEMENT paragraph (#PCDATA | image | comment | embedvar | br | emph | item | link | switchinline | variable | ahelp | object | bookmark)*>
<!ATTLIST paragraph role CDATA #REQUIRED level CDATA #IMPLIED id CDATA #REQUIRED l10n CDATA #REQUIRED
xml-lang CDATA #REQUIRED oldref CDATA #IMPLIED localize CDATA #IMPLIED
>

Example

<paragraph role="heading" level="1" id="par4711_001" xml_lang="en-US">
Italic characters
</paragraph>'
<paragraph role="paragraph" id="par4711_002" xml_lang="en-US">
Proceed as follows to write an italic character
</paragraph>

section

This element serves as a generic container for multiple elements to make them able to be embedded in other documents. Each section takes a unique ID which is used to identify it when embedded in other documents. Subsections are allowed. A section can only contain sub-elements.

Attributes

Attribute Required Contents Values allowed Description
id yes See #Common Attributes.
localize no fixed value "false" See #Common Attributes

Table 20: Attributes of the section element

Parent Elements

body, listitem, section, tablecell, case, default

Child Elements

section, paragraph, table, list, comment, bookmark, embed, switch, sort

Element Definition

<!ELEMENT section (section | paragraph | table | list | comment | bookmark | embed | switch | sort )*>
<!ATTLIST section id CDATA #REQUIRED
localize CDATA #IMPLIED
>

Example

<section id="4711"><paragraph>This applies to multiple applications</paragraph><section>

sort

This element is used to mark up a set of sections that are to be sorted. The sequence of the sections inside the sort element plays no role for the display sequence.

Im-jabber.svg

Note:
Note that sorting does not work for embedded sections.

Attributes

Attribute Required Contents Values allowed Description
order no fixed values "asc", "desc"
Defines the sorting order as being
ascending or descending.

Table 27: Attributes of the sort element

Parent Elements

body, section

Child Elements

section

Element Definition

<!ELEMENT sort (section+)> <!ATTLIST sort
order (asc | desc) #IMPLIED
>

Example

<sort order="asc">
<section id="123243">...</section>
<section id="24345">...</section>
</sort>

sub

This element is used to mark subscripts content. It can only contain PCDATA.

Attributes

none

Parent Elements

ahelp, caption, caseinline, defaultinline, link, paragraph, variable

Child Elements

item, comment, help-id-missing

Element Definition

<!ELEMENT sub (#PCDATA | item | comment)*>

Example

<paragraph>H<sub>2</sub>O is the water molecule</paragraph>


sup

This element is used to mark superscripts content. It can only contain PCDATA.

Attributes

none

Parent Elements

ahelp, caption, caseinline, defaultinline, link, paragraph, variable

Child Elements

item, comment, help-id-missing

Element Definition

<!ELEMENT sup (#PCDATA | item | comment)*>

Example

<paragraph>6.5 x 10<sup>5</sup> is 65000 in scientific notation</paragraph>


switch

This element is used to switch sections or paragraphs for different platform, application, distribution, target medium or language context. For switching content inside paragraphs, switchinline must be used.

Attributes

Attribute Required Contents Values allowed Description
select yes fixed values
"sys"
"appl"
"distrib"
"target"
"lang"
"ver"
Defines the context that is to be evaluated, see also Switching Content on page 27.
localize no fixed value "false" See #Common Attributes

Table 21: Attributes of the switch element

Parent Elements

body, listitem, section

Child Elements

case, comment, default

Element Definition

<!ELEMENT switch ((case | comment)* | default?)*> <!ATTLIST switch
select (sys | appl | distrib | target | lang | ver) #REQUIRED localize CDATA #IMPLIED
>

Example

<switch select="sys">
<case select="WIN">
<paragraph>This appears in Windows.</paragraph> </case>
<case select="UNIX">
<paragraph>This appears in Unix.</paragraph> </case>
<default>
<paragraph>This appears in all other cases</paragraph>
</default>
</switch>

switchinline

This element is used to switch parts of paragraphs for different platform, application, distribution, target medium or language context. For switching complete paragraphs or sections switch must be used.

Attributes

Attribute Required Contents Values allowed Description
select yes fixed values "sys", "appl", "distrib", "target", "lang", "ver" Defines the context that is to be evaluated, see also Switching Content on page 27.

Table 22: Attributes of the switchinline element

Parent Elements

caption, caseinline, defaultinline, paragraph, variable, link

Child Elements

caseinline, defaultinline

Element Definition

<!ELEMENT switchinline ((caseinline)+, (defaultinline?)?)> <!ATTLIST switchinline
select (sys | appl | distrib | target | ver | lang) #REQUIRED
>

Example

<paragraph>Press the
<switchinline select="sys">
<caseinline select="WIN">Ctrl</caseinline> <caseinline select="MAC">Apple</caseinline>
<defaultinline>any</defaultinline>
</switchinline> key to start.
</paragraph>

table

This element defines a table containing one or more tablerows. The table element itself only contains child elements.

Attributes

Im-jabber.svg

Note:
Note that not all attributes are currently evaluated in the transformation style sheet (see also The Main Transformation Style Sheet on page 16)


Attribute Required Contents Values allowed Description
name no CDATA Contains a table name.
width no CDATA Contains the width of the table in units as given in the units attribute. If omitted, the table width is set by the help viewer.
height no CDATA Contains the height of the table in units as given in the units attribute. If omitted, the table height is set by the help viewer.
unit no Fixed values "px", "pt", "cm", "in", "pct"
Contains the unit to be used for table width and height:
Px = pixels
Pt = points
cm = centimeters
in = inches
pct = percent (%)
If omitted, pixels (px) are used as units.
class no CDATA Contains a class descriptor for the table which can be used to assign special formats.
id yes CDATA See #Common Attributes.
localize no fixed value "false" See #Common Attributes

Table 23: Attributes of the table element

Parent Elements

body, case, default, listitem, section

Child Elements

caption, tablerow

Element Definition

<!ELEMENT table (caption*, tablerow+)> <!ATTLIST table
name CDATA #IMPLIED width CDATA #IMPLIED height CDATA #IMPLIED unit CDATA #IMPLIED class CDATA #IMPLIED id CDATA #REQUIRED localize CDATA #IMPLIED
>

Example

'''<table id="tab4711" name="List of Shortcuts" width="90" unit="pct" class="shortcutlist">'''
<caption>
<paragraph>List of shortcuts</paragraph>
</caption>
<tablerow>...</tablerow>
</table>

tablecell

This element contains child elements taking the cell content. Complex tables can be created using the rowspan and colspan attributes of tablecell.

Attributes


Im-jabber.svg

Note:
Note that not all attributes are currently evaluated in the transformation style sheet (see also The Main Transformation Style Sheet on page 16)


Attribute Required Contents Values allowed Description
colspan no CDATA Contains the number of columns spanned by this cell. If omitted, the cell spans 1 column.
rowspan no CDATA Contains the number of rows spanned by this cell. If omitted, the cell spans 1 row.
width no CDATA Contains the width of the table cell in units as given in the units attribute. If omitted, the table cell width is set by the help viewer.
unit no fixed values "px", "pt", "cm", "in", "pct"
Contains the unit to be used for width:
Px = pixels
Pt = points
Cm = centimeters
in = inches
pct = percent (%)
If omitted, pixels (px) are used as units.
class no CDATA Contains a class descriptor for the table cell, which can be used to assign special formats.
localize no fixed value "false" See #Common Attributes.

Table 24: Attributes of the tablecell element

Parent Elements

tablerow

Child Elements

section, paragraph, comment, embed, bookmark, image, list

Element Definition

<!ELEMENT tablecell (section | paragraph | comment | embed | bookmark | image | list)*>
<!ATTLIST tablecell colspan CDATA #IMPLIED rowspan CDATA #IMPLIED width CDATA #IMPLIED class CDATA #IMPLIED unit CDATA #IMPLIED localize CDATA #IMPLIED
>

Example

<table
id="tab_4711" name="List of Shortcuts" width="90" unit="pct" class="shortcutlist">
<tablerow>
<tablecell>Column 1</tablecell> <tablecell>Column 2</tablecell> <tablecell>Column 3</tablecell>
</tablerow>
<tablerow>
<tablecell colspan="2">
This cell spans 2 columns, namely column 1 and 2
</tablecell>
<tablecell>
This cell spans 1 column, namely column 3
</tablecell>
</tablerow>
</table>

tablerow

This element contains table rows, which themselves only contain table cells.

Attributes

Attribute Required Contents Values allowed Description
height no CDATA Contains the height of the table row in units as given in the units attribute. If omitted, the table row height is set by the help viewer.
unit no fixed values "px", "pt", "cm", "in", "pct"
Contains the unit to be used for height:
Px = pixels
Pt = points
Cm = centimeters
in = inches
pct = percent (%)
If omitted, pixels (px) are used as units.
class no CDATA Contains a class descriptor for the table row which can be used to assign special formats.
localize no fixed value "false" See #Common Attributes

Table 25: Attributes of the tablerow element

Parent Elements

table

Child Elements

tablecell

Element Definition

<!ELEMENT tablerow (tablecell+)> <!ATTLIST tablerow
height CDATA #IMPLIED class CDATA #IMPLIED unit CDATA #IMPLIED localize CDATA #IMPLIED
>

Example

<table id="tab_4711" name="List of Shortcuts" width="90" unit="pct" class="shortcutlist">
<tablerow>
<tablecell>Column 1</tablecell> <tablecell>Column 2</tablecell>
<tablecell>Column 3</tablecell>
</tablerow>
</table>

title

This is the title of the help page as displayed in the list on the Contents tab page, the Index list and the search results. The title content can not contain HTML entities like

' or &.

Attributes

Attribute Required Contents Values allowed Description
xml-lang yes CDATA See #Common Attributes.
id yes CDATA #Common Attributes.
localize no fixed value "false" See #Common Attributes.

Table 26: Attributes of the title element

Parent Elements

topic

Child Elements

none

Element Definition

<!ELEMENT title (#PCDATA)> <!ATTLIST title
xml-lang CDATA #REQUIRED id CDATA #REQUIRED localize CDATA #IMPLIED
>

Example

<topic>
<title xml_lang="en-US" id="tit1233">Opening a text document</title>
</topic>

topic

This element contains child elements with information about the current help topic.

Attributes

Attribute Required Contents Values allowed Description
id yes CDATA See #Common Attributes.
indexer no fixed value "exclude", "include" Specifies whether the current file is to be excluded from the indexing process. An excluded file cannot be found using the help search facility.

Table 27: Attributes of the topic element

Parent Elements

meta

Child Elements

title, bookmark, filename

Element Definition

<!ELEMENT topic (title+, filename, bookmark*)> <!ATTLIST topic
id CDATA #REQUIRED
indexer (exclude | include) #IMPLIED
>

Example

<topic id="4711" indexer="exclude">
<title xml_lang="en-US">Invisible help file</title>
<filename>text/swriter/01/08154711</filename>
</topic>

variable

This element is used to define reusable text fragments. The fragments can be embedded in other contexts by means of the embedvar element.

Attributes

Attribute Required Contents Values allowed Description
id yes CDATA See #Common Attributes.
visibility no fixed values "hidden", "visible" Specifies whether the element content will be shown in the help viewer. If this attribute is omitted, the variable will be visible.

Table 28: Attributes of the variable element

Parent Elements

ahelp, caption, caseinline, defaultinline, link, paragraph, variable

Child Elements

ahelp, embedvar, br, emph, item, link, variable, image, object, switchinline

Element Definition

<!ELEMENT variable (#PCDATA | ahelp | embedvar | br | emph | item | link | variable | image | object | switchinline)*>
<!ATTLIST variable id CDATA #REQUIRED
visibility (hidden | visible) #IMPLIED
>

Example

You may use the <variable id="dlg_FileOpen"><item type="dialog">Open a file</item></variable> to open a file.
<comment>List of menu names to be embedded</comment>
<paragraph xml_lang="en-US">
<variable id="menu_File" visibility="hidden">File Menu</variable> <variable id="menu_Edit" visibility="hidden">Edit Menu</variable> <variable id="menu_View" visibility="hidden">View Menu</variable>
</paragraph>

Contents File (*.tree) Elements

The contents files (*.tree) are used to specify the hierarchy displayed on the Contents tab page of the help viewer (see also Hierarchical List of Contents on page 10).

tree_view

This is the root element for a contents file.

Attributes

Attribute Required Contents Values allowed Description
version yes CDATA

Table 29: Attributes of the tree_view element

Parent Elements

none

Child Elements

help_section

Element Definition

<!ELEMENT tree_view (help_section)+>
<!ATTLIST tree_view version CDATA #REQUIRED
>

Example

<tree_view version="24-Aug-2004">
<help_section application="swriter" id="01" title="Installation">
...
</help_section>
</tree_view>

help_section

The help_sections are the top-most elements in the table of contents as displayed by the help viewer.

Attributes

Attribute Required Contents Values allowed Description
application yes CDATA Designates the help module that a help_section is referring to
id yes CDATA
title yes CDATA This is the title of a help_section as displayed in the help viewer

Table 30: Attributes of the help_section element

Parent Elements

tree_view

Child Elements

node, topic

Element Definition

<!ELEMENT help_section (node|topic)*>
<!ATTLIST help_section application CDATA #REQUIRED id CDATA #REQUIRED
title CDATA #REQUIRED
>

Example

<tree_view version="24-Aug-2004">
<help_section application="swriter" id="01" title="Installation">
...
</help_section>
</tree_view>

node

Nodes are the hierarchical elements that represent topic groups and contain help topics. In the help viewer, they are represented by book icons. Nodes can have subnodes.

Attributes

Attribute Required Contents Values allowed Description
id yes CDATA
title yes CDATA
This is the title of a node as displayed in the help viewer

Table 31: Attributes of the node element

Parent Elements

help_section

Child Elements

node, topic

Element Definition

<!ELEMENT node (topic)*>
<!ATTLIST node
id CDATA #REQUIRED title CDATA #REQUIRED
>

Example

<tree_view version="24-Aug-2004">
<help_section application="swriter" id="10" title="Common Topics">
<node id="1001" title="General Information">
<topic id="shared/text/shared/main0400.xhp">Shortcut Keys</topic>
...
</node>
</help_section> </tree_view>

topic

Topics are links that point to help files. The id attribute contains the URL of the file to be loaded. The element contains the file title.

When the script update_tree.pl from the helpers directory in the helpcontent2 module is used to update the tree files, the element content is automatically updated based on the file titles. This also applies to localized languages.

Attributes

Attribute Required Contents Values allowed Description
id yes CDATA

Table 32: Attributes of the topic element

Parent Elements

help_section, node

Child Elements

none

Element Definition

<!ELEMENT topic (#PCDATA)>
<!ATTLIST topic
id CDATA #REQUIRED
>

Example

 <tree_view version="24-Aug-2004">
 <help_section application="swriter" id="10" title="Common Topics">
 <node id="1001" title="General Information">
 <topic id="shared/text/shared/main0400.xhp">Shortcut Keys</topic>
 ...
 </node> </help_section>
 </tree_view>

  1. They are automatically excluded in the Sun release engineering localization process.
  2. For legacy reasons, the help files contain many IDs that are not valid XML "id" types. Therefore, the id attribute is defined in the DTD to be of the type CDATA.