Understanding the TextLoc.offset property

Question

I am working on a script that, among other things, converts autonumber strings in a structured document into regular text.
One thing that has been surprisingly unintuitive is setting up the TextLoc object that is passed to the AddText() function in order to get the new text to appear in the correct place in the document's structure.
Through trial and error I've determined that for some elements I need an .offset value of 1, and for others this same value results in the text appearing before the target element. For these other elements, an .offset of 2 results in correct placement. I tried calculating the offset based on the length of the autonumber sting, but this didn't produce good results (esp. for longer strings), I just turn off the autonumbering before inserting the text.
The value that works seems pretty consistent on a per-element type basis, so I'm able to get the script working by passing the appropriate value as an argument, but I'm wondering if anyone can explain the reason for this variation, and/or a consistent method for determining the correct value other than by trial and error. If there's a pattern, I'm not seeing it.
This is the function I'm currently using:
function hardCodeNum(thisDoc, tLoc, offSet) // Converts autonumber at a given text location into regular text
// thisDoc = app.ActiveDoc
// tLoc =  this TextLoc object is initially the beg object from a TextRange returned by a Find() function.
// offSet = either 1 or 2, as explained in post
     var autoNumber = tLoc.obj.PgfNumber;
     tLoc.offset = offSet;
     tLoc.obj.PgfIsAutoNum = false;
     thisDoc.AddText(tLoc, autoNumber);
    return; 

Answer 1

Oliver,
FrameMaker’s paragraph objects are very powerful structures, as they contains a lot of information apart from the obvious text content. Each format change (aka character formatting), each line break, each start (and/or end) of special objects like cross-references, markers etc. are stored there. In structured documents on top of all of this come element begin and element end as well as element prefix start/end or element suffix strat/end in case they are applied by the EDD formatting rules. Some of those items consume offset positions and some don’t. Element start/end items do consume each 1 offset position. Think of you document as shown with elements as brackets – each bracket is like a character and consumes one offset position; other wise you would not be able to position the cursor exactly between two element start items to add a new firct child element.
All tis power is hidden in the GetText{} method, which can be use on many objects, it is described in the framemaker_10_scripting.pdf on page 452 (paper) resp. 460 (PDF).
Because of the intricacies with autonumbering and or prefix/suffix rules your best bet to get the first location where you can add text is to look for the first text item of type FTI_String and use its offset.
HTH,
- Michael