1 LISP LIBRARY PACKAGES MANUAL 1 LISP LIBRARY PACKAGES MANUAL DINFO 1 ON-LINE DOCUMENTATION TOOLS 1 DINFO 6 DInfo is a system for browsing graph structured documentation. The only graph currently available for browsing is the Interlisp-D Reference Manual. Sadly, tools for editing documentation graphs have not yet been thoroughly developed, although hooks are provided. 2 User Interface 1 Loading DINFO.DCOM adds DInfo to the backgroung menu. To start DInfo, one should select DInfo from the background menu. Note that the global variable IRM.HOST&DIR must be set correctly before DInfo is started (see Installing DInfo below). DInfo will take a moment to read in the initial graph, and then be available for use. Most interaction with DInfo is through a menu at the top of DInfo's window, which looks like this: `?0| 0f Plf Pl6f?6f l| ` `` @ @@0` @@0` %àDK#(0hyĒ2$&$`DMD$H(L " Ē$$ (HD!%'ȉ #RL$$ (HD&H%$  "22 H$$`HDdH"$H  " D$#H3"#Ι  00O >0H& 0H%0H%OĤ0H$>0H$D0H$D00π2@>y0@6͙R8pG!Ϗ0RDH!!"08C!!0͙L!!yDH!#"8pGPπ <3< fٳd#EϘ~lٳp#$AE!#"`lٳ!')!!>f8ٳL!$)!! <8x#$A!#"#00 0 0@??D30@ @Ͷg09p%p !.xpͷ 0D&d>!1"DĈ  $D !! Dpg0d $D !! Ds0D $D #!"D:g $Dp !4xp`πp?c`πp c ϙ ̂cgy08"@ĞfLlـ alͶ0Dđ"@fLـ scn̓`8fL ـ cć@fLlـ ací"Dđ$ ̀3π coy8@@0`` fflfpxflf @ ff@c>A@ff ϛ6f 6f 6` 6f 3   Next to Graph!, Node:, Top!, Parent!, Previous!, and Next! are printed the names of the node currently being visited, the name of the top node in the current graph, the name of the node previous to the current node, and the name of the node next to the previous node, respectively. Graph!, Top!, Parent!, Previous!, and Next! are also commands as follows: Graph! raises a menu with the names of the graph's DInfo knows about (see DInfo Internals, below). Selecting an item from this menu will cause DInfo to switch to that graph. Top! visits the top node in the current graph. Parent! visits the parent of the current node. Previous! visits the node previous to the current node. Next! visits the node following the current node. Thus Previous! and Next! provide sequential access to the graph. The Display commands control what will be displayed when a node is visited: Graph toggles display of a Grapher display of the graph local to the current node. Selecting a node in this display will visit the corresponding node in the current DInfo graph. Menu toggles display of a menu of subnodes of the current node. If the current node has no subnodes no menu will be displayed. Selecting an item in the subnode Menu will visit that node in the graph. Text toggles display of the text of the current node. Turning this off will speed up the visiting of nodes considerably, useful when searching for a particular node. History toggles recording and display of a menu containing the history of nodes visited. Selecting an item from this menu will revisit that node. Lookup! and Find! have editable items to their right in the menu. These items are initially empty, and hence invisible. Lookup! will look up the term to its right in the index of the Interlisp-D Reference Manual, and then bring you to the node containing this term. Note that once you have started DInfo, all manual lookup is modified to work this way, i.e., the ? TTYIN macro and the HELP lispxmacro will use this facility. Note also that "*" is a wild card in lookup strings. Find! will search for the string to its right in the text of the current node. User Variables 1 DINFOGRAPHWINDOWPOSITION [Variable] Determines where DInfo will place the window used for displaying the graph. Default is (1 . 1). DINFOMODES [Variable] Determines which of the toggles will be selected when DInfo is initially started; it should be a list with recognized members being GRAPH, MENU, TEXT, and HISTORY. Default is (GRAPH TEXT). DINFO.HISTORY.LENGTH [Variable] Determines the maximum length of DInfo's history. Default is 10. Because DInfo sits atop the HelpSys manual lookup facility, the two packages share some resources, including the window. Thus the position of DInfo's window is determined by a variable in HelpSys, namely IRMWINDOWREGION. 2 Installing DInfo 1 As DInfo is only currently implemented for the Interlisp-D Reference Manual, installation of DInfo is identical to installation of HelpSys. That is, the entire contents of the Interlisp-D Reference Manual floppies must be put on one directory (either on a file server or on disk), and the variable IRM.HOST&DIR should be set to the name of this directory. DInfo Internals 1 The following information is included for the programmer interested in adding alternate graphs to DInfo. DINFONODE [Record] Contains the following fields: ID Unique identifier for node in graph, ala GRAPHNODE field NODEID. Note that EQ is used for checking identity of nodes. LABEL The print name of a node. Analagous to the GRAPHNODE field NODELABEL. FILE The file containing the documentation for this node. Should not generally include HOST and DIRECTORY fields as DInfo will default these (assuming all documentation files are on one directory, see below). FROMBYTE Byte number in FILE where the documentation for this node begins. TOBYTE Byte number in FILE where the documentation for this node ends. DInfo uses OPENTEXTSTREAM to display its files, and thus any TEdit file can be included. Note that if a file has any formatting (image objects in particular), the byte number of a character in a file is not necessarily the same as the TEdit character number of that character. Thus this random access feature is really only useful with plain text files. PARENT The ID field of the node parent to this node. CHILDREN A list of the ID's of the subnodes of this node. NEXTNODE The ID of the next node in the graph. PREVIOUSNODE The ID of the node previous to this node in the graph. USERDATA Unused. Note that there is no special access function for this field as, for example, WINDOWPROP is for the USERDATA field of a WINDOW. This field is left open for use by implementors for whatever they see fit. DINFOGRAPH [Record] Contains the following fields: NAME The name of the graph. Should be an atom. Note that when DInfo reads a graph from a file (with DINFO.READ.GRAPH) this field is set to the NAME field of the file name the graph is read from. NODELST The list of nodes in the graph. Each node should be a DINFONODE record. TOPNODEID The ID field of the root, or top node of the graph. CURRENTNODE Used by DInfo to keep track of where in the graph DInfo is. DEFAULTHOST Used if no host is specified in the FILE field of a node. DEFAULTDIR Used if no directory is specified in the FILE field of a node. Note that DEFAULTHOST and DEFAULTDIR are set when a DINFOGRAPH is read from a file (by DINFO.READ.GRAPH) to the host and directory of that file. TEXTPROPS Will be passed as the PROPS argument to OPENTEXTSTREAM when the file for a node in the graph is displayed. This feature is used to fake formatting of the Interlisp-D Reference Manual files, which are really plain text. LOOKUPFN Will be called when the user selects Lookup! from DInfo's FreeMenu with two arguments: The string to look up, and the current DInfo graph. EDITFN Called when the middle mouse is depressed in DInfo's window. If not specified, DINFO.DEFAULT.EDITFN will be used. Passed one argument of the current DInfo graph. USERDATA Spare field for use by applications. DINFO.INIT.FILE.NAME [Variable] If NIL, DInfo will assume the only graph is in Interlisp-D Reference Manual.DINFOGRAPH on Interlisp-D Reference Manual.HOST&DIR, otherwise DInfo will READFILE the file named by this variable to find out what graphs it knows about. READFILE of this file should return a list, the CAR of which is discarded (assumed to be a comment) and the CDR of which should be a list of files containing DINFOGRAPHs (written by DINFO.WRITE.GRAPH, of course). You should have gotten a sample DINFO.INIT somewhere with this release. DINFOW [Variable] Bound to the window that DInfo uses. One should never set this variable, as DInfo uses it to determine whether DInfo has been initialized. WINDOWPROPS of interest: CURRENT.GRAPH [Window property] The current DINFOGRAPH. GRAPH.FILES [Window property] A list of file names of graphs DInfo knows about. Used to create the menu raised by the Graph! command in DInfo's FreeMenu. DInfo caches lots of things as WINDOPROPS of DINFOW. A wise programmer would do well to look here if in search of some obscure aspect of DInfo's state. (DINFO.UPDATE NODE SEL) [Function] Will visit node in current DInfo graph. NODE should be a DINFONODE record. SEL is used by DInfo's Interlisp-D Reference Manual lookup facility, and should be useful in implementing other lookup facilities. SEL determines what in the TEXT of this node will be selected. SEL should be a list of the format (NAME X . Y) where NAME is the name of the selection, X is the character number in the text of NODE where SEL starts, and Y is the length of the selection. If Y is NIL (i.e., SEL = (NAME X)) then the length of name is used as the length of the selection. This is useful for the lookup of terms. (DINFO.RESET) [Function] Will completely reset DInfo. Hopefully there will be a full editing interface in the next release. This would allow the user to add and and change graphs, allowing DInfo to act as a document organizer. (LIST ((PAGE NIL (PAPERSIZE Letter FOLIOINFO (ARABIC ) STARTINGPAGE# 117) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD RIGHT) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO (ARABIC )) (270 12 288 36) NIL) (HEADING NIL (HEADINGTYPE FOOTINGR) (54 27 558 36) NIL) (HEADING NIL (HEADINGTYPE RECTOHEAD) (54 762 558 36) NIL) (TEXT NIL NIL (54 54 504 618) NIL))) (PAGE NIL (PAPERSIZE Letter FOLIOINFO (ARABIC )) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD LEFT) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO (ARABIC )) (54 12 288 36) NIL) (HEADING NIL (HEADINGTYPE FOOTINGV) (54 27 558 36) NIL) (HEADING NIL (HEADINGTYPE VERSOHEAD) (54 762 558 36) NIL) (TEXT NIL NIL (54 54 504 684) NIL))) (PAGE NIL (PAPERSIZE Letter FOLIOINFO (ARABIC )) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD RIGHT) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO (ARABIC )) (270 12 288 36) NIL) (HEADING NIL (HEADINGTYPE FOOTINGR) (54 27 558 36) NIL) (HEADING NIL (HEADINGTYPE RECTOHEAD) (54 762 558 36) NIL) (TEXT NIL NIL (54 54 504 684) NIL)))))/T(. )T/T(()T)2T) T.)T( )T(((( C PAGEHEADING VERSOHEADTB PAGEHEADING VERSOHEADB PAGEHEADING RECTOHEADA PAGEHEADINGFOOTINGVA PAGEHEADINGFOOTINGR( MODERN MODERNMODERNMODERN MODERN ?1(DEFAULTFONT 1 (GACHA 10) (GACHA 8) (TERMINAL 8))  HRULE.GETFNMODERN  HRULE.GETFNMODERN  HRULE.GETFNMODERN  HRULE.GETFNMODERN  HRULE.GETFNMODERN  vw  HRULE.GETFNMODERN  HRULE.GETFNMODERNd BMOBJ.GETFN3MODERN f//82ALy?O HRULE.GETFN%a! B  HRULE.GETFNMODERN  HRULE.GETFN.f  HRULE.GETFNMODERN  i  w G   C A d .  1  &  7     I  4  <  :  ?   %     %  /    }    ) R>! ( %l   >z