Indexing Clarification Needed

Hi All,

The Contributor Guide is extremely helpful and I deeply appreciate that someone --presumably Jean--invested the time and energy to create it. I would just like a little bit of clarification.

Chapter 2 provides guidelines for indexing. On page 11, the guidelines say: "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."

What is the rationale for not creating index entries that surround words or phrases? How does this help the translators?

Then, in the next paragraph, it says "Either highlight the word or phrase to add to the index or place the cursor at the beginning of the word."

This appears to contradict the previous paragraph, where it says to not highlight entire words and phrases. What should the guideline be?

Two lines later, it says: "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.

This requirement seems puzzling. I am sure that there are good reasons for changing the word or phrase and would appreciate some insight.

Thanks for whatever clarification people can provide.

Cathy

Hi Cathy,
Several people contributed to the Contributor Guide, and some parts of
it are out of date, as you know.

Some comments inline below.

Hi All,

The Contributor Guide is extremely helpful and I deeply appreciate that
someone --presumably Jean--invested the time and energy to create it. I
would just like a little bit of clarification.

Chapter 2 provides guidelines for indexing. On page 11, the guidelines
say: "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."

What is the rationale for not creating index entries that surround words
or phrases? How does this help the translators?

Olivier or Sophie or someone can provide the technical explanation. My
understanding is that it interferes with the translation software
somehow.

Then, in the next paragraph, it says "Either highlight the word or
phrase to add to the index or place the cursor at the beginning of the
word."

This appears to contradict the previous paragraph, where it says to not
highlight entire words and phrases. What should the guideline be?

This is ambiguous wording on my part. There is a difference between
"highlighting" the word or phrase before indexing it and "surrounding"
the word or phrase with the index entry itself, but it's hard to
explain.

Two lines later, it says: "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.

This requirement seems puzzling. I am sure that there are good reasons
for changing the word or phrase and would appreciate some insight.

That is simply an effective way to ensure that the index entry does
NOT "surround" the word or phrase, but instead is embedded just before
it. There are other ways, which might be better.

BTW, I think some of the indexing may have changed in the software;
I've recently noticed some things working differently (at least some
of the time) than they did when I wrote those instructions. If so, the
instructions may be out of date and need rewriting to match reality.

Thanks for whatever clarification people can provide.

Cathy

Regards, Jean

Oh yes, that's likely me. It was because of field references to *custom*
number range inside the text. For standard number range such as Table,
Illustration, Figure, frame etc... available in Autocaption settings,
translation seems to be handled well and can be carried at the caption
paragraph. When it comes to custom number range field, you can't translate.

The issue raised when I was translating A. Pitonyak's well known macro
book, where the custom number range field "Listing" was untranslatable
and forcing translation at caption paragraph broke the references to it.
The right approach then is to manually translate the caption and
reference the number range field only by its number, which is invariant.

Kind regards

Are you saying that an issue arises when there is a custom number field inside an index entry? That seems highly unlikely.  Perhaps I am not following what you are saying.

Olivier, the question is about (alphabetic) index entries, which are not
the same thing as number range fields.

Jean

HI Milos,

Thank you for taking the time to explain.  For editing Writer documentation, I needed to learn about Hunspell, so understand the issue you are facing.

To help me understand this better, I have some questions:

Is it correct that you want only the singular nominative form of nouns in the index?

What do you mean by "embedded" index entries?

It sounds like surrounding a word or phrase to save it creates a different result than inserting the cursor before or after the word or phrase. But what is the difference in what is saved?

The few times I have made an index entry by inserting the cursor before or after a word (with no space between) only that word appears in the index. Since we need to write the exact index entry in the index dialog, it is puzzling that Writer would still grab neighboring words. This seems like a bug. Do you know if it has been reported as a bug? Do we know for sure that it is still a problem?

I think it would be helpful to understand more about what is involved in translation. My understanding is that some language translators write their own documentation while others start with the English version. I don't have a clear sense of how that works. I tend to make a lot of changes, including sharpening text and rearranging content. However, I don't have a good sense of what this means for translators. To what extent does it matter if there are many as opposed to few changes for you?

Thank you for whatever clarification and information you can provide.

Cathy

Hi,

Reading along and having Writer open trying to do what you seem to be
asking and to be honest I am totally confused.

Here is what I think you are looking for.

You want me index a space character and give that a tag, which I suppose is
us typing in the word that we didn't just select before we opened the
dialog box.

Assuming that this word is in multiple places in the document, which I
didn't select for the index, i then forego the ability to auto select all
the instances and instead find them by hand, then select another space
character and do it all over again and again.

Is that it?

I was trying to get clarification about the instructions on pages 11 and 12 of Chapter 2 of the Documentation Contributors' Guide. The instructions are clear. It is the rationale behind them that I am trying to understand.

right you are - I was reading the email alone and not thinking about what
was in the How To doc.

Hi Martin,

I understand the need and certainly want to make sure that your needs are met. I am questioning the rationale.

Rather, I am just trying to understand how it works. Specifically:

1. How does simply clicking before a word or phrase rather than
    selecting it give the result you want? What is the difference in
    what is produced?
2. Does LibreOffice still grab neighboring words rather than the
    specific word or phrase we write in the Insert Index Entry dialog?
    It sounds like a bug that should be addressed at some point. It also
    does not sound like a difficult issue to fix. If it has not been
    addressed, has a bug report been filed?

Thank you.

Cathy

oops. I meant to say that I am *NOT* questioning the rationale.

Howdy Milos,

Ďakujem!

Všetko najlepšie.

Drew

HI Milos,

Thank you for taking the time to explain this. It is quite helpful.

From what you describe, this is what I gather about how it works.

  * When a word is selected for an index entry, that word/phrase is
    automatically inserted in the Entry field in the Insert Index Entry
    dialog. It is also given a tag. Index entries for words/phrases with
    that tag cannot be different from what is in the text so the
    translators can’t change them.
  * When the cursor does not highlight a word but rather is next to a
    word, the word it is next to is automatically inserted into the
    Entry field.
  * When the selection and the index entry differ, however slightly, the
    selection is tagged differently. This tag breaks the link between
    the word in the text and the index entry. Thus, the translators are
    able to change the index entries independently of what is in the text.

If my understanding is correct, this means that we could select a word/phrase as long as we modify it in the Entry field. This would make our task slightly simpler (and more understandable, at least to me) and the Contributor Guide could be modified accordingly.

Thanks again,

Cathy