Help File XML Editor

    From The Document Foundation Wiki

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


    Introduction

    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.

    Warning.svg

    Warning:
    Any contents edition of the Help files must be done in English only. Help contents in other languages are obtained after the translation cycle and are carried in the Localization (L10N) project.


    Acessing the Help Editor

    The current installation of the XHPEditor runs at 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.

    The Editor

    The editor is a javascript software (CodeMirror) set to edit XML files. The editor has some nice editing features implemented.

    • 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


    Tip.svg

    Tip:
    You can copy a XHP contents from your favorite text editor and paste in the XHPEditor area to render it for you. You also can copy the XHPEditor contents and paste back to your favorite text editor.


    The Editor Menu

    The menu contains commands to add XHP tags and predefined XHP contents to the help file.

    Note pin.svg

    Note:
    Some commands are better used when performed on a selection. Select the contents and choose the desired menu. The contents will be enclosed by the selected tags. Use the feature with paragraphs, headings and character commands. Paragraph class of tags also get an unique id value within the 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.
    Tip.svg

    Tip:
    As example, type the help text in an empty line. Select the words to empahsize, click <emph> button. Select the whole line, click the <paragraph> button to generate a paragraph with id and some words emphasized.


    The Rendered Page [Tools -> Render page]

    Note pin.svg

    Note:
    The rendered page is obtained applying the stylesheet transformation to the Help page, but displaying only the DisplayArea <div> of the transformed page. In other words, the Contents, Search Index, Module, Donation and Language selectors of the LibreOffice Help system are not displayed

    .

    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

    1. XML formation: verifies if the XML is well formed. Common mistakes are
      • No proper closing tags,
      • Proper use of XML entities (e.g. &amp; or &nbsp;)
    2. 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.
    Tip.svg

    Tip:
    The current XHP reference and DTD is available in this page.
    1. 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= .
    Tip.svg

    Tip:
    The editor code snippets can produce automatic unique id by generating a random number combined with the clock time of your computer. If you hit a duplicated id in your Help file, chances are that you can fix it by changing only one digit of the id string


    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.

    Known Limitations

    • 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
      • AllLangHelp_sbasic.mk
      • AllLangHelp_scalc.mk
      • AllLangHelp_schart.mk
      • AllLangHelp_sdatabase.mk
      • AllLangHelp_sdraw.mk
      • AllLangHelp_shared.mk
      • AllLangHelp_simpress.mk
      • AllLangHelp_smath.mk
      • AllLangHelp_swriter.mk
      • Package_html_media.mk for media files
    • Table of contents need to be updated too when adding a new file
      • source/auxiliary/sbasic.tree
      • source/auxiliary/scalc.tree
      • source/auxiliary/schart.tree
      • source/auxiliary/sdraw.tree
      • source/auxiliary/shared.tree
      • source/auxiliary/simpress.tree
      • source/auxiliary/smath.tree
      • source/auxiliary/swriter.tree

    depending on the module the new Help page belongs to.

    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.

    Other important settings

    Source

    https://opengrok.libreoffice.org/xref/dev-tools/help3/xhpeditor/

    Retrieved from "https://wiki.documentfoundation.org/index.php?title=DocumentationHelpEditor&oldid=769784"