CP/M

home *** CD-ROM | disk | FTP | other *** search

/ CP/M / CPM_CDROM.iso / enterprs / cpm / utils / f / pwtour.arc / TOURGUID.DOC < prev next >

Wrap

Text File | 1993-03-27 | 47.4 KB | 1,387 lines

. TOUR Guide - Version 2.0 TOUR --- Document Hierarchy Editor --- Copyright (c) 1985 Written by Edward L. Taychert. All rights reserved. Version 2.0 TOUR is supported through its user community. If, after using TOUR for a while, you feel that its is a program that you would have paid money for, I encourage you to send a contribution so that I may continue to develop and support it. (I think that TOUR is worth $30.) Please send any comments, questions or contributions to: Canal Town Computing P.O. Box 191 Palmyra, NY. 14522 Feel free to pass on TOUR to anyone you'ld like, however, the TOUR.COM and MAKETINI.COM programs and the TOURGUID.DOC file must be distributed together in unmodified form. And in no case may you change the copyright notice or receive any fee or consideration for distributing TOUR. . 1 . TOUR Guide - Version 2.0 1. What is TOUR? TOUR is a program to help you collect and organize your thoughts. It maintains them in a textual database that can be formatted for printing. 2. What can you use TOUR for? TOUR can be used whenever your ideas need to be organized clearly. A few uses for TOUR are given below. 2.1 Making an outline of your writing TOUR was originally designed to outline documents. The most critical phase of writing comes at the very beginning, when you are not completely sure what your writing will contain. TOUR will help you collect your ideas and turn them into an outline. 2.2 Preparing an agenda An agenda is an outline of a meeting. You can use TOUR to prepare an agenda. When your meeting is over, use TOUR to add comments from the meeting to the outline. Now, you have a report of the meeting! 2.3 Preparing a presentation If your are giving a presentation, prepare an outline of it using TOUR. As in writing a document, outlining will help you organize your presentation. Copy the outline onto clear transparencies for use during the presentation. If a report is to be generated, fill in the presentation outline to generate it. 2.4 Designing software Software design is typically done in a top-down fashion. TOUR provides the tools for top-down, divide and conquer strategies. When your design outline is complete, you should have identified systems, sub-systems, units, modules and procedures. Include their specifications, rather than their code, in the outline. 2.5 Project breakdown When contemplating a project, its essential to know what has to be done to complete it. Tasks are broken down into sub-tasks into more sub-tasks and so on. This is another divide and conquer application. At the top level, make sure that no tasks are missing. Keep breaking down tasks until you can estimate the time to complete each task. Consider higher level tasks to be milestones or project reviews. Estimate review times. . 2 . TOUR Guide - Version 2.0 Add all the time estimates. This is the total number of man-hours, man-days, or man-years that the project will take. 2.6 Desk calendar Use TOUR as a desk calendar or as a note pad for leaving memos to yourself. Make an outline consisting of months and weeks. Add appointments and schedule dates. When you have finished an appointment, leave a note describing the meeting or accomplishment. Use TOUR to build your monthly report from your calendar. Review: TOUR can be many ways to do different things. 3. CRT terminal setup Before you first use TOUR, your must create a terminal definition file. The terminal defintion file must be named TOURINI.INI. The included program MAKETINI.COM will assist you in building this file. (If you have a H19 or equivalent terminal, you may skip this. TOUR uses H19 terminal controls by default.) The file MAKETINI.DOC contains instructions for using the MAKETINI program. Review: Run the MAKETINI.COM file to generate a TOURINI.INI file. 4. Using TOUR 4.1 Invoking TOUR To run TOUR, type TOUR and then push the return key when you are at your system's normal command line prompt. Example: A> TOUR Alternatively, if you have a TOUR file that you would like to edit, you may include it on the command line. Example: A> TOUR note.rno In either case, the first thing you will see in response to invoking TOUR is the TOUR copyright notice and a prompt to push the return key. After you push the return key, the copyright notice will disappear and you will either see an empty outline or the top-most level of the outline contained in the file you specified on the command line. A command prompt will appear beneath the outline. . 3 . TOUR Guide - Version 2.0 4.2 TOUR screens Unless you specifically ask otherwise, TOUR will only show part of your outline. This is to help you focus on one particular issue or idea. TOUR works on a "divide and conquer" philosophy that should be familiar to users of top-down development strategies. To this end, TOUR allows you to build hierarchical outlines. It shows you, by default, one level of a hierarchy. This means one point or idea, and one level of sub-points or supporting ideas. The major point or idea is called the "current heading" in this document. The supporting points or ideas are called "sub-headings" in this document. Because of the hierachical nature of TOUR outlines, a heading may be a sub-heading at a higher level in the outline, and a sub-heading may be a heading at a lower lower level in the outline. A TOUR screen shows you three other things: First, for each individual sub-heading, TOUR tells you if there are any sub-headings or notes hidden from view beneath it. If there are, TOUR prints a period after the sub-heading's index. If there are not, TOUR prints an "E" for empty after the sub-heading's index. (Sub-headings are numbered from one to the number of entries in the heading. The number associated with a sub-heading is called its "index".) Second, TOUR tells you which sub-heading your commands will operate on. It does this two ways. If your terminal supports highlighting, the title of the current sub-heading will be highlighted. Regardless of your terminal's capabilites, the command prompt will contain the index number of the current sub-heading. (The rest of the documentation may refer to this as the "current index".) Third, TOUR will tell you if there is any text (other than the outline itself) associated with the current heading. The message "... plus text" is a reminder to you that text is present. Review: Usage: tour [<filename>] TOUR builds hierarchical outlines. TOUR screens show one level of an outline at a time. TOUR commands operate on the "current index". 5. Your first TOUR This section contains a demonstration of TOUR. I suggest that you print a copy of the documentation so you can type the demonstration into TOUR as you read it. The purpose of this section is not to give an in-depth explanation of TOUR, but . 4 . TOUR Guide - Version 2.0 rather is to familiarize you with it. So, not everything will be explained here. 5.1 A demonstration of TOUR The demonstration walks you through the creation of a note to a house sitter. Supposedly, you are going away for a month and have asked a friend to stay at your home and take care of it. You would like to leave a note explaining the things which must be done in your absence. When I'm showing a simulated TOUR screen, you'll see a bar "|" on the beginning of the line. (Not on your terminal screen; just in this document.) Also, I can't show terminal highlighting on paper. Where TOUR would highlight something on your terminal, I show it here enclosed in "<<<" and ">>>". Only the first three letters of the sample commands need be entered exactly; don't worry about typing the sample data exactly. Every prompt in TOUR is followed by a double colon, "::". Everything before the :: is typed by TOUR. Everything after it, you must type. And, at the end of every line you type, push the return key. If you are not using an H19 or equivalent terminal, and haven't run the MAKETINI.COM program, do so now. When you are finished, type "TOUR" to begin your demo. | A> tour | TOUR 2.0 -- Document Hierarchy Editor | Copyright 1985 -- Ed Taychert, PO box 191, Palmyra, NY, 14522 | All rights reserved. | <<<Push return>>> :: At this point the screen will clear and you will see an empty outline. | 0E <<<Contents>>> | | 0 :: Review: This is a demonstration of using TOUR to create a note. Every TOUR prompt ends with a double colon. 5.2 Starting the outline Let's type in some things we'd like the house sitter to do. The "append" command adds enties to an outline. Type the append command and enter the following four things for the house sitter to do. . 5 . TOUR Guide - Version 2.0 | 0 :: append | Enter headings (push return at beginning of line to stop) | 1 :: Cut the grass | 2 :: Feed the cats | 3 :: How I can be reached | 4 :: Get the mail | 5 :: Let's say that's all that we can think of for know. Push the return key to stop the heading entry mode. TOUR will display: | 0. <<<Contents>> | 1E Cut the grass | 2E Feed the cats | 3E How I can be reached | 4E <<<Get the mail>>> | | 4 :: Notice that entry 4 is highlighted and that the command prompt contains the number "4". This tells you that any command you type will use the number "4" or the heading "Get the Mail". Throughout the TOUR Guide, the number in the command prompt is called the "current index". Its easy to change the current index. Simply type in another number and push the return key. Try "2". | 4 :: 2 | TOUR will clear the screen and display : | 0. <<<Contents>> | 1E Cut the grass | 2E <<<Feed the cats>>> | 3E How I can be reached | 4E Get the mail | | 2 :: Now, any command you type will operate with the number "2" or the entry "Feed the cats". Try typing in different numbers, one per line, to see what happens. When you are done, type "4" and push return to highlight "Get the mail" again. You should see | 0. <<<Contents>> | 1E Cut the grass | 2E Feed the cats | 3E How I can be reached | 4E <<<Get the mail>>> | | 4 :: on your screen. If you typed any number less than zero, or greater than five, TOUR will have printed out an error message followed by the prompt "push return ::". If you didn't try that, go ahead an do it now to see the kind of messages TOUR will print out. Again, when you are finished, type "4" and push return to make "4" the current index. . 6 . TOUR Guide - Version 2.0 At this point, we don't really have an outline. That's because ideas don't come packaged in nice outlines. They come whenever and however they like. To make an outline, we must decide on a logical organization for our ideas. Looking at the screen, I see three categories. Things to do daily, things to do weekly, and things to do in an emergency. Enter these into the outline. Use "append" to add entries after "Get the mail" | 4 :: append | Enter headings (push return at beginning of line to stop) | 5 :: Daily | 6 :: Weekly | 7 :: In case of emergency | 8 :: Now push the return key to stop heading entry mode. You should see: | 0. <<<Contents>> | 1E Cut the grass | 2E Feed the cats | 3E How I can be reached | 4E Get the mail | 5E Daily | 6E Weekly | 7E <<<In case of emergency>>> | | 7 :: Reveiw: The append command adds entries to an outline. Type a number to change the current index. 5.3 Adding structure to the outline Its now clear that "Cut the grass" is someting to do weekly, "Feed the cats" and "Get the mail" are daily chores, and "How I can be reached" is part of "In case of emergency". What we are going to do next is develop our three point outline by placing the original four tasks inside their proper headings. Let's move "Cut the grass" into "Weekly" first. Make "Cut the grass" current. Type a 1 and push return. You should see: | 0. <<<Contents>> | 1E <<<Cut the grass>>> | 2E Feed the cats | 3E How I can be reached | 4E Get the mail | 5E Daily | 6E Weekly | 7E In case of emergency | | 1 :: Type "Cut" (without the quotes) and push return. . 7 . TOUR Guide - Version 2.0 | 1 :: cut You should see: | 0. <<<Contents>> | 1E <<<Feed the cats>>> | 2E How I can be reached | 3E Get the mail | 4E Daily | 5E Weekly | 6E In case of emergency | 1 :: "Cut the grass" in now in the paste buffer. The paste buffer can store 20 entries. There is no need to type numbers and commands on different lines. You may enter them both on one line by putting the number in front of the command. "1 Cut" would have worked. Placing entries inside other entries makes the outline deeper and gives structure to the outline. Right now, our outline has a "flat" structure because no entries contain sub-entries. (This is what the E's after the indices on the screen mean.) We are about to change that. We want to add an entry to "Weekly" so type "5 down". | 5 :: down You should see: | 5E <<<Weekly>>> | | 0 :: Entry 5, "Weekly" is now the current heading and has no sub-headings. Now we'll use the "paste" command to remove "Cut the grass" from the paste buffer and place it inside "Weekly". | 5E <<<Weekly>>> | | 0 :: paste | Did you mean an index of 1? (Y/n) :: yes TOUR can't give an entry an index of 0 and assumed we wanted to paste at index "1". It maded sure by asking. The "(Y/n)" tells you that TOUR is asking a yes or no question and that "yes" is the default. That means that you didn't have to type "yes", pushing the return key would have been the same as typing "yes". (When "no" is the default answer to a yes or no question, the question will be followed by "(N/y)". ) The message could have been avoided by typing "1 paste" instead of "paste". Anyway, your terminal screen should now look like: | 5. <<<Weekly>>> | 1E <<<Cut the grass>>> | . 8 . TOUR Guide - Version 2.0 | 1 :: About this time, we think that the house sitter should water the lawn also. Since we only want to add one entry, it can be placed on the same line as the append command. | 5. <<<Weekly>>> | 1E <<<Cut the grass>>> | | 1 :: append Water the lawn The screen will clear and display: | 5. <<<Weekly>>> | 1E Cut the grass | 2E <<<Water the lawn>>> | | 2 :: That seems like everything, let's go back up to top of our outline. The opposite of the down command is "up". Since we are only "down" one level, "up" would have the same effect as "top". In more complicated outlines, "up" moves up one level, while "top" always takes you to the top-most level of an outline. Go ahead and enter the "up" command. You should see this on your CRT: | 0. <<<Contents>> | 1E Feed the cats | 2E How I can be reached | 3E Get the mail | 4E Daily | 5. <<<Weekly>>> | 6E In case of emergency | | 5 :: Now use the "cut", "down", "paste", and "up" or "top" commands to put "Feed the cats", "How I can be reached" and "Get the mail" in their proper places. When you are done, return to the top of the outline and make "In case of emergency" the current index. Your screen should look like this: | 0. <<<Contents>> | 1. Daily | 2. Weekly | 3. <<<In case of emergency>>> | | 3 :: Moving up and down in your outline is called "navigation" in the rest of this document. Other ways to navigate are explained in later sections. When you were moving the "Feed the cats" heading, did you think of another emergency situation? I did. Let's add the vet's number to "In case of emergency". Further more, let's do it all on one command line. The semicolon character is used to place more than . 9 . TOUR Guide - Version 2.0 one TOUR command on a single line. Ready? | 0. <<<Contents>> | 1. Daily | 2. Weekly | 3. <<<In case of emergency>>> | | 3 :: down ; append The vet number is 555-1234 ; up Verify that the vet number is really there by using the "subtree" command. Type "subtree". The screen will clear and you should see: | 3. <<<In case of emergency>>> | 1E The vet number is 555-1234 | 2E How I can be reached | <<<Push return>>> :: After you push return, the screen will display the top level of the outline again. | 0. <<<Contents>> | 1. Daily | 2. Weekly | 3. <<<In case of emergency>>> | | 3 :: Review: Cut and paste are used to move outline entries. Up, down and top are used to move to different levels, or "navigate" in your outline. The subtree command shows the lower level outline entries of a sub-heading. 5.4 Adding text to the outline Let's make this into a real letter. Start by entering an opening note. This is done by the "introduction" command. At any level in your outline, "introduction" will place a text note before the sub-entries. Type "introduction" and the following lines: | 3 :: introduction | enter text (push return at the beginning of a blank line to stop) | 1 :: Steve, | 2 :: Thank's for taking care of the house. Here's a list of a few | 3 :: things I thought you should know: | 4 :: After pushing return at the beginning of text line 4, TOUR will show you the outline. It now tells you that you have entered text, even though it doesn't show you the text. | 0. <<<Contents>> . 10 . TOUR Guide - Version 2.0 | 1. Daily | 2. Weekly | 3. <<<In case of emergency>>> | ... plus text | | 3 :: To read the text, type "view". TOUR will display: | 0. <<<Contents>> | Steve, | Thank's for taking care of the house. Here's a list of a few | things I thought you should know: | 1. Daily | 2. Weekly | 3. <<<In case of emergency>>> | <<<push return ::>> After you push return, TOUR will show you the outline without the text. If a heading has subheadings, TOUR only shows you its text if you explicitly ask for it. Otherwise, you would find that the display would fill quickly and your outline would be cluttered. At this point, we are trying to make sure that the structure of the document to be is clear and complete. The outline is more important than the text. Another command, "summary", will place text after the sub-headings (if any exist.) Use the "summary" command to close out the letter with the following note: | 3 :: summary | enter text (push return at the beginning of a line to stop) | 1 :: Thank's again for everything. I'll be back on the 27'th. | 2 :: Ed | 3 :: Use "view" to see the result. Note that TOUR has no editing capability other than simply adding the intro and summary text. At this point, play with the outline, add any other things that you think a house sitter should know or do. For example, the names of my cats are Tinker, Boots, and Surprise, and their food should be laid out, left to right, in that order. Add this as an "introduction" to "Feed the cats" Experiment with the append command. Use different "current indicies" and observe where TOUR places the headings. Delete outline entries that you don't want with the "delete" command. The delete command removes the current sub-heading and its sub-trees from the outline. (Do be carefull!) Review: The introduce command adds text to the outline in front of a section's first sub-heading. The summary command adds text to the outline after a section's . 11 . TOUR Guide - Version 2.0 last sub-heading. The veiw command displays introductions and summaries. The delete command removes outline entries. 5.5 Saving the outline When you are done, save your outline. To save the entire outline, you must first issue a "top" command. Here, "up" won't do. Then, type "write note.rno". Any filename that's valid for your computer may be used instead of "note.rno". Exit the TOUR program by typing "exit". | :: top | 0 :: write note.rno | 0 :: exit You can look at note.rno with your text editor. You will see a lot of lines that begin with ".hl" and ".sl". Together, they form your outline structure. You will probably notice the entries of our outline following the .hl's. You can use your editor to correct any misspelling in the document and resave it to disk. However ... Never add, move, or delete .hl's or .sl's unless you totally understand what they are for. To do so could mean that neither TOUR nor ROFFTOUR (the text formatter) will be able to make sense of your document. (They're not really that had to understand! The ROFFTOUR.DOC file describes their meaning.) When you have fixed any misspellings and saved the changes, use the text formatter to produce the final letter. (But don't delete note.rno in case you want to change it later.) | A>rofftour note.rno >note.mem There is a lot more that you can do with TOUR. Additional commands and ideas for using TOUR are given in THE TOUR GUIDE. Review: Use the top and write commands to save an outline. You can edit the outline with a text editor. A text formatter is used to produce the final listing. 6. Terminology and conventions 6.1 Headings A heading is the name of a section in a TOUR file. Headings may contain any printable characters, any number of embedded blanks, . 12 . TOUR Guide - Version 2.0 and some of the ascii control characters. In particular, control Z and control @ are not allowed. 6.2 Sections A section is the collection of text and sub-headings contained within a heading. Every outline entry heads a section. Some sections, however, may be empty. 6.3 Sub-headings and sub-trees A sub-heading is simply a heading which is contained within another heading. If sub-heading contains other headings it may also be called a sub-tree. 6.4 Indicies All headings and sub-headings within TOUR are numbered. The number given to a heading or sub-heading is called its index. Most TOUR command operate on the current sub-heading. Its index number is called the current index. You may make any sub-heading current by typing its index number. If the sub-heading that you wish to make current is not in the current heading, you may make it current by typing its complete or "absolute" index number. Absolute indices begin with a zero (for "Contents") and contain the index of every heading above it. For example, no matter where you are in the outline, typing "0 4 2" will make the top level entry "4" the current heading and entry "2" within it the current sub-heading. In addition, TOUR has "relative" indices. If "0 4" were the current heading, and you wished to make its sub-heading "1" the current heading and subheading 1's subheading "3" the current sub-heading, you could type "1 3" (without a zero). This would have the same effect as typing "0 4 1 3". 6.5 Screen mode TOUR will make limited use of your terminals screen capabilities. When doing this, TOUR is said to be in screen mode. As an alternative TOUR may be placed in line mode. The screen command toggles between these two modes. If your terminal can respond to an ascii sequence to home and clear its screen, you will probably want to use screen mode. Screen mode is the default. 6.6 Command entry Command entries consist of numbers (used to specify indices), command words, and optional or required arguments to the command. Commands may be typed in upper or lower case. Many commands may be entered on one line by separating them with . 13 . TOUR Guide - Version 2.0 the command delimiter character. The default command delimiter character is the semicolon. Be careful when entering multiple command per line; the indicies may change as a result of a previous command's execution. If an error is detected in a command line, the command in error, and all those following, will not be executed. The following section documents each of the commands recognized by TOUR. By convention, The fewest number of characters needed for TOUR to recognize a command are shown capitalized. Optional entries are enclosed in square brackets, and data descriptions are enclosed in pointed brackets. Don't type in brackets unless you intended them to be part of the entry. Review: TOUR uses relative and absolute indices. Screen mode is the default. The general command syntax is <index> <command> <argument> Multiple commands may be typed on a single line if they are separated by a semicolon. 7. TOUR command reference 7.1 <index> The <index> command is used to change the current heading and/or current index. TOUR commands operate on the current heading and current index. Using index commands allows you to tell TOUR what is to be affected by commands to follow. Indices consist of numbers which are separated by non-alphabetic characters. Indices which begin with the number 0 are absolute indices. That is, they index (address) a heading from the top-most contents of the file. For example: "0 4 1 2" refers to the fourth heading in the document, the first sub-heading under that and the second sub-heading under that. The result of typing in 0 4 1 2 would be that "4 1" would become the current heading, and "2" would become the current index. Relative indices begin with a number other than zero. They index (address) sub-trees of the current heading. For example, if the current heading was "4 1", typing "3" would be equivalent to typing "0 4 1 3" The current heading remains unchanged, "3" becomes the current index. Typing "3 2" would be equivalent to typing "0 4 1 3 2". In this case, the current heading would be changed to "4 1 3" and the current index would become 2. TOUR checks your index to insure that it actually refers to a heading in your file. An index may PRECEDE a command on a line. For example: . 14 . TOUR Guide - Version 2.0 3 Insert Complete the TOUR documentation causes subheading 3 of the current heading to become the current index, and then inserts the heading "Complete the TOUR documentation" as new sub-heading "3". The old sub-heading "3" and all sub-headings indices after it are renumbered automatically. 7.2 Append [<heading>] If a heading is specified, Append inserts it into the current heading immediately after the current sub-heading. The current index is incremented to refer to the new sub-heading. Any sub-heading indices following the appended sub-heading are automatically renumbered. If a heading is not entered on the command line, TOUR enters append mode. It prompts for new sub-headings. Enter one per line and terminate each line by pressing the return key. When you are finished entering sub-headings, press the return key without any other text on the line in response to the prompt. 7.3 Back Back moves you to the section of your outline that would be printed before the current section in your final document. To do so, it moves you up and down the levels of your outline. 7.4 CHange [<heading text>] CHange allows you to re-enter the title of the current sub-heading. If you do not enter the heading as part of the command line, TOUR will prompt you to enter it. Pushing return without entering text will abort the change. 7.5 Cut Cut removes the current sub-heading from the current heading and automatically renumbers any sub-heading which follow it. The Cut heading is saved on a stack until it is used by the Paste command. You may Cut up to 20 headings. Note: To help you move sub-trees between files, the paste stack is not cleared by the NEW command. 7.6 DElete DElete removes the current sub-heading from the TOUR file. All sub-headings which follow the DEleted heading are automatically renumbered. 7.7 Down . 15 . TOUR Guide - Version 2.0 Down moves you deeper into you outline. The current sub-heading becomes the current heading. The current index becomes 0. 7.8 Entire Entire lists the complete outline on the screen. 7.9 EXIt EXIt terminates your tour. If your TOUR file has been modified and has not been saved, TOUR will ask you to verify your intent to lose your work. 7.10 Help and ? Both Help and ? list the valid TOUR commands. 7.11 Insert [<heading>] Insert adds a new heading to the outline. The new heading is placed before the current sub-heading. The inserted heading becomes the new current sub-heading. If a heading is not entered on the command line, TOUR will prompt you to enter it. 7.12 INTroduce [<text line>] INTroduce allows you to enter text into your TOUR file. The text will appear before any sub-headings of the current heading. If you enter text as part of the command line, TOUR will place it at the end of any existing text in the heading introduction. Otherwise, TOUR will prompt you to enter lines of text. When you have finished entering text, push the return key WITH NO OTHER TEXT ON THE LINE to resume command entry. To enter a blank line of text, you must enter at least one space. Your system's normal line entry editing commands may be used. 7.13 List List causes all of the sub-headings of the current heading to be listed on the terminal. List has no effect in screen mode. 7.14 NEW NEW caused TOUR to be re-initialized. If you have modified your outline, and haven't save the modified contents, TOUR will verify . 16 . TOUR Guide - Version 2.0 your intent to lose your work. Note: To help you move sub-trees between files, the paste stack is not cleared by the NEW command. 7.15 Next Next moves you to the section that would be printed next in the final document. To do so, it moves you up and down the levels of your outline. 7.16 Paste Paste removes the last Cut heading from the stack and inserts it at the current index. 7.17 Read [<filename>] Read causes the contents of a file to be inserted at the current index. The file should be a TOUR file, although ordinary text files may be read into empty sub-headings. If no <filename> is specified, TOUR will ask you if you want to read the last filename entered (Yes/no question). If you specify "no" it will prompt you to enter a the filename to read. 7.18 SCreen The SCreen command toggles TOUR between screen mode and line mode. The default is screen mode. If your are working in a section that won't fit on one terminal screen, you may want to turn screen mode off. 7.19 Subtrees Subtrees causes TOUR to display the sub-headings of the current sub-heading. It the current index is zero, Subtrees will display the sub-trees of every sub-heading in the current heading. 7.20 SUMmarize [<text line>] SUMmarize places text lines after the sub-headings of a heading. (Regardless of when the sub-headings are entered.) To use the SUMmarize command, there must be at least one sub-heading in the current heading. See the INTroduce command for details on text entry. 7.21 Top Top moves you to the top of the TOUR file. The current heading . 17 . TOUR Guide - Version 2.0 becomes "Contents" and the current index becomes zero. Top is used before a Write to save the entire contents of a TOUR file. 7.22 TYpe [<filename>] TYpe causes the contents of the file specified to be listed on the terminal one page at a time. If you do not specify a filename, TOUR will prompt you for it. The contents of the TOUR file are not modified. 7.23 Up Up moves you towards the top of the outline. The current heading becomes the current sub-heading. 7.24 View View works like List, but also displays text. It is used to interactively read a document. 7.25 Write [<filename>] Write causes the current sub-heading and its subtrees to be saved on disk. If the current index is zero, the entire outline SECTION is written instead. If you are not at the Top of the TOUR file, you will be warned that you are not saving the entire contents and will be asked if you wish to proceed. If a filename is not entered, TOUR will ask you if you wish to use the last filename entered. If you answer no, it will ask for the name of a new file. Review: The valid TOUR commands are: Append Back CHange Cut DElete Down Entire EXIt Help ? Insert Introduce List NEW Next Paste Read SCreen Subtrees SUMmarize Top TYpe Up View Write 8. Using ROFFTOUR The ROFFTOUR program is described in the separate document ROFFGUID.TXT. Refer to it for instruction. 9. Hints on outlining 9.1 Introduction . 18 . TOUR Guide - Version 2.0 Most people were taught to make an outline before writing. Typically, the points to be made are written on index cards and then shuffled around to make an outline. The outline is then examined and refined. More cards are added, some are consolidated into major points while others are expanded into minor points. You can use TOUR instead of index cards to make an outline. With TOUR you shuffle your outline on a CRT screen instead of on the kitchen table. On a 64k computer system, TOUR can maintain hundreds of outline entries. When you have finished your outline, it may be printed out for reference while you actually write. Some people embed their outline within their writing. The outline appears as chapter titles and section headings. Typically, the headings are shown with numbers to reflect their relationship to each other. Such a document is said to have decimalized headings. If you would like to have decimalized headings within your writing, TOUR can be of further assistance to you. TOUR stores outlines in ordinary text files. You may add paragraphs to this file, developing each point in your outline, with your favorite text editor. (TOUR itself is not a text editor.) When you are finished, the supplied text formatter, ROFFTOUR, can format your writting and supply the decimalized headings. TOUR does have a limited text entry capability. (It does not have text editing capabilies.) With it, you may associate text with any outline entry. This is kind of like writing notes on your index cards. When you use TOUR to shuffle outlines, it automatically keeps the text with the proper outline entries. Since TOUR is totally memory based, the amount of text it can maintain is severely limited. In terms of a final document, it works out to about 10 pages of single spaced text. TOUR includes all text entered in its output file. Again, you may edit this text with your favorite text editor. At any time when your document will fit into memory (including text) you may use TOUR to restructure it via its normal outline processing commands. Alternatively, you may use TOUR to interactively read your (10 page) document. Sections of interest may be quickly found in outline mode and read individually. I call this feature "touring a document" and it is the origin of TOUR's name. REVIEW: Use TOUR to create an outline. Add text with your favorite text editor or TOUR. Use ROFFTOUR for final formatting of the document. 9.2 Collect ideas as they come to you When you are first starting an project, ideas about it do not . 19 . TOUR Guide - Version 2.0 come prepackaged in neat outlines. That's okay. The most important part of starting a project is to collect your all of your ideas so that none fall through the cracks. Forget about structure to begin with. 9.3 Look for natural grouping After you have collected your first ideas and thoughts, look for a natural grouping. A chronological grouping is often used at the top of an outline. Sometimes, as when writing a technical reference, ideas are introduced according to increasing levels of complexity. Background and pre-requisite information is given first. Lower levels of the outline will expand upon or develop higher levels. Everything contained in one level of an outline should be of equal importance in developing that section's point. 9.4 Assign ideas to the natural grouping Take your original ideas and move them into your outline. If they don't fit, either your outline is inappropriate for your ideas, or (some of) your ideas are not necessary for the development of your point. 9.5 Fill in the blanks Examine your outline. Is it complete? If not add additional entries. Look for entries that need further expansion or research of supporting facts and ideas. This is normally an iterative process. It is critical that your outline be complete at each level. The reward for doing so is that you may then concentrate on each point individually without worring about "the big picture". 10. Limitations TOUR is totally memory based. If your TOUR file will not fit into memory, TOUR will read as much of it as it can. This is probably not very useful. Instead, try splitting it into multiple files. The program occupies about 25K of your computer's memory. On a 64k system, that leaves about 30K for your TOUR file. For performance reasons, TOUR is a memory pig. In addition to the text in your TOUR file the following overhead exists: every heading : 16 bytes every text line : 4 bytes TOUR is capable of managing a text document of approximately 4000 words. It is suitable for small reports and chapters of larger reports. This document represents approximately twice TOUR's capacity. . 20 . TOUR Guide - Version 2.0 Control C is not trapped. If you type control C, your session will be lost. Do not type control Z on the terminal. Doing so terminates input to TOUR, but not the TOUR program. Again, anything not saved will be lost. Beware of text editors which do not terminate each and every line (including the last) with a carriage return line-feed. WordStar is notorious in this regard. TOUR will not work properly with these files. Use non-document mode or use one of the public domain programs to remove all special characters from the file. CHanging and DELeting headings may cause memory fragmentation. If TOUR reports that it is out of memory, you may be able to get a little bit more in by writing the file, and restarting TOUR. When determining if a TOUR file has been modified, TOUR really checks its internal memory. So, if you simply Read a file and issue the EXIt command, TOUR will tell you that "the contents haven't been saved." Command words are not completely decoded. You may find that if you forget to enter a command, TOUR could think what you typed was a command anyway. For example, assume that the first heading you wanted to add to your outline was "Introduction". If you didn't type Append or Insert, TOUR would take your intended heading and execute it as a command. . 21 remov