CFR: documentation rendered in PDF with FOP

[Gabor Kovesdan]

On 2013.07.24. 1:28, Warren Block wrote:
> On Wed, 24 Jul 2013, Gabor Kovesdan wrote:
>
>> On 2013.07.23. 23:11, Warren Block wrote:
>>
>>> There is something weird about bulleted lists and sub-lists, 
>>> starting on page 35 of the PDF Handbook (page 7-9 of the content). 
>>> Some entries in the first list are blank, the ones in the second 
>>> list have an extra linefeed after the bullet. 
>> It is a known issue and is actually the result of misplaced 
>> indexterms, not a bug in the rendering. I've already fixed some of 
>> them in the English docs but translations still has to be fixed and 
>> there may be slightly different cases, which I haven't caught yet. We 
>> should document in fdp-primer that indexterms should be put right 
>> inside of the text after the referred word. Not between paragraphs, 
>> not into <itemizedlist>, not into <listitem> but right inside <para> 
>> after the referred word without leaving a single a space. If they are 
>> not in <para>, it can cuase such problems. And if you put a space 
>> before the indexterm, there may be a page break and you get a wrong 
>> page number in the index. But the probability of this latter is very 
>> low, the former thing is more important.
>
> Presently, indexes and indeterms are not even mentioned in the FDPP. 
> I'll start a list of things to add after the doc slush.  If you or 
> anyone else have found things which are not documented well or at all 
> in the FDPP, please let me know or enter a PR. 
Thanks! Some more guidelines on indexing would be useful. I'm unsure 
about the actual conventions, probably we should consult some 
bibliography. I'm thinking of some hints on what to index. We currently 
index company names. Should we do it or just technical terms? Shall we 
index acronyms or the full term and add a see entry for the former ones? 
How should we use secondary terms? As for translations, I think that 
indexterms should be translated if the term is translated in the body 
text but currently it is not always done. We should clarify these questions.

Gabor