Documentation
Contributors’ Guide

Chapter 2
Producing LibreOffice
User Guides

CopyrightThis document is Copyright © 2016 by the LibreOffice Documentation Team. Contributors are listed
below. You may distribute it and/or modify it under the terms of the Creative Commons AttributionShareAlike 3.0 Unported license (http://creativecommons.org/licenses/by-sa/3.0/), version 3.0 or
later.
All trademarks within this guide belong to their legitimate owners.

Contributors
Jean Hollis Weber
Dan Lewis

Feedback
Please direct any comments or suggestions about this document to the Documentation Team’s
mailing list: documentation@global.libreoffice.org
Note: Everything you send to a mailing list, including your email address and any other personal
information that is written in the message, is publicly archived and cannot be deleted.

Publication date and software version
Published 7 October 2016.

Documentation for LibreOffice is available at http://www.libreoffice.org/get-help/documentation

Contents
Copyright.............................................................................................................................. 2
Contributors................................................................................................................................. 2
Feedback..................................................................................................................................... 2
Publication date and software version......................................................................................... 2

Introduction.......................................................................................................................... 4
How to set up LibreOffice for working with user guides................................................. 4
Change General options.............................................................................................................. 4
Change View options................................................................................................................... 4
Change Memory options.............................................................................................................. 4
Change Advanced options........................................................................................................... 5
Download and install the chapter template.................................................................................. 5(If necessary) Download and install the Liberation fonts.............................................................. 5(Optional) Download and install the AltSearch extension............................................................. 6

How to create a new chapter from the template............................................................... 6
How to create images for LibreOffice user guides...........................................................7
Screen captures........................................................................................................................... 7
Cropping...................................................................................................................................... 7
Annotation (labelling)................................................................................................................... 8
Flowcharts and other diagrams.................................................................................................... 8

How to insert images into ODT files.................................................................................. 9
How to cross-reference within a document...................................................................... 9
How to cross-reference to another document................................................................ 10
How to index a user guide chapter.................................................................................. 10
Adding index entries................................................................................................................... 11
Generating a chapter index........................................................................................................ 12
Viewing and editing index entries............................................................................................... 12
Compiling and editing the index for a book................................................................................ 13
Tips for indexing chapters.......................................................................................................... 13

How to review a chapter.................................................................................................... 14
What to look for in a review........................................................................................................ 14

How to publish a chapter.................................................................................................. 15
How to compile a book...................................................................................................... 15
How to publish a book.......................................................................................................16
Naming conventions for LibreOffice user guides.......................................................... 17
Naming convention for draft chapters........................................................................................ 17
Naming convention for reviewed chapters................................................................................. 17
Naming convention for published chapters................................................................................ 17
Naming convention for published books.................................................................................... 18

Producing LibreOffice User Guides | 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
When working on the English version of the user guides, please download and use the
US English version of LibreOffice, not the British or any other English version. This is toimprove consistency within the guides; some dialogs have different field labels in the
US and British versions.

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 andTable AutoFormat entries.

Change General options
The setting for one General option (Use LibreOffice dialogs) is important for consistency whenreviewing 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 thesame 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 Tools > Options > LibreOffice > View and make sure the choices for Icon size and style in
the User Interface section near the top are set to Small, Tango.
If you are using Ubuntu or another Linux distribution and the icon style drop-down list does notshow Tango as one of the choices, go into the distribution’s package manager and install thelibreoffice-style-tango package.

Change Memory options
User guide chapters often contain a lot of images, and a full book may have several hundred.
When you open one of these documents in LibreOffice, you may discover that images seem todisappear from the document. In most cases, the images are still in the file even if you cannot see
them on screen or in a PDF created from the file.
The “invisible images” problem can usually be cured by changing the default memory settings for
LibreOffice, to make more memory available to LibreOffice, to increase the time that objects
remain in memory, and to increase the number of cached objects. To offset the extra memory
needed for large numbers of objects, you can usually decrease the memory for each object(images in our documents are typically less than 1 MB).
To change memory settings, go to Tools > Options > LibreOffice > Memory.

4 | Producing LibreOffice User Guides

Here are some suggested settings for working with LibreOffice user guide files:•

Image cache
–
–
–

•

Use for LibreOffice: 250–300 MB
Memory per object: 1.0 MB
Remove from memory after: 0:00 hh:mm

Cache for inserted objects (when working with a compiled book)–Number of objects: 250–500

Note
The best settings for working with our user guides may not be the best settings forother documents that you work on, if those other documents contain larger objects.

Change Advanced options
Depending on what you are writing about, you may need to enable some of the options found inTools > Options > LibreOffice > Advanced: Use a Java runtime environment, Enable
experimental features, and Enable macro recording (limited).

Download and install the chapter template
The template we use when writing chapters of the user guides (LO 5.0 Chapter
Template.ott) is located in http://www.odfauthors.org/libreoffice/english/resources-forcontributers.
1)

Download the template and save it anywhere on your computer.

CautionIf your web browser gives you a choice of Open with LibreOffice or Save File, choose
Save File. Otherwise, the template opens as an untitled .ODT (text) file; if you thensave this file, it is saved as an .ODT file, not as an .OTT (text template) file.
2)

In LibreOffice, import the template into a template folder:a) Choose File > Templates > Manage Templates.
b) In the Templates dialog, on the bottom right, click the Import button.
c) In the Select Category dialog that pops up, select the required template folder. Usually
this is My Templates, but you can choose or create any folder you wish.
d) A standard file browser window opens. Find and select the template that you justdownloaded. Click Open. A thumbnail now appears in the list of templates.

(If necessary) Download and install the Liberation fonts
The LibreOffice user guides use Liberation fonts. If these are not present on your computer, youneed to download and install them. To make this easier, we have put a file containing these fonts in
the Resources section the ODFAuthors website.
1) Download liberation-fonts-ttf-2.00.1.tar.gz fromhttp://www.odfauthors.org/libreoffice/english/resources-for-contributers2) Decompress this file, which contains a folder of .ttf (TrueType Font) files.

How to set up LibreOffice for working with user guides | 53) Install the font files, using the procedures appropriate to your operating system. On
Windows and Mac OS X, this can be done by double-clicking on the font name and thenclicking 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.

(Optional) Download and install the AltSearch extension
If you are updating old chapters, you may need to replace the old OOo-named styles with thestyles used in the new template. Writer’s built-in Find & Replace function handles paragraph styles
but not character or list styles. You will need to install and use an extension, Alternative Find &Replace. The extension’s help file explains how to use it. Get the extension fromhttp://extensions.libreoffice.org/extension-center/alternative-dialog-find-replace-for-writer

How to create a new chapter from the template
To create a new document from the chapter template:
1)

Open the Templates dialog, for example by File > New > Templates.

2)

Find and double-click LO 5.0 Chapter Template, or choose the template and click Open.
A new document based on this template opens in Writer.

The new document includes all the text and graphics contained in the template. Much of thismaterial must be modified or deleted, as follows:
1)

On the title page:–

Change [Component] to the name of the book this chapter will be in, for example
Getting Started, Calc, Writer. If you are using the template for some other document(such as a HowTo or Tutorial) that is not part of a user guide, delete the words[Component Guide] but leave the paragraph marker so the rest of the text on the pageis spaced out correctly.

–

Change n to the chapter number. Do not delete the two blank spaces after the chapter
number; they are required for correct spacing of text in the footer in a compiled book.

–

Change Type Chapter Name Here to the name of the new chapter.

2)

Choose File > Properties and go to the Description page. In the Title field, replace LO 5.0
Chapter Template with the name of the chapter that you put on the title page. Delete thetemplate revision information in the Comments box. Click OK.

3)

On the Copyright page:

4)–

Change 2016 to the current year, if necessary.

–

Add your name in the Contributors section.

–

Add anything you wish to the Acknowledgments section (optional).

–

In the Publication date and software version section, replace [N.n] with the version of
LibreOffice used for this chapter.

–

Other changes to the page will be made later.

We recommend that you read the template document before beginning to write; it explains
what styles to use for what purpose. You may wish to retain some or all of the contents forreference while you are writing and delete them only when ready to upload the chapter for
review. This information is also in Chapter 5, Using the Chapter Template, in thisContributors’ Guide.

6 | Producing LibreOffice User Guides

Before you continue, save the file using the naming convention for draft chapters on page 17.
Just before uploading a chapter for review, do these things:
1)

Update the table of contents: hover the mouse cursor over the TOC, right-click, and choose
Update Index/Table from the context menu.

2)

On the Copyright page, in the Publication date and software version section, replace [date]with the current date.

How to create images for LibreOffice user guides
Images may be screen captures, photographs, or graphics (such as diagrams) created in Draw oranother program.
This section describes how to create images that show what the reader needs to know, can beread 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. Hereare some suggestions for creating consistency.
•

Avoid making screen captures from Windows; use them only as a last resort, or as a firstdraft. First choice for screen captures is Ubuntu or another Linux distribution. Most dialogs
can also be captured from Mac OS X.

•

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 agood choice.

•

Use the Tango icon set (in Tools > Options > LibreOffice > View), 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.

•

Read the text carefully to ensure you set up any data that should be shown and havemarked any selections (such as checkboxes or radio buttons) that are discussed. If theimage 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 chapterswhere 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 fromcropping (cutting off parts of the original image). There are two reasons for cropping: to fit animage on the page and still have the relevant parts readable, and to reduce wasted space andfocus 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, becausethat cropping is not retained when the file is exported to MediaWiki, HTML, and possibly otherformats (PDF does retain the cropping).

How to create images for LibreOffice user guides | 7

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 thearea 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 Tools > Options 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 tolabel screen captures, group and save the result as a single image so the labels are part of theimage. In addition, save the original as an editable file such as .ODG and upload it to the
ODFAuthors website along with the chapter .ODT file.
To assist translators, label images without text (such as toolbars) using numbers, not words, andput explanations in the figure caption. Screen captures with text (such as dialogs) need to berecaptured 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 theimage. You can use a light color for the background of labels placed inside an image (tohelp 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 thesides, 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 publisheddocuments. 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 filesuch as .ODG and upload it to the ODFAuthors website along with the chapter .ODT file.
When diagrams contain text, use a line weight and font size and weight that will be compatible withthe surrounding text when the image appears in the document.
If a diagram needs color to improve its usefulness, choose colors that provide good contrast whenprinted in black-and-white (grayscale). Consider using hatching patterns. Be sure any text has
good contrast with its background when printed in grayscale.

8 | Producing LibreOffice User Guides

How to insert images into ODT files
To prevent images from moving around during editing (especially when you are adding or deletingtext), please follow the procedure below.

Note
These instructions apply mainly to screenshots and other images that are large enoughto put between paragraphs of text.
1)

Have paragraph marks turned on (helps you to see what's happening).

2)

Press Enter at the end of a paragraph to create a new blank paragraph.

3)

Change the new paragraph’s style to Figure. The paragraph marker should now becentered on the page.

4)

Choose Insert > Image OR use copy-and-paste to insert the image.

5)

When the image comes in, it is selected. Immediately right-click on it and choose Anchor >As Character.

6)

With the image still selected, right-click again and choose Caption. Select Figure as theCategory (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.

7)

Click anywhere outside the frame to deselect it, then click in the caption line and change
the paragraph style to Caption.

8)

Click again on the image itself to select it. Right-click on it and choose Anchor > As
Character.

Note
We do not follow the practice that every figure and table must have a numberedcaption and must be cross-referenced in the text. For example, when the figure
immediately follows the paragraph in which it is discussed and it is obvious which figure
is being discussed, and when the figure will not be cross-referenced from elsewhere in
the document, a caption and cross-reference are optional.

How to cross-reference within a document
Do not type in cross-references to other parts of the document, because those references caneasily 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, numberedparagraphs, 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:1)

In your document, place the cursor where you want the cross-reference to appear.

2)

If you are cross-referencing to a figure or table, type the word Figure or Table, followed by aspace.

3)

Choose Insert > Cross Reference. On the Cross-references tab, in the Type list, click thetype of item you are referencing (for example, Heading or Figure).
How to cross-reference within a document | 9

4)Click on the required item in the Selection list, which shows both automatically createdentries (for example Headings) as well as user-defined references (for example
bookmarks).

5)

In the Insert reference to list, choose the type of reference required. The choices vary with
the item being referenced.

6)–

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, becausethat causes problems for the translation software.

Click Insert.

Occasionally you might want to insert a cross-reference to something that is not automaticallyshown on the Cross-references page. Before you can do that, you must prepare the item as atarget to be referenced. We generally use bookmarks for this purpose.
1)

Select the text you want to bookmark. Click Insert > Bookmark.

2)

On the Bookmark dialog, the larger box lists any previously defined bookmarks. Type aname 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 inthe 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 thatcase, writers and reviewers need to manually change the references in other documents.

How to index a user guide chapter
An alphabetical index is a list of keywords or phrases used throughout a document that may help
the reader find information quickly. Generally an index is found in the back of a book.
We use the tools built into Writer to embed index entries into the chapter ODT files. Writer's tools
are fairly easy (though tedious) to use. The difficult part, of course, is deciding what terms toinclude. Here is a checklist of things to consider when creating, reviewing, or editing an index:“Tips for indexing chapters” on page 13.

Note
We do not use initial capital letters on all index entries, as some publishers do.

10 | Producing LibreOffice User Guides

Adding index entries
The translators have requested that we do NOT create index entries that surround words orphrases in the text. Instead, we need to create entries that are embedded before or after the words
or phrases to be included in the index.

Note
If field shading is active (see Tools > Options > LibreOffice > Application Colors >Text Document > Field shadings), when a selected word or phrase has been added
to the index, it is shown in the text with a gray or other colored background. Index
entries whose text is different from the text in the document are marked by a small grayor other colored rectangle.
To create some index entries in a chapter, follow these instructions:
1)

Either highlight the word or phrase to add to the index or place the cursor at the beginningof the word.

2)

Click Insert > Table of Contents and Index > Index Entry to display the Insert Index Entry
dialog. See below for an explanation of the fields on this dialog.

3)

DO NOT simply accept the word or phrase shown in the Entry box. Instead, first change theword or phrase in some way, for example by typing a blank space at the end or (ifappropriate) changing an initial uppercase letter to lowercase.

4)

Click Insert to create the entry.

Here is a brief explanation of the fields in the Insert Index Entry dialog and how to use them.
•Index – The type of index this entry is for. We use Alphabetical Index.

•

Entry – The word or phrase to be added to the selected index. This word or phrase does
not need to be in the document itself; you can add synonyms and other terms that you want
to appear in the index.

•

1st key – An index key is an index entry that has no associated page number and has
several subentries that do have page numbers. Keys are useful ways of grouping related
topics. See below for an example of using an index key.

•

2nd Key – You can have a three-level index, where some of the first-level keys have level-2
entries that are also keys (without page numbers). Avoid this level; it is not often necessary
in our documents.

•

Main entry – When the same term is indexed on several pages, often one of those pages
has more important or detailed information on that topic, so it is the main entry. To make thepage number for the main, or most important, entry stand out, select this checkbox andthen define the character style for the page number of a main index entry to be bold, forexample.

•Apply to all similar texts – Select this option if you want Writer to automatically identify andmark any other word or phrase that matches the current selection. The Match case andWhole words only checkboxes become available if this checkbox is selected. In mostcases we avoid using this option because it results in unnecessary index entries that thenneed to be deleted.

Example of using an index key
An index key is a primary entry under which subentries are grouped. For example, you might wantto create a grouping similar to this:How to index a user guide chapter | 11

LibreOffice
Writer, 5Calc, 10
Impress, 15
In this example, LibreOffice is the 1st key. The subentries (with the page numbers showing) are theindexed entries. To insert an index entry for the topic Writer, on the Insert Index Entry dialog, type
Writer in the Entry box and LibreOffice in the 1st key box.
You can create multiple entries without closing the Insert Index Entry dialog. For each one:
1)

Click at the location in the document that you want to index.

2)

Click again on the dialog.

3)

Change the entry if needed, and click Insert.

4)

Repeat steps 1–3 until you have finished with the entries, then click Close.

Generating a chapter index
We do not publish indexes in chapters, but you should generate an index to check your entries tosee if any need editing. This is particularly important if you are updating a chapter that includes
existing index entries as well as any new ones you may have added. When a chapter is revised,the existing index entries may become out of date or simply wrong (for example, if a section was
copied from another guide, it may contain index entries for a different component of LibreOffice).
1)

Go to the end of the file, click in the last (blank) paragraph, and choose Insert > Table ofContents and Index > Table of Contents, Index or Bibliography from the menu bar.

2)

In the Type box on the Type tab, select Alphabetical Index.

3)

In the Options section, select Combine identical entries. Deselect Case sensitive (sothat capitalized and lower-case words are treated as the same word) and deselectCombine identical entries with p or pp.

4)

Because we are not publishing this index, it does not matter what it looks like, but you may
wish to go to the Columns tab and choose 2.

5)

Click OK to generate the index.

6)

Look at the index and decide what's missing or needs to be changed. Delete, insert, oramend entries as needed in the chapter itself. (Never edit an index directly.)

7)

Writer does not update an index automatically. If you add, delete, or change the text ofindex entries, you need to update the index. To do this, right-click anywhere in the index
and choose Update Index/Table from the pop-up menu.

8)

You may need to go through several iterations before you are done.

9)

When you are done, delete the compiled index from the end of the chapter.

Viewing and editing index entries
To view and edit index entries, use the following steps:
1)

Ensure that field shading is active (Tools > Options > LibreOffice> Appearance > Text
Document > Field shadings), so you can locate index entries more easily.

2)

Hover the cursor over an existing index entry in the body of the document, right-click, andselect Index Entry from the context menu.

3)

In the Edit Index Entry dialog, make the necessary modifications or additions to the entry.
To move through the various index entries, use the forward and back arrow buttons; thisfeature is helpful because the index markers can be difficult to see in the text.

4)

When you are finished editing index entries, click OK.

12 | Producing LibreOffice User Guides

Compiling and editing the index for a book
After the book is compiled (see “How to compile a book” on page 15), the resulting index needs tobe edited for consistency and completeness and the entries changed as needed in the chapter files
before recompiling the book index. Some (usually sub-)entries that make sense in the context of abook don't make as much sense in a stand-alone chapter.
This work is usually the responsibility of the person who will publish the book when it has been fullycompiled, indexed, and checked.

Tips for indexing chapters
Here is a checklist of things to consider when creating, reviewing, or editing an index.
•

The first word of an index entry (especially a level 1 entry) should be meaningful, something
the reader is likely to be looking for.

•In most cases, do not start an entry with a verb such as using or displaying. The reader ismore likely to be looking for the thing being used or displayed. (In some cases, for example
printing, such words might be appropriate; in most cases, they are not. You will need to use
your judgment.)•

Do not make a main entry (level 1) for the name of the product (the topic of the book) andthen put numerous level 2 entries under it. Turn all those level 2 entries into level 1 entries.
(Some topics do appropriately go under the name of the product, but they are theexceptions.)•

Make sure all important topics have a main entry (level 1), not just appearing as level 2
entries. A common problem is for field names to be listed as subentries under the window
or dialog name. Readers must then know what command to look up before they can findthe parameter entry. This also often leads to long lists of subentries, all on the same page.

•

Don't start entries with how, what, why, where, or similar words.

•

Try to think of concepts and synonyms that readers might be likely to be looking for, and put
them in the index as well.

•If a main entry has subentries under it, change the main entry so that no page numbers
print on the higher level.

•

Avoid third level entries, unless there is a very good reason for them.

•After indexing a chapter, generate the index and review it.

•

If two or more topics start with the same word or phrase, in most cases they can be turned
into level 2 entries under the common word.

•

Check for non-significant differences in capitalisation or plurals that cause separate index
entries to appear, rather than one entry with more than one page number. Either make theentries identical, or make the difference explicit in level 2 entries.

•

Check for not enough detail. In most cases, any one index entry should not have more than
two page numbers listed for it. If it has three or more page numbers listed, the entry
probably should be split into subentries, to help readers find exactly what they are looking
for. Sometimes two or more of the pages contain exactly or essentially the same
information; in this case, simply remove the entry for one of the pages (usually you would
leave the first one in).

•Check for too much detail. The most common error here is to have a level 1 entry withseveral level 2 entries, where all the level 2s are on the same page (or on a series ofpages, all identical). Usually the solution is to make the level 2s into level 1s and have theoriginal level 1 entry as a main entry as well, but removing the subentries beneath it.

•

If a main entry has only 1 subentry under it, combine the subentry into the main entry.
How to index a user guide chapter | 13

•Remove any irrelevant entries.

•

Do some random lookups in the book, to see whether the term or topic is in the index. If
several random selections are not in the index, this suggests that a lot more work needs tobe done.

How to review a chapter
1)

Download the chapter from the ODFAuthors website. If your browser gives you a choice of
opening or saving the file, choose Save File.

2)

In LibreOffice, turn on Record changes (Edit > Track Changes > Record Changes).

3)

To leave a comment, use Insert > Comment.

4)

Add your name to the Contributors section of the chapter’s copyright page.

5)

Change the file name to include your initials and the date; see “Naming convention forreviewed chapters” on page 17.

6)

When done, upload the reviewed file to the Feedback folder for the relevant book.

What to look for in a review
Chapters must be checked carefully against the latest released version of LibreOffice (or theforthcoming 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.
1)

Make sure the correct template is applied to the chapter; we often change templates
between releases (for example, between LibreOffice 4.x and 5.x).

2)

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 orif any essential steps are missing or unclear.

3)

Pay close attention to the screenshots. If anything is different, make a note of it. If you cancapture new screenshots that will match the ones in the chapter, then you can replace theout-of-date ones with up-to-date ones. If you cannot match the existing screenshots, thenleave 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 Mac OS.

4)

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, but the writer fails tochange the name in the text.

5)

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 fromthe user guide), revising topics to make them more useful, or reorganising chapters (either
moving topics within a chapter or, in some cases, moving material from one chapter toanother).
Be aware that in some cases a topic may be covered in another chapter; in that case across-reference would be helpful, or in some cases duplicating some information might be
the best solution.

6)

Check that the paragraph and character styles used are correct (see Chapter 5, Using theChapter Template). Check the spelling.

14 | Producing LibreOffice User Guides

How to publish a chapter
When you have decided that a chapter is ready for publishing, do the following:
1)

Make a final pass to check page breaks and make any necessary changes. (Use the keepwith-next attribute, not manual page breaks, and/or change the sequence of text andfigures.)2)

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:a) Right-click on the first list paragraph and choose Paragraph.
b) Go to the Outline & Numbering tab. In the Numbering section, select the option Restartat this paragraph and select Start with, making sure the number is 1.
c) Click OK to save the change.

3)

Update the ToC. Make sure there is no (alphabetic) index at the end of the chapter.

4)

On the copyright page, insert the current date and the software version. Verify that thecorrect email address for feedback, and the correct URL for published chapters (in thefooter), are shown.

5)

Save the ODT file with the correct file name, using the naming convention for publishedchapters (see below).

6)

Export the file to PDF, using these settings:a) On the General tab, select JPEG compression and Export bookmarks.
b) On the Initial View tab, select Page only, Default magnification, and Default pagelayout.
c) On the User Interface tab, select Display document title (under Window Options) andAll bookmark levels. Leave all the other options unselected.
d) On the Links tab, select Default mode under Cross-document Links and leave otheroptions unselected.
e) On the Security tab, make sure that NO passwords are set.

7)

Upload both files to the Published folder for the relevant book.

8)

Tell the Documentation list that you have published the chapter.

How to compile a bookThe 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:1)

Download the ODT files for the book and all of its chapters from the Published folder for the
book.

2)

Open the book file and go to the title page for the preface.

3)

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 thetitle page for the preface.

4)

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.
How to compile a book | 15

5)

Close the preface file and open the file for chapter 1.

6)

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.

7)

Repeat steps 4–6 for each of the other chapters in the book, inserting each at the end of
the previous chapter.

8)

Regenerate the table of contents and index by right-clicking on each of them and choosing
Update index from the pop-up menu.

9)On the copyright page:–

Change the publication date to the current date.

–

Check that the Contributors section includes all the contributors’ names from all thechapters in the book.

–

Change the LibreOffice version information to the version covered by the book.

10)

Check that the information in File > Properties is correct.

11)

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.

12)

Check that the first item in the first numbered list in each chapter is numbered 1 as it should
be. Fix if necessary:a) Right-click on the first list paragraph and choose Paragraph.
b) Go to the Outline & Numbering tab. In the Numbering section, select the checkbox for
Restart at this paragraph and select the checkbox for Start with, making sure thenumber is 1.
c) Click OK to save the change.

13)

Review the compiled index. If any entries need to be changed, make the changes in thechapters, not in the index itself. See also “Compiling and editing the index for a book”
and “Tips for indexing chapters”on page 10.

14)

Select File > Export as PDF. Choose the following settings:a) On the General tab, select JPEG compression and Export bookmarks.
b) On the Initial View tab, select Page only, Default magnification, and Default pagelayout.
c) On the User Interface tab, select Display document title (under Window Options) andAll bookmark levels. Leave all the other options unselected.
d) On the Links tab, select Default mode under Cross-document Links and leave otheroptions unselected.
e) On the Security tab, make sure that NO passwords are set.

15)

Name the PDF according to the instructions in “Naming convention for published books” onpage 18.

How to publish a book1)

Log in to ODFAuthors and upload the ODT files to the Published folder for the book.

2)

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.

3)

Log in to the LibreOffice wiki and add the ODT and PDF files for the book to the
Publications page.

16 | Producing LibreOffice User Guides

4)

If any published chapter files were modified during book production, replace the chapter
files on the wiki. To do this:a) To get to the File History wiki page for the chapter, use an address similar to
http://wiki.documentfoundation.org/File:WG5001-IntroducingWriter.odtb) Choose Upload a new version of this file.
c) On the Upload File page, browse for the chapter file, type something in the File
Changes box (usually, "corrected typos" is sufficient). Click the Upload file button.

5)

Tell the Documentation list that you have published the book.

Naming conventions for LibreOffice user guides
Book initials used in filenames:
GS = Getting Started
WG = Writer Guide
CG = Calc Guide
DG = Draw Guide
IG = Impress Guide
BG = Base Guide
MG = Math Guide
BH = Base Handbook

Naming convention for draft chapters
File names take the following form: AA5xBB-Name_Author_Date,
where AA=book initials, 5=LibreOffice V5, x=the next digit in the version, BB=chapter number,
Name=chapter name, Author=initials of author/editor/reviewer, Date=date of review (may be in anyof several forms: YYYYMMDD, DDMmmYYYY, as long as date is unambiguous).
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 5.2 Writer Guide, Working with Text, reviewed by Jean
Hollis Weber on 24 August 2016, has the following file name:
WG5203-WorkingWithText_JHW_20160824.odt

Naming convention for reviewed chapters
If you are reviewing a draft chapter, add your initials and change the date. For example, Dan Lewis
reviews the third chapter of the Writer Guide on 15 September 2016. Dan saves the reviewed filewith the name WG5203-WorkingWithText_JHW_DL_20160915.odt

Naming convention for published chapters
File names take the following form: AA5xBB-Name,
where AA=book initials, 5=LibreOffice V5, x=the next digit in the version, BB=chapter number, andName=Chapter name.
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 5.2 Writer Guide, Working with Text, has the following file
name: WG5203-WorkingWithText.odt

Naming conventions for LibreOffice user guides | 17

Naming convention for published books
File names take the following form: AA5x-Name.pdf,
where AA=book initials, 5=LibreOffice V5, 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 5.2] is GS52-GettingStarted.pdf

18 | Producing LibreOffice User Guides