Producing LibreOffice User Guides
TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate
| Previous: Chapter 1 | Up: Preface | Next: Chapter 3 |
Introduction
This document is for anyone working on the LibreOffice user guides, which are produced using LibreOffice for distribution in .ODT, .PDF, and possibly other forms such as ePub, wiki, or HTML.
It assumes some familiarity with Writer (the word processor).
 |
Note:
|
How to set up LibreOffice for working with user guides
When working on the user guides, you may need to change a few option settings in LibreOffice. You also need to download and install some files, and you may wish to create some AutoText and Table AutoFormat entries.
Change General options
- Wherever possible, use the default options of a clean LibreOffice installation and avoid user interface customization, if you plan to take screenshots of dialogs, toolbars and menus.
- Use the en-US locale that you set in ▸ ▸ ▸ ▸ box. It will enable the English USA spelling and grammar checking. Check if these tools are available in your installation.
- The setting for one General option ▸ ▸ ▸ ▸ is important for consistency when reviewing user guides and capturing some screens. Because the layout and appearance of default Open and Save dialogs vary with the user’s operating system, but the LibreOffice dialogs are the same regardless of the operating system, our guides use the LibreOffice dialogs in illustrations.
Change View options
The setting for one View option (Icon size and style) is important for consistency when capturing screens to illustrate our documents.
Go to ▸ ▸ ▸ and make sure the choices are
- Set Icon style in the User Interface section near the top to Colibre (SVG). Use of SVG (scalable vector graphics) provides perfect rendering when icons are resized.
- Set Icon size to Small for the Toolbar, Notebookbar, and Sidebar.
If you are using Ubuntu or another Linux distribution and the icon style drop-down list does not show Colibre as one of the choices, go into the distribution’s package manager and install the libreoffice-style-colibre package.
If necessary, you can download the Colibre SVG icon set from Media:Colibre_svg_icons.zip
(If necessary) Change Advanced options
Depending on what you are writing about, you may need to enable some of the options found in ▸ ▸ ▸ : Use a Java runtime environment, and Enable macro recording (may be limited). Normally you should NOT choose Enable experimental features (may be unstable), because most chapters of most books do not discuss them and having them enabled can cause some features to work different and/or some dialogs to have extra fields, which may be confusing to new users.
(If necessary) Download and install the Liberation fonts
 |
Tip:
|
The LibreOffice user guides use Liberation fonts. If these are not present on your computer, you need to download and install them. To make this easier, we have put a file containing these fonts in the Resources section the TDF NextCloud website.
- Download liberation-fonts-ttf-2.00.1.tar.gz from the TDF NextCloud server.
- Decompress this file, which contains a folder of .ttf (TrueType Font) files.
- Install the font files, using the procedures appropriate to your operating system. On Windows and macOS, this can be done by double-clicking on the font name and then clicking the Install Font button on the window that opens. If you know where fonts are stored on your system, you can also copy the font files into the appropriate folder; on Linux, copying font files into the appropriate folder is the standard way to install them.
When you next open LibreOffice, the fonts will be available for your use.
Download and install the chapter template
See Chapter 5, Using the LibreOffice chapter template, for instructions on how to download, install, and create a new chapter from the chapter template.
Naming conventions for LibreOffice user guides
Book initials used in filenames:
- GS = Getting Started
- BG = Base Guide
- CG = Calc Guide
- DG = Draw Guide
- IG = Impress Guide
- MG = Math Guide
- WG = Writer Guide
- LOOLG = LibreOffice Online
Naming convention for draft chapters
File names take the following form: AANxBB-Name_Author_Date, where AA=book initials, N=LibreOffice Version, x=the next digit in the version, BB=chapter number, Name=chapter name, Author=initials of author/editor/reviewer, Date=date of review: please use DDMmmYYYY, NOT all numerals).
In the chapter name, each word begins with a capital letter and there are no spaces between words.
For example, the third chapter of the LO 6.4 Writer Guide, Working with Text, updated by Jean Hollis Weber on 24 April 2020, has the following file name: WG6403-WorkingWithText_JHW_24Apr2020.odt
Naming convention for reviewed chapters
If you are reviewing a draft chapter, add your initials and change the date to the day you return the reviewed file. For example, Dan Lewis reviews the third chapter of the LO 6.4 Writer Guide on 15 May 2020. Dan saves the reviewed file with the name WG6403-WorkingWithText_JHW_DL_15May2020.odt
Naming convention for published chapters
Remove reviewers' initials and dates from the filename; otherwise the same as for draft chapters.
For example, the third chapter of the LO 6.4 Writer Guide, Working with Text, has the following file name: WG6403-WorkingWithText.odt
Naming convention for published books
File names take the following form: AANx-Name.odt, where AA=book initials, N=LibreOffice Version, x=the next digit in the version, and Name=book name (may be abbreviated).
In the book name, each word begins with a capital letter and there are no spaces between words.
For example, the file name for Getting Started [with LibreOffice 6.4] is GS64-GettingStarted.odt
Tracking progress using the Status spreadsheets
Each book has a status spreadsheet, discussed in Chapter 3.
When you are working on a chapter, please place your initials and the date in the Checkout column of the appropriate table on the Status spreadsheet for the book.
When you return the file to TDF NextCloud, please remove your initials and date from the Checkout column and add your initials and the date to the appropriate column (reviewed, edited).
How to create a new chapter from the template
See Chapter 5, Using the LibreOffice chapter template, for instructions.
How to create images for LibreOffice user guides
Images may be screen captures, photographs, or graphics (such as diagrams) created in Draw or another program.
This section describes how to create images that show what the reader needs to know, can be read easily on screen and when printed in grayscale.
Screen captures
Members of the Documentation team use a variety of operating systems and desktop themes (color schemes), but we want the images in our user guides to look reasonably consistent. Here are some suggestions for creating consistency.
- Preferably use a neutral (primarily grey or similar) theme with high contrast. Highlight colors can be green, blue, orange, dark gray, or brown. Green is the LibreOffice color, so that is a good choice.
- Use the Colibre icon set (in ▸ ▸ ▸ ), not Automatic (which can vary with your operating system). On the same page, set Icon size to Small.
- Capture only the required dialog or other area, or crop the image after capturing it. If you include the mouse pointer, be sure it is pointing to a relevant item, not randomly positioned.
|
Tip:
|
- Read the text carefully to ensure you set up any data that should be shown and have marked any selections (such as checkboxes or radio buttons) that are discussed. If the image is supposed to show the dialog before you make changes, be sure it does not show the results instead.
- We rarely need to capture the full LibreOffice window, except for the introductory chapters where the parts of the window are labelled and described. When a full window is required, reduce its size as much as possible (while retaining essential information) and then capture the image.
Cropping
Some screen captures can be used without further modification. Many, however, benefit from cropping (cutting off parts of the original image). There are two reasons for cropping: to fit an image on the page and still have the relevant parts readable, and to reduce wasted space and focus the reader’s attention on a particular portion of the screen.
Some screen capture programs have a feature for choosing an area when you do the capture. You can also crop the images in a graphics package. Do not crop them in LibreOffice itself, because that cropping is not retained when the file is exported to MediaWiki, HTML, and possibly other formats (PDF does retain the cropping).
Here are some suggestions for choosing what to crop:
- Focus the readers’ attention on the part being discussed, especially when the full dialog has already been shown and the text is referring to one particular part of it.
- Remove blank space in dialogs that are of standard size but use only a small portion of the area for data or selections. In most cases, cutting off the bottom portion (with the standard OK, Cancel, and Next buttons) does not reduce readers’ comprehension, especially when the full dialog has already been shown.
- Make a wide dialog (such as the ▸ one) fit on a page by cropping off the portion that is not essential to the discussion, for example the navigation tree on the left. In some cases (such as the dialog for customizing a Table of Contents), the optional Preview section can be deselected.
Annotation (labelling)
Do not use Writer's drawing tools to label an image. Instead, use Draw or a graphics package to label screen captures, group and save the result as a single image so the labels are part of the image. In addition, save the original as an editable file such as .ODG and upload it to the TDF NextCloud website along with the chapter .ODT file. When exporting to image format, prefer PNG format and set for maximum quality.
To assist translators, label images without text (such as toolbars) using numbers, not words, and put explanations in the figure caption. Screen captures with text (such as dialogs) need to be recaptured by the translators anyway, so you can label them with text.
When creating labels:
- Use a line weight and font size and weight that will be compatible with the surrounding text when the image is at its final size in the document (images may be reduced in size when in the document).
- Use a white background for the area surrounding an image, when labels are outside the image. You can use a light color for the background of labels placed inside an image (to help them be noticeable), but choose a color that will print as pale grey in black-and-white.
- Ensure all numbers or words in the labels are lined up neatly.
- When labelling dialogs, it is often best to put the labels above or below the image, not to the sides, to help fit the image on the Writer page. With small images, labels beside the image may work well or better; this is a matter of judgment.
Flowcharts and other diagrams
Do not use Writer's drawing tools to create flowcharts and other diagrams for use in published documents. Instead, use Draw or another program of your choice, and then export the diagram to PNG before including it in the Writer document. In addition, save the original as an editable file such as .ODG and upload it to the TDF NextCloud website along with the chapter .ODT file.
When diagrams contain text, use a line weight and font size and weight that will be compatible with the surrounding text when the image appears in the document.
If a diagram needs color to improve its usefulness, choose colors that provide good contrast when printed in black-and-white (grayscale). Consider using hatching patterns. Be sure any text has good contrast with its background when printed in grayscale.
How to export a drawing as an image
In the LibreOffice Draw page that contains the drawing:
- Select all the contents to be exported. You can select with the mouse of use Ctrl + A to select all the elements in the page.
- Group all elements ▸ ▸ or Ctrl + ⇧ Shift + G.
- Export image with ▸ , choose a name for the file and select PNG as file type. Click .
- The Export to PNG dialog opens (PNG is a raster-graphics file format that supports lossless data compression).
- Keep the size in pixels suggested and the resolution to 96 pixels/inch. Keep all other setting as default. Click .
How to insert images into ODT files
Reviewed by Olivier
To prevent images from moving around during editing (especially when you are adding or deleting text), please follow the procedure below.
|
Note:
|
- Have paragraph marks turned on (helps you to see what's happening, ▸ ).
- Press ↵ Enter at the end of a paragraph to create a new blank paragraph.
- Change the new paragraph’s style to Figure. The paragraph marker should now be centered on the page.
- Choose ▸ or use copy-and-paste to insert the image.
- Right-click on the image, and choose ▸ .
- Adjust the size of the image. Hint: Select one of the corner handles and drag to the desired size. The resizing will keep the image proportions.
- With the image selected, right-click and choose Caption. Select Figure as the Category (if it shows anything else in that box) and type the caption. If Figure is not one of the choices, type the word Figure in the Category box to create that category.
- When adding the caption, LibreOffice automatically adds a frame that contains the image and the caption paragraph. That frame needs some tweaks.
- Select the frame, right-click on it, and choose ▸ .
- Delete any spurious line break that may appear between the image and the caption.
- Click anywhere outside the frame to deselect it, then click in the caption line and change the paragraph style to Caption.
|
Note:
|
How to for syntax highlighting code
For consistent code color presentation please follow the procedure below to add colour to the existing style.
- Install Code Colorizer Formatter
- Configure with:
- ▸ ▸
- Library ▸ ▸ Macro Name RunCfgFmtDialog
- Set Code font, Font name Liberation Mono
- Set Code Paragraph style, Text paragraph style name Code
- All other settings are ignored
- Click OK
- The macro can be accessed from ▸ ▸ ▸ ▸ . Run:
- for selected text in any paragraph style, or
- for any text in paragraph if paragraph style is Code Paragraph style setting
To format numerous code sections follow https://books.libreoffice.org/en/GS73/GS7314-CustomizingLO.html#toc15 and assign macro to a keyboard shortcut, for example Ctrl + ⇧ Shift + S.
How to cross-reference within a document
Do not type in cross-references to other parts of the document, because those references can easily get out of date if you reword a heading, add or remove figures, or reorganize topics. Instead, use Writer’s automatic cross-references; when you update fields, all the references will update automatically to show the current wording or page numbers.
The Cross-references tab of the Fields dialog lists some items, such as headings, numbered paragraphs, and bookmarks. If figure captions, table captions, user-defined number range variables, and some other items have been defined in a document, they also appear in the Type list. You can leave this dialog open while you insert many cross-references.
To insert a cross-reference to a heading, figure, or other item shown on the Cross-references tab:
- In your document, place the cursor where you want the cross-reference to appear.
- If you are cross-referencing to a figure or table, type the word Figure or Table, followed by a space.
- Choose ▸ . On the Cross-references tab, in the Type list, click the type of item you are referencing (for example, Heading or Figure).
- Click on the required item in the Selection list, which shows both automatically created entries (for example Headings) as well as user-defined references (for example bookmarks).
- In the Insert reference to list, choose the type of reference required. The choices vary with the item being referenced.
- For headings, usually you will choose Reference (to insert the full text of the heading) or Page (to insert the number of the page the heading is on).
- For figures, choose Numbering (to insert the figure number) or Page (to insert the number of the page the figure is on). We do not use Category and Number, because that causes problems for the translation software.
- Click Insert.
Occasionally you might want to insert a cross-reference to something that is not automatically shown on the Cross-references page. Before you can do that, you must prepare the item as a target to be referenced. We generally use bookmarks for this purpose.
- Select the text you want to bookmark. Click ▸ .
- On the Bookmark dialog, the larger box lists any previously defined bookmarks. Type a name for this bookmark in the top box. Click OK.
Now you can cross-reference to the bookmark as described above.
How to cross-reference to another document
Writer provides methods for automatic cross-referencing to other documents (usually chapters in the same or different books), but we do not use them at this time. Instead, follow the instructions below.
- When refering to a chapter in the same book, use Chapter N, Chapter Title.
- When refering to a chapter in another book, use Chapter N, Chapter Title, in the [Component] Guide. Here the book title is in italics.
In both cases, it’s best to avoid referring to a section in the referenced chapter, because section names are more likely to change. Sometimes chapter numbers or names are changed; in that case, writers and reviewers need to manually change the references in other documents.
How to index a user guide chapter
This topic is on its own page.
How to update or review a chapter
Updating a chapter means to bring it up to date from the software version it was previously written for to the version that you are writing about.
Reviewing a chapter means that you are checking the work of the person who updated it, to see if they missed anything.
In both cases:
- Download the chapter from the TDF NextCloud website. (See Chapter 3 for details.)
- For updating, the folder is usually the Published folder for the previous edition of the book.
- For reviewing, the folder is usually the Drafts folder for the current edition of the book.
- If your browser gives you a choice of opening or saving the file, choose Save File.
- In LibreOffice, turn on change recording ( ▸ ▸ ).
- To leave a comment, use ▸ . Additionally, use ▸ ▸ ▸ to get your name attached to your comments.
- Add your name to the Contributors section of the chapter’s copyright page.
- Change the file name to include your initials and the date when you return the file; see #Naming convention for reviewed chapters.
- When done, upload the reviewed file to the Feedback folder for the relevant book.
What to look for in an update or review
Chapters must be checked carefully against the latest released version of LibreOffice (or the forthcoming version, when writing or updating in preparation for a new release). Please do not just improve the wording or grammar; that is important, but well-worded wrong instructions are worse than poorly-worded correct information.
When updating, also check the Release Notes for every release between the one the chapter was previously written for and the one you’re writing about. This can also be useful when reviewing.
- Make sure the correct template is applied to the chapter; sometimes we change templates between releases (for example, between LibreOffice 4.x and 5.x).
- Go through the instructions in the chapter. Follow the instructions exactly as they are written, so you can see if anything is different between the instructions and the software or if any essential steps are missing or unclear.
- Pay close attention to the screenshots. If anything is different, make a note of it. If you can capture new screenshots, then you can replace the out-of-date ones with up-to-date ones. If you cannot capture new screenshots, then leave a comment in the file that Figure x needs to be replaced. Note that some minor differences in appearance may exist between dialogs in Windows, Linux, and macOS.
- Ensure that the text and the illustrations (such as screenshots) agree with each other. For example, sometimes the name of an option is changed in the program (and thus in a new screenshot), but the writer fails to change the name in the text.
- Please also suggest other topics that should be included in the chapter, or better ways of explaining things, or any other improvements you can think of. These might include adding topics or examples (or creating stand-alone tutorials or how-tos and referring to them from the user guide), revising topics to make them more useful, or reorganizing chapters (either moving topics within a chapter or, in some cases, moving material from one chapter to another).
- Be aware that in some cases a topic may be covered in another chapter; in that case a cross-reference would be helpful, or in some cases duplicating some information might be the best solution.
- Check that the paragraph and character styles used are correct (see Chapter 5, Using the Chapter Template). Check the spelling.
How to publish a chapter
When you have decided that a chapter is ready for publishing, do the following:
- Make a final pass to check page breaks and make any necessary changes. (Use the keep-with-next attribute, not manual page breaks, and/or change the sequence of text and figures.)
- Verify that the first item in the first numbered list in the chapter is explicitly set to start at 1 (this is to make sure the chapter works properly when it is included in a compiled book). To do this, right-click on the first list paragraph and choose Bullets and Numbering > Restart numbering.
- Update the Table of Contents. Make sure there is no (alphabetic) index at the end of the chapter.
- On the copyright page:
- Make sure the date and the software version are correct.
- Verify that the correct email address for feedback, and the correct URL for documentation (in the footer), are shown.
- Make sure the list of contributors is correct, and that any empty rows are removed from the table.
- Save the ODT file with the correct file name, using the naming convention for published chapters (see below).
- Export the file to PDF, using these settings:
- On the General tab, select JPEG compression and Export bookmarks.
- On the Initial View tab, select Page only, Default magnification, and Default page layout.
- On the User Interface tab, select Display document title (under Window Options) and All bookmark levels. Leave all the other options unselected.
- On the Links tab, select Default mode under Cross-document Links and leave other options unselected.
- n the Security tab, make sure that NO passwords are set.
- Upload the ODT file to the Published folder for the relevant book on TDF NextCloud. (See details in Chapter 3, Using the Documentation Team Website.)
- Tell the Documentation list that you have published the chapter.
How to compile a book
The user guides consist of a set of individual chapter files, plus a book file that contains the cover page, copyright page, table of contents page, title page for the preface, and index page. It also has front and back cover images. These components are all in the Published folder for the book.
We are not using master documents to compile books.
To compile a full book, do this:
- Download the ODT files for the book and all of its chapters from the Published folder for the book.
- Open the book file and go to the title page for the preface.
- Open the file for the book’s preface and copy the contents from the first Heading 1 (usually “Who is this book for?”) to the end of the file. Paste this into the book file at the end of the title page for the preface.
- Check that the page style changes from First Page (on the title page for the preface) to Default for the other pages of the preface. Fix if necessary.
- Close the preface file and open the file for chapter 1.
- In the book file, go to the end of the preface and copy-paste the title page from chapter 1, then copy-paste the contents of chapter 1 from the first Heading 1 (usually the Introduction) to the end of the file.
- Repeat steps 4–6 for each of the other chapters in the book, inserting each at the end of the previous chapter.
- Regenerate the table of contents and index by right-clicking on each of them and choosing Update index from the pop-up menu.
- On the copyright page:
- Change the publication date to the current date.
- Check that the Contributors section includes all the contributors’ names from all the chapters in the book.
- Check that the LibreOffice version information is correct.
- Check that the information in ▸ is correct, especially on the Description page.
- Check that the footers show the correct information: book title on left-hand (even) pages and chapter title on right-hand (odd) pages. Fix if necessary.
- Check that the first item in the first numbered list in each chapter is numbered 1 as it should be. Fix if necessary: right-click on the first list paragraph and choose Bullets and Numbering > Restart numbering.
- Review the compiled index. If any entries need to be changed, make the changes in the chapters, not in the index itself. See also “Compiling and editing the index for a book” and “Tips for indexing chapters” in Indexing LibreOffice User Guides.
- At the end of the file, place the cursor in the blank page at the end and insert the back cover image. Anchor the image To Page, stretch the image to fill the entire page, and change its Wrap to Wrap Through.
- Select ▸ . Choose the following settings:
- On the General tab, select JPEG compression and Export bookmarks.
- On the Initial View tab, select Page only, Default magnification, and Default page layout.
- On the User Interface tab, select Display document title (under Window Options) and All bookmark levels. Leave all the other options unselected.
- On the Links tab, select Default mode under Cross-document Links and leave other options unselected.
- On the Security tab, make sure that no passwords are set.
- Name the PDF according to the instructions in #Naming convention for published books.
How to publish a book
- Log in to TDF NextCloud and upload the ODT and PDF files to the Published folder for the book.
- If any chapter files were modified during book production, upload the changed ODT files to the Published folder for the book, replacing the previous versions.
- Log in to the LibreOffice wiki and add the ODT and PDF files for the book and its chapters to the Publications page.
- Tell the Documentation list that you have published the book.