How to Prepare a Cookbook File for Running the Perl Scripts

1

How to Prepare a Cookbook File for Running the Perl Scripts

1. Creating customization files in XMetaL
Because the arrangement of tags in an XML document is done through a customizations file associated with the DTD applied to that document ([dtdname].ctm), it will save you a lot of time if you create multiple copies of the cookbook DTD so that you will also be able to create different versions of the customizations file for each perl script you plan to run. I currently have three different copies of the cookbook DTD in my version of XMetaL: cookbook.dtd (the original), pre-perl.dtd (originally intended for both ingredients and implements, now just for ingredients), and indexing.dtd (to prepare a file for indexing, a step of the process I don't actually handle).

Once you have created the customizations files for these DTDs once, you don't have to touch them again unless the DTD is changed. Unfortunately, when you update a DTD, the changes won't take effect unless you delete all the files that were associated with the old DTD, including the old customizations files—which means you will have to recreate the same customizations each time you update the DTD. Luckily, the process doesn't take too long, and you only have to do it once each time the DTD is changed. In fact, if the DTD stays the same for the rest of the project, you may never have to do this at all. Still, better safe than sorry. Here are some step-by-step instructions on how to create the customizations files I have been using throughout the project:

1)Delete the old DTD files from the XMetaL Rules folder. You will have to delete not only the DTDs themselves, but also their associated .ctm, .rlx, and .tbr files. Here's a list of the files that would need to be deleted, assuming you use the same file names I did:
cookbook.dtdpre-perl.dtdindexing.dtd
cookbook.ctmpre-perl.ctmindexing.ctm
cookbook.rlxpre-perl.rlxindexing.rlx
cookbook.tbrpre-perl.tbrindexing.tbr
These files are located in
C:\Program Files\SoftQuad\XMetaL 2\Rules\.

2)Select and copy the new version of the DTD from the K:\ (dsc on 'lib8web') drive. The new version of the DTD should be in the "cookery" folder, and will be called cookbook.dtd.

3)Paste a copy of the new DTD into the XMetaL Rules folder. Once again, the file path is
C:\Program Files\SoftQuad\XMetaL 2\Rules\.

4)Make two more copies of the cookbook DTD in the XMetaL Rules folder, and rename the two copies appropriately. I always called the two extra files "pre-perl.dtd" and "indexing.dtd."

5)Open XMetaL.

6)Create a "New" document in XMetaL, and choose "cookbook.dtd" as the associated rules file when prompted. Also choose "Preserve Space" as the Perserve Space Option when prompted. The DOCTYPE declaration should appear at the top of the blank page in XMetaL.

7)From the "Tools" menu at the top of the screen, choose "Customizations". Within the "Customizations" box, click on the "Text Layout" tab. You should get a box that looks like this:

8)Set the "General Options" for the DTD. Check the box marked "Enable Text Layout." Set the "Line Length" to an impossibly high number, and change the "Indent" to 0.

9)Delete all default "Element Options" for each element in the DTD. If you look in the scrolling window at the left side of your box, each element that has some Element Options already set has a pair of angle brackets (>) next to it. These default options do not match the ones we want to use for the cookbook DTD, so for each element that has angle brackets next to it, you will need to uncheck all the boxes under "Element Options" for that element. Clicking on the element in the list on the left will bring up the Element Options for that element; clear all boxes for all elements in the list.

10)Set the proper "Element Options" for the DTD. These will be the same no matter what changes you have made to the DTD. The following table lists the cookbook elements in the order they appear in the text layout screen, followed by the Element Options you should set for each element.

TEXT LAYOUT "ELEMENT OPTIONS" FOR COOKBOOK.DTD

Element Options

Start Tag

End Tag

*In cookbooks that do not have recipe <purpose>s placed as headings above the recipe, you don't need to apply any Text Layout Element Options to <purpose>.

11)Click "OK" to save the Text Layout Customizations.

12)Change the document to "Tags On" view. This is done by selecting Tags On from the View menu.

13)Open the Quick Styles Editor by selecting Quick Styles... from the Format menu. You should get a window that looks like this:

14)In the "Block" column of the Quick Styles Editor, set each element that was assigned an Element Option in the Text Layout screen (those in boldface in the above table) to "Block." This is done by simply double-clicking the space beneath "Block" next to the appropriate elements until "Block" appears or disappears (whichever would be appropriate) in the column. The other columns (Align, Bold, Italic, Size) may be left alone.

15)Click "OK" to save the Quick Styles customizations.

16)Close the file. You don't need to save—you're done creating the customizations for cookbook.dtd!

17)Repeat steps 6-16 twice more to create the customizations files for pre-perl.dtd and indexing.dtd. The process is exactly the same for the other two DTDs, except that you choose "pre-perl.dtd" or "indexing.dtd" when prompted to select a rules file, and the text layout for each is of course different. The following two tables provide the Text Layout Element Options for pre-perl.dtd and indexing.dtd. (You will also need to refer to these for the Quick Styles options, of course.)

TEXT LAYOUT "ELEMENT OPTIONS" FOR PRE-PERL.DTD

Element Options

Start Tag

End Tag

TEXT LAYOUT "ELEMENT OPTIONS" FOR INDEXING.DTD

Element Options

Start Tag

End Tag

...And that's all! The customizations files are now complete.

2. Preparing a file to run the ingredients and indexing perl scripts

While the implements perl script requires no special preparation whatsoever before it is run on a file, the indexing and particularly the ingredients perl scripts require some prep work to the file on which they will be run. This is because, in these two perl scripts, a line of code dependent on the string of characters at the start of a line determines where tags will be pasted in, and where they will be left out. The ingredients perl script, for example, is designed to only paste tags inside recipes and formulas. The indexing script, on the other hand, assigns ID attributes to various elements in the document, which will only be tagged if they appear at the beginning of a line of code. To get these scripts to work properly, then, the text in the file will need to be rearranged so that certain tags appear at the beginning of lines. These tags will determine whether a line of code is tagged or skipped.

This is the reason we create customizations files in XMetaL. By setting Text Layout customizations through this program, it becomes very easy to rearrange the tags in a document so that they will work with the perl script. Once you have created the customizations files, all you have to do is apply the appropriate Text Layout settings to the document, and the tags will (for the most part) line up as they are supposed to.

I say "for the most part" because, of course, the system is not entirely perfect, and files being prepared for ingredients perl scripting will need more preparation than just applying the text layout settings. The indexing script, on the other hand, only needs the text layout—so I will describe how to prep for the indexing script first.

1)Open the file (in XMetaL) that is ready for the indexing perl script. Once a coder has finished putting all the structural, ingredient, and implement tags in a file, it is ready to be indexed. The complete file will be named [bookcode]3.xml, and it should be located in K:(dsc on 'lib8web')\cookery\xml in progress\. ([bookcode].xml and [bookcode]2.xml, which should be in the same folder, are old versions of the same book.)

2)Check to be sure the document validates. None of the coders have forgotten to validate the document before turning it in as complete yet, but better safe than sorry. You may also want to check for leftover notes from the typists, which will be in curly brackets—occasionally these slip through the cracks.

3)Select "Save As" from the File menu to rename and move the file to the "complete" folder. Rename the file [bookcode].xml and save it in
K:\cookery\xml in progress\complete (ingr & impl added)\.

4)Delete the extra copies of the file. Once you have saved a copy of the finished file in the "complete" folder, you may delete all the extra files from K:(dsc on 'lib8web')\cookery\xml in progress\ —there should be four altogether: the original typed text file and three xml files, titled [bookcode].xml, [bookcode]2.xml, and [bookcode]3.xml (which you have just made a copy of in the "complete" folder). (No, this isn't exactly part of running the indexing script, and it isn't essential that you delete the extra files at this point—but this is usually when I remember to do it, so I thought I'd make a note of it here.)

5)Change the rules file in the DOCTYPE declaration from "cookbook.dtd" to "indexing.dtd." The DOCTYPE declaration appears at the top of each cookbook file, and looks like this (only on one line):
<!DOCTYPE cookbook SYSTEM "C:\Program Files\SoftQuad\XMetaL 2\Rules\cookbook.dtd">
You will need to change it to this:
<!DOCTYPE cookbook SYSTEM "C:\Program Files\SoftQuad\XMetaL 2\Rules\indexing.dtd">
by simply replacing the word "cookbook" with the word "indexing."

6)Choose "Save As" from the File menu to save the file in the indexing folder. The directory for new files ready to be indexed is K:(dsc on 'lib8web')\cookery\ready for perl\indexing\new\. Save the file in this folder (you don't need to change the name of the file).

7)Close the file in XMetaL. You will need to reopen the file for the new DTD to take effect.

8)Reopen the file from K:(dsc on 'lib8web')\cookery\ready for perl\indexing\new\ in XMetaL.

9)Apply the indexing Text Layout to the file. This is done by choosing Customizations... from the Tools menu, bringing up a box containing a Text Layout tab. Click on the Text Layout tab to display the Text Layout options, which are already set for the indexing process (as per the procedure above). Check the box that says "Enable Text Layout" if it isn't already checked, then click "OK" to apply the Text Layout to the document. The lines of code will automatically be rearranged for the indexing script.

10)Save the file. Just a normal save will do it—no need to Save As, just replace the file in the indexing\new\ folder.