[Framers] Source versus Target - a problem in FM documentation

[Klaus Daube]

Developing a script to convert footnotes to endnotes costed my a detour of about 20h 
tests and coding experiments. See https://forums.adobe.com/thread/2641818 . 
The footnote reference is converted to a cross-reference. The footnote itself becomes 
an endnote with new ¶ format.
In a single document the endnotes are placed at the end of the document.
For a book the endnotes are collected in a separate document.
To streamline the process a single document is handled similar to a book document (it 
is just the only one handled in the loop).

I had this statement in the script:
  oDoc.UpdateXRef(oDoc, oXRef); // establish the cross reference 
   
This does not work for the case of the separate file for the endnotes. I looked 
everywhere in my script and finally discovered the discrepancy between the FDK 
Reference and Scripting Guide - and could not interpret this correctly for long time:

In the FDK documentation this function (F_ApiUpdateXRef) has 3 parameters: 
docId    The ID of the document that contains the cross-reference.
srcDocId The ID of the source document that the cross-reference references.
xrefId   The ID of the cross-reference to be updated.

The Scripting Guide (as of August 22, 2018) tells on page 761:
«Updates the cross-references in a document. It performs the same operation as 
clicking Update in the Cross-Reference window. You can OR the values listed in the 
following tables into the updateXRefFlags argument.»
A Table of these constants follows. Then another table of Error values (FA_errno).
Only after this the essential information (syntax) comes:
  UpdateXRef(srcDoc, xref)
The table with the parameters confuses me even more:
Parameter name Data Type Description
srcDoc         Doc     The document in which to update cross-references.
xref           XRef    Flags to indicate which cross-references to update.

? How can flags have a data type of XRef?
? Where is the target document (where the XRef marker resides)?

After searching my problem in other functions, the different type of source document 
(doc vs. bookcomponent) etc. I identified the above mentioned statement as the 
culprit. But IMHO in the FDK documentation the word source is used ambiguously: once 
for the document containing the cross reference, once for the document pointing to 
(IMHO this is a target, not a source). The Scripting Guide doesn't even talk about 
the target document - it talks about flags, which turns out to be nonsense.

And there is another flaw in the documentation:
FA_errno was -3 in all failing tests. But this is not mentioned in the doc. I had to 
check the list of constants: -3 is FE_BadObjId

Of course at beginning of my development I searched in the scripting forum, but only 
very late I found with keyword updatexref: https://forums.adobe.com/thread/1721502 
from March 2015 (before I always searched for crossreference or cross-reference or 
cross reference).

So at least part of my confusion is 4 years old - and the doc has not been 
corrected...

Yesterday I decided to follow my personal logic, not that of the documentation...
So the correct statement in the script is: 
  oDoc.UpdateXRef(oTgtDoc, oXRef);

Hooray!
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Klaus Daube             Phone:  +41-44-381 37 77
Schäracher 11           Mail:   klaus at daube.ch
CH-8053 Zürich          Web:    www.daube.ch