@begin(header) author: ackerman@athena.mit.edu show_author: ShowNone author_organization: MIT node_expert: ackerman@guilder.mit.edu expiration_date: 06/25/93 last_modifier: ack@foobar.mit.edu last_mod_date: 11/06/91 mod_num: 9 @end(header) WRITING OR EDITING ANSWER GARDEN NODES Mark Ackerman ackerman@athena.mit.edu last revision: 10/24/91 modifications and additions from the last version marked with a '+' at the beginning of the paragraph Vocabulary ---------- A node is an instance of a generic node-type. In other words, the node-type is the code template for particular occurrences of nodes. The node-types that are available are: Grapher - displays a tree SBrowser - displays a structured answer or a set of question buttons QA - displays a series of questions and answers Discussion - displays a series of opinions or email messages Code - displays code segments + Ascii - displays an ascii file (no Answer Garden header assumed) These will be discussed in detail below. Authoring --------- To add or edit an Answer Garden node, you must select the appropriate action from the edit menu. You get the edit menu by pressing the control key and the mouse button2 at the same time. Hold down the mouse button and drag the cursor to the appropriate action. If this doesn't work, see your AppDefaults resource file for the correct bindings. I'm going to give the easiest path, in my conception, through the authoring process. You may find another way easier - your choice. After I go through the "official" way, I will tell you how to brute force any change you want. (Hey, this *is* Unix.) Editing node of an existing node-type ------------------------------------- The easiest way to author is to modify an existing node. After all, you are going to generally modify the information network. Let's start by editing the Root node. On the Control node (the first node you see, the one that says this database is about the X Window System), go into the button that says "Ask Questions". You can get the edit menu using a combination of the control key and mouse button 2. If this doesn't work, check the appdefaults file for the changed bindings. Select the first item from the menu, "Edit File". The Root node for the X database should then come up in an editing node. The text should be: @b Are you having a problem with @Button(Finding information about X,General_Information) @Button(Using an X application,Using_Applications) @Button(Programming with X,General_Programming) @Button(Administering X,General_Admin) @button(Using Answer Garden, Info_AnswerGarden) It comes up in a separate pane, with (currently) 7 buttons across the bottom. The "Abort" button appears at first. If you change any text, the "Save File" button becomes active. Once you save the modified file, you cannot undo the change. To signal this, the "Abort" button becomes insensitive and the "Close" button becomes sensitive. +The editor uses the Athena Ascii Text widget. You should check the Athena widget documentation to find out what the capabilities and key bindings are. Generally, the Ascii Text widget is an emacs-alike (close enough but not quite to emacs to be annoying). I'll explain the various markups later, but for now, think of the @button as a link to another node (which is exactly what it is). If you wish, you can edit a subnode of the Root by selecting one of the @button statements. Visually selecting a line, for example, @Button(Administering X,General_Admin) places the line in the XA_PRIMARY selection (for cutting and pasting). Once you have selected a line, you can edit the node by clicking "Edit File", edit the node information by clicking "Edit NodeInfo", or show (display normally) the node by clicking "Show". Go ahead and try these. - Use "Abort" or "Cancel" on the two edit panes to exit, and "Close" in the normal way on the normal display. - If you didn't visually select some line (by dragging the mouse with button1 down across the line), you will get the error "Warning: please select a line beforehand" +You can also click on any grapher button (that is, any button in any SBrowser or Grapher) to edit a node. Editing the text of a node is straight-forward (presuming you can get along with the Athena text widget). The widget is a simplified version of Emacs, and any changes saved will show up in the node the next time it is displayed. Note that changes to a node do not yet automatically show up in any open nodes. The "edit node" brings up the actual text of the existing node. All nodes are stored as ascii files, and the body of the node is therefore just ascii. Each node-type has a different format, and these formats are detailed below. Enter your text, and then hit "Save File" to store out the file. If you wish to abort the addition of the node, you can do so by hitting the "Abort" button. You cannot abort the addition once you have saved the file. You can finish the addition of the node by hitting the "Close" button. (It is greyed out until you save the file.) Editing the node information is also straight-forward. Each data entry item is a one-line text widget. Select the @button line for Administrating X, and click "Edit NodeInfo". You can see that this node is an SBrowser type (explained below), has the node name "General_Admin", a label, a physical storage location of "General_Admin", an expiration date and an expert list. You can edit the label (used currently for the title bar when the node is opened), the expiration date (to indicate the useful "shelf-life" of information, this is the date of review for a node's information), and the expert list. The expert list is who "owns" questions from this node. If you wish to change the expert for a node, read "How the Experts Are Found" below. Adding a new node of an existing node type ------------------------------------------ You can also add a node by entering a new line in the widget. For example, enter the line @button(test label,Test137) The string up to the comma is the node's label, and the subsequent text is the node's name. +If you try to show this node at this point, you will get the error "Warning: Node does not exist yet." You must first add the new node to the Node Service. If you select the line with @button, and click the "Add Node" button, you start a two-step process. In the first step, you will be given the Node Info pane. You must select the node-type. This is a choice of what kind of node to create. In the scenario you have just gone through, the NodeInfo pane comes up with the node name and the label set. (It should be identical to the @button line.) The physical location is the file name (if using the default FileService) for the physical file. It defaults to the node name, and in most cases, this is sufficient. You will not be able to change the node name or the node-type later. +(Changing the node-type is coming. Now, you must change the node-type by editing the AGNodeFile; details below.) You can also set the expiration date for the data. It defaults to two years from the present date. Additionally, you can set the node experts manually. If you do not, you will be the node expert by default. Note, that in the manual setting, if you leave this field blank, the authoring system will assume that you do not want an expert for this field. (Currently, this means that Answer Garden will use the global expert list, given in the appdefaults file, for mailing from this node.) Currently, Answer Garden cannot select a node name for you. In version 0.8, Answer Garden will be able to provide a node name in the auto setting. Additionally, in version 0.8, the text fields should be able to grow when more room is needed. Currently, a poor substitute of having scrollbars on the text fields is provided. The second step in adding nodes is to create the actual node's text. All nodes are stored as ascii files, and the body of the node is therefore just ascii. Each node-type has a different format, and these formats are detailed below. Enter your text using the edit pane provided. This edit pane uses the Athena text widget (no grumbling allowed). Note that you may have to hit cntl-L occasionally to the text widget for it to appear correctly - cntl-L just refreshes the text widget's display, and does no actual formatting You should hit "Save File" to store out the file. If you wish to abort the addition of the node, you can do so by hitting the "Abort" button. You cannot abort the addition once you have saved the file. You can finish the addition of the node by hitting the "Close" button. (It is greyed out until you save the file.) If you create a node by clicking control-button2 and getting the edit menu *on any grapher button*, you will need to enter enter a name for the node (ie, how the node will be known to the Answer Garden code) and a label for the node (ie, how the node will be identified in trees and in sbrowsers). This is the same as creating a node that will be placed later. If you do this from a SBrowser node's display, even Root's, and the "auto-link" feature is on, the @button will be placed automatically in the parent node's text. Header Information and Brute Force ---------------------------------- Note, these nodes also have header information. In general, you cannot directly edit the header information (which includes things like the authoring date and the last modification date) within Answer Garden. EVERYTHING IN ANSWER GARDEN IS STORED IN ASCII. You can edit any node in a text editor such as vi or emacs. Information about a node is found in 2 places: - the node itself. + - the AGNodeFile. +The AGNodeFile contains one record per node. The format is + node name #node type #label #physical location If there is no physical location, the default is the same name as the node name. +The '!' character is the comment character in the AGNodeFile. A line begun with '!' will not be processed, for example: ! This is a comment line. +You can add nodes or modify attributes of the node by editing the AGNodeFile if necessary. Caution is urged in using this file by hand - you should always keep a backup copy. The authoring tools within Answer Garden are for convenience. There is nothing that you cannot do easily within vi or emacs. Other authoring tools --------------------- To determine whether your network is complete, use the everybody_here authoring tool. Everybody_here will check whether there are dangling references (ie, whether you have linked to nodes that do not actually exist) and whether there are any nodes in the directory that are not referenced in the If you do construct a system with dangling references, the symptom will be that you will get a message like: Warning: missing name Programming_C++ in node service. Continuing... This means that you should either change the reference or add the node (in this case called "Programming_C++"). One more caution: When you create a new node, do not forget to link to this new node. You can do that by editing a pre-existing node's text. Node-Types ---------- +The node-types that come as defaults with Answer Garden are currently the SBrowser, Grapher, QA-Node, Discussion, Code, and Ascii node-types. You can easily add additional node-types into Answer Garden including virtual nodes. See the document "Adding Node-Types" (which does not yet exist). SBrowsers -------- +The SBrowsers look like menus of buttons. They can also include normal, bold, and italic text, and they can serve as menus, answers, tutorials, and so on. SBrowsers use a language quite similar to Scribe, a text mark-up language used at MIT. There are an extremely limited number of commands implemented at this time. If you want additional commands, please let me know. The commands are case insensitive. The commands are: @b(string) - Boldface the string. @i(string) - Italicize the string. @button(label,node_name) - Place a link button in the node. Link buttons are centered in the text. When the button is hit by the user (by a mouse click), the node given by node_name is activated. To get the node name of an existing node, you can cut the node's name with a control-button3. You can then paste the name into the SBrowser buffer. @system(string) - Issue a system command. The string is passed directly to the system call. @crush(node name) or @close(node_name) - Closes a node if it is open. + @dynamic(callback name) - call a Dynamic Callback. (See the document "Adding Functionality to Answer Garden" ). You can write your own procedure to do whatever you want, and hook it into any of the Answer Garden displays. +SBrowsers can point to any type of node. Thus you can activate a QA Node, Code, Ascii, or Discussion node from an SBrowser as well as another SBrowser. Note that the linkage can be a network (actually it should be a directed non-cyclical graph), not just a tree. The fonts are given in the appdefaults resource file. Graphers ------ The Graphers display a tree. The Graphers read an ascii file. Each line has two important features. The number of blank characters beginning of the line give the information on the level in the tree. The text on the line is of the form "label/node_name". The label is what will be shown in the tree. When the user selects the label in the tree, the Grapher will activate the node given by the the node_name. Thus the file: The X Window System/Root Info about X/General_Info Programming/General_Programming has a 2 level tree. The first level (the root) is called "The X Window System" on the tree. When the user selects it, Answer Garden will activate the node called "Root". Similarly, when the user selects "Info about X", the Answer Garden will activate the node called "General_Info". To create the Graphers automatically after you have a network of SBrowsers and other nodes, use the make_graphers authoring tool. As of version 0.77, Graphers also have mailer and help buttons. QA -- QAs (sometimes also called QA-Nodes) use a markup language to indicate the annotations that go in the left margin. To indicate a question, surround the text of the question with a @begin(Q) and an @end(Q). To indicate an answer, surround the text of the answer with a @begin(A) and an @end(A). @begin(Q) question text @end(Q) @begin(A) answer text @end(A) +displays as Q question text A answer text The QA Node is rather stupid. It will actually put anything you place in the @begin() tag in the left margin. Thus, you can use this node- type for bug reports and enhancement reports as well as questions and answers. If you do not want anything in the left margin, omit the @begin's. The QA-Node was created to allow experts to throw a bunch of questions and answers together in one node without having to structure them. In version 0.8, you will be able to provide users with the ability to select portions of the QA. The QA node will have toggle buttons for any subsets you wish to identify in the tags. The commands @select(Question,Q) @select(Question,Question) @select(Answer,A) @select(Answer,Answer) @select(release 3,r3) @select(release 4,r4) @select(release 5,r5) will place 5 toggle buttons at the bottom of the QA Node, one for questions, one for answers, and one each for the 3 releases. You may tag text with either the @begin() and @end() to place labels in the left margin or a @begin-tag() and end-tag() to just index the text. Discussion ---------- Discussion nodes are just straight ascii. Just place the ascii directly in the node. Sometime in the future, they will allow users to move up and down by message. Code ---- +Code nodes are essentially the same as Discussion nodes. The header is slightly different. Ascii ----- +Ascii files are just that. No edit pane will come up - you insert an ascii file in the Answer Garden network by specifying a file name on the "EditInfo" pane (under physical location). This node will have no Answer Garden header information, and thus mail will go to the default experts for the installation. As well, the node will have no expiration date or author information. Turning Editing Off ------------------ To turn editing off for users, you must set the EditMode resource in the appdefaults file to False. You must also re-compile with the NO_EDIT flag. Unfortunately, the design of the Athena menu widget is such that there is no way to turn editing completely off without recompiling. +For most sites, modifying the GrapherButton translations in the app-defaults file to remove editing should be sufficient. Setting Editing Resources ------------------------- If you are creating nodes, the major resource to set is: AnswerGarden*nodeExpert: devnull@guilder.mit.edu which is the expert by default for any nodes you create. If you comment this line out in the app-defaults or in your .Xdefaults file, the node will not have a node expert and the default installation experts will be used at run-time. If this line is present, this resource (person, list of people, or mailing list) will appear in the "EditInfo" pane. You can always change the expert manually for any node. The other major thing to check is that the resource: AnswerGarden*organization: MIT is set correctly. Answer Garden determines whether a node is local or non-local by the author's organization.