Documentation/Screenshots

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

Other languages:

Screenshots for documentation

This page describes how to create screenshots of LibreOffice dialogs and include them in LibreOffice documentation/help. The precondition is to have a git clone of LibreOffice help repository and/or to build core LibreOffice code including help (--with-help switch). For screenshots in multiple languages, build with --with-lang=$language_list, where $language list is a list of two- or three-letter language codes separated by space, for example en-us de fr es ru

Basic concepts

Every LibreOffice dialog has a Help ID that uniquely identifies it (so that help browser knows which help page to display when the user invokes help for a particular dialog). Help ID usually looks like this:

cui/ui/areatabpage/AreaTabPage

i.e. it resembles a path where this dialog's .ui file is stored. We have decided to have IDs of dialog screenshots (and thus file paths where screenshot images are stored) copy their help IDs in order to avoid maintaining of alternate mapping. Given that, the screenshot of the dialog above (Format ▸ Area) will be found in the following path:

cui/ui/areatabpage/AreaTabPage.png

and its localized version (where $language_code is a two- or three-letter code of the given language) in:

cui/ui/areatabpage/$language_code/AreaTabPage.png

Within LibreOffice (help) source tree, files with screenshot images that are included in help pages (.xhp files) are stored in the following folder:

helpcontent2/source/media/screenshots

in the paths corresponding to their screenshot IDs as outlined above.

Creating series of screenshots automatically

To create screenshots of every dialog in LibreOffice in one go, run:

make screenshot

in the root directory of your LibreOffice source tree. You can also create screenshots of individual modules. For instance, the following command creates screenshots of all LibreOffice Calc (sc) dialogs:

make sc.screenshot

After this command completes, the screenshot will be stored in the following folder in your LibreOffice source tree:

workdir/screenshots

in the paths corresponding to their screenshot IDs as outlined above. If you have built LibreOffice with multiple language/locale support (--with-lang, see above), this screenshot run will automatically create screenshots in all languages you are building with.

Creating screenshots manually

To create dialog screenshots from running LibreOffice, you need to activate screenshotting mode (akin to experimental mode) in Tools ▸ Options ▸ Advanced ▸ Open Expert Configuration, the relevant configuration key is org.openoffice.Office.Common.Misc.ScreenshotMode. Once screenshotting mode is active, right mouse click into any dialog action area (where "OK", "Cancel" etc. buttons are) will make a context menu appear:

Click Screenshot item of the context menu to create screenshot of the current dialog. In the dialog that appears, you'll see a screenshot preview and a text area. If you're happy with the result, click Save Screenshot... button to store the screenshot into the folder of choice, preferably directly to helpcontent2/source/media/screenshots folder and the path corresponding to their screenshot ID.

Explanation in video

Activate English subtitles:

Please accept this video. By accepting you will be accessing content from YouTube, a service provided by an external third party.

YouTube privacy policy

Including screenshots in help pages

If you have created screenshot with the help of make screenshot, copy the screenshot image from workdir/screenshots folder to helpcontent2/source/media/screenshot folder
If you have created screenshot manually, the best approach is to save it directly to helpcontent/source/media/screenshots, respecting screenshot ID path.

Now you can use your preferred way of editing help files (either manually or using HelpAuthoring extension). A .xhp snippet to be included in the help file can look for example like this (for the above area tab dialog, path to screenshot image highlighted):

<paragraph id="par_id083120160609088310" role="paragraph" xml-lang="en-US"><image id="img_id083120160608495768" src="media/screenshots/cui/ui/areatabpage/AreaTabPage.png"
 width="9.0417in" height="6.9791in"><alt xml-lang="en-US" id="alt_id083120160608495768">Area dialog</alt></image></paragraph>

Alternatively, when creating a screenshot manually, you can copy and paste the markup snippet as generated in the screenshot annotation dialog:

Committing your changes

This is no different from committing other changes to help content, the only gotcha is adding new files with screenshots under git version control:

git add source/media/screenshots/screenshot/you/have/added.png 
git add source/text/help/file/you/have/changed.xhp
git commit -m "Added new cool screenshots"