Highlighted

ExtendScript documentation considered harmful

Advocate ,
May 28, 2019

Copy link to clipboard

Copied

Dear all,

In the scripting documentation (Scripting Guide, FDK documentation) you find the same attributes/properties in the description of neary any object.

For example: NextGraphicInFrame; NextGraphicInDoc, NextGraphicInGroup is listed for Doc, Frame, Line, PolyLine, Ellipse etc.

I wanted to treverse the graphic objects within an anchored frame:

  • oDoc, oFrame is the current environment.
  • oGraphic is a selcected grahic item (polyline) within the frame
  • I want to select the next graphic in the frame.
  • oFrame.NextGraphicInFrame creates an invlid object
  • oDoc.NextGraphicInDoc creataes an undefined object
  • oGraphic.NextGraphicInDoc finally is the solution

Why is it necessary to fiddle around with such outrageous information?

Neary any basic function must be verified by experimental scripts - or the help of You all.

I'm in the comfortable situation having time for such experiments - but anyone in need of solution in due time...

Klaus

TOPICS
Scripting

Views

1.2K

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more

ExtendScript documentation considered harmful

Advocate ,
May 28, 2019

Copy link to clipboard

Copied

Dear all,

In the scripting documentation (Scripting Guide, FDK documentation) you find the same attributes/properties in the description of neary any object.

For example: NextGraphicInFrame; NextGraphicInDoc, NextGraphicInGroup is listed for Doc, Frame, Line, PolyLine, Ellipse etc.

I wanted to treverse the graphic objects within an anchored frame:

  • oDoc, oFrame is the current environment.
  • oGraphic is a selcected grahic item (polyline) within the frame
  • I want to select the next graphic in the frame.
  • oFrame.NextGraphicInFrame creates an invlid object
  • oDoc.NextGraphicInDoc creataes an undefined object
  • oGraphic.NextGraphicInDoc finally is the solution

Why is it necessary to fiddle around with such outrageous information?

Neary any basic function must be verified by experimental scripts - or the help of You all.

I'm in the comfortable situation having time for such experiments - but anyone in need of solution in due time...

Klaus

TOPICS
Scripting

Views

1.2K

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
May 28, 2019 0
Advocate ,
May 28, 2019

Copy link to clipboard

Copied

Hi Klaus,

Most FM objects are organized in linked lists. Some are pointing in both directions (Next and Prev), others are not. When you start from a selected object, there is no way of knowing where that object is in the list of graphic objects in the same frame.

The various linked lists in which the same object may appear may not be in the same order. For instance, the paragraphs in the main flow of the document are listed from top to bottom. The graphic objects in a document may well be organized by the moment of their insertion, which has nothing to do with the order from top to bottom (I don't know this and I have not tried to figure it out, but I would not count on the order being in the direction of the document). With graphic objects in a frame there is no way to tell which one is first and which is next in a linked list.

It could simply be that the selected graphic in your frame is the last one in the linked list of graphic objects in that frame. So you should follow the link from the object to its parent and then find the first object of the same type in that parent - that is the start of the list. Follow that to the end of the list (the first invalid object) and you have traversed all graphic objects in that same frame. Using the NextGraphicInDoc gets you to all the graphic objects in the entire document, of course. If you then try to figure out whether they have the same parent, you are doing much more work than you need to.

Find the start of the rainbow first, then follow it to the pot of gold at the other end. 🙂

I hope this sheds some light on why there is so much complexity in FM. I have had a peek inside Word and Excel and I can tell you that we are the lucky ones !

4everJang

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
May 28, 2019 1
Adobe Community Professional ,
May 28, 2019

Copy link to clipboard

Copied

A couple of things about linked lists in FrameMaker: Apparently, they are somehow memory efficient and are from the early days when computers didn't have a lot of RAM. It's true that some of the lists don't necessarily reflect document order; for example FirstPgfInDoc/NextPgfInDoc; FirstGraphicInDoc/NextGraphicInDoc.

However, some lists do reflect some kind of order: FirstTextFrameInFlow/NextTextFrameInFlow and its more useful FirstTextFrameInFlow.FirstPgf/NextPgfInFlow. Of course, this skips tables and the paragraphs in the them, so you sometimes have to work around that.

There is actually some order to FirstGraphicInFrame/NextGraphicInFrame; these are determined by stacking order of the objects in the frame. FirstGraphicInFrame will be the bottom of the stacking order if there are multiple graphics in the frame.

In your case: you have a selected graphic which could be the FirstSelectedGraphicInDoc (I say could because there could be more than one graphic selected). If that graphic happens to be at the top of the stacking order in the frame, then NextGraphicInFrame will be undefined. That is probably the cause of your confusion. You could go "down" the stacking order by trying PrevGraphicInFrame.

Or you could jump back to the parent frame and start from there:

oGraphic = oDoc.FirstSelectedGraphicInDoc;

oFrame = oGraphic.FrameParent;

// Switch to the first graphic in the frame which might not be the one selected.

oGraphic = oFrame.FirstGraphicInFrame;

while (oGraphic.ObjectValid ()) {

    // Do something here?

    // ...

    oGraphic = oGraphic.NextGraphicInFrame;

}

-Rick

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
May 28, 2019 1
Advocate ,
May 29, 2019

Copy link to clipboard

Copied

Jang and Rick - thank You both for the detailed explanation - especially the existance of various lists for the same object!

Oh really, it is learning the hard way round...

But still I can't wind Adobe's wreath for the kind of script documentation...

Klaus

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
May 29, 2019 0
Mentor ,
May 29, 2019

Copy link to clipboard

Copied

It is an absolutely true statement that the documentation is weak. And that may not be true enough, because I think any complete newcomer would struggle heavily to even get started. It seems that those of us who have had success with ExtendScript did so because we previously had success with the FDK or FrameScript, and/or overwhelming expertise on the inner workings of the product. We generally understand the scripting guide because we already understood it. I imagine that somebody at Adobe already recognized that, but that somebody else also recognized that the audience is small and the book does not merit the expense to improve. I can understand that reasoning. I think the much bigger fault is the fact that the audience is small. It's just another example of a powerful differentiator that sets this product well apart that Adobe seems to think is better kept a secret. It amazes me the things that Adobe promotes instead of the most useful features of the product, like its API and the general structured interface. Were it not for either of those, I would not be using the product today. The vast majority of users are missing out on the best parts of the product and it seems Adobe wants to keep it that way.

I should have kept this political rant to myself, but I couldn't resist. Thanks for putting up with it.

Russ

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
May 29, 2019 1
Adobe Community Professional ,
May 29, 2019

Copy link to clipboard

Copied

Russ, your rant is totally appropriate and appreciated. If I was starting out today with just the ExtendScript documentation, I would have a difficult time learning it. I got my start with FrameScript and its documentation, which was just a reworking of the FDK documentation. And I still use the FDK documentation for help with properties and constants, etc.

The small FrameMaker market makes it difficult to find third-party materials. I wrote my book "FrameScript: A Crash Course" because there was a need to for concrete examples and good scripting practices, but I only sold a couple of hundred copies. I have been tempted to rewrite it for ExtendScript, but I am not sure that the demand would justify the effort.

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
May 29, 2019 0
Engaged ,
May 29, 2019

Copy link to clipboard

Copied

Hi,

ExtendScript Documentation, what's that?:-)

I never use that, as I'm still refering to FDK Programming Guide and FDK Reference. These documents are not that bad, even if you are working with ExtendScript. The only difference is the syntax and may be some things are easier to implement, but it's the same stuff beside that.

Yes, Adobe can port this documentation to a documentation with ExtendScript-Syntax, I would appreciate that very much  Even more I would appreciate to get a better context sensitive help, as this "help system" is not usable. (DITA would help).

But what do you need more than this stuff, anything is well explained.

You will have a (big) learning curve in any case if you start from scratch. And even after 20 years of FDK and ES programming, sometimes I come to a point, where I need support by the community.

I have been implementing a lot of other APIs and I have to say, this FM API documentation is not that bad.

I do trainings for ES here in Germany and if one explains the mapping of C-samples to ES Syntax, FDK documentation is OK for users.

Markus

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
May 29, 2019 0
JonEBe LATEST
Explorer ,
Jun 13, 2019

Copy link to clipboard

Copied

Hi Klaus,

I feel your pain. As others have said, Adobe to have not put that much effort into the object model documentation for FrameMaker with Extendscript IMO. I find myself referring to the FDK documentation whenever I am working with Extendscript. And then there are the bugs, the memory leak we have discussed elsewhere, and now it looks like Doc.Find has changed again, or been fixed from 2017, sigh.

As for the small FrameMaker market, I have two customers with 100 licenses between them, with FrameMaker as the key element in a custom structured authoring solution. To them it is critical.

Jon

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
Jun 13, 2019 0