Documenting your Scripts

/

Excerpted from my book FrameScript for Newbies Copyright [7/17/2007] by Paul Schnall

As you write scripts you should always document them. Anything that is relevant to the creation and use of the script can be put in the script as a comment. It is always advisable to put a section at the top of the script to give you and other readers pertinent information. This information can include:

  • a short description of what the script does
  • what input files are needed
  • what parameters in the script need to be specified, and include the line of code where to specify them (unless you are using dialog boxes to input parameters into the script)

I also include:

  • the date the script was written
  • last date the script was modified
  • Author

You can include any other information you like, just remember if you give out the script, other people will be able to read the comments.

It is also a good idea to use a comment to explain a subroutine or a few lines of code, especially when you start writing scripts. For example, you wrote a script that loops through all the tables of a document. It would be wise to write a comment about the script, so you can find this loop later on, in order to copy and paste it into another script if the need arises.

Commenting out lines in a script

Commenting out lines is a way to hide the line from the compiler so the line of text is not interpreted as a command or a line of code.

To comment out a line in FrameScript there are two methods.

The first method uses // two backslashes one after the other. This must be at the beginning of each line. If a comment wraps around to the next line two backslashes must also be placed at the start of that line and every line that wraps around.

// This script finds all empty paragraphs and checks for
// any table anchors, frame anchors, or marker
// anchors. If There are any anchors this script will
// not delete the Paragraph.

I find that when I am writing a script I use this function instead of deleting a line of code. This way it still remains in the script if I want to add it back later or add it somewhere else in the script. This is of great use when debugging a script.

For example I insert the command

Display 'I got to Here';

When the script reaches this line of code a message window pops up with the message
I got to Here. Now I know that the script ran at least to this line.

Then I can add // to the beginning of this line of code and it effectively erases it. I can always copy and paste this Display command anywhere in the script to see if the script reaches that line.

This is especially useful for displaying variables in order to see how far the code progressed when it stopped or crashed. For Example the Display command can be used to display the text within the current paragraph being manipulated by the script.

Display vPgf.text;

When the script reaches this line of code the text within the current paragraph will be displayed. Thus, you can see how far into the document the script has progressed before it crashed.

Once the script is finished you can go through the script and delete any extraneous Display commands.

The second method for hiding comments uses /* to open a commenting area and */ to close a commenting area.

// This double backslash indicates a comment.

/* This indicates the start of a

section to be understood by the FrameScript

Compiler as comments. To end the comment

section use */