RefGuide User's Guide

1. Check out the entire _RefGuide project from StarTeam into a folder named RefGuide.
2. If not already constructed, add the following subdirectories to RefGuide:
   Bin - Holds the AisRefGuide.db repository
   Foundry - Holds the files to be evaluated by the aisRefGuide program
   wwwroot - Holds the generated html documentation pages
   
3. To work on the existing AIS Documentation:
• You may edit a document in CoreContent. To edit, click on the CoreContent cabinet in the cabinets tab. The contents of this cabinet will appear in the right hand text pane. Double-click on the document to be edited. Edit the document as needed.
• To prepare for HTML generation of the AIS Documentation, copy all the files from the CoreContent folder and Templates folder to Foundry.
4. To make own documentation and generate it using aisRefGuide program:
• Create a separate folder in RefGuide.
• Create ontology objects as needed. See Creating Ontology Objects below.
• Save the created ontology objects in your created folder.
• To prepare for HTML generation of your own documentation, copy all the files from your created folder and all the files in the Templates folder to Foundry.
5. Click on Astartup.sl in the refguide directory to start up AIS.
6. Initialize RefGuide as follows:
• Open the Cabinets Tab in the session form.
• Right-click on the RefGuide cabinet. Select Import. Import Source/RefGuide.sl
7. Return to the console tab and run RefGuide by entering "(aisRefGuide)" in the Console command text area. This command will generate a set of HTML document files in wwwroot. For more options on running aisRefGuide, please see Running AisRefGuide
8. Copy the files from wwwroot into your ais/docs/onlinedocs directory.

AisRefGuide may be run by entering any one of these commands in the Console command text area.

 (aisRefGuide)

This runs aisRefGuide and generates the HTML documents in wwwroot.

  (aisRefGuide "targetCabinet" "targetLambda" "export folder path") 

This command is used to extract any embedded documentation from a source file.The aisRefGuide Lambda will get the file from the "targetCabinet". Then it writes the source files in the Foundry subfolder in the "export folder path". The html output will be placed in the wwwroot subfolder also in the "export folder path".

Example: (aisRefGuide "JavaScript" "javaScript" "C://ais/libraries/javaScript/")

Note: Just make sure you have the "wwwroot" and "Foundry" subfolders under the "export folder path".

  
(setq aisrefGuide.myVerboseSwitch true/false)  
(aisRefGuide) 

Setting myVerboseSwitch to true lets aisRefGuide print the time it takes in seconds to run aisRefGuide and all its child Lambdas. Set myVerboseSwitch to false if you want to turn this timing option off.

  (setq aisRefGuide.exampleChecking true/false) 
								(aisRefGuide)

Setting exampleChecking to true lets aisRefGuide run the source code examples you have in the Syntax->Expression field in the Example Ontology Object. If the sample source code does not run, RefGuide prints the file name of the file containing the incorrect source code. Set exampleChecking to false if you want to turn this option off.

Document Ontology Objects:

See the Document Ontology Example. The Document Ontology is divided into KnowledgeBase and the list of Essays. The KnowledgeBase division is composed of the Document Title, Topic, Subtopic and a list of Keywords (termed as Human Keywords). The contents of KnowledgeBase are used to cross-index, cross link and search for Documents and Essays. The list of Essays enclosed in the <Essay> tags is composed of the topical subdivisions of the document.

To create a Document Ontology Object, just fill in values for the XML tags in the Document Ontology and save it as "Document_DocumentOntologyTitle.html"

Essay Ontology Objects:

See the Essay Ontology Example. Make sure that all the Essays in the <Essay> tags of the Document Ontology Object have its own corresponding Essay Ontology Object. The Essay Ontology Template is divided into KnowledgeBase and the list of Sections. The KnowledgeBase division is composed of the Essay Title, Topic, Subtopic and a list of Human Keywords The contents of KnowledgeBase are used to cross-index, cross link and search for Documents and Essays. The Sections contain the contents of the Essay Object.

To create an Essay Ontology Object, just fill in values for the XML tags in the Essay Ontology and save it as "Essay_EssayOntologyTitle.html". Make sure that the title of your Essay Ontology Object is the same as the Essay specified in the Document Ontology Object.

Datatype Ontology Objects:

See the Datatype Ontology Example. The Datatype Ontology Template is divided into KnowledgeBase and the list of Sections. The Datatype Ontology objects are cross-linked and cross-referenced with other Datatype Ontology Objects and with Function and Example Ontology Objects.

To create a Datatype Ontology Object, just fill in values for the XML tags in the Datatype Ontology and save it as "Datatype_DatatypeName.html".

Function Ontology Objects:

See the Function Ontology Example. The Function Ontology Object are cross-linked through referencing the <ArgumentTypes> tag, <Datatype> tag and <RelatedFunctions> tag.

<Datatype> tag contains all the supported datatypes for the function. <RelatedFunctions> tag contains the list of the related AIS Functions.

<ArgumentTypes> tag in the KnowledgeBase contain the AIS Datatypes of the Function arguments. Since functions support multiple datatypes, the ArgumentType for a function of one datatype may not be the same for another datatype. To differentiate the ArgumentTypes for the Datatypes, just add the Datatype to the ArgumentType tag (<ArgumentType-Datatype>).

For instance, the inside function works on Vectors and Dictionaries. For the Dictionary Datatype, the syntax is: (inside key dictionary) . The Argument Names with its corresponding AIS Datatypes are as follows:

• key - String or Text
• dictionary - Dictionary

For the Vector Datatype, the syntax is: (inside obj vector) . The Argument Names with its corresponding AIS Datatypes are as follows:

• obj - Character String Symbol Vector BitVector ByteVector IntVector FltVector ObjVector Structure Dictionary Directory Matrix NumMatrix Integer Float Number Complex
• vector - Vector BitVector ShortVector IntVector NumVector

Therefore, the <ArgumentName> for the inside function may look like this:

<ArgumentTypes-Dictionary> String Text Dictionary </ArgumentTypes-Dictionary>   
<ArgumentTypes-Vector> Character String Symbol Vector BitVector ByteVector Number Complex Vector
		        IntVector FltVector ObjVector Structure Dictionary Directory Matrix NumMatrix Integer Float 
		        BitVector ShortVector IntVector NumVector  </ArgumentTypes-Vector>  

For functions with the same argument type regardless of the supported Datatype , there is no need to specify the Datatype in the ArgumentType tag, <ArgumentTypes> will do. Having the <ArgumentTypes> tag may also mean that the contents inside the <ArgumentTypes> tag is the default argument types of the other datatypes supported by the function. For the inside function, the ArgumentTypes tags may be written as:

<ArgumentTypes-Dictionary> String Text Dictionary </ArgumentTypes-Dictionary>   
<ArgumentTypes> Character String Symbol Vector BitVector ByteVector Number Complex Vector
		        IntVector FltVector ObjVector Structure Dictionary Directory Matrix NumMatrix Integer Float 
		        BitVector ShortVector IntVector NumVector  </ArgumentTypes>  

Like the <ArgumentTypes> tag, the <Overview>, <Usage> and <Syntax> tags may specify the specific supported Datatype of the Function if the contents of the Overview, Usage and Syntax tags are unique to that function of the supported datatype. But for functions with the same text for overview, usage or syntax, there is no need to specify the Datatype in the tag.

To create a Function Ontology Object, just fill in values for the XML tags in the Function Ontology and save it as "Function_FunctionName.html".

Example Ontology Objects:

See the Example Ontology Example. The Example Ontology objects are cross-linked and cross-referenced with other Example Ontology Objects and with Datatype and Function Ontology Objects.

The <TypeKeywords> found in the KnowledgeBase refer to the function argument datatypes used in the example.

To create an Example Ontology Object, just fill in values for the XML tags in the Example Ontology and save it as "Example_Datatype_ExampleName_ExampleNumber.html".

Sample source code may be written either in the Example Ontology or the VMInstruction Ontology Objects. RefGuide can check whether the sample source code is working or not. Working source code samples must be enclosed between <sc> </sc> XML tags to enable checking by RefGuide. If the user does not want to have the source code checked, or if the purpose of such code is to illustrate an error, <sc> </sc> tags must be omitted.

VMInstruction Ontology Objects:

Open the file VMInstruction Ontology Example. To create a VMInstruction Ontology Object, just fill in values for the XML tags in the VMInstruction Ontology and save it as "VMInstruction_VMInstructionName.html".

Special Characters in Ontology Objects

AIS RefGuide Ontologies read and evaluate alphanumeric characters as PCDATA or parsable character data. RefGuide also recognizes Special Characters but other Special Characters must be represented in the Ontology Objects as an HTML name or RefGuide will either flag an error or wrongly evaluate and render the special character.

Below is a list of Special Characters that must be represented in their HTML name:

• < must be represented as &lt
• > must be represented as &gt
• & must be represented as &amp
• " must be represented as &quot

Special Characters in File Names

Function and Example Ontology file names may contain special characters. This happens because function names are part of the file names in the file naming convention for Function and Example Ontology Objects. (Please see "Creating Ontology Objects" above for file naming convention.)

Currently, file names containing special characters are renamed as (sym)SpecialCharacterName. For instance, the function * has the following files: Function_(sym)mul.html and Example_Complex_(sym)mul_002.html