Help File XML Editor
- 1 Introduction
- 2 Acessing the Help Editor
- 3 The Rendered Page [Tools -> Render page]
- 4 The Help Pages Checkings [Tools -> Check XHP]
- 5 Opening a Help File
- 6 Saving the File in Local Computer
- 7 Known Limitations
- 8 Setting the Help editor work place
The LibreOffice Help system is a set of XML files with specific Data Type Definition (DTD) suited for writing, refering and displaying applications Help.
The Help Editor (XHPEditor) is an online PHP application to allow opening, editing, display, verification and saving of Help (XHP) files.
Acessing the Help Editor
The current installation of the XHPEditor is in this address: https://newdesign.libreoffice.org/xhpeditor/index.php .
The left screen side
Contains the editor area and menu to perform editing commands and file operations.
The right screen side
The right area displays the rendered Help page or the result of a Help page verification.
- Commands for cut, copy, paste, cursor movements, page movement and more uses the common key combinations found in most text editors.
- Autocomplete: when typing the firsts characters of a XHP tag, the editor suggests its completion. Press ↵ Enter to accept the suggestion.
- Close tags: when typing '>' to end a tag, the corresponding closing tag is inserted just after.
- Search feature: Click on the editor text area and press Ctrl+F. Insert a regular expression and press Enter.
- Ctrl-F / Cmd-F : Start searching
- Ctrl-G / Cmd-G : Find next
- Shift-Ctrl-G / Shift-Cmd-G : Find previous
- Shift-Ctrl-F / Cmd-Option-F : Replace
- Shift-Ctrl-R / Shift-Cmd-Option-F : Replace all
- Alt-F : Persistent search (dialog doesn't autoclose, enter to find next, Shift-Enter to find previous)
- Alt-G : Jump to line
The Editor Menu
The menu contains commands to add XHP tags and predefined XHP contents to the help file.
- File: perform files operation.
- Open: Open a local Help file and loads into the editor.
- Save Local file: Saves the editor content to a local file. The name suggested is taken from the <filename> tag of the Help file.
- Edit: Commands for editing contents.
- Document: document-wide commands
- Start New XHP Document: cleans the editor contents (after confirmation pop-up) and adds the XML heading, license and mandatory tags for a new Help file. Fill the "CHANGE ME" placeholders with the right contents.
- DocHeading: Adds a set of tags for the heading of the help page.
- ahelp: Adds an <ahelp></ahelp> tag.
- Bookmarks: add several bookmarks type.
- Section: adds section tag and predefined named sections such as "Related topics" and "To access this command", and more.
- Tables: commands to insert tables and table fragments.
- Paragraphs: commands to insert paragraphs, notes, warnings and other special paragraphs. tip:select the text and apply the tags.
- Characters: commands to add characters attributes. tip:select the text and apply the tags.
- Headings: commands to add headings h1 to h4. tip:select the text and apply the tags.
- Switches: commands to add switches. Plus some special and very often used switches for MacOS.
- Lists: commands for lists.
- Links: commands for links, embeds, and so on.
- Tools: Command to render page, validation and other.
- Render page: displays the rendered XHP page on the right side of the screen. The rendered page has extra debug information, very usefull to check if the contents are correct.
- Get Patch: not implemented yet.
- Check XHP: perform XHP contents validation and display on the right side.
- Open Master: not implemented yet.
- Help: links to the XHP Reference page in wiki and command for the editor.
The Rendered Page [Tools -> Render page]
The rendered page on the right displays the page as it will shows on the DisplayArea <div> of the LibreOffice Help system, with some exceptions explained below:
- A row of radio buttons on the top allows selection of switches for system and aplications.
- Links are rendered in blue but are actually dead hyperlinks, to prevent clicking on them and leave the editor environment. Moreover, the rendered link would have been an invalid link in the editor environment.
- Images are displayed with their src attributes in magenta. This allows visual inspection of the src attribute if the image display is broken.
- Embedded contents are enclosed in a light grey box, with their href= displayed in magenta.
The Help Pages Checkings [Tools -> Check XHP]
Before submitting a patch to gerrit you must check if your edition conforms to the XML, DTD and translations requirements. The checkings verifies
- XML formation: verifies if the XML is well formed. Common mistakes are
- No proper closing tags,
- Proper use of XML entities (e.g. & or )
- Data Type Definition (DTD) compliance: Verifies if the XML edited is conformed ot the DTD. Common mistakes are
- Tags placed in wrong place. For example, a <paragraph> outside of a <body> tag.
- Missing required attribute. For example, missing "id=" attribute in <paragraph>.
- Wrong attribute for the tag. For example a role= attribute in a <note> tag.
- Duplicated id=: The Help translation process requires that every paragraph in a Help file must have an unique id= attribute within the file. This verification checks if paragraphs, notes, warning, tips, headings (1 to 6) have unique id's in the file. Common mistakes are
- You copied and pasted a paragraph in the editor and forgot to change the id= attribute.
- You pasted data from another source and was unlucky to get a duplicated id= .
Opening a Help File
Click Open button to open the browser file dialog and select a XHP file to edit.
Saving the File in Local Computer
When saving the editor contents into a file, the XHPEditor picks the file name from the <filename> tag of the Help page. The editor does not remember the location where the file was loaded originally and thus it actually creates a new file. You must ensure that the file is stored in the right place when pressing the save button of the browser file dialog.
- The editor handles one file at the time. Embedded contents and images are fetched from a server copy of the Help master branch updated manually (for the moment). If you update a file A and expect to have it embedded right away in file B, this will not work until the full cycle of patch submission and update is done.
- Patching the Help system must be done out of the XHPEditor for the moment. Use the git commands on the Help local copy to send patches.
- The editor does not render .tree files (used in the Contents section of the Help system) but you can actually edit the tree files XML. Just that the code snippets buttons should not be used in any case.
- Links are dead: as explained above, links are rendered but are not active.
- Bookmarks are transformed but - because of their nature - you can't see them (they are internal targets for hyperlinks).
- Image upload: The image upload is not considered in this implementation and must be performed out of the editor, directly patching the helpcontent2/ project.
- New Help files can be created and edited in the XHPeditor but its upload must follow the usual git command sequence (git add, git commit, git push and so on)
- When adding a new file to the Help system, remember to edit the right makefile of your local copy, before creating a commit. The makefiles to edit are
depending on the module the new Help page belongs.
Setting the Help editor work place
Obtaining a login for TDF services
Setting up a gerrit account
Cloning the Help Contents
For the moment, the best way to use the editor is to have a local copy of the helpcontent2/ project that you keep updated with the git commands.
To clone the HelpContents2 submodule
git clone https://gerrit.libreoffice.org/help helpcontent2
all Help files are in helpcontent2/ folder
To keep your local copy updated
git pull -r
However, we advise to get familiar with git commands when dealing with the repositories and local copies of the helpcontent2/ project.