Rules for writing Help pages contents
TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate
Introduction
These rules are meant to help content creators and editors of the help files contents. They have been written by the past and then lost, but have been followed anyway by writers. Now that we have more contributors, it's time to have them set again in the wiki to preserve the consistency of the whole content. Be aware that when you introduce a change in the original content in English, it will be reflected in all the languages LibreOffice is translated on, so be cautious when you take the decision to modify the content.
Help XML (XHP) Reference
The complete list of XHP tags is described in details in this page.
Checking XML consistency
XHP files will be verified for compliance to the DTD by gerrit before merging and at build time. Therefore you must ensure that your changes in the XHP files are good for building the Help contents. The DTD file is located in
helpcontent2/helpers/xmlhelp.dtd
To verify the DTD conformance of your XHP editings in the file source/text/module/myfile.xhp, issue
cd helpcontent2/ xmllint --dtdvalid helpers/xmlhelp.dtd source/text/module/myfile.xhp
If all is OK, the xmllint command will print the XHP file in the terminal with no error, otherwise it will stop complaining either malformed XML - for example a tag not closed - or a DTD violation - for example, a XHP tag located where it should not be.
Formatting
- Keyboard Shortcuts:
- First letter of the shortcut key is capitalized: Ctrl
- There is no space between key combinations: Ctrl+Shift+O
- Paragraphs:
- Do not add <br\> to break a sentence (length is language dependent) instead add a new paragraph.
New XML tags
Since the patch [63954] was merged, the following tags can now be used as replacement some XHP tags
<div>-like tags
New Tag | Old tag & attribute | Notes |
---|---|---|
<bascode> | (none) | Starts a set of paragraphs with role="bascode". Used to display a block of BASIC code. |
<pycode> | (none) | Same as <bascode> but for Python code. |
<paragraph>-like tag
New tag | Old tag & attribute | Notes |
---|---|---|
<note> | <paragraph role="note"> | |
<tip> | <paragraph role="tip"> | |
<warning> | <paragraph role="warning"> | |
<h1> ... <h6> | <paragraph role="heading" level="1 ... 6"> |
<item>-like tag
New tag | Old tag & attribute | Notes |
---|---|---|
<menuitem> | <item type="menuitem"> | Used to highlight a menu path "File - New - Spreadsheet". |
<literal> | <item type="literal"> | Used to highlight contents taken document contents. |
<input> | <item type="input"> | Displays a tip on hovering the text. On mouse click, copies the contents to clipboard for usage in a LibreOffice document. Often used in Calc formula examples, but not restricted to Calc. |
<widget> | <item type="widget"> | Renders a reference to a dialog widget in a boxed text. |
<keycode> | <item type="keycode"> | Used to highlight a keystroke "Ctrl+Shift+O" |
Tips for XML Tags
- bookmark_value: do not add space between elements separated by semicolon (;), this is only a mark to delimiter the index entries
- On writing BASIC code, PYTHON code or Starmath code, please evaluate if the contents must be translated. If the contents does not need to be translated, please add attribute localize = "false" to the paragraph. Examples:
Code | Recomended Tagged paragraph | tagged paragraph |
---|---|---|
Dim A as String | <paragraph role="bascode" id="par_id815" xml-lang="en-US" localize="false">Dim A as String</paragraph> | The line is pure Basic code and does not need to be translated. |
Dim A as String 'comment at end of statement | <paragraph role="bascode" id="par_id815" xml-lang="en-US">Dim A as String ' comment at end of statement</paragraph> | Keep translatable because of the comment at end of statement. |
REM this is a BASIC comment statement | <paragraph role="bascode" id="par_id815" xml-lang="en-US">REM this is a BASIC comment statement</paragraph> | Keep translatable because the statement REM is a comment. |
ctx = XSCRIPTCONTEXT.getComponentContext() | <paragraph role="pycode" id="par_id815" xml-lang="en-US" localize="false"> ctx = XSCRIPTCONTEXT.getComponentContext()</paragraph> | The line is pure Python code and does not need to be translated. |
left lbrace x right none | <paragraph role="code" id="par_id3155960" xml-lang="en-US" localize="false">left lbrace x right none</paragraph> | No need to translate this Starmath code. |