Documentation/Proposed Extensions for XHP

    From The Document Foundation Wiki

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

    Proposed extensions to XHP markup

    Introduction

    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

    Green rows means tags implemented.

    Proposed XHP extension New Attributes Old XHP tags Old XHP Attributes HTML equivalent Notes Usage
    h1 id, localize paragraph role="heading" level="1" h1 preserve id="xyz" in target tag !! <h1 id="123” localize=”false” ></h1>
    h2 id, localize paragraph role="heading" level="2" h2 preserve id="xyz" in target tag same as h1
    h3 id, localize paragraph role="heading" level="3" h3 preserve id="xyz" in target tag same as h1
    h4 id, localize paragraph role="heading" level="4" h4 preserve id="xyz" in target tag same as h1
    h5 id, localize paragraph role="heading" level="5" h5 preserve id="xyz" in target tag same as h1
    h6 id, localize paragraph role="heading" level="6" h6 preserve id="xyz" in target tag same as h1
    note id, localize paragraph role="note" Generate a 1-row, 2-cells table <note id=”123” localize=”true” ></note>
    tip id, localize paragraph role="tip" Generate a 1-row, 2-cells table same as note
    warning 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>
    p id, localize paragraph role="paragraph" <p class="paragraph"> preserve id="xyz" in target tag same as h1
    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.

    Note pin.svg

    Note:
    This element was introduced in LibreOffice

    Attributes

    Attribute Required Contents Values allowed Description
    id yes See #Common Attributes.
    xml-lang no 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,widget

    Element Definition 

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

    Example 

    <note id="par4711_001">
You can paste contents 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

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

    Retrieved from "https://wiki.documentfoundation.org/index.php?title=Documentation/Proposed_Extensions_for_XHP&oldid=643969"