Copyright (C) 1992-2006 William B. Ackerman and Stephen Gildea Permission is granted to make and distribute verbatim copies of this manual. Sd is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. Sd is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Sd; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Table of Contents ***************** Introduction What Sd Is Not Quality and Correctness Authenticity of Calls and Concepts Deviations from Official Lists Misuse of Computers Judgement, Controversy, and Warning Messages Variations of the Program Getting Sd or Sdtty Documentation Software Safety A Few Technical Details Installing on a PC Licensing Terms How to Contact the Authors Acknowledgements Getting Started Calling Entering Your Choice Starting a Sequence Heads/Sides Start 1P2P Lines Just As They Are Entering Calls Call Variations Call Menus Entering Concepts Supercalls Call Modifications Recentering the Setup Retaining Concepts After an Error Asymmetric Selectors The Completing Reader Question Mark and Exclamation Point Minimizing the Amount of Typing You Must Do Ignoring Hyphens and Apostrophes when Typing Abridgement Associating an abridgement file with a session Deleting an association Resolving and Searching Resolving Mini-Grand Getouts Normalizing or Standardizing the Setup Letting the program pick a random call Creating a Specific Setup The `Reconcile' operation Editing Moving the Last Call to the Clipboard Moving One Call Back From the Clipboard Moving The Whole Clipboard Back Throwing Away Just One Call Throwing Away the Entire Clipboard Printing Miscellaneous Commands Saving the Sequence Changing the Output File Changing the Title Changing to the New File Name Style `Abort', `Exit', and `Undo' Inserting Comments Keeping Pictures Singing Call Progressions Changing Modes The Initialization File Session Control Option Control Accelerator Key Control Creating an Intialization File Invoking Sd via Command Line (DOS or UNIX only) Command-Line Options Terminal Interface Sdtty Function Keys Sdtty on Unix Linguistic Idiosyncrasies Using Off-Level Concepts Call Notes Sweeping Direction ANYTHING and the ANYONE roll Roll after Exchange the Gears C1 Single Rotate Spread Centers Back Away `ANYONE' Promenade Up to the Middle `ANYONE' Cloverleaf And N/4 More Ends Divide Little, Little More, and Plenty Flip Back Face DIRECTION Adjust Alamo to Other Pairing Going Through Impossible Situations Changing between a 4x4 matrix and a Phantom Setup Matrix Calls in 1/4 Tags Concept Notes Phantom Concepts Tandem or Couples Concepts Distorted Setup Concepts 4-person distorted concepts Miscellaneous Concepts Concentric Assume Waves Assume Normal Casts With Active Phantoms Assuming a Quarter-Tag Interruptions and Replacements Designating Certain People `ANYONE' `ANYONE Disconnected' `ANYONE in your Distorted Setup' `ANYONE Do Your Part' `Ignore the ANYONE' `Own the ANYONE' `ANYONE Start' 12 Matrix and 16 Matrix Miscellaneous Advice and Warnings Customization with X Resources Introduction ************ Sd is a square dance caller's helper. The program assists you in writing sequences for Western square dancing by doing the checker pushing. You tell the program what call you want to call next, and it computes the resulting setup and shows it to you. Sd is intended to be used to write challenge-level dances where the sequences are often complex and the checker pushing tedious and error-prone. Most challenge callers write out the sequences they will call before they get to the dance, unlike Mainstream callers, who often invent the sequences on the fly from the stage. What Sd Is Not ============== Sd knows nothing about timing, body flow, or esthetics. This program is not appropriate for Traditional square dancing. A good Traditional square dance sequence requires, among other things, extremely accurate control of timing and phrasing. The program is not capable of this. Since the emphasis here is on checker pushing, you will find various Mainstream staples missing, such as Circle Left, Grand Square, and Do-Si-Do. Since these calls are "zeros", there is no reason to have them in a checker-pushing program. However, if you wish to write sequences containing calls such as these, you can use the `insert a comment' command to write them into the sequence. In short, if you are writing a Traditional or Mainstream dance, you may find that this program is not for you. It is most emphatically not the goal of Sd to present a polished graphical display of the dancers, or to show animation. The goal is to write sequences so that you can create pleasing animation among live people. If you want to enjoy the esthetic visual patterns created by square dance choreography, we recommend that you turn off your computer and go to a dance. The use of this program is not a good way to learn to call or to improve your calling or dancing skills. In fact, reliance on a computer program to write material could easily make you a worse caller, or interfere with your attempts to improve your calling skills. The knowledge of calls and concepts that this program can provide is only a tiny part what you need to learn in order to be a good caller or dancer. To call successfully, you need to master many skills, such as timing, flow, judging difficulty, floor interaction, and choosing precisely the right words to say. This last skill is as important at high levels as at low levels. Subtle differences in the words you choose, and their timing and inflection, can have a tremendous influence on the success of the dancers. Sd attempts to print the correct words in all cases, but you will only succeed if you have a deep understanding of what the words mean and how they should be delivered. That understanding can only be obtained through a great deal of experience calling at that level. If you do not have a good understanding of a call or concept, such that you could explain it to a dancer after the tip is over, you should not use it. Do not rely on Sd to provide the necessary insight into challenge dancing. For beginning callers in particular, the best thing to do is to receive instruction from a qualified teacher or coach, and to practice. We recognize that people sometimes have to learn a level in a tape group without benefit of any human expertise at that level, and that such people may have no choice but to rely on a computer program as one of their sources of information. This is an undesirable situation, and we believe that computer programs should not be used as references except in emergencies. There is an enormous body of knowledge about the accepted usage of various calls and concepts. That body of knowledge is generally possessed by all competent dancers and callers at a given level. No computer program can possibly possess that knowledge. In particular, computer programs should not be used for resolving controversial issues. This is not to say that computers have no place in the education and training of callers. A number of caller training programs have been written that may help you develop such skills as formation management and sight resolving. Sd is not suitable for this. Quality and Correctness ======================= Quality, correctness, and reliability are fundamental and extremely important design objectives of Sd. Before any version is released, it passes very rigorous diagnostic tests. These tests include verification of large amounts of C4 material from recent National Advanced and Challenge Conventions, and other C4 weekends. The elusive but ever-sought-after goal is to make a program that * never makes mistakes, * is able to write virtually all of the non-bogus material called by the top challenge callers, whatever computer program they may have used, and * is developed and tested carefully, so users can be assured that this ability will be maintained in all future releases. Authenticity of Calls and Concepts ================================== We have endeavored to use the current Callerlab lists and definitions as the source for call and concept names and definitions wherever possible. Where this is not possible, either because Callerlab does not publish lists or definitions at all levels, or because a definition is unclear in some area, we have used other well-respected encyclopedias, along with our best attempts to make things clear and sensible. Particularly at extremely high challenge levels, where there are no standardization bodies to rein in callers' tendencies to change the definitions or usage of calls, concepts, and fundamental assumptions, it is not always possible to do this to everyone's satisfaction. Spelling variations that would be insignificant in normal calling become a serious problem for computer programs. We have attempted to use the spelling in official lists where possible, but sometimes even these lists are careless. In such cases, we have attempted to correct the errors where possible, using a variety of sources. Priority is given to those sources that have shown the greatest care in their editing. Deviations from Official Lists ============================== It is a known fact that challenge callers routinely call various "popular" calls that are not on the official or semi-official lists. In an attempt to allow this, while maintaining the appearance of strict compliance with the lists, Sd has two special levels `c3x' and `c4x'. These contain the calls that are currently believed to be called at C3 and C4 but are not yet on the semi-official C3 list or the various informal C4 compilations of "commonly used" calls. It is generally _not necessary_ to run the program at either of these levels. When you run at C3, C3X calls may be used. When you run at C4, C4X calls may be used. Whenever such a call is used, a warning is printed. (If you explicitly run the program at C3X or C4X, you may use the calls without getting a warning.) Misuse of Computers =================== The phenomenon of "clueless clicking", that is, using a computer to generate challenge choreography that one doesn't really understand, is by now well-known. There are very few more effective ways to exhibit your ignorance and incompetence as a caller. High level challenge dancers are extremely sophisticated in their ability to detect this. If dancers didn't understand what you meant by something that you called, they may ask you about it after the tip is over. The answer "I meant whatever the computer did" is _never_ an acceptable answer to such a question. If you can't give an answer in terms of your understanding of how the calls and concepts really work, or if you don't agree with the program's interpretation, you shouldn't be calling that material. Judgement, Controversy, and Warning Messages ============================================ Not all callers exercise good judgement in their calling, and occasionally some controversial, or even illegal, things are called. It is not possible for a computer program to enforce good judgement or good taste. Sd nevertheless sometimes prints warning messages of various types to alert less-experienced callers that something might be unusually difficult or controversial, or might violate some definition or some commonly accepted notion. These warning messages are intended for callers less competent than you. Ignore them. You can prevent the program from displaying or printing these warning messages by giving the `toggle nowarn mode' command. This turns on (or turns off if it was already on) the "no warnings" mode. *Note Changing Modes::. You can also place a line "`no_warnings'" in the "`options'" section of the `sd.ini' initialization file (*note Option Control::) or start the program with a command-line option "`-no_warnings'" (note the leading hyphen). *Note Command-Line Options::. Variations of the Program ========================= Several user interfaces are available. They come in two general types, and the program name is different for these types. `Sdtty' is the name of the program that uses a character-oriented keyboard interface. Calls are selected by typing their names. `Sdtty' runs on Unix-like systems and under DOS, Windows 3.1, Windows 95, Windows 98, and NT on PC's. `Sd' is the name of the program that uses menus and a "graphical user interface". Calls may be selected by clicking with the mouse on the chosen menu item. You may also type calls in from the keyboard. In fact, `Sd' is keyboard-compatible with `Sdtty'--you can use it almost exactly the same way. `Sd' runs on Windows 95, Windows 98, and NT on PC's. A somewhat different version runs on Unix systems running the X Window System interface. Getting Sd or Sdtty =================== The most straightforward way to obtain `Sd' or `Sdtty' is to download the program from http://www.lynette.org/sd/ on the World Wide Web. The reference manual and other documentation may be browsed there or downloaded for your local use as well. You can obtain Sdtty for PC-compatible computers, on a 3.5-inch HD diskette, with printed documentation. The price is $4 (price valid for 2000). *Note Author Contact::. Documentation ============= If you are on the Internet, you can browse or download `Sd'/`Sdtty' documentation from http://www.lynette.org/sd/readings.html on the World Wide Web. The documentation is the same for the two programs. Documentation files are provided in several formats. There is `html' format for browsing, Postscript format for downloading and printing, `PDF' (Acrobat) format for browsing or printing, and plain text format for downloading. You can also download "gzipped" Unix archives of the various files in Unix format. The file `sd_doc' is this manual. See the file `relnotes' for information about what is new in the most recent release. There are also some documents describing a few special features in more detail. Printed copies of the manual are available from the authors, or may be printed from the file `sd_doc.ps'. Software Safety =============== The computer on which `Sd' and `Sdtty' and their documentation are developed has no Internet or modem connections at all. No mail is sent or received, and no web browsing is done, on this computer. Only software from trustworthy sources is installed. Each version of the program is digitally signed, using a 512-bit secret PGP/RSA key, and then transferred to another computer by Zip disk. The files are then mailed to the web server. Before placing it on the web, the server authenticates the signature and verifies, with the PGP signature algorithm, that the files were not tampered with in transit. Prior to May, 2000, the computer from which the web updates take place had Microsoft Outlook installed, but not used. (Netscape Communicator is used as my mailer, because of its technical and ethical superiority. Outlook had been installed only because of the policy of my employer.) The "Love Bug" virus of May, 2000 demonstrated that Microsoft is unable or unwilling to make its email software adhere to the most basic common-sense principles of safety. Accordingly, Outlook and the Visual Basic scripting / virus-propagating mechanism (wscript.exe) have been removed from that computer. No Microsoft email or virus-propagating products exist anywhere on the `Sd' development path. Various terms in the preceding paragraphs are trademarks of various corporations. A Few Technical Details ======================= Although it is a "Windows application", `Sdtty' does not use the mouse while running. It looks rather like the Command Prompt window. `Sd' runs only on Windows 95, Windows 98, and NT 4.0. Users of DOS, Windows 3.1, or NT 3.51 can only run `Sdtty', and need to run a special version, identified by the installation file being `install3.exe' instead of `install.exe'. (If you use DOS, Windows 3.1, or NT 3.51, be sure to download the correct version of the program from the web, or request the correct version when ordering it on diskette.) `Sd' and `Sdtty' are identical in their behavior with respect to square dance calling. `Sd' and `Sdtty' are believed to be insensitive to slight inaccuracies in floating-point division. It should operate correctly with early Pentium chips. The program is mostly "Year 2000 Compliant", but some care will be needed. File names created with the special names `*' and `+' contain only the last two digits of the year. We therefore recommend that you delete old files at least every 75 years or so. The date printed at the top of each sequence contains the full 4-digit year, so there should be little danger of calling a 100-year-old card without realizing it. Callers are nevertheless urged to be careful, since some dancers have extraordinarily long memories. Installing on a PC ================== `Sd' and `Sdtty' are two separate programs, that are both installed simultaneously. Whether you obtain them from the World Wide Web or by diskette, they are provided in the file `install.exe'. The two programs will share the same initialization file, and hence will use the same sessions, options, and accelerator keys. (If you are running DOS, Windows 3.1, or NT 3.51, you can only use `Sdtty', and you must obtain the file `install3.exe'.) To install the programs, execute ("launch") the file `install.exe'. You can do this by double-clicking it in the Windows Explorer, by launching it during a Web download, or by starting the "Run" operation from the start menu and giving the location of the `install.exe' file. For example, you can install from a diskette by selecting "Run" and typing "A:install.exe". If any pre-existing calling program files were in the `C:\Sd' folder, they will be saved in a folder with a name like `C:\Sd_pre3281' before the new version is installed. The installation will not damage or delete any sequence transcript files or initialization files. If you have downloaded the documentation files in "bulk" form in self-extracting zipped archives, you can launch them also. The files are `textdoc.exe', `psdoc.exe', and `pdfdoc.exe'. Launch them in the same way as `install.exe'. They will unpack the appropriate text, Postscript, or PDF files into the directory. When the installation is complete, the programs will be in the `Sd' subfolder of the `Programs' folder of the Start Menu. The installation procedure also leaves an Explorer open on the shortcut icons. There are several icons for starting `Sd' or `Sdtty' with various color schemes, for browsing the manual or release notes, and for editing the initialization file. You may copy any or all of these from the open Explorer to the Desktop and/or the Start Menu. To do this, perform a drag-and-drop operation, using the right mouse button. If the system asks, select "Copy Here". To place icons in on the Desktop, just perform a right-mouse drag-and-drop to any unused place on the Desktop. To place icons in the Start Menu, just drop them on the actual "Start" button in the lower left corner. When finished, close the Explorer by clicking the "X" in the upper-right corner. (If you are running DOS, Windows 3.1, or NT 3.51, you must place the `install3.exe' in the folder in which you want `Sdtty' to operate (typically `C:\sd'), and launch it there. You can create a shortcut icon by copying the file `SDTTY.PIF' to the appropriate place. Use the PIF editor to modify it if necessary.) You may delete the `install.exe' file at this point, along with any documentaion archives, perhaps saving copies on diskette. You do not need to copy the shortcuts again when upgrading to a new version. Installing a new version requires only obtaining and launching `install.exe'. You can, of course, copy the shortcuts anywhere, and edit them with the "Properties" operation of the Windows Explorer. Among the things you can do is put command-line arguments into them. For example, you can make another copy of the `Sd' icon on the Desktop (under a different name), and arrange for the program, when launched with that icon, to run in reverse video mode. Run the "Properties" operation on the copied icon, and change the `Target' specification on the `Shortcut' page from "`C:\sd\sd.exe'" to "`C:\sd\sd.exe -reverse_video'". Licensing Terms =============== `Sd' and `Sdtty' are "free software" programs, licensed under the GNU General Public License, which is in the file `COPYING.txt' in the distribution. You can also get it by writing to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. In short, this means that it is perfectly legal and ethical to copy and redistribute the program, documentation, and source files. You are, of course, not required to download the source files when you obtain a copy of `Sd' from the web page. If you want to make the program available to someone else, and you do it by giving them the URL for downloading, that is OK. However, if you distribute the program by other means, such as giving someone a copy that you have placed on a CD or diskette, you must either place the source files on the disk also, or tell the person the URL (http://www.lynette.org/sd/) from which they can download them. Also, if you redistribute `Sd' on your own web page or similar mechanism, you must make the source files available there. If you modify the program, the terms of the license are very strict. Programs constructed from modified source files may never be duplicated or redistributed by anyone, even just in executable form, without obeying the conditions of the license and copyright. Read the license carefully. Note in particular that any modified program based on `Sd' or `Sdtty' must obey the licensing terms every time it is redistributed by anyone. This requires redistribution of all of the source files, or otherwise complying with section 3 of the license. The Windows installation program `install.exe' contains licensed commercial decompression software. The licensing terms prohibit extracting or reverse-engineering that software. This document is distributed in both formatted and plain-text form, in the files `sd_doc.ps' and `sd_doc.txt', respectively. Some other documents are also distributed with the program. Permission is given to distribute verbatim copies of these documents, either by photocopier or by computer, but modification of them is forbidden by copyright law. How to Contact the Authors ========================== Please send any praise, bug reports, or other comments on Sd to the authors at the addresses given below. Be sure to include the version number. William Ackerman wba@alum.mit.edu Stephen Gildea gildea@.stop.mail-abuse.org If you do not have access to electronic mail, write to Bill Ackerman 100 Parlmont Park North Billerica MA 01862-2722 Acknowledgements ================ Thanks to Kathy Godfrey, Sue Curtis, Chris Stacy, and Lynette Bellini for their help, encouragement, suggestions, contributions of calls, feedback, testing, and many other contributions. The non-windowed interface for `Sdtty' (*note Terminal Interface::) was contributed by Alan Snyder. The `Sd' interface for Windows was contributed by Robert Cays. We received helpful feedback and testing from Robert French, Judy Anderson, Bill van Melle, Tom Rinker, Lois Lew, Ron Nicholson, Dave Decot, Kristin Jensen, Larry Dunn, and Nick Martellacci. Getting Started *************** Throughout this manual, the name `Sd' will generally be used to denote both `Sd' and `Sdtty', except in those areas in which the programs are different. If you are using a PC and have installed `Sdtty' to run under Windows 3.1 or Windows 95, start the program in the usual way by clicking its icon. `Sdtty' is actually a DOS program, so, once it is started, it will not use the mouse. The first thing it will do (assuming you are not using the session control feature of the initialization file) is ask you for the level. Type the desired level and press . `Sd' or `Sdtty' can be run from a shell (on Unix or DOS) by typing its name and the level you want to write sequences for, e.g., sd c2 or sdtty c2 In addition to calls and concepts, there are program commands for actions such as automatic resolves, exiting the program, and other miscellaneous actions. *Note Resolving and Searching::. In `Sd', they are found in the menu in the upper left corner. In `Sdtty', just type the name of the command. The following chapters cover the operation of `Sd' in detail. Calling ******* This chapter describes how to use the program in its normal mode to generate a sequence of calls of your choosing. Entering Your Choice ==================== Selections are made in the same way almost everywhere in the program. In either `Sd' or `Sdtty', you may type in the selection. The program has a sophisticated "completing reader" that lets you abbreviate what you type. It is discussed in detail in *Note The Completing Reader::. In `Sd', you may additionally select an item from the menu in the usual ways. You may double-click it, or highlight it (by using the cursor keys, for example) and click the `Accept' button. (You may activate things with a single mouse click, if you prefer that style of operation, by issuing the `toggle singleclick mode' command or by placing the `single_click' option in your initialization file.) You can see the choices that are available by typing a question mark or exclamation point. This is discussed in detail in *Note Question Mark::. In normal operation, the menu lists calls first, concepts next, and miscellaneous commands last. This menu is typically extremely large and needs to be manipulated with cursor keys or the scroll bar. Starting a Sequence =================== A special "startup" menu is displayed when the program starts, and after each sequence has been completed and written to a file. It provides a number of miscellaneous commands, including commands to change various modes such as the `active phantoms' mode or the `singing call' mode. *Note Miscellaneous Commands::, for further discussion of these. The startup menu also allows you to `exit from the program' and return to your computer's operating system. The main use of this menu is to select the starting operation. Heads/Sides Start ----------------- If you select `heads start' or `sides start', the sequence will begin with `heads' or `sides' and the first call. Normally this means that the designated people will move into the center and do the first call while the others wait. Subsequent calls will be directed to everyone. For example, one might select `heads start', and then `star thru', and then `double pass thru', and so on. You can also select `heads start' or `sides start' followed by a call such as split square thru or split dixie style to a wave. If you want to have the heads go into the middle and do several calls before the sides join in, as in head ladies chain and then heads square thru 4, or heads touch 1/4 and then walk and dodge, you must select `centers' before all calls after the initial one. Typically, you won't need to read the card that way, but can rely on precise phrasing and inflection of your voice to express what you want. 1P2P Lines ---------- The `heads 1P2P' and `sides 1P2P' starting actions refer to caller jargon for a common starting maneuver, typified by lead right and circle to a line. You can read the card that way, or as wheel thru and circle to a line, or as step right, or as bring us together, or whatever improvisation you like. The promenade distance shown at the end of the sequence will assume that you said step right or lead right (or wheel thru) and circle to a line. Whether you consider 1P2P openings to be overused is up to you. Just As They Are ---------------- The `just as they are' selection starts the sequence on squared set spots, without having the heads or sides begin. This is generally useful only if the all 4 couples concept is to be used. After using this, you typically need to have the heads or sides (or headliners or sideliners, in some cases) press ahead, in order to continue the sequence. Entering Calls ============== The usual thing you do when writing a sequence is to select calls, perhaps preceded by one or more concepts. You can select concepts and calls separately, or, if using the completing reader, type concepts and calls together. That is, you can type the entire "line". You should be aware that a number of "modifier" words like `cross', `left', and `grand' are treated as concepts by `Sd' and `Sdtty'. While concepts don't officially exist below the Advanced program, `Sd' and `Sdtty' consider words such as these to be concepts. When typing things in, this generally makes no difference. Because of the way the program operates, you can just type the call, with whatever concepts or modifier words it has, in the natural way. For example, you could type: grand swing thru or: centers cross run In a few cases, either because a concept has a complex structure (e.g., `checkpoint'), or because an utterance is ambiguous (e.g., doing 1/2 of a stable swing thru vs. doing a 1/2 stable swing thru), it is necessary to type concepts by themselves, pressing after each one. This will be discussed further in *Note Entering Concepts::. When using `Sd' and selecting things with the mouse, you will usually not see full combinations listed in the menu. For example, there is no item `grand swing thru'. The menu would be too unwieldy if such things were listed separately. Instead, all concepts, modifier words, and calls are listed separately in the menus. To get a grand swing thru with mouse clicks, click on `grand' and then `swing thru'. Call Variations --------------- There are a number of issues that make call entry less than completely straightforward. These have to do with variations that calls have--directions (as in `quarter left'), numbers (as in `square thru 3' or `three quarter thru'), person designators (as in `sides kickoff'), subcalls (as in `clover and [quarter thru]' or `vertical tag your neighbor' or `shuttle [rally]' or `in roll motivate'), and modifiers (as in `strut left' or `trans cross chain reaction'). To list all possible variations in the menu would be unwieldy for a variety of reasons. Because of this, various methods are used to shorten the menu and to allow the user to specify the desired variation. These methods will be discussed in detail presently, but in most cases what happens is the following: In `Sd', the menu lists only the base calls with special keywords as in `face ' or `square thru '. When you click on such a menu item, a new menu appears listing the possible choices. In `Sdtty', the "menu" (that is, what you see if you type a question mark) also has keywords. You can type the item just as shown, e.g., `quarter ' or `square thru ' (you would actually type the angle brackets) and then answer the question that `Sdtty' asks. But there is an easier way--you can type what you want directly. That is, just type `quarter left' or `square thru 3'. If you want to see the choices, type `quarter ' or whatever, and then type a question mark. Directions .......... Calls that take a direction have the keyword `' in them in the menu, like `pass ' or `spin a windmill, outsides '. You can just type the call naturally, for example, `pass in' or `shuttle left'. You can also type such things in a piecemeal fashion, typing the keyword "`'" literally, and then typing the direction. When using the mouse with `Sd', the second way is the only way--click on the call, and then select the direction from the new menu that will appear. If you decide you don't want that call, click the `Cancel' button. The menu lists all possible directions, including some that may not be legal in the given context. Numbers ....... Calls that take a number have the keyword `', `', or `' in their name. Examples are the calls `eight chain ', `invert the column ', and `square thru, but on the hand '. You can just type the call naturally, for example, `invert the column 3/4' or `square thru 2' or `1/4 thru' or `square thru but on the 3rd hand'. You can also type such things in a piecemeal fashion, typing the keyword "`'" or "`'" or "`'" literally, and then typing the number(s). If the keyword was `', enter just the value of `N'. When using the mouse with `Sd', the second way is the only way--click on the call, and then select the number from the new menu that will appear. If you decide you don't want that call, click the `Cancel' button. Not all values of `N' will be meaningful for all calls. For example, you can `eight chain 5', but you can't `invert the column 5/4'. Some calls have the words `quarter', `half', or `three quarter' in their names. Examples are `quarter thru', `quarter the deucey', `quarter mix', `quarter the alter', and `quarter chain and circulate in'. These are listed in the Callerlab lists with the words spelled out, though individual preferences vary. Some people prefer to write `1/4 thru' and `3/4 thru'. `Sd' and `Sdtty' list the call as ` thru' in the menu. When using mouse input in `Sd', you click on that and then click on a number (only 1 and 3 are legal, of course). You can also type ` thru' and then type 1 or 3, or you can type the call directly, either in numbers or in words. That is, you can type either `1/4 thru' or `quarter thru'. No matter how you enter one of these calls, it will always be printed out in words, as in `three quarter thru' or `half chain and circulate in'. Person designators .................. These work like the others in a straightforward way. The calls appear in the menu with the `' keyword, as in `patch the '. You can just type the call naturally, for example, `patch the sides'. You can also type such things in a piecemeal fashion, typing the keyword "`'" literally, and then typing the designator. When using the mouse with `Sd', the second way is the only way--click on the call, and then select the designator from the new menu that will appear. If you decide you don't want that call, click the `Cancel' button. The gender designators are `boys' and `girls'. This is the way they appear in the Callerlab Mainstream list. The author does not take a position on whether the adult terms would be more reasonable words to use in any given context. You must use your own judgement in deciding what to say. Not all designators are legal in all cases; for example, you can't call `leads run' from a tidal wave. The program specifically refuses to recognize the meaning of the designators `centers' and `ends' while in a 1x8 setup (e.g., a tidal wave). This is because these terms can be ambiguous in such a setup. If you want the centers of each 1x4, you must use the `EACH 1X4', `EACH LINE', `EACH COLUMN', or `EACH WAVE' concept in order to make the `centers' or `ends' designators work. Of course, in many cases, other designators, such as `boys' or `girls' can identify the same people unambiguously. If you want to designate the 4 people in the center of the set, use `center 4'. `Outer pairs' specifies the others. Tagging calls ............. Calls that use tagging calls have the keyword `' (for Any Tagging Call) in them, as in ` your neighbor' or ` chain thru and scatter reaction'. Specify these in the usual way. In `Sdtty' you can type the `' directly or you can enter the complete call. At C3 and above, the tagging calls include the calls `revert ' and `reflected ', which make use of another tagging call. When using mouse input in `Sd', you will be presented with another menu. In `Sdtty', you can type in the entire call directly, as in `revert cross flip chain thru reactivate'. Subcalls ........ Some calls have an "`'" in them when they appear in the menu, such as `clover and ' or ` and roll'. The "`'" is intended to be replaced by a subcall. When you type these in, put the subcall in brackets. That is, you literally type something like: clover and [tandem shazam] [flip the diamond] and roll busy [lockit] catch [erase] 2 slant [swing thru] and [turn and deal] fascinating [ah so] [jay walk] and plenty, turn the star 3/4, interrupt before the star turns with [trade circulate] The subcall in brackets may be any combination of concepts and calls, and these may be nested. As an example of this, you can type: [[vertical tag your neighbor] and spread] er's percolate clover and [3/4 stable left catch [[reflected flip your neighbor] and spread] 3] (Two of the examples above don't fit on one line in this manual, but you would type them on one line.) *The brackets are required.* Without them, the program couldn't tell the difference between clover and [[swap around] and roll] and [clover and [swap around]] and roll or between first 1/2 stable swing thru and first [1/2 stable swing thru] You can also enter such things in a piecemeal fashion, typing the keyword "`'" literally, and then typing the subcall when the program asks for it. For example, you could type clover and and then type square thru 2 . When using the mouse with `Sd', the second way is the only way--click on the call, and then select the subcall. *Important note:* Nesting these subcalls too deeply can make the program run very slowly. You should not type more than two consecutive left brackets. If you need to nest things more deeply than that, use the word "`'", and enter the subcall when the program asks for it. For example, suppose we wanted to enter: [[[trans cross reactivate to a diamond] chain thru] and anything] percolate, boys to a wave (Berkshires C4 weekend, May 1996.) (As if that weren't complicated enough, note that the word "anything" in the above call is the literal "anything" concept, not the `' mechanism of `Sdtty'.) This is too complicated to type directly. We would instead type: percolate, boys to a wave The subcall we want is now `[[trans cross reactivate to a diamond] chain thru] and anything'. When asked for the subcall, we type: and anything The subcall we want is now `[trans cross reactivate to a diamond] chain thru'. When asked for the subcall, we could type that directly, or we could type: chain thru and then type: trans cross reactivate to a diamond These "mandatory" subcalls, with the keyword `' in the menu, are just one of many types of modifications. *Note Call Modifications::, for some other types of modifications. Calls with circulate replacements ................................. A number of calls, all of whose definitions start with a circulate, are subject to a special circulate modification mechanism, recognized at C2, and officially called the "(anything)" concept. The call name (e.g. "`motivate'") is preceded by a word or phrase such as "`in roll'" telling how the circulate should be modified. Examples are in roll motivate bias trade perk up split counter coordinate (not actually a type of circulate) counter cover up (not actually a type of circulate) These variations are in the menu as "` motivate'". They can be typed in just as shown above. You can also enter them in a piecemeal fashion, typing the keyword "`'" literally, and then typing the circulate replacement as a complete call, for example, "`out roll circulate'". When using the mouse with `Sd', the second way is the only way--click on the call, and then select the circulate replacement from the new menu that will appear. If you decide you don't want that call, click the `Cancel' button. Only bona-fide circulate-type calls, and other well-recognized similar things such as `split counter percolate' can be obtained by this method. You can get more general substitutions by using the `' (as opposed to `') mechanism. The more general substitutions are in brackets. Such things will print out with the word "er's" to distinguish them. You can type in the "er's" or not, as you choose. The apostrophe is optional. For example, you can type `[2/3 recycle] er's percolate' or `[2/3 recycle] percolate'. Note that trade motivate (an instance of ` motivate') and [trade] er's motivate (an instance of ` motivate') are very different. There is a third way to enter such calls. By giving the `simple modifications' or `allow modifications' command and then just entering the call (e.g. `motivate'), the program will ask you for replacements. These replacements may be anything and will appear in brackets in the final transcript. This is discussed in *Note Call Modifications::. Modifiers such as cross, left, split, grand, single, magic, and interlocked ........................................................................... As discussed above, the program considers these to be actual concepts, even though they aren't really. Some calls use these concepts in ways that have a tricky word order. Whether the word order is tricky or not, you can always enter the concept followed by the call as separate items. For example, in `Sd', you can click on `left' followed by `chase right'. In `Sdtty', you can type in `left' and then `chase right'. In addition, `Sdtty' allows more natural text entry. You can type in `grand swing thru' or `chase left' directly. Other examples of this phenomenon are switch to an interlocked diamond unwrap the magic diamonds hang a left scoot and cross ramble trans cross reactivate revert cross flip chain thru cross nuclear reaction No matter how you entered it, the calls will be printed out with the words in the correct place. The foregoing only applies to calls in which the word is an actual concept or modifier. Some calls happen to have the word `cross' as part of their names. Examples are: `cross and wheel', `cross and turn', `cross your neighbor', and `crossfire'. Such calls appear in the menu just as they are spelled. Call Menus ---------- The menu in `Sd', or the list of available calls in `Sdtty', changes according to the current setup. For example, if the current setup is right-hand waves, the menu will contain only those calls that the program believes might be legal from right-hand waves. This determination is approximate but conservative--appearance on the menu does not necessarily mean it is legal, though absence from the menu means that the program is fairly certain that it can't be legal. There is a "universal" menu that appears when the setup is not one of the common ones, or when anything complex is going on. This contains every call that is in the database for the chosen level. The call menu is alphabetized in a way that ignores blanks and hyphens. Special keywords such as `', `', `', or `' are listed after letters. Hence, ` run' and ` your neighbor' will be found near the end of the menu. Entering Concepts ================= A call may be preceded by concepts, which modify the action of the call. These may be nested ("stacked") to any reasonable depth. When using the completing reader, just type the concept you want. The completing reader will operate in the usual way. Nearly all concepts may be entered in a natural way, on the same line as the call that they affect. As discussed previously, this means that you can type things like grand swing thru or boys 1/2 stable split the difference or random tandem swing thru Whether you typed concepts separately or together, the result is the same, and the output file will look the same. For example, the following are all legal and equivalent. reverse random tandem swing thru reverse random tandem swing thru reverse random tandem swing thru In the output file, they will all be shown as `reverse random tandem swing thru'. Occasionally some ambiguous situations can arise. What if you wanted the boys to do 1/2 of a stable split the difference? The phrase `boys 1/2 stable split the difference' is ambiguous. Whenever `Sd' is confronted with an ambiguity, it chooses the option that nests concepts least deeply. A single application of the 1/2 stable concept is less deep (simpler) than an application of the 1/2 concept followed by an application of the stable concept, so it chooses the former. If you really want to tell the program to do the latter, you must make clear that you mean the 1/2 concept by itself. The way to do this is to enter each concept separately, pressing after each one. That is, type boys 1/2 stable split the difference When using the mouse with `Sd', you must click on exactly the concepts that you want. To get the `boys' concept, you must click on `' and then make the appropriate selection. To get the `1/2' concept, you must click on `/' and then make the appropriate selections. If you want the 1/2 stable concept instead, click on ` stable', and then select `2'. When `Sd' resolves an ambiguity, it shows how it did so through the judicious use of commas. For example, the preceding operation will be printed as `boys, 1/2, stable, split the difference', as opposed to `boys, 1/2 stable, split the difference'. Do not type the commas in. Whenever you run into trouble typing concepts, try typing each one separately, pressing after each one. Concepts displayed after the call ................................. The concepts `twice', ` times', and `1-/' will be displayed and printed after the call rather than before it, unless doing so would be ambiguous. *You still type the concept before the call.* For example, you type `1-1/2 swing thru'. The result will appear as `swing thru 1-1/2'. The program will sometimes use parentheses to prevent ambiguity. Concepts that operate on two calls .................................. Some concepts require two calls (e.g., `checkpoint' and `interlace'). You must enter such concepts by themselves. That is, you must press after typing any of these concepts. You can't type checkpoint ah so by recycle nor boys trade (while the others) u-turn back You must type checkpoint ah so recycle or boys (while the others) trade u-turn back After choosing such a concept, enter the first call, preceded by whatever concepts apply to it. The program will then prompt you for the second call. A complex tree of concepts and calls can thus be constructed. Some concepts require a numeric designator (e.g., `interrupt after the 3rd part') or a people designator (e.g., `girls are stable'). The handling is the same as for calls that require these. The program recognizes the level at which concepts are legal, but lets you override this if you wish. The `toggle concept levels' command toggles (turns on or off) the state of off-level concept permission. *Note Changing Modes::, and *Note Using Off-Level Concepts::. When you select any concept, the universal call menu replaces whatever special call menu may have been presented, since the set of legal calls becomes highly unpredictable. Supercalls ========== Thinking in mathematical or computer terms, a concept is a "function" that operates on an "argument". That argument is a call, or perhaps another application of a concept to another argument. For example, in `tandem lockit', the function `tandem' applies to the argument `lockit'. Calls of the `clover and [anything]' variety behave the same way. This call takes an "argument" call, and has the centers do that while the outsides cloverleaf. Such a thing is called a "supercall". It could just as easily have been considered a concept. The significance of this is that some concepts, called "meta-concepts", operate on _concepts_ rather than on calls or concept-call combinations. Examples of meta-concepts are `random', `initially', `finally', and `echo'. Since supercalls are like concepts, meta-concepts can operate on them. What would happen if we applied the `finally' concept to the supercall combination `clover and [right and left thru]'? We do the `right and left thru' without the "concept" up until the last part. The "concept" is `clover and [anything]'. If we skip the concept, we just do the `right and left thru' up to the last part. That is, we do a right pull by. Then, for the last part, which is a courtesy turn, we apply the supercall. That is, we do a `clover and [courtesy turn]'. So `finally clover and [right and left thru]' is danced as: right pull by clover and [courtesy turn] `Sd' can handle straightforward cases of supercalls with meta-concepts. You must enter the supercall in the square bracket notation. That is, you may not use the method of typing `' and expecting to type in the second call later. Because the search mechanism (`pick random call', etc.) does not fill in subcalls, it will not find applications of meta-concepts and supercalls. Sorry. Some supercalls take their "argument" call at the beginning of the phrase rather than the end, as in `[anything] and roll'. Such supercalls don't scan very tastefully. For example, `echo [hinge] and roll' means that the "and roll" is applied first, even though it is at the end of the phrase. We do a `[hinge] and roll' first, and then just a `hinge'. The word order doesn't make that clear. Supercalls in which the `[anything]' call is at the end, like `busy [anything]', `transfer and [anything]', `eight by [anything]', and `dodge [anything]' are much more likely to be executed successfully. Call Modifications ================== Some calls can be modified in a natural way, such as `catch [fan the top] 3', `busy [1/2 tag]', and `vertical tag your neighbor'. Some calls can be modified in unnatural ways, such as `trade the diamond but replace the diamond circulate with explode the diamond'. The usual way to perform natural modifications is simply to type the call as decribed in *Note Call Variations::. To form an unnatural type of modified call, you must first enable call modifications by selecting `simple modifications' or `allow modifications' before choosing the call. There are two levels of this feature. With `simple modifications', you get the simple version, which only prompts you for "natural" modifications. Natural modifications have been somewhat arbitrarily defined as those for which there is an accepted way of fitting the words in without using the phrase "but replace the with ." With `allow modifications', you allow a potentially large number of modification possibilities, sometimes several in the same call. In most cases, `simple modifications' is probably the right thing. For all but the most extreme cases of modifications, you don't need to do it this way, because the "`'" mechanism can be used instead. Just type the call with the replacement call in brackets, as in busy [lockit] fascinating [ah so] *Note Call Variations::, for more details about this. When either level of modifications is selected in `Sd', the status line above the text transcript area indicates this. Also, the universal call menu is chosen whenever modifications are enabled, since the possibilities are unpredictable. When you select a call for which modifications are possible, the program will ask a question like `The box circulate can be replaced. Do you want to replace it?' If you want to replace the designated call, click in the active area of the popup; otherwise, move the mouse away. If you indicate that you want to replace the call, you will then be prompted for the replacement call. Enter it, along with any concepts. In some cases you may be asked repeatedly about various modifications. For example, in motivate, you can replace the initial circulate, and you can turn the star a different amount. You may select any or all of these modifications. Note: When complex modifications are involved, the program may ask for them in an order that seems unnatural. This is because it asks in the order that it executes the call internally, which may not be the same as the order in which the words are spoken. Do not be alarmed. Observe the popup titles and prompts carefully. The final result will come out in the correct order. For both these optional modifications and the mandatory subcalls discussed earlier (e.g., `clover and '), the program attempts to show unambiguously how everything is structured, by putting subcalls and their accompanying concepts in square brackets. It also attempts to put natural modifications in their natural place in the phrase. In complex cases, like `[CHECKPOINT LEFT catch [SINGLE CONCENTRIC snake] 3 BY [2/3 recycle] the difference] cover up' things may be quite difficult. How (and whether) you choose to read such a card is up to you. Recentering the Setup ===================== When writing unsymmetrical material, one sometimes moves the entire square into a position that is not centered on its original location. In such a situation, it is sometimes useful to tell the dancers to forget that original location and consider their present location to be the entire setup. `Sd' has a pseudo-call `recenter' that can be used for this purpose. It recenters the setup, that is, throws away unsymmetrical phantoms. Its level has been set to C1. It is not a real call, of course. There is no standard convention for what you have to say to the dancers when you want to perform this operation. Retaining Concepts After an Error ================================= When an error occurs in the execution of a call, `Sd' has an option whereby it tries to leave in place any concepts that were associated with that call. That is, after displaying the error message, the program will behave as though you had once again typed those concepts. The assumption here is that only the call was mistaken, and you really wanted the concepts and do not wish to have to enter them again. If you don't want those concepts, you can remove them one by one with the `undo' command. Or you can use the command `discard entered concepts' to get rid of all of them at once. The `toggle retain after error' command toggles (turns on or off) the state of this option. *Note Changing Modes::. It can also be turned on when the program begins, either by giving a command-line option (*note Command-Line Options::) or through the use of the initialization file (*note Option Control::). Asymmetric Selectors ==================== The people selector popup contains various asymmetric selectors such as `near line' and `far box'. You can use these selectors with the ` do your part' concept to call near column pass thru, etc. The resultant setup must be reasonable--shape-changers on one side of the set may lead to problems. If you have not restored symmetry, resolves may be extraordinarily difficult to find. The Completing Reader ********************* `Sd' and `Sdtty' use a "completing reader" for interpreting the characters that you type. In `Sdtty', this is the only means of entering calls and commands. In `Sd' you can use the mouse and menus, but you can also type. When you type characters into `Sd', it uses the same completing reader as `Sdtty'. In fact, the two programs are completely compatible with each other if only keyboard input is used. The completing reader requires you to type only as much of the word or command as is required to be unambiguous. Whenever you type a space, the program completes the word you just typed, if necessary and possible. Whenever you type (or on some keyboards), the program completes the entire line if necessary and possible. For example, at Mainstream, you can enter a swing thru by typing `swing thru '. When the space after `swing' is typed, no completion is required. When the after `thru' is typed, no completion is required either. If you type `sw thru ' instead, `Sd' completes the word `swing'. It does this by displaying `ing' on the screen as soon as you type the space after `sw'. If you type `sw th ', `Sd' will complete both words. It displays `ing' as soon as you type the space, and it displays `ru' as soon as you type . In fact, you could just type `sw '. `Sd' completes the entire line, if necessary and possible, when is pressed. So it will display `ing thru' after your `sw'. In each case, the full phrase `swing thru' will appear on the screen, and will be printed in the final sequence. Because of this completion, you can get into the habit of just typing `sw ' at Mainstream. However, it will only work if what you type is unambiguous. At higher levels, `sw' could also mean `swap around'. When there is an ambiguity, `Sd' will complete as much as it can and beep at you. You can type `?' or `!' (discussed below) to see what the problem is. With practice, you can get a reasonable feel for how much abbreviation you can get away with in a given context. Typing will complete the entire line, just like , but will not actually process the line. If you like what you see, you can then press to execute the call. If the line is ambiguous, the program will display as much of the line as it can. When used effectively, this can save you a lot of typing. `Sd''s completing reader is completely indifferent to the capitalization of what you type. It capitalizes its output according to its own notions of aesthetics and ambiguity avoidance. Question Mark and Exclamation Point =================================== At any time, you can type a question mark or exclamation point. Either of these will make `Sdtty' display all legal completions of the line that has been typed so far. If what you have typed is unambiguous, that will consist of just one thing. If you have typed nothing, it will consist of every legal thing you could type--typically that is every call, every concept, and every special command. The difference between question mark and exclamation point is that the question mark actually attempts to execute every call in the current call menu (that is, every call whose name matches the text you have typed so far), and shows only those that can be legally performed. Exclamation point simply displays every call on the menu that matches the text that you have typed so far. Remember that the call menus are only approximate--they often have many calls listed that are in fact not legal in the present setup. This is particularly true when concepts are in place. The program simply has no idea what calls are legal without trying them. Question mark tells it to do so. The difference between question mark and exclamation point only applies to calls. All concepts and special commands (`resolve', for example) are always listed whenever either character is typed. The output from typing a question mark or exclamation point may be quite lengthy. If it fills more than one screenful, `Sdtty' will stop and display `--More--' at the bottom of the screen. Type to go on to the next screenful. Type to see just one more line. Type a backspace (or ) to stop. When the output ends, either because `Sdtty' displayed everything or because you typed a backspace, the partially entered line will be redisplayed, just as it was before you typed the question mark. When you are typing calls or concepts and you type while the line that you have typed is ambiguous, `Sdtty' will display something like `(10 matches, type ! or ? for list)'. The number that it displays is the number of syntactically legal choices among which it can't decide. This is the number of choices that would have been listed if you had typed `!'. It may be more than the number of things that would be listed if you had typed `?'. The reason is that the `?' operation has to test every call before listing it. It can easily do this faster than you can read the list of choices. When you type while there are multiple syntactic choices available, the computer can't count them fast enough to respond instantaneously. It therefore displays an approximate number, computed by looking at its database without testing each call. Minimizing the Amount of Typing You Must Do =========================================== The `Sdtty' completion mechanism, especially the (or or ) key, can save you a lot of typing. For example, typing heads do your part is probably more than you want to do. If you type just heads do the line will be almost unambiguous--there are only two possible commands that start this way. By typing a question mark, `Sdtty' will show them to you. They are heads do your part and heads do your part (while the others) What these concepts actually mean will be discussed at length in *Note Designating Certain People::. For now, we are just discussing how to type them. These commands don't differ until the `t' in `part'. If you type after `part', `Sdtty' will know that you want the first of these commands. If you type a space and then , `Sdtty' will know that you want the second. Does this mean that you must type the whole command up to `part', followed by a space or ? No. Just type `heads do', and then press . `Sdtty' will display `heads do your part', since that is the text that is common to both commands. At that point, you may press to get the `heads do your part' concept. Or you could type space and then to get the `heads do your part (while the others)' concept. You could, of course, type the complete phrase `(while the others)' after the space, but there is no need to. Once you type the space, `Sdtty' knows exactly which command you want. What would happen if you tried to shorten the command still further by typing just `heads d' instead of `heads do'? Below C2 this would work just fine. At C2 and above, an ambiguity would exist because of the `heads disconnected' concept. Typing a question mark after `heads d' will show you the ambiguity. In general, typing a question mark will help guide you in minimizing the amount of typing you must do. With practice, you will be able to enter your favorite calls and concepts with minimal typing. Here is another example. To enter `criss cross the shadow' or `criss cross your neighbor', it is not necessary to type `criss cross t' or `criss cross y'. You can just type `cri' followed by . The program will display everything up to the point of ambiguity, which, at C2, is `criss cross '. At that point, you just need to type `t' or `y', followed by . Above C2, there are more possible calls, but typing `cri' followed by is still a good way to start. Ignoring Hyphens and Apostrophes when Typing ============================================ You can type a space instead of a hyphen in call and concept names. For example, you can type `ping pong circulate' or `tandem based triangles' instead of `ping-pong circulate' or `tandem-based triangles'. The calls will always be printed out with the hyphen. You can omit apostrophes when typing in call and concept names. For example, you can type `lockers choice' instead of `locker's choice'. The calls will always be printed out with the apostrophe. Abridgement *********** The program recognizes four operations which allow use of an abridged list of calls: `Write list (with a filename)' write out the call list for the indicated level and exit `Write full list (with a filename)' write out the call list for the indicated level and all lower levels and then exit the program. `Use abridged list (with a filename)' read in the file, strike all the calls contained therein off the menus, and proceed. `Delete abridgement' only meaningful with a session. It permanently removes the association of an abridge list with that session. These may be invoked by checking the appropriate box in the `Sd' startup dialog, and filling in the file name if required. They may also be invoked by starting the program with command-line options: -write_list FILENAME -write_full_list FILENAME -abridge FILENAME -delete_abridge The first two operations are used to prepare a call list. The call list for the indicated level, exactly as the calls appear in the menu, will be written to the named file. If `-write_list' is used, only the calls exactly on that level will be written. If `-write_full_list' is used, the lower level calls will be written as well, so the file will look exactly like the main call menu. After performing either of these operations, the program exits. The third special flag is used to read in a list of calls to be avoided. Any call listed in the file, in precisely the same format as it was written out, will be removed from the internal database prior to running the program. Every sequence written under control of such a file will say `(abridged)' on its header line. To write sequences for a group that is learning C2, for example, start Sd from the Start Menu and then check the box marked "Write list", enter the desired filename, click "accept", and choose the C2 level. Or, if you prefer command-line operation, do (with either `Sd' or `Sdtty'): sd -write_list mondayC2.txt c2 In all cases, this will write out its C2 list into the file `mondayC2.txt'. Then delete from that file those calls that the group has learned, i.e., those calls not to be avoided. Use a plain text editor, such as Emacs or Notepad, for this. When writing sequences, start Sd from the Start Menu and then check the box marked "Use abridged list", enter the desired filename, click "accept", and choose the C2 level. Or you can do: sd -abridge mondayC2.txt c2 As the group learns new C2 calls, delete the corresponding lines from the file `mondayC2.txt'. That file always contains the calls that they don't yet know. When the file goes to zero, they (presumably) know the whole list. Be aware that the abridgement mechanism works only for calls, not for concepts. You must keep track of what concepts not to use. The lines in the abridgement file must always be in exactly the same format as the strings that are written out by the list creation operation. The program has no tolerance for creative capitalization, stray blanks, or other variations. Any line in the file that does not match a call in the menu is simply ignored. The order of the lines is not important. We recommend using the file exactly as it is written out with the "write list" or "write full list" operation, and using an editor only for the purpose of deleting lines from it. The abridgement mechanism, and the session mechanism, work interchangeably between `Sd' and `Sdtty'. You can use one program to create or manipulate abridgement files or sessions, and then use the other program to use them. Associating an abridgement file with a session ============================================== You can associate abridgement lists with sessions. To create a new session with a given abridgement file, start Sd from the Start Menu and then check the box marked "Use abridged list", enter the desired filename, select the session labeled "create a new session", select the desired level, and enter the session number when prompted. Or you can do: sd -abridge mondayC2.txt c2 and create the session from there. If you want to associate an abridgement file with an already existing session, do the same thing, but select the existing session. Once the association is made, it is permanent-this step will not be required again. Simply selecting the session will get the abridgement list. Deleting an association ======================= You might want to do this after the class has finished learning the list, and you want to continue writing material for that session. Start Sd from the Start Menu and then check the box marked "Delete abridgement", and select the desired session. Or you can do: sd -delete_abridge Resolving and Searching *********************** This chapter describes how to have the program find calls for you to accomplish various goals. Resolving ========= Whenever the setup is in a resolved state, whether intentionally or accidentally, the program indicates that fact at the bottom of the transcript area. The program looks for right and left grand, left allemande, promenade, single file promenade, and circle left/right getouts from a variety of setups. If the sequence needs an extend, slip the clutch, circulate, pass thru, trade by, cross by, or dixie grand first, the program reports that too. Whenever the `resolve' message appears, you can end the sequence and write it to a file by selecting `write this sequence'. In `Sd', the button for this is in the group in the upper left portion of the screen. In `Sdtty', simply type the command, with the usual completion mechanism. There are at least three ways to resolve a sequence: you can wander into a resolve by accident, you can "sight resolve" the square, entering the calls that you want, or you can use the `resolve' command. This command adds the necessary calls to the sequence, exactly as if you had entered them. When you select `resolve', the program goes into a special mode in which it searches for resolutions, saves them, and lets you look through them and pick one that you like. A resolution is a sequence of up to three calls that leads to a resolved state. While the program is in resolve mode, the call menu is replaced by a special menu of options, along with information about the current resolution. That information tells how many resolutions are currently stored and which one is currently shown. When you select `resolve', the program finds the first resolution and displays it, showing information `1 out of 1', which means that it has one resolution stored, and resolution number one is currently displayed. The transcript area shows the effect of that resolution. You can select `find another' to search for another resolution and add it to its stored list. When the list has more than one resolution in it, selecting `previous' and `next' will move around in its list of previously found resolutions and show whichever one you want. In this way, you can search for a better resolution than the one you already have, but go back to the earlier one if no better one is forthcoming. Selecting `accept current choice' will leave resolve mode, causing the current resolution to be added to the sequence exactly as though you had entered those calls manually. Selecting any of `abort the search', `exit the search', `quit the search', or `undo the search' will throw away all of the saved resolutions and leave resolve mode, but will not destroy the sequence. The sequence will be left just as it was before `resolve' was selected. Selecting anything else, such as `write this sequence', is equivalent to `accept' followed by whatever that action is. So, for example, you can select `write this sequence' as soon as you see a resolution that you like. These special commands may be typed into the completing reader in the usual way. To make it more convenient to enter them, the command names have been chosen to be unambiguous from just one or two letters. So, for example, `p' means `previous', `n' means `next', and `f' means `find another'. If one or more concepts have been entered when you select `resolve', the program will search only for resolutions whose first call starts with those concepts. So, for example, selecting `once removed' and then `resolve' might get you this resolution: ONCE REMOVED reverse the pass linear flow right and left grand (7/8 promenade) The program searches for resolutions by using a random number generator to generate up to 15000 random sequences, occasionally inserting concepts. It biases the search in favor of short sequences (one call) rather than long ones (three calls) and against resolutions that require all 8 circulate, pass thru, or trade by at the end. If, after 15000 attempts, no resolution is found, the `find another' operation fails. (This tends to happen if you try to resolve out of an hourglass at Mainstream.) You can select `find another' again to make another 15000 attempts if you wish. Remember that the `resolve' operation by itself does not write the sequence to a file. You will not be able to print a sequence until it has been written to a file. You must give the `write this sequence' command (or press function key ) to write out the sequence. Mini-Grand Getouts ================== Some callers like to use the getout of "Right and Left Grand, but promenade on the third hand", sometimes known as a "Mini-Grand". Under normal circumstances, `Sd' will not search for such things. If you want them, issue the "toggle minigrand getouts" command. You may also customize the program by putting the line "minigrand_getouts" in the initialization file, or "-minigrand_getouts" in the command line of a shortcut icon. *Note Option Control::. Normalizing or Standardizing the Setup ====================================== These commands invoke an operation very similar to the resolver, except that they search for sequences of up to three calls that make the setup nicer. The `normalize' command reduces various matrices, such as 4x4, into an 8-person setup. It uses a variety of phantom-like concepts to do its work. Be aware that the phantom-like concepts that this command uses are not the only ways to get out of large matrix setups. There are a number of calls, like press, truck, loop, squeeze, Z axle, and finish a long trip that are also useful. The `normalize' operation does not search for such things. It is only intended to search for things that might not be obvious. The `standardize' command turns the setup into an 8-person setup in which people are facing in "reasonable" directions. That is, it gets out of T-bone setups. It uses both plain calls and calls with concepts. If you have selected `toggle concept levels', these commands may make use of concepts that are not legal at the chosen level. This is sometimes useful in emergencies. Letting the program pick a random call ====================================== There are five commands in this family: `pick random call', `pick simple call', `pick concept call', `pick level call', and `pick 8 person level call'. They search for any legal single call. While this may sound like a fairly pointless operation, remember that you can use this while one or more concepts are already entered, in which case it will search for legal calls that involve those concepts. Hence, this operation is useful for finding clever uses of difficult concepts such as checkpoint, interlace, or on your own. The command `pick random call' attempts to pick completely random calls, sometimes with a concept and sometimes not. The `pick simple call' command never uses concepts. The `pick concept call' always uses at least one concept with the call that it picks. `Pick level call' picks only calls that are at or near the specified calling level. (By "near" we mean that, if the calling level is C4, it will pick C4A or C4 calls. If the level is A2, it will pick A1 or A2 calls.) `Pick 8 person level call' is similar, but it picks only calls that involve all 8 people. Creating a Specific Setup ========================= These commands pick some call or calls that go into a specified setup. The commands are: create any lines create waves create 2fl create lines in create lines out create inverted lines create 3x1 lines create any columns create columns create magic columns create dpt create cdpt create trade by create 8 chain create any 1/4 tag create 1/4 tag create 3/4 tag create 1/4 line create 3/4 line create diamonds create any tidal setup create tidal wave "Any lines" and "any columns" mean any 2x4 setup in which people are all in generalized lines or columns, respectively. "Any tidal setup" means any 1x8, no matter how people are facing. All the commands are independent of handedness--for example, a two-faced line can be of either handedness. The `Reconcile' operation ========================= Selecting `reconcile' invokes an operation like resolving, but it puts the generated calls someplace other than at the end of the sequence. This is useful if you have a clever getout at the end of the sequence, and you want it to be the resolve, but people don't have their partners and corners. This lets you retroactively modify the sequence so that the clever getout will work. Note first that this operation may only be invoked when the setup is left-handed two-faced lines, right-handed waves, or left-handed waves, in which case it assumes you want a promenade, right and left grand, or left allemande respectively. The program must know which getout type you want. If the setup is an 8-chain, it can't tell. In that case, either do a `touch' or a `left touch', to tell the program that you really want a right and left grand or allemande left, respectively. Then, after the reconcile operation is complete, you can erase that extra call. The reconcile operation is very similar in behavior to resolve, except that the program needs to know the insertion point. Rather than searching for the first resolve as soon as you enter the mode, the reconcile operation lets you set the insertion point before searching. Select `raise reconcile point' or `lower reconcile point' to set it. A dotted line will be displayed showing where in the sequence the generated calls will be placed. When this is in the right place, select `find another' to find the first reconcile. You can change the insertion point at any time. Reconciles are extremely difficult to find--much harder than resolves. To avoid frustration, make the insertion point be at a place where the setup is very simple and a large number of calls are legal. We recommend making the insertion point be at a place where the setup is in waves. Remember that, if the insertion point is at an hourglass, the program has to find a random sequence of up to three calls that goes from an hourglass to another hourglass while miraculously performing the required permutation. Avoid using reconcile when a gender-dependent or head/side-dependent call lies between the insertion point and the end of the sequence. The program checks every reconcile by re-executing all calls from the insertion point to the end and verifying that everything is exactly as it was except for the permutation of the people. For example, if the call `heads kickoff' occurs after the insertion point, and a potential reconcile changes heads and sides, it will not be offered. For gender-dependent calls the situation is a little better: if, at the end of the sequence, the boys are in the center and the girls on the end before doing the reconcile, you know that any inserted sequence will have to be gender-preserving anyway, so calls like `star thru' and `boys kickoff' will be okay. At-home Reconciling ------------------- If you have a nice getout that finishes on squared-set spots (or a 2x4 approximation to same), you can use the reconcile operation to make it work. First, move the headliners into the middle if necessary to make a 2x4. Then have the centers face out, and have everyone do a `left touch'. Start the reconciler, set the insertion point, and search. Discard any solution that doesn't say "at home". When you find one that you like, accept it, and then delete the calls that you had to put in at the end. Editing ******* This section describes the "editor". `Sd' allows you to edit any part of your sequence while you are writing it. Normally, of course, you are just adding calls to the end, or perhaps undoing the last call. What happens if you decide you want to change something farther back? You could undo all the calls back to that point, while remembering them or writing them down, make the changes, and then type them in again. `Sd' can remember them for you. It does this with a "clipboard". You move the calls, one at a time, from the sequence that you have written, onto the clipboard. Then you can "edit" the sequence at the chosen point, adding calls, undoing calls, or whatever. When you are done, you can restore the later calls by moving them from the clipboard back to the sequence. The `Sd'/`Sdtty' clipboard has nothing to do with the Windows clipboard. The former stores calls, and the latter stores text. You can cut, copy, and paste text between the `Sd' text entry window and the Windows clipboard, using the "Edit text" menu, though there is rarely any reason to. The commands to manipulate the clipboard are: `cut to clipboard' `paste one call' `paste all calls' `delete one call from clipboard' `delete entire clipboard' Moving the Last Call to the Clipboard ===================================== Normally the clipboard is empty. To start the editing process, issue the `cut to clipboard' command, or press function key shift-. This will move the last call onto the clipboard, removing it from the active sequence. If this is done repeatedly, the calls will all be stacked on the clipboard. Do this until you reach the point in the sequence that you want to change. While there are calls in the clipboard, they will be displayed (well, the first three will be displayed) between two rows of dotted lines. This way, you can see what will be pasted back. Moving One Call Back From the Clipboard ======================================= After you have finished editing the sequence, you can move the calls back. The command `paste one call', or pressing function key control-, will move the nearest call from the clipboard back to the active sequence. There are a few tricky issues involved with this process. `Sd' assumes that you want the indicated call replaced, even if the formation is different. For example, if the call in the clipboard was `swing thru', and you have changed the formation to left-handed waves, it will still do a (right) swing thru. If the formation has changed radically, the interpretation may be very different. If there are sex-dependent calls and you have rearranged people, things might turn into something very different from the original sequence. There is one case in which `Sd' will alter a call while it is being pasted. If a call has a designator like `boys' or `heads', and the formation is geometrically the same as before, `Sd' will try to change the designator to get the equivalent geometrical effect. For example, if the pasted call had been `boys run' from waves in which the boys were looking out, and you edit the sequence so that the formation is once again waves, but with some other people looking out, the call will be changed to `heads run' or whatever. Of course, if you had originally said `leads run' no change would be required. Whenever a designator is changed, or whenever the formation in which the pasted call is performed is different from the original formation, `Sd' prints a warning. You may find a change from `boys run' to `side corners run' to be unwelcome. It may happen that the pasted call is illegal in the new formation. If that happens, the call will not be pasted, `Sd' will print an error message, and you will have to take further action. Moving The Whole Clipboard Back =============================== You can paste all the calls back from the clipboard at once by issuing the `paste all calls' command. If any formation changes, or any designator is altered, a warning will be printed. If any call is illegal in its new context, the pasting operation will be stopped just before the pasting of that call. Earlier legal calls will have been pasted. Throwing Away Just One Call =========================== If you are pasting calls back and an illegal one is encountered, you may decide that the correct action is to change what is on the clipboard. You can do this by issuing the `delete one call from clipboard' command. This throws away the offending call and lets you proceed with further editing. For example, suppose you were writing a sequence in which the formation was diamonds at some point, and the next call was `flip the diamond' followed by other clever stuff. You decide that you want to do something interesting with the diamonds, followed by the flip the diamond and the other stuff. So you cut the `flip the diamond' and all later stuff onto the clipboard. Then you edit from the diamonds. While editing, you get into some wonderful situation in which you have triple boxes, you want to do a `triple box circulate' to get to waves, and then you want to proceed with the rest of the sequence, but _without_ the `flip the diamond'. The diamonds are no longer what you want at that point. So you call the `triple box circulate' and want to paste the calls back. Unfortunately, the first call on the clipboard is `flip the diamond'. `Sd' refuses to paste it. You can throw it away with the `delete one call from clipboard' command. The rest of the clipboard is still there, starting with the waves that were originally created by flipping the diamond. You can now paste them. Throwing Away the Entire Clipboard ================================== Sometimes you decide that everything you cut to the clipboard was stupid, and you just want it to go away. Issue the `delete entire clipboard' command. Printing ******** There are a number of ways to have your sequences printed. The simplest is to let `Sd' do it directly, at the end of a session. Before `Sd' exits, it offers to print the current file. You can also give the explicit command `print current file' at any time. However, we don't recommend doing this except at the very end of a session, because `Sd' always prints the entire file. If you issue the print command twice in one session, the second command will duplicate all the sequences printed the first time. You can also leave the sequences on a disk file and print the file later. Click `No' when it offers to print the file. You can print it later with `Sd'. Just start `Sd' and give the `print any file' command. This lets you browse to the file that you want. (In fact, the `print any file' command can print any file at all. This is sometimes useful. Do not use it to print documents from word processors such as Word 97.) When `Sd' prints a file, the default font is 14 point Courier Bold. You can choose another font or type size by giving the `choose font for printing' command. This only affects printing. It has no affect on the screen display. Only `Sd' is capable of printing. `Sdtty' is not. Of course, `Sd' can print files prepared by `Sdtty'. You can also print sequence files by other means. You can simply copy the file to the printer, using the Windows Explorer. There are also a large number of software packages that are capable of printing files. We do not recommend Notepad or Wordpad for printing sequence files. These formatters do not recognize the page boundaries in imported files, so the "cards" will not be on separate pages. If you want to print files with a word processor, we recommend Word 97. It handles page boundaries correctly, though its line margins may cause unwanted line breaks. To read a file into Word 97, select `File' and `Open' from the menu. Set the "Files of Type" pulldown to "All Documents". Navigate to the desired folder and select the desired file. If you want to print in a different font or type size, first select `Edit' and `Select All' from the menu. (This will put the entire file into reverse video.) Then select the desired font and/or type size from the pulldown menus on the Format Bar. Then choose `File' and `Print'. If you made any changes to the file while in Word 97 or another word processor, including just changing the font for printing, the program may ask whether to save the changes. It is dangerous to do so unless the file was written with an `Sd' session file name of `*'. See the "sessions" document for details on file management. Miscellaneous Commands ********************** This section describes commands that are not concerned with generating sequences. Saving the Sequence =================== At any time when the sequence is resolved (for example, after a successful use of the `resolve' operation), you can select `write this sequence' or press . (This command used to be called `end this sequence'.) This will append the current sequence to the current output file, and then go back to the startup menu. You will be given an opportunity to enter a line of text to be used as a subtitle, for example "very hard interlace" or "stupid biggie." The written sequence will also be annotated with the level, the session title, the current date and time, and the version numbers of the program and database. Until you have done the `write this sequence' operation or pressed , the sequence is not written to disk and you cannot start writing a new sequence. Just resolving isn't enough. Changing the Output File ======================== You can change the name of the file to which the program writes its output by selecting the `change output file' command. A popup will appear, prompting you for a new file name, or `Sdtty' will ask you to type in the new name. This action will become effective the next time a sequence is written out. Sequences previously written will stay under their old name. When the initialization file is used (*note The Initialization File::), any change in the output file name will be written back to the init file at the end of the session. Changing the Title ================== You can change the title that will appear at the top of each sequence by selecting the `Change Title' command. A popup will appear, prompting you for a new title, or `Sdtty' will ask you to type in the new title. This action will become effective the next time a sequence is written out. Sequences previously written will keep their old title. You can remove the title by just pressing when asked for the new title. When the program starts, there is no title unless the initialization file was used. *Note The Initialization File::. When the initialization file is used, any change in the title will be written back to the init file at the end of the session. Changing to the New File Name Style =================================== Prior to version 34.6, when support for DOS and Windows 3.1 were withdrawn, the program used names for the transcript (output) files in an "old" style, which looked like "13aug05.c1" or "sequence.c1". It now supports a "new" style, which looks like "13aug05_c1.txt" or "sequence_c1.txt". (The names with dates in them are what you get if you use the "+" file name. *Note Session Control::.) The part after the period is called the "extension". When using modern operating systems, it is very helpful for files to have a correct extension, and ".txt" is the right extension for these files. For example, attaching files in email messages is sometimes facilitated by having the ".txt" extension. Whether you use old or new style file names is controlled by your initialization (session) file, in the options `new_style_filename' or `old_style_filename'. *Note Option Control::. There is a command to change the style specified in your initialization file from old to new. The command is "change to new style filename". It must be given when the program starts, not when it is in the middle of a sequence. After giving the command, you must exit the program and restart it. When you change to new style file names, no previously written files will be renamed. Only newly created files will have the new names. Also, no pre-existing sessions that use explicit old style names (e.g. "sequence.c1") will have those names changed. (You may change the explicit names used by existing sessions with the "change output file" command.) Pre-existing sessions that use the "+" or "*" file name will be changed to the new style for all future sequences, based on the date. `Abort', `Exit', and `Undo' =========================== If you select the `exit' command, the program will exit. If a sequence is in progress, the program will ask for confirmation first. (Remember that a sequence is not finished until the `write this sequence' command has been given.) In `Sd' with the X Window System, using your window manager to send a `Delete Window' message to the program is equivalent to clicking on the `exit' button. This is what normally happens when you double-click the special control button in the upper left corner of the `Sd' window. If you select the `abort' command, the program will abort the sequence but not exit. It will go back to the startup menu to allow you to start another sequence. It will ask for confirmation first. If you select the `undo' command, or press function key , while no call is partially entered, that is, while no concepts have been entered, the program will erase the last complete call, with all of its concepts. If one or more concepts have been entered, only the last concept will be erased. Inserting Comments ================== You can insert arbitrary text strings into the sequence transcript in the form of comments. This is useful for things that you may want to say to help the dancers, such as "side boys be careful--go to your left." Also, if you want to call something that the program can't do, so you have to trick the program into doing it by means of several other calls, it is useful to enter a comment saying what you originally wanted. This can guide you when editing the transcript file. To enter a comment, select `insert a comment'. In `Sd', a popup will appear into which you may enter the text. In `Sdtty', simply type the comment text on the next line. The comment will be enclosed in curly braces in the transcript. A comment may be entered in front of any concept or call and goes into the transcript exactly where it was entered. Because of the way the program assembles mouse-clicks into transcript lines, it is not possible to enter a comment at the end of a line. Keeping Pictures ================ The program shows pictures on the screen for the current position and the position just before the last call. Normally, those pictures will not appear in the sequence written to a file. If you want the current position to have its picture written in a file (say, because the sequence is very difficult and you believe it may be necessary to say something helpful then like "check a parallelogram with boys in the center box") select the command `keep picture'. You may also cause the program to keep pictures in the output file for the entire sequence by issuing the `toggle keep all pictures' command or by placing the `keep_all_pictures' option in your initialization file. Singing Call Progressions ========================= You can write singing call sequences with the usual "progressions" in them. At the start of the sequence (that is, when you could have typed `heads start'), issue one of the following commands: toggle singing call toggle reverse singing call The first gives the usual "corner" progression, and the second gives a reverse ("right hand lady") progression. When in singing call mode, the program looks for resolves that cause people to promenade with the appropriate person who is not their partner. It assumes that you are looking primarily for `swing and promenade' getouts, though it will show other types of getouts when they appear. Note that, for the "usual" type of singing call figure (equivalent to `square thru 4, swing corner, and promenade') the promenade distance will be shown as 1/8. The dancers will of course promenade 1-1/8. You should consider `at home' or `1/8 promenade' to be the "usual" timing for singing call figures. Changing Modes ============== There are several commands that change some aspect of the way `Sd' or `Sdtty' runs. They are: toggle singlespace mode toggle concept levels toggle active phantoms toggle retain after error toggle nowarn mode toggle keep all pictures toggle singleclick mode toggle minigrand getouts toggle singing call toggle reverse singing call Normally, all of these are off. You may want to turn one or more of them on for your own personal preference, or for some special reason. These commands "toggle" their respective modes. That is, they turn the mode on if it was off, and off if it was on. The current status of some of these modes is always displayed in the input prompt in `Sdtty', or the status bar at the bottom in `Sd'. The `toggle singlespace mode' command changes the format of the output file between single spacing and double spacing. The default is double spacing. This command affects only future sequences. It has no effect on sequences already written. The `toggle concept levels' command changes the legality of concepts that are not on the specified calling level. *Note Entering Concepts::, and *Note Using Off-Level Concepts::. The `toggle active phantoms' command changes the persistence of phantoms during certain calls. *Note Assume Waves::. We do not recommend using this. It may make the program refuse to do things that real dancers consider completely legal, due to phantoms colliding with or otherwise interfering with live dancers. Instances in which this option is needed are nearly unheard-of. The `toggle retain after error' command changes the option whereby program retains the concepts that you had typed when an error occurs. *Note Retaining Concepts After an Error::. The `toggle nowarn mode' command changes the suppression of warning messages. The `toggle keep all pictures' changes the mode that keeps all pictures. This mode effectively puts a "keep picture" command at every point in the sequence. The `toggle singleclick mode' changes the acceptance of single mouse clicks on menu items. The `toggle singing call' commands change the singing call mode, which affects resolves. *Note Singing Call Progressions::. The `toggle minigrand getouts' command changes the search for "mini-grand" getouts in the resolver. *Note Mini-Grand Getouts::. Any of these modes, except the singing call modes, can be turned on automatically when the program begins, either by giving a command-line option (*note Command-Line Options::) or through the use of the initialization file (*note Option Control::). The Initialization File *********************** When `Sd' or `Sdtty' starts, it looks for a file `sd.ini' in the working directory. This file, if present, contains information about dances you might be working on, and about possible individual preferences you might have for the way the program runs. Such a file might look like this: [Options] reverse_video no_warnings print_length 68 window_size 850x650 singlespace [Sessions] sequence.C3 C3 12 NACC, June 1995 sequence.C4 C4 31 NACC, June 1995 workshop C1 75 My Wednesday group + A2 9 NESRDC * A1 2 Lake Shore Farm There are up to three sections in this file, called the "sessions" section, the "options" section, and the "accelerators" section. Each section starts with a header word in brackets. The sections are separated from each other by blank lines. Session Control =============== Each line after the line `[Sessions]', up until a blank line or the end of the file, describes a possible session of using the program, showing the output filename, level, next sequence number, and title. Th example file above shows 5 possible things you could work on. You can select any one of them during a session. When the program is started, it will display the 5 lines and ask you which one you want to use, like this: Do you want to use one of the following sessions? 0 (no session) 1 sequence.C3 C3 12 NACC, June 1995 2 sequence.C4 C4 31 NACC, June 1995 3 workshop C1 75 My Wednesday group 4 + A2 9 NESRDC 5 * A1 2 Lake Shore Farm 6 (create a new session) Enter the number of the desired session: In `Sdtty', type the number of the selection that you want. In `Sd', either select the desired line with a double mouse click, or use the cursor keys to highlight the line and then press . If you select "0", or just press , the program will ignore the sessions and proceed normally. If you enter the number of one of the lines that are displayed, the program will operate at that level, and use the named output file and title. It will also print a sequence number on each card, starting with the number shown. For example, if you entered "3" after the file above is displayed, the program will operate at C1. The output file will be "workshop" instead of the default "sequence.C1". Cards will be serialized starting at 75. Each card will have a title saying "My Wednesday group". If the given file name is "+", the program will generate a file name for you, based on today's date. This may be useful for managing files, so that you know when it is safe to delete a file that you have printed. The program will of course tell you what the name of that file is. All runs of the program using that session on the same day will append their sequences to the same file. The file name will be something like like`9mar96.C3'. If the given file name is "*", the program will generate a file name in the same way, except that it will always generate a new file for each run of the program. If the program is started several times in one day, the files will be different. The generated file names will be something like `9mar96a.C3'. Note the `a' after the year. At the end of the session, the initialization file will be updated with the next index number. For example, if you wrote 12 sequences, they would be numbered 75 through 86, and the file would be rewritten as workshop C1 87 My Wednesday group so that the next session for that group would start with sequence number 87. The title bar displays the level, session title, current sequence number, and starting sequence number. If, at any time during the session, you change the output file (with the `Change Output File' operation) or the title (with the `Change Title' operation), the initialization file will be updated at the end of that session to show the effect of the change. When the program starts, you can tell it to create a new entry in the file by entering the number corresponding to `(create a new session)'. In the above example, select "6". The program will ask you for the level and title, and will set the output file to the standard "sequence.C1" or whatever. You may use the `Change Output File' command and the `Change Title' command to change these later if you wish. At the end of the session, item number 6, containing the appropriate data, will be written to the updated initialization file. If you no longer want some entry in the initialization file, you can delete it. In `Sdtty', type the negative of its line number. In the above example, if you entered "-4", the line + A2 9 NESRDC would be deleted. In `Sdtty', check the box labeled "Delete this session" and select the line to be deleted. Either way, the program will terminate immediately after doing this. Run it again to use the new initialization file. Whenever the program updates the initialization file `sd.ini' at the end of a session, it saves the old contents in `sd2.ini'. By copying that back to `sd.ini', you can restore it. You can also edit the file with an editor. Simple editors, such as `Emacs' and `Notepad' are preferable to sophisticated word processors when editing this file, since word processors often insert specialized control information into the file. The simplest way to edit the file is to double-click the icon `Edit sd.ini' in the `C:\sd' folder. This is a shortcut to the `Notepad' editor. Option Control ============== Each line after the line `[Options]', up until a blank line or the end of the file, contains an option specifier. When the program is started, it will use those specifiers to determine a number of aspects of the program's behavior. This makes it possible to encode your personal preferences so that the program will always use them. Do _not_ place a hyphen in front of an option in the initialization file. A few of these options can also be changed while the program is running, by giving suitable commands. *Note Changing Modes::. Here are the available options: `singlespace' This makes the program write the output file with single spacing instead of the usual double spacing. This may be useful for those who use special fonts or special printer arrangements. This option is the same as giving the `toggle singlespace mode' command while the program is starting a sequence. `print_length NUMBER' This sets the length of print lines for the output file, that is, the point at which long lines will be broken. The default is 59, which seems to be correct for the Courier 14 point font on standard American (8.5 x 11 inch) paper size. `concept_levels' This allows all concepts, even those that are not actually legal at the specified level, to be used. It is the same as giving the `toggle concept levels' command while the program is running. `active_phantoms' This turns on the "active phantoms" behavior, which makes phantoms persist throughout calls. This option is the same as giving the `toggle active phantoms' command while the program is running. `minigrand_getouts' This turns on the acceptance of "mini-grand" getouts in the resolver. This option is the same as giving the `toggle minigrand getouts' command while the program is running. `no_warnings' This suppresses the display and printing of the warning messages that are sometimes given to help less-experienced callers. It is the same as giving the `toggle nowarn mode' command while the program is running. `retain_after_error' This makes the program automatically retain all concepts that had been typed prior to the current call whenever an error occurs. The usual behavior is to discard all typed concepts when an error occurs. It is the same as giving the `toggle retain after error' command while the program is running. *Note Retaining Concepts After an Error::. `discard_after_error' This is the opposite of `retain_after_error'. Since this is the usual behavior, you don't need this option. It is present only for compatibility with older versions. If it is in your `sd.ini' file, take it out. `tab_changes_focus' This applies to `Sd' only. Windows programs normally use the tab key to move keyboard focus around among the active windows in some fixed order, and the shift-tab key to move in the opposite order. This change of focus is nearly useless in `Sd' for most users, because the keyboard focus is almost always in the text input region. Therefore, `Sd' normally has the tab key do something different--it performs the same completion function as the escape key, just as `Sdtty' does. (The shift-tab key still moves window focus in the backwards order.) The `tab_changes_focus' option re-enables the conventional Windows meaning of the tab key. With this option turned on, if you are typing in a call, and you type tab, it will not complete the call. Instead, focus will shift to the call menu. You can use the arrow keys to move around in the call menu, and then press to select that call. `keep_all_pictures' This keeps a picture after every call, as if the "keep picture" command had been given each time. It is the same as giving the `toggle keep all pictures' command while the program is running. `single_click' This makes `Sd' respond immediately to a single mouse click in a menu. Normally, a double click, or pressing the `Accept' button, is required. This option is meaningless in `Sdtty'. It is the same as giving the `toggle singleclick mode' command while the program is running. `maximize' This tells `Sd' to "maximize" its window, that is, to use the full screen. It is the same thing that would happen if you clicked the open box button in the upper right corner. This has no effect on `Sdtty'. `Sdtty' runs as a "command prompt" program and cannot set its window size. `window_size SIZE-DESIGNATOR' This argument is followed by a designator like "750x450". It will set the window size to the indicated number of pixels. There is enormous variation in the screen size of various displays and graphics cards, and in people's preferences, so you may find the standard default size (780x560 pixels) not to your liking. The two size numbers are separated by the letter "x", with no space. You can also adjust the screen position by giving 4 numbers, as in "window_size 750x450x20x20". The arguments are the X and Y size, and the X and Y position of the upper left corner, all in pixels. These options do not affect `Sdtty'. `Sdtty' runs as a "command prompt" program and cannot set its own window size. However, you can usually control this either by editing the icon that starts the program (right click the icon, select "properties", and, on the "shortcut" tab, select "maximized") or by changing the general layout of command prompt programs (start, control panel, console, and use the "options" and/or "layout" tabs.) `no_checkers' `Sd' normally draws the formation on the screen with icons that are intended to look like callers' "checkers". This option disables that, and displays dancers by more normal means. Pictures drawn in the output file never use these icons. This option is meaningless in `Sdtty'. `no_graphics' This suppresses the use of special PC graphics characters ("triangles") when drawing pictures on the screen. These characters are not standard on all PC's. Pictures drawn in the output file will never use the special graphics characters. This overrides `no_checkers'. `no_color' `Sdtty' and `Sd' normally color-code the dancers shown on the screen, according to various color schemes that are controlled by options listed below. This option disables the use of color. These options affect only the display on the screen. Pictures drawn in the output file will never be in color, and will never use "checkers" or triangles. `color_by_couple' This draws dancers on the screen in four colors, one for each couple, in the sequence red, green, blue, and yellow. `color_by_couple_rgyb' Like color_by_couple, but the color sequence is red, green, yellow, and blue. `color_by_couple_ygrb' Like color_by_couple, but the color sequence is yellow, green, red, and blue. `color_by_corner' Like color_by_couple, but dancers have the same color as their respective corners. In the absence of these color options, girls are drawn in red and boys in blue. Pictures drawn in the output file never use color. `reverse_video' This displays the transcript area (or the whole window in `Sdtty') with a black background and white text. This is the default for `Sdtty', so you only need this option for `Sd'. `normal_video' This displays the transcript area (or the whole window in `Sdtty') with a white background and black text. This is the default for `Sd', so you only need this option for `Sdtty'. `no_intensify' This changes all "white" displayed matter to be light gray instead. In reverse_video mode, text will be light gray on black instead of white on black. In particular, this will make `Sdtty' look like the customary appearance of a Command Prompt window. In normal_video mode, text will be black on light gray instead of black on white. `pastel_color' This causes the colors for the usual girls-are-red and boys-are-blue scheme to use lighter shades. This may be preferable if `reverse_video' is used. It has no effect when using the `color_by_couple', `color_by_couple_rgyb', `color_by_couple_ygrb', or `color_by_corner' schemes (but see `use_magenta' and `use_cyan', below.) This is the default for `Sdtty', so you only need this option for `Sd'. `bold_color' This is the opposite of `pastel_color'--it uses darker shades. This is the default for `Sd', so you only need this option for `Sdtty'. `use_magenta' This lightens the shade of red in all color schemes. (`Pastel_color' does not apply in any of the `colr_by_couple' schemes.) It substitutes magenta for red. `use_cyan' This lightens the shade of blue in all color schemes. It substitutes cyan for blue. `no_sound' Do not ring the bell or make any other sound when reporting errors. `new_style_filename' The output file will be written with the extension `.txt', as in `sequence_C1.txt' or `01sep02_C1.txt'. Without this switch one gets the default "old" behavior, which is `sequence.C1' or `01sep02.C1'. This default may change soon. Having a file name of this form should make the output files able to be read and printed by common text editors and word processors. `old_style_filename' This forces the output file to be written in the "old" style. This will be needed after the default changes to the "new" style. `db FILENAME' location of the calls database. The default is `sd_calls.dat' in the current directory. `sequence FILENAME' base name of the file to write sequences to. The calling level will be used as the extension of the file name. The default base name is `sequence', so a complete file name might be `sequence.C1'. `sequence_num NUMBER' Initial sequence number. This overrides any sequence number given in a session from the initialization file. `no_cursor' Dumb terminal mode: do not use cursor motion commands to keep the screen up-to-date efficiently. Use this if the cursor motion and screen manipulation operations of your terminal or operating system are not available or are not working satisfactorily. This is only legal in `Sdtty', and is meaningless on Windows 95 or similar systems. *Note Sdtty::. `no_console' Extremely dumb terminal mode: turn off all special input/output processing completely. This allows input or output to be redirected from files. `lines NLINES' The number of lines on the screen. Default is 25. This is only legal in `Sdtty', and is meaningless on Windows 95 or similar systems. `no_line_delete' Do not use the insert line or delete line cursor control commands. Use this if these commands are not working satisfactorily on your terminal. This is only legal in `Sdtty', and is meaningless when running Windows. Accelerator Key Control ======================= The text of the `sd.ini' initialization file, from the line `[Accelerators]' up to the next blank line or the end of the file, consists of key definitions, one per line, or comments. A comment is any line starting with a "pound sign" (`#'). The first item on a non-comment line is a description of the key, and the remaining items are the meaning, exactly as you would type it to `Sd'. The meaning may be any single call, concept, or special command. (To see what special commands are available, type a question mark during a resolve, during program startup, or during normal program operation, or look at the `Sd' menu.) Keys may have different definitions during program startup, during resolves, and during normal operation. If the first character of the key description is a plus sign (`+'), that key definition line is meaningful during program startup. For example, the standard definition contains the line +f1 heads start to indicate that function key means `heads start' during program startup. If the first character of the key description is an asterisk (`*'), that key definition line is meaningful during resolve searches. For example, the standard definition contains the line *f12 find another to indicate that function key means `find another' during resolves. It is perfectly legal to have the same keystroke mean three different things during startup, during resolves, and during normal operation. After the optional plus sign or asterisk, there may be an optional `s' to mean shift, `c' to mean control, `a' (or `m') to mean alt (meta), or `ca' to mean control-alt (hold both the control and alt keys while pressing the indicated key). What follows must be `a letter' Usable only with `c', `a', or `ca'. (Plain and capital letters always have their normal meaning.) `a digit' Usable only with `c', `a', or `ca'. (Plain digits always have their normal meaning, and shift digits are punctuation.) `a function key: f1 through f12' These may be plain, shifted, control, alt, or control-alt. `a numeric keypad key: n0 through n9' Usable only with `c', `a', or `ca'. (Plain numeric key presses are always equivalent to that digit.) `an "enhanced" key: e1 through e14' These may be plain, shifted, control, alt, or control-alt. The "enhanced" keys are encoded as follows: e1 page up e2 page down e3 end e4 home e5 left arrow e6 up arrow e7 right arrow e8 down arrow e13 insert e14 delete So, for example, the line: cae8 u-turn back would define `control-alt-' to do a `U-turn back'. In specifying a key name, you can use either "m" (for meta) or "a" (for alt) to mean the same thing. (Some people refer to it as the meta key.) Also, if a key is both meta/alt and control, you may list them in either order. Also, you may put hyphens into the key name, and put it in upper or lower case. The command value (the rest of the line) must be in lower case. Hence c-m-e8 u-turn back c-a-e8 u-turn back m-c-e8 u-turn back a-c-e8 u-turn back mean the same thing as the above example. If a key is defined to mean a concept, and that concept is not legal at the level at which the program is invoked, the key will still mean that concept. If the key is pressed, the concept will be used, but it will be considered an off-level concept, and a warning will be printed. *Note Using Off-Level Concepts::. If a key is defined to mean a call, and that call is not legal at the level at which the program is invoked, that key definition in the initialization file will simply be ignored, unless the level is C4X. Therefore, whenever you change your initialization file, it is a good idea to test it by starting the program at C4X to find out if any warning messages are printed. Creating an Intialization File ============================== When `Sd' or `Sdtty' is first installed, no initialization file `sd.ini' exists. When you run the program, it will print You do not have a session control file. If you want to create one, give the command "initialize session file". After doing that, exit from the program and start it again. The file will have been created, with some sample sessions. It will also contain all of the standard accelerator key bindings and abbreviations. You may edit those. Invoking Sd via Command Line (DOS or UNIX only) *********************************************** sd level [ Xt options ... ] [ Sd options ... ] sd level -write_list filename sd level -write_full_list filename The program is normally invoked with a single argument--the level. This is one of the following: `m' (mainstream), `p' (plus), `a1', `a2', `c1', `c2', `c3a', `c3', `c3x', `c4a', `c4', or `c4x'. The level can also be determined by the selection made when using the "session" feature. If the level is not given, or the program was started by a mouse click from Windows, the program will ask you for it. However it is specified, the level determines the calls and concepts that will be made available, according to our best guess of what the levels mean. Various optional arguments are permitted to control the window system, customize the list of calls used, and set other options. These will be described later. The call definitions will be read in from the encoded database file `sd_calls.dat'. The program will then ponder the database for a few seconds while it determines what calls to put on what menus. Depending on the speed of your computer and the level you selected, this could take from a few seconds to over a minute. Command-Line Options ==================== Any of the option keywords that can be placed in the "options" section of the initialization file may be given on the command line instead. *Note Option Control::. Each keyword has a hyphen in front of it when used on the command line. Examples: sd -singlespace -maximize plus sdtty -no_warnings -active_phantoms In addition to giving these options if you invoke the program from the command line, you can place them (and the level also, if you wish) in a Windows shortcut. For example, you can place an icon on your desktop that runs `Sd' at A2, with the `color_by_corners' scheme. Make a copy of the standard shortcut (or make a new shortcut with the "Taskbar" option or the "Settings" operation in the Start Menu), and then use the "Properties" command to add the desired switches at the end of the "Target" line. There are X resources associated with some options: `Sd.sequenceFile' is equivalent to the `-sequence' switch, and `Sd.databaseFile' is equivalent to `-db'. If you almost always will be passing the the same value for a command-line switch, you may find it more convenient to set the corresponding resource. With the X Window System interface, Sd accepts all Xt command-line options. The following are some of the more useful options for use with Sd. `-rv' reverse video `-bg color' background color `-fg color' foreground color `-bd color' border color `-font font' font used everywhere `-geometry geom-spec' geometry in pixels `-title string' title for window manager and icon use `-name string' name to look up resources under. default: program name. `-xrm resource-line' an X resource manager string. Terminal Interface ****************** One version of the program, called `Sdtty', uses a character-oriented terminal interface. Sdtty ===== The program `Sdtty' uses the completing reader for call, concept, and command entry. When typing, press to complete the current word. Type or to complete as much as possible. Type `C-u' (that is, Control U) to clear a partially-typed line. Type `C-v' (that is, Control V) to clear just the last word. `Sdtty' has a special command `refresh display' that has no counterpart in `Sd'. It causes a complete clean transcript of the current sequence to be displayed. This can be used if the screen got messed up due to such things as unreliable terminal or modem behavior. `Sdtty' tries to keep the screen up-to-date efficiently, maintaining a clean transcript of the current sequence on the screen at all times, by using whatever Operating System facilities it thinks are appropriate. If, for any reason, this doesn't work properly for you, you can place the `no_cursor' option in your initialization file, or the `-no_cursor' command-line switch at program startup. *Note Option Control::, and *Note Command-Line Options::. This will cause `Sdtty' to treat the computer's display as if it were a dumb typewriter. When started in this way, the part of