6 Replies Latest reply on Jun 5, 2009 12:23 PM by [Jongware]

    Lack of documentation

    steveo de stevelux Level 1

      In regards to finding ExtendScript APIs and documentation,

      none of them has a complete reference and only anecdotal examples.

      Specifically, I'm updating a solution written for InDesign CS2 and

      have found it is now broken with InDesign CS3. This is a chronicle of

      my efforts to find documentation thus far and a complaint to Adobe:

       

      BAD SOURCE

      0. Adobe.com -> Search -> ExtendScript

      I got a Flash tutorial, robohelp tutorial, etc. What I did NOT get

      is a centralized center for scripting Adobe applications. ExtendScript

      can be used on nearly all Adobe products, but you'd never know that's

      what the name is or its breadth.

       

      GOOD SOURCE - (yet not complete):

      1. Extendscript Tookit 2 ->Help->Adobe InDesign CS3 Object Model

      Seriously, you put it under Help ... Help is where I should look for this?

      That's about as intuitive as putting the gas pedal in the glove box. It's the

      closest thing I could find to a full API reference but I suspect it's incomplete

      and why is it not in an indexable HTML format on Adobe's site anywhere?

       

      BAD SOURCE

      2. http://www.adobe.com/devnet/

      Not 1 mention of ExtendScript. This is the technology as a name.

      It's not called InDesign Script. It's called EXTENDSCRIPT. No illustrious

      articles, videos, blogs. And it puzzles me why the InDesign Server Resources

      site links to this dead end but the same link on regular InDesign goes to the next one:

       

      GOOD SOURCE

      3. http://www.adobe.com/devnet/indesign/

      Finally, we're getting somewhere. You'll find this:

      http://www.adobe.com/devnet/indesign/documentation.html

       

      What you'll see here are pretty useful PDFs, I'll admit. With some good

      use cases fleshed out. There are even ZIPs with sample code in it.

      The inherent problem is that there is not an example for EVERY use case

      and EVERY possible scenario.

       

      What is missing from this page (and Adobe's entire web presence) is a

      full Reference (see #1). For those who haven't experienced the bliss of a full

      instructions manual, it would be akin to this:

       

      WHAT WOULD BE NICE:

      http://livedocs.adobe.com/flex/3/langref/

       

      InDesign CS2 had a full reference guide. It disappeared with CS3 and CS4.

       

      As a developer, this is beyond frustrating. I wouldn't ask a mechanic to fix

      my car without a complete manual for repair. It shouldn't be a maze to hunt

      and peck around for this information.

        • 1. Re: Lack of documentation
          steveo de stevelux Level 1

          Also, if you look in your ExtendScript Toolkit folder - there are PDFs that might be useful.

          • 2. Re: Lack of documentation
            Olav Martin Kvern Level 3

            Hi steveo,

             

            re: "It disappeared with CS3 and CS4."

             

            No, it didn't. It just moved into the object model viewer in the ExtendScript Toolkit. All of the content from the previous PDF reference manuals was folded into the information provided there. At the same time, by not publishing the reference PDF, we were able to significantly increase the number of examples (which now make up the bulk of the Scripting Guide).

             

            re: "The inherent problem is that there is not an example for EVERY use case

            and EVERY possible scenario."

             

            Look at the size of the InDesign model. Consider that most objects can be nested almost infinitely (a text frame can hold a character which can contain a group, which can contain another text frame, etc.). There is just no way that we can provide an example for every possible scenario.

             

            I agree that the documentation and examples are too hard to find. But the InDesign scripting home page (which is listed in most of the sample scripts that get installed with InDesign) is at:

             

            http://www.adobe.com/products/indesign/scripting/index.html

             

            You'll need to click the Scripting Resources tab once you get there. I don't know why.

             

            That said, there's little specifically for InDesign CS2 there (it's been awhile since CS2 was released, but if it were up to me, the content would still be there). Most of the CS4 scripts will work with CS2, one notable exception being the find/change scripts.

             

            re: "What is missing from this page (and Adobe's entire web presence) is a

            full Reference (see #1). For those who haven't experienced the bliss of a full

            instructions manual, it would be akin to this."

             

            Agreed, that would be great.

             

            The PDFs in the ESTK folder, by the way, are accessible from the Help menu in the ESTK.

             

            Thanks,

             

            Ole

            • 3. Re: Lack of documentation
              [Jongware] Most Valuable Participant

              GOOD SOURCE - (yet not complete):

              1. Extendscript Tookit 2 ->Help->Adobe InDesign CS3 Object Model. [...] It's the closest thing I could find to a full API reference but I suspect it's incomplete and why is it not in an indexable HTML format on Adobe's site anywhere?

               

              In that case, would you rate my HTML version of that very same Help an "EVEN BETTER SOURCE"? 

              See http://www.jongware.com/idjshelp.html

               

              I have versions for CS3 and CS4, as HTML and (for Windows users) as Windows CHM -- which is fully indexed and searchable.

              I'm still waiting for a Mac developer who can work with the Dictionary SDK. Seems a rare thing.

              • 4. Re: Lack of documentation
                steveo de stevelux Level 1

                Olav, thank you for looking at this thread. I can only hope that in the

                future Adobe folds in one anecdotal tyraid into its usability thinking.

                 

                Your points are valid, there are developer docs available, just difficult to find.

                If someone only has a copy of CS2 they would be out of luck. That's a shame

                for all those who don't have the funds to upgrade to CS4.

                 

                That thinking is more tied to sales logic instead of developer logic.

                 

                If I might suggest one other thing that I think would be nice:

                 

                http://blog.flexexamples.com/

                 

                This blog has been invaluable to me as a FLEX developer. I can only

                dream, but if Adobe were to use such a model for InDesign Extendscripting

                you would have a wonderful resource for all types of developers. It would be

                nice to have all those examples scattered across PDFs in one searchable

                place that can be indexed easily by search engines.

                 

                EVEN BETTER SOURCE!

                Jongware, you rock! God bless you for doing all that work and offering

                it here. I hope you keep that resource up for as long as possible. I've

                downloaded it and am going through this right now.

                • 5. Re: Lack of documentation
                  Olav Martin Kvern Level 3

                  steveo wrote: "Jongware, you rock!"

                   

                  Seconded.:-)

                   

                  Thanks,

                   

                  Ole

                  • 6. Re: Lack of documentation
                    [Jongware] Most Valuable Participant

                    Aww, you guys ...