Documentation/Proposed Extensions for XHP

From The Document Foundation Wiki
Jump to: navigation, search

Proposed extensions to XHP markup

Introducton

XHP markup was created for an ambitious objective of offline, online document display and content reuse. However its richness also carries a steep learning curve for Help contents newcomers.

The following proposed XHP extensions aims to simplify XHP markup for frequently used combinations of markup tags, besides making hopefully easier to read textual XML. It worth to note that the existing XHP markup is kept untouched, to preserve legacy contents.

Global rules

  • always preserve existing id=""
  • on textual tags, always add an id=""

Suggested XHP Extensions

Proposed XHP extension New Attributes XHP tags XHP Attributes HTML equivalent Notes Usage
h1 xml-lang, id, localize paragraph role="heading" level="1" h1 preserve id="xyz" in target tag !! <h1 id=123” localize=”true” xml-lang=”en-US”></h1>
h2 xml-lang, id, localize paragraph role="heading" level="2" h2 preserve id="xyz" in target tag same as h1
h3 xml-lang, id, localize paragraph role="heading" level="3" h3 preserve id="xyz" in target tag same as h1
h4 xml-lang, id, localize paragraph role="heading" level="4" h4 preserve id="xyz" in target tag same as h1
h5 xml-lang, id, localize paragraph role="heading" level="5" h5 preserve id="xyz" in target tag same as h1
h6 xml-lang, id, localize paragraph role="heading" level="6" h6 preserve id="xyz" in target tag same as h1
note xml-lang, id, localize paragraph role="note" Generate a 1-row, 2-cells table <note id=”123” localize=”true” xml-lang=”en-US”></note>
tip xml-lang, id, localize paragraph role="tip" Generate a 1-row, 2-cells table same as note
warning xml-lang, id, localize paragraph role="warning" Generate a 1-row, 2-cells table same as note
icontable same as <table> <table><tablerow> <table><tr></tr></table> Generate a 1-row, 2-cells table <icontable><iconimage /><icontext ></icontext></icontable>
iconimage same as <image > <tablecell><image> <td><img .../></td> cell that contains icon image <iconimage href=”path-to-img” alt=”alt text” localize=”true” />
icontext same as <paragraph> <tablecell><paragraph> <td><p>text icon</p> </td> cell that contains icon text <icontext localize=”true” xml-lang=”en-US”>text of the icon</icontext>
menuitem same as <item> <item> type=”menuitem” <span class=”menuitem”> <menuitem>File - New - Spreadsheet</menuitem>
input same as <item> <item> type=”input” <span class=”input”> <input>=SUM(A1:A200)</input>
keycode same as <item> <item> type=”keycode” <span class=”keycode”> <keycode>Ctrl + Shift + N</keycode>
literal same as <item> <item> type=”literal” <span class=”literal”> <literal>A1:A200</literal>
ol same as <list> <list> type=”ordered” ol
ul same as <list> <list> type=”unordered” ul

Extensions DTD

h1

This element is the top heading element holding content.

Attributes

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

Parent Elements

body, case, default, listitem, section, tablecell

Child Elements

embedvar, br, emph, help-id-missing, item, link, switchinline, variable, ahelp, bookmark, keycode, menuitem, input, literal

Element Definition

<!ELEMENT h1 (#PCDATA | comment | embedvar | br | emph | item | link | switchinline | variable | ahelp | bookmark | keycode | menuitem | input | literal)*>
<!ATTLIST h1 id CDATA #REQUIRED  xml-lang CDATA #REQUIRED localize CDATA #IMPLIED
>

Example

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

h2

This element is the heading level 2 element holding content.

Attributes

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

Parent Elements

body, case, default, listitem, section, tablecell

Child Elements

embedvar, br, emph, help-id-missing, item, link, switchinline, variable, ahelp, bookmark, keycode, menuitem, input, literal

Element Definition

<!ELEMENT h2 (#PCDATA | comment | embedvar | br | emph | item | link | switchinline | variable | ahelp | bookmark | keycode | menuitem | input | literal)*>
<!ATTLIST h2 id CDATA #REQUIRED  xml-lang CDATA #REQUIRED localize CDATA #IMPLIED
>

Example

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

h3

This element is the heading level 3 element holding content.

Attributes

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

Parent Elements

body, case, default, listitem, section, tablecell

Child Elements

embedvar, br, emph, help-id-missing, item, link, switchinline, variable, ahelp, bookmark, keycode, menuitem, input, literal

Element Definition

<!ELEMENT h3 (#PCDATA | comment | embedvar | br | emph | item | link | switchinline | variable | ahelp | bookmark | keycode | menuitem | input | literal)*>
<!ATTLIST h3 id CDATA #REQUIRED  xml-lang CDATA #REQUIRED localize CDATA #IMPLIED
>

Example

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

h4

This element is the heading level 2 element holding content.

Attributes

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

Parent Elements

body, case, default, listitem, section, tablecell

Child Elements

embedvar, br, emph, help-id-missing, item, link, switchinline, variable, ahelp, bookmark, keycode, menuitem, input, literal

Element Definition

<!ELEMENT h4 (#PCDATA | comment | embedvar | br | emph | item | link | switchinline | variable | ahelp | bookmark | keycode | menuitem | input | literal)*>
<!ATTLIST h4 id CDATA #REQUIRED  xml-lang CDATA #REQUIRED localize CDATA #IMPLIED
>

Example

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

h5

This element is the heading level 2 element holding content.

Attributes

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

Parent Elements

body, case, default, listitem, section, tablecell

Child Elements

embedvar, br, emph, help-id-missing, item, link, switchinline, variable, ahelp, bookmark, keycode, menuitem, input, literal

Element Definition

<!ELEMENT h5 (#PCDATA | comment | embedvar | br | emph | item | link | switchinline | variable | ahelp | bookmark | keycode | menuitem | input | literal)*>
<!ATTLIST h5 id CDATA #REQUIRED  xml-lang CDATA #REQUIRED localize CDATA #IMPLIED
>

Example

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

h6

This element is the heading level 2 element holding content.

Attributes

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

Parent Elements

body, case, default, listitem, section, tablecell

Child Elements

embedvar, br, emph, help-id-missing, item, link, switchinline, variable, ahelp, bookmark, keycode, menuitem, input, literal

Element Definition

<!ELEMENT h6 (#PCDATA | comment | embedvar | br | emph | item | link | switchinline | variable | ahelp | bookmark | keycode | menuitem | input | literal)*>
<!ATTLIST h6 id CDATA #REQUIRED  xml-lang CDATA #REQUIRED localize CDATA #IMPLIED
>

Example

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

note

This element adds a note paragraph holding content.

Attributes

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

Parent Elements

body, case, default, listitem, section, tablecell

Child Elements

embedvar, br, emph, help-id-missing, item, link, switchinline, variable, ahelp, bookmark, keycode, menuitem, input, literal

Element Definition

<!ELEMENT note (#PCDATA | comment | embedvar | br | emph | item | link | switchinline | variable | ahelp | bookmark | keycode | menuitem | input | literal)*>
<!ATTLIST note id CDATA #REQUIRED  xml-lang CDATA #REQUIRED localize CDATA #IMPLIED
>

Example

<note id="par4711_001" xml_lang="en-US">
You can paste content with <keycode>Ctrl + Ins</keycode>
</note>

tip

This element adds a tip paragraph holding content.

Attributes

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

Parent Elements

body, case, default, listitem, section, tablecell

Child Elements

embedvar, br, emph, help-id-missing, item, link, switchinline, variable, ahelp, bookmark, keycode, menuitem, input, literal,

Element Definition

<!ELEMENT tip (#PCDATA | comment | embedvar | br | emph | item | link | switchinline | variable | ahelp | bookmark | keycode | menuitem | input | literal)*>
<!ATTLIST tip id CDATA #REQUIRED  xml-lang CDATA #REQUIRED localize CDATA #IMPLIED
>

Example

<tip id="par4711_001" xml_lang="en-US">
You can paste content with <keycode>Ctrl + Ins</keycode>
</tip>

warning

This element adds a warning paragraph holding content.

Attributes

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

Parent Elements

body, case, default, listitem, section, tablecell

Child Elements

embedvar, br, emph, help-id-missing, item, link, switchinline, variable, ahelp, bookmark, keycode, menuitem, input, literal,

Element Definition

<!ELEMENT warning (#PCDATA | comment | embedvar | br | emph | item | link | switchinline | variable | ahelp | bookmark | keycode | menuitem | input | literal)*>
<!ATTLIST warning id CDATA #REQUIRED  xml-lang CDATA #REQUIRED localize CDATA #IMPLIED
>

Example

<warning id="par4711_001" xml_lang="en-US">
You cannot paste contents in read-only sections
</warning>

menuitem

This element is used to mark up menu items. This element resembles the element in HTML.

Attributes None

Parent Elements

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

Child Elements

none

Element Definition

<!ELEMENT menuitem (#PCDATA)> 
>

Example

<paragraph>You see the <menuitem>File Open</menuitem> dialog. </paragraph>

input

This element is used to mark up input items.

Attributes None

Parent Elements

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

Child Elements

none

Element Definition

<!ELEMENT input (#PCDATA)> 
>

Example

<paragraph><input>=SUMIF(A1:A10,">0",B1:B10)</input></paragraph>

keycode

This element is used to mark up a keystroke.

Attributes None

Parent Elements

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

Child Elements

none

Element Definition

<!ELEMENT keycode (#PCDATA)> 
>

Example

<paragraph>Press <keycode>Ctrl + Shift + V</keycode> to open paste special dialog box.</paragraph>

literal

This element is used to mark up a literal content.

Attributes None

Parent Elements

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

Child Elements

none

Element Definition

<!ELEMENT literal (#PCDATA)> 
>

Example

<paragraph>Fill the range <literal>A1:A100</literal> with data.</paragraph>

icontable

This element defines a table containing one row and 2 columns. 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

iconimage, icontext

Element Definition

<!ELEMENT icontable > <!ATTLIST table
name CDATA #IMPLIED width CDATA #IMPLIED height CDATA #IMPLIED unit CDATA #IMPLIED class CDATA #IMPLIED id CDATA #REQUIRED localize CDATA #IMPLIED
>

Example

<icontable id="tab4711" name="List of Shortcuts" width="90" unit="pct" class="myicontable">
<iconimage/>
<icontext> <paragraph>List of shortcuts</paragraph> </icontext>
</icontable>

iconimage (WIP)

This element carries information about icon image in the document.

Attributes


Attribute Required Contents Values allowed Description
src yes URL A URL pointing to the icon image.
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

icontable

Child Elements

alt

Element Definition

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

Example

<iconimage src="picture/win/common/writermainwin.svg" id="img4711" width="75" height="75">
<alt xml-lang="en-US" id="alt4711">Main program window</alt>
</iconimage>

icontext

This element holds contents of an icontable

Attributes

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

Parent Elements

icontable

Child Elements

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

Element Definition

<!ELEMENT icontext (section | paragraph | comment | embed | bookmark | image | list)*>
<!ATTLIST icontext class CDATA #IMPLIED localize CDATA #IMPLIED
>

Example

<icontext id="par4711_001" xml_lang="en-US"> <paragraph id="123" role="paragraph">Proceed as follows to write an italic character</paragraph> </icontext>