Documentation/New Help Content

    From The Document Foundation Wiki

    This page will describe the steps to create new articles or modify existing ones in the offline and online help of LibreOffice, in its new presentation mode, with a modern browser.

    Help files are in .xhp file format, they are XML files which, inside LibreOffice, are transformed in HTML file format. Therefore they will contain all the information necessary to this transformation. LibreOffice is not a xml editor, styles and other elements are used to match the xml tags.

    Environment

    Warning.svg

    Warning:
    DO NOT INSTALL OR USE the HelpAuthoring Extension. It will break the improvements done in New Help.


    Retrieve the help files

    Help files are on LibreOffice git repository. Therefore you need to have a git environment installed on your computer.

    Command to retrieve the files

    git clone http://anongit.freedesktop.org/git/libreoffice/help.git 
    cd help

    The files you will need in a first time are located in the source/text directory

    Editing the files

    Use your preferred text editor with support for UTF-8.


    TODO: Review / fix below

    Opening/Saving

    Opening
    To open a help file, in the Help Authoring menu, choose Open or select the 'help' file type in the file picker under File ▸ Open and navigate to the .xhp file you want to work on.
    The document opens in Writer. Some information are not displayed like the par_id, but are noted with a small yellow mark. It is mandatory to use the styles provided by the template, any other style will be ignore when the file will be parsed.
    Saving
    When, saving the document, a check of the file is run. It doesn't check the syntax extensively, but make sure that there is no empty paragraph or that id are added.

    Help Authoring menu

    Menu Help Authoring

    • Create help file: creates a new .xhp file based on the template. If the template is not found, the file can't be created and an error message is displayed.
    • About: displays the version number of the extension
    • Set Document Root: selects the document as root file
    • Edit meta data: gives a title to the help file or leaves a comment. The Indexing button includes or ignores the file when running a search
    • Validate this help file: runs some checks on the xml structure of the file
    • Toggle l10n: sets the localize attribute on false:
    localize="false" - which appears as par_id0202201317491162_NOL10N in the document
    
    • Assign ID: adds an ID identifier to the paragraph
    • Insert Comment: adds a comment in the file
    <COMMENT>my comment here</COMMENT> 
    
    • Insert Table: inserts a table in the document
    • Insert Link: inserts a link to another file
    • Insert Help ID: inserts a bookmark branch tag of the type
    <BOOKMARK branch="hid/1234567" id="bm_id0202201317594049" localize="false"/>
    
    • Insert Index Entry: inserts tags marking an index entry
    <BOOKMARKVALUE>Insert;Name</BOOKMARKVALUE>
    
    • Insert Extendid tip: insert tags marking extended tips. The dialog box asks whether they are hidden. If you answer by YES, it will appear in the UI but not in the help.
    • Insert How to Get section: inserts a section named How To Get
    • Insert Image: inserts a link to a picture
    • Insert Section: inserts a section which name is the name of the section
    • Insert variable: inserts a variable, the dialog box names it
     <VAR ID="newvariable">
    
    • Transclude: incorporates another existing paragraph
    • Related topics section: inserts a 'Related Topics' section that links to other help articles. Usually placed at the end of the page.

    Unused/Ignored Tags and Attributes

    If you are editing the .xhp help files in a text editor, the following tags and attributes are ignored.

    • The <history> tag found in the <meta> tag
    • The l10n and oldref attributes of the <paragraph> tag.
    • The <alt> tag within the <image> tag
    • The width and height attributes of the <image> tag.
    • The status attribute of the <topic> tag.

    Make Images Appear

    Images shown in Help are found within LibreOffice's icon theme files and in order to get them to appear within the authoring tool, you would need to create a symbolic link between the helpauthoring tool's assumed location of images (i.e. [help repo base path]/../default_images) and a folder that contains the galaxy icon theme. The galaxy icon theme folder can either be through having a copy of the LibreOffice core git repo (found in icon-themes/galaxy/) or alternatively by grabbing the galaxy icon theme zip file that comes with an installation of LibreOffice (e.g. /opt/libreoffice/share/config/images_galaxy.zip, C:\Program Files\LibreOffice\share\config\images_galaxy.zip) and extracting it into a folder.

    Here is the Linux command to create the symbolic link with the core git repo if the help repo was located at ~/help

    ln -s ~/core/icon-themes/galaxy ~/default_images

    If the help repo is located in the helpcontent2 folder of the LibreOffice core repo, then use this command to create the symbolic link if the core repo is located at ~/core

    ln -s ~/core/icon-themes/galaxy ~/core/default_images

    Test Changes in LibreOffice Help Viewer

    It is possible to view the changes you make to the xhp help files within LibreOffice help viewer's, which is accessible by pressing F11 or Help ▸ LibreOffice Help.

    Without the LibreOffice Core Repo

    On Linux, open the script found at helpers/zip_help.sh and modify the last line to point to the folder in your LibreOffice installation that contains the help files (it normally ends in help/en-US/). Once modified, execute the script in the terminal and it will create the necessary packaged .jar help files and move them into the defined folder. If the script isnt modified, the .jar files will be left in the source/ folder and you can manually copy them to the LibreOffice help folder.

    With the LibreOffice Core Repo

    If you have the LibreOffice core repo, it has a blank helpcontent2 folder which you should put the LibreOffice help repo in, and with the help repo in that folder, you can run the make command and it will build the help files in core/instdir/help/en-US/, so that you can test them within your built version of LibreOffice.

    See also