Rules for writing Help pages contents

From The Document Foundation Wiki
Jump to: navigation, search


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.

Gnome-dialog-warning.svg

Warning:
Always check your XHP files before submitting a patch.


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
Gnome-dialog-warning.svg

Warning:
The following tags always triggers re-translation when the tag contents changes, including tag attributes such as roles, levels, or id's and internal tags such as <emph>, <item> etc...

  • <paragraph>, <h1>, ..., <h6>, <note>, <tip>, <warning> .
  • <bookmark_value>
  • <image>, <object>

Avoid changes in these tags without a very good reason.



  • 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.