Documentation/Help

    From The Document Foundation Wiki


    The LibreOffice Help underwent a radical change since version 6.1 and is now displayed in the system browser.

    Warning.svg

    Warning:
    The HelpAuthoring Extension is now considered DEPRECATED. Avoid using it to edit help pages as it can break the Help XML.


    Introduction to LibreOffice Help editing

    LibreOffice Help pages are text pages in XML (Extensive Markup Language). Here is a summary to help you in contributing to the Help project:

    My current skills Simple tasks (typos, grammar, linguistics) Medium tasks (update with respect to current version, menus reordering, better formatting) High volume (new pages on features, add images or multimedia, many files involved...)
    I have a Gerrit account, I know XHP Edit the XHP file directly in Gerrit Can be hard to edit in Gerrit; avoid. Even harder; avoid.
    I cloned the Help submodule, I can test locally, I have development skills and I know XHP Edit the XHP file locally, make, test and submit a patch Same as simple task Same as simple task
    None of the above, I'm not skilled in development, I have no skills in XML, but I'm good at documenting. Send a message to the documentation team. Describe the issue and give the link to the page that needs fixing. Open a bug report on Bugzilla for the "Documentation" component. Add as much info as possible, including the link to the page that needs fixing. Open a bug on Bugzilla to report the defect/enhancement. Add as much info as possible, even better if you attach files with the proposed contents.

    Documentation for Help editing

    A minimal knowledge on XML or even HTML is necessary. The XML for LibreOffice Help (also known as XHP) is not hard to catch if you know XML basic concepts. It will be useful for small changes until you get more familiar with the do's and don'ts of the LibreOffice Help files.

    Documentation for the understanding, authoring and editing of LibreOffice Help can be found in online version. These wiki pages are under revision and enhancement and will follow the development of LibreOffice Help resources.

    The most important wiki page for XHP is page 2: XHP Reference.

    The original PDF book is available: Understanding, Authoring and Editing OpenOffice.org HELP (PDF). Note that this book is now outdated.

    Editing LibreOffice Help Files directly in gerrit

    A complete page on the subject is available here

    Editing LibreOffice Help file in your local computer

    Sources of the LibreOffice Help with git

    The sources of the LibreOffice Help are in git. The easiest way to set everything up is to simply add this line into your autogen.input file inside your core LibreOffice directory:

    --with-help=html

    Now the next time you run make, the Help submodule will be cloned into helpcontent2 and automatically configured. The only manual configuration you need to do is to add the pushurl like so:

    cd helpcontent2 && git remote set-url --push origin ssh://logerrit/help

    From then on, you work with the git repository in the normal way:

    Read How to setup gerrit the first time, and How to send a patch for review. If you have trouble setting up, please contact the developers at #libreoffice-dev IRC:// channel, they will be glad to help you!

    Sources of the Help as packed archive

    Admittedly, git is the safest way to have the latest help source code. But if git is not a solution for you, you can download the Help source file as a tarball and uncompress it in your working directory.

    To download the latest help source code look for the latest version in this page

    http://download.documentfoundation.org/libreoffice/src/X.Y.Z/ where X, Y and Z must be replaced by the most recent version. For example, as of today (May 24th, 2017) X.Y.Z is 5.4.0 .

    Editing the Help

    A short manual describing how to author the help content is available here.

    How to find the file to work on

    When you have the sources of the help, and string you want to change (like to change the "wide variety of options" on https://help.libreoffice.org/Writer/Writer_Features#Designing_and_Structuring), do:

    cd helpcontent2
    git grep "wide variety of options"

    This will return you:

    source/text/swriter/main0503.xhp:<paragraph role="paragraph" id="par_id3147239" xml-lang="en-US" l10n="U" oldref="10">$[officename] offers ...
    

    which means this text is in source/text/swriter/main0503.xhp .

    How to change it

    Warning.svg

    Warning:
    The HelpAuthoring extension is DEPRECATED.


    Using a text-based editor

    Practically any text editor is able to open the file .xhp (for example, it is Kate in KDE, gedit in Gnome, or Notepad2 in Windows. You may want to use vim or any professional xml-editor).

    Note pin.svg

    Note:
    The text-based editor must support files in UTF-8.

    1. Open a Help file in the menu File ▸ Open or by using Open with... function from a file manager (for example in KDE, right-click on the file and select in popup menu Open with... ▸ Kate).
    2. For the reason that files may be very big and have a large number of xml-tags, you can use the find by file (usually Edit ▸ Find... or Ctrl + F).
    3. Make the necessary changes (if you are not confident with xml-tags of help files, make sure you have not touched them).
    4. Save the file.

    This method is good when we need to make minor changes without touching the xml-tags, for example, to correct a typing error.

    Using the XHP Editor assistant

    The Documentation XHP Editor offers some assistance in order to check .xhp files rendering. It does not support all .xhp tags, but covers a reasonable subset of them. The XHP Editor does not provide DTD compliance, which means permanent care is still necessary while editing an .xhp file.

    Understanding LibreOffice Help file structure

    Th LibreOffice Help file is composed of several mandatory parts. Look at this guided example.

    How to verify changes

    If you make changes or create a new page for Help, it is good idea to check how it will look in the interface. You must build the Help of LibreOffice.

    For the first time you need to build LibreOffice. In the future, this can be done from time to time to update the version. More information about the build of LibreOffice can be found on these pages: for Linux, for Windows, and for macOS.

    The local Help

    Use the option --with-help=html for autogen.sh when you build LibreOffice

    The resulting build is placed in instdir/help/ together with many companion files needed to navigate the pages. Open the file instdir/help/index.html from your browser or hit press F1 from your LibreOffice build to access the Help entry page.

    The online Help

    Use the option --with-help=online for autogen.sh when you build LibreOffice

    The resulting build is placed in instdir/help/X.Y together with many companion files needed to navigate the pages. X.Y is the major release you are building. To navigate in the online Help build locally, set a web server in your computer and make it open the page https://localhost/<path-to-instdir>/instdir/help/X.Y/index.html.

    Note pin.svg

    Note:
    The LibreOffice build takes 3 to 8 hours, depending on the capacity of your computer. Help build takes about 5 minutes per language.

    How to send it back for approval (via gerrit)

    Gerrit is a tool that allows easy review of changes that go into LibreOffice. Help uses the same workflow that is described in the wiki article for sending a patch for review. The detailed documentation about working in submodules are in a separate article.

    If you want to create a new change, create a new branch:

    cd <submodule>
    git checkout -b my_branch

    Edit the files in helpcontent2 and commit your changes inside the directory. While in the helpcontent2 directory, submit to Gerrit with this command

    git push origin my_branch:refs/for/master

    Once your submodule patch is merged, you can delete 'my_branch':

    ./g checkout master
    cd <submodule>
    git branch -D my_branch

    By using the ./g script, you do not need to worry about git submodule update.

    If you get a gerrit error about not having a Change-ID, run this command in the core directory:

    ./g -z

    If that command does not help, follow the advice in the error "Hint: To automatically insert Change-Id, install the hook:".

    See also