@begin(header)
author: ackerman@athena.mit.edu
show_author: ShowNone
author_organization: MIT
node_expert: ackerman@xv.mit.edu
expiration_date: 06/25/93
last_modifier: ack@amt.media.mit.edu
last_mod_date: 09/02/91
mod_num: 5
@end(header)
WRITING OR EDITING ANSWER GARDEN NODES
	Mark Ackerman
	ackerman@athena.mit.edu

	last revision: 6/24/91


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 

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<The X Window System>

	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.

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.  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 Tree 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 the Root 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
The physical location is the file name (if using the default File
Service) 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.

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, 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.)  

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 AGNSFile.

The AGNSFile contains one record per node.  The format is

#node name 	#label		#node type		#physical location

If there is no physical location, the default is the same name as the node
name.	

You can add nodes or modify attributes of the node by editing the
AGNodeServiceFile 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, and Code 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
--------

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.
	
SBrowsers can point to any type of node.  Thus you can activate a QA
Node, Code, or Discussion node from an 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 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.

In version 0.8, Graphers will 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)

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.  


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.  If
you are not worried about having users set their translations in a resource
file to be able to edit (by giving themselves the appropriate action for
