Documentation/Help page description

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

We comment the contents of the LibreOffice Help file located in https://opengrok.libreoffice.org/xref/help/source/text/swriter/01/04020100.xhp

Header of the file

<?xml version="1.0" encoding="UTF-8"?>
<helpdocument version="1.0">
    <!--
    * This file is part of the LibreOffice project.
    *
    * This Source Code Form is subject to the terms of the Mozilla Public
    * License, v. 2.0. If a copy of the MPL was not distributed with this
    * file, You can obtain one at http://mozilla.org/MPL/2.0/.
    -->

The header of the file is constant and should not be changed.

The meta tags

<meta>
    <topic id="textswriter0104020100xml" indexer="include" status="PUBLISH">
        <title id="tit" xml-lang="en-US">Section</title>
        <filename>/text/swriter/01/04020100.xhp</filename>
     </topic>
</meta>

topic
- id: any string. Usually we combine some form of mnemonic string
- indexer: keep "include"
- status: Keep "PUBLISH"
title
- xml-lang: always en-US
- id: any string unique in the file
filename: full file name qualifier similar to the example

The body, sections and bookmarks

<body>
<section id="bereich">
    <bookmark xml-lang="en-US" branch="index" id="bm_id5941038">
        <bookmark_value>sections;inserting sections by DDE</bookmark_value>
        <bookmark_value>DDE; command for inserting sections</bookmark_value>
    </bookmark>
    <bookmark xml-lang="en-US" branch="hid/modules/swriter/ui/sectionpage/@@nowidget@@" id="bm_@@nowidget@@" localize="false"/>
    <bookmark xml-lang="en-US" branch="hid/modules/swriter/ui/sectionpage/SectionPage" id="bm_id3145414" localize="false"/>
    <bookmark xml-lang="en-US" branch="hid/modules/swriter/ui/editsectiondialog/EditSectionDialog" id="bm_id3145415" localize="false"/>
    <bookmark xml-lang="en-US" branch="hid/modules/swriter/ui/editsectiondialog/@@nowidget@@" id="bm_@@nowidget@@" localize="false"/>
    <paragraph role="heading" id="hd_id3157557" xml-lang="en-US" level="1">
         <link href="text/swriter/01/04020100.xhp" name="Section">Section</link>
    </paragraph>
    <paragraph role="paragraph" id="par_id3154644" xml-lang="en-US"><ahelp hid=".">Sets the properties of the section.</ahelp></paragraph>
</section>

body: identical to body in HTML
section: used here to wrap the contents into a container with name given by its id= attribute.
bookmark, branch="index": indicates that the following bookmark_values are keywords for the LibreOffice Help index.
bookmark_values: keywords or pairs or keywords (level1;level2) for the LibreOffice Help index.
bookmark, branch="hid/....": Sets the entry point to display the Help page. The string "hid/..." is defined in the software and is mapped to this help file when you press F1 or the help button in a dialog.
paragraph
- id: must be UNIQUE in the file.
- role: role of the paragraph. heading, paragraph, note, warning, tip, bascode, and more...
- level: combined with role="heading", sets the H1... H6 heading levels.
- xml-lang: keep always en-US.

The contents

The contents may include paragraphs, tables, section, objects, images, embedded contents, embedded variables, switches and more.

<paragraph role="paragraph" id="par_id171534888116942" xml-lang="en-US">%PRODUCTNAME Help pages are displayed in your system default web browser.</paragraph>
    <embed href="text/shared/05/00000100.xhp#neuehilfe"/>
    <paragraph xml-lang="en-US" id="par_id3156183" role="warning">The Help system for all versions of the software is based on the same source files. Some of the functions described in Help may not be included in this particular distribution. Some features specific to a distribution may not be mentioned in this Help.</paragraph>
(...)
(...)

paragraph role="paragraph": a normal paragraph
- id: An UNIQUE id for the paragraph within the file. This uniqueness ensure a perfect one-to-one link with the translated content of the translation process used in LibreOffice.
embed: this tag insert a piece of contents located in another file. When used correctly, it prevents repeated contents and spares translation work.

Predefined Sections

Some sections are predefined (special id), and will be transformed with special settings.

How to get

This section describes the actions to get the resource to work. Can be a menu path, a icon to press or a mouse click. This section is usually placed in the beginning of the description text.

<section id="howtoget">
  <embed href="text/swriter/00/00000404.xhp#bereicheinbereich"/>
</section>