The diagram_text_file is processed in paragraph mode, each paragraph is separated from the next by a blank line. The order of the paragraphs is important (that is a minor bug). The order is:

node layout
starting states
accepting states
edges...

You may include as many edge paragraphs as you like, but each one should have a different label.

At least two example input files are included in the distribution. Look in the samples subdirectory for files ending in .input. The README file in that directory explains what these input files represent. The corresponding .svg and .png files hold the resulting images. The .png images were produced with the freely available Batik rasterizer, which is part of the Batik project from Apache. See http://xml.apache.org/batik/ for information on Apache Batik.

This represents the states in a coin operated vending machine which accepts coins with values of 5, 10, and 25. The purchase price for the machine is 25, so 25 and 30 are accepting states. Zero is the start state. Each deposited coin increases the total, which is used to label the nodes. Edges represent deposits and are labeled with the value of the deposited coin. (The diagram is not complete. It is meant to show features of diagrams. If you have a coin-op machine you need to build, feel free to extend it as needed.)

Each paragraph except the one for node layout has a label. The labels are only used for edge paragraphs. All coordinates are in terms of the node layout which is numbered from 0. Columns are listed first, then rows (think x and y from algebra). Sides of the nodes (where edges begin and end) are labeled with compass points N(orth), S(outh), E(ast), and W(est).

This input format is idiosyncratic. If you don't like it, you should design your own and interface directly with UML::State. If you don't like listing columns first, or numbering from zero, you will need to account for that in your new script or change UML::State.

The order of the paragraphs matters. All paragraphs except the node layout must be labeled.

All edges using the same label must be in the same paragraph. If an edge paragraph repeats a label used by an earlier edge paragraph, it overwrites that paragraph. (Think of the labels as hash keys, I do.)

The bugs in UML::State apply here as well, since this script uses it to make the pictures. See perldoc UML::State for those bugs.