Indexing LibreOffice User Guides

From The Document Foundation Wiki
Jump to: navigation, search
This page contains changes which are not marked for translation.


Documentation Contributors’ Guide
Chapter 2A Indexing LibreOffice User Guides
Previous: Back to Chapter 2 Up: Preface Next: Chapter 3

How to index a user guide chapter

SOME DETAILS MAY BE OUT OF DATE

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 to include. Here is a checklist of things to consider when creating, reviewing, or editing an index: #Tips for indexing chapters.

Im-jabber.svg

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

Adding index entries

The translators have requested that we do not create index entries that surround words or phrases 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.

Im-jabber.svg

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 gray or 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 beginning of the word.
  2. Select 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 the word or phrase in some way, for example by typing a blank space at the end or (if appropriate) 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 the page number for the main, or most important, entry stand out, select this checkbox and then define the character style for the page number of a main index entry to be bold, for example.
  • Apply to all similar texts – Select this option if you want Writer to automatically identify and mark any other word or phrase that matches the current selection. The Match case and Whole words only checkboxes become available if this checkbox is selected. In most cases we avoid using this option because it results in unnecessary index entries that then need 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 want to create a grouping similar to this:

LibreOffice
    Writer,  5
    Calc,  10 
    Impress,  15 

In this example, LibreOffice is the 1st key. The subentries (with the page numbers showing) are the indexed 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 to see 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 of Contents 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 (so that capitalized and lower-case words are treated as the same word) and deselect Combine 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, or amend 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 of index 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 ▸ Application Colors ▸ 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, and select 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; this feature is helpful because the index markers can be difficult to see in the text.
  4. When you are finished editing index entries, click OK.

Compiling and editing the index for a book

After the book is compiled (see “How to compile a book” in Chapter 2), the resulting index needs to be 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 a book 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 fully compiled, 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 is more 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) and then 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 the exceptions.)
  • 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 find the 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 the entries 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 with several level 2 entries, where all the level 2s are on the same page (or on a series of pages, all identical). Usually the solution is to make the level 2s into level 1s and have the original 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.
  • 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 to be done.