Created: Sat 8 Dec 2001 00:15:13 GMT+00:00
Modified: Wed 17 Nov 1858 00:00:00 GMT+00:00
Enhanced a2h
Moving AUGMENT files and browsing functionality onto Bootstrap Web

Doug Engelbart
7-Dec-2001 16:46-PST (BI,2220,)1

Note: This draft memo describes background and requirements for converting exported Augment files into web-browsable html files. Eugene Kim then developed an a2h tool (see his OHS page for details) building on earlier work of Shinya Yamada and Raylene Pak. Although this tool was made obsolete in 2006 by augXml written by Jonathan Cheyer as part of the HyperScope project. However, the background and requirements are still very much illustrative of the Augment file architecture. [CE]2


This memo is about more-detailed and -automatic translation of AUGMENT files into "Web-useable" form -- AND about then developing browser extensions that provide enhanced, AUGMENT-equivalent, mobility and viewing options on the translated AUGMENT files. 3a

Note that the implementation would provide much enhanced value if it could be "integrated" with that proposed in -- i.e. if this "A2H" translation would target the same (probably XML) file form as used for the HhyperScope's Intermediary File.3a1

Multiple payoff is anticipated:3b

  1. A good many AUGMENT documents contain material of direct value to important facets of the "Bootstrap Program." Having their translated versions available for Web access should be quite useful -- especially when their significant segments can be explicitly addressed.3b1

  2. Implementing AUGMENT's viewing and addressing options would be directly possible -- AND would provide a significant head start on developing planned HyperScope functionality and deriving expected value from it. Thus, the resultig a2h file structure needs to be compatible for employment of the forty-one explicit AUGMENT viewspec parameters.3b2

  3. Their structure needs also to be compatible for employment of AUGMENT's fifteen explicit structure-relative addressing parameters and eight explicit in-paragraph addressing parameters. These include provision for the uniquely powerful "indirect" addressing.3b3

  4. An important HyperScope implementation possibility would be to adapt the a2h translation and the subsequent mobility/viewing operations using evolvable HyperScope "Intermediary" files (instead of HTML files), which would be a valuable way to get started with learning how to do HyperScope implementation.3b4


Translating AUGMENT files into HTML form, with level indentation and "purple numbers," was first done in the mid 90's by Christina Engelbart and Bob Czech (who wrote the Smalltalk program for our "modern" AUGMENT client, called "VAT" for "Visual AugTerm"). This translation process required a fair amount of specialized hand labor.4a

Early in 2000, Shinya Yamada began working on a more direct translator, but had to return to Japan before getting it useable for me.4b

Frode Hegland suggested adding a feature to the Purple Numbers, which orignally were simple address labels. He suggested (and did the installation on some trial files) that the Purple Number installation be enhanced by making these numbers be clickable links to their respective paragraphs -- and thereby enabling a user to do the "right-click" copy process which enabled her subsequently to paste the complete URL for that paragraph into another document.4c

In Fall 2000, Eugene Kim produced (and named) the "a2h" translator, for which I put together some simple processes to apply to an AUGMENT file which produce a sequential file which could be ftp'd to a location where Eugene's translator would automatically process it and install the translated HTML file in an appropriate location. This also provided for level indentation and Purple (Location) Numbers. Per AUGMENT file, preparing and shipping requires only about five mintues of personal work by me. The first translation was of , translated into , a basic description of Hyperscope purpose and architecture. 4d

Subsequently, Eugene produced his "Purple" processor which automatically added Purple Location Numbers as well as AUGMENT-like Purple (integer) SIDs Statement Identifiers -- with both numbers having Frode-like links to their paragraphs. 4e

Extending the a2h translation process5

Planned -- A fully automatic process: Simply supply name(s) of AUGMENT file(s); then automatic processes in AUGMENT environment operates on each designated file, creating an appropriate sequential-ASCII file and ftp-ing it to the Kim-developed translator, which installs the translated XML (evolvable, HyperScope intermediary) file at appropriate web address. 5a

Raylene Pak will develop this "AUGMENT-launch" capability.5a1

Automatically deriving the "a2h-installed" file names (and thus URLs) from the AUGMENT-file addresses:5b

Journal files:5b1

E.g. becomes ""5b1a1

NOTE: a2h translator recognize journal-target links because they are the only ones for which the "file name" is an integer.5b1a2

Most-used Journals likely to be: AUGMENT; BI; perhaps ALLIANCE.5b1b

Other Journals that may contribute: MDC; OAD; ASD; ESL; TAC; ... 5b1c

Non-Journal files:5b2

Likely use non-journal files from only two of the DEC20 Structures:5b2b

USER: holding all personal directories, plus a number of "group" directories.5b2b1

USER2: 5b2b1a

DEV: holding all of the developer-spec and source-code files.5b2b2

JRNL: 5b2b3

Each registered user owns a directory in the USER Structure; e.g. ENGELBART, PAK, COPPERNOLL, ... from which some files may be translated.5b2c


Adding the rest of AUGMENT-file properties to the translation:5c

Origin-node, every file5c1

"External" Link: Command Jump Name External, click on a word, and the system goes to the file pointed to by this file's "External Link" property, finds the node labelled with that selected word, and expects to find a link on that node which is traversed. This "indirect addressing" feature is VERY useful in situations such as for source code, where the compiler creates the external-ref-linkage file, so that the sorce-code definition for every procedure and global variable is always just one "jump-name-external" click away. 5c1a

"Link-default Directory" -- usually cites its own Directory/File combination; but offers value in special circumstances when set to point to another directory/file. 5c1b

Marker name/link pairs -- up to ten "labelled markers" can be set up within a file, arbitrarily named/renamed and located/re-located to serve as always-useable addresses to a node, or actually to a given character in a node's string. the data for these, consisting for each established marker of (up to 5-character) label string, and the SID+Offset address of the "marked" character -- are kept in the file's "origin node" property structure .5c1c

Origin-node, Journal Files also have5c2

Journal "Fields": Slightly enhanced Mail-node fields, as in 5c2a

Every node5c3

Name Delimiters 5c3a

Statement signatures 5c3b

[* a2h has already been dealing with the following: *]5c3c

Location Number 5c3d

Statement IDentifier 5c3e

Statement Name 5c3f

Special file-body nodes:5c4

Mail-header nodes 5c4a

Mail Properties (Questionable value in early AUGscope? But, what if later we got clever about making use of them?)5c4a1

Tail-node flag (hmmm, really necessary?)5c4b

Later Need/Possibility:5c5

Nodes pointing to .ppt/.gif/... graphic frames // for "Fig-1" etc.5c5a

Translating AUGMENT links to URL-links whose "link executions" would replicate the addressability within the translated XML files to the equivalent of what would be done by AUGMENT link jump actions withing the originating AUGMENT files. (Note below that the equivalent of the AUGMENT link's viewspec actions are also planned to be implemented within the HyperScope's evolving, XML-intermediary-file actions.)5d

Note: AUGMENT's addressing conventions enable minimal link-address strings:5d1

  1. refers to a node labelled "nnn" in this same file.5d1a

  2. refers to node "nnn" in file named "FFF" located in the same Directory as the file in which the link is embedded.5d1b

  3. refers to node "nnn" in file named "FFF" located in the Directory "DDD" in the same Structure as the file in which the link is embedded.5d1c

  4. refers to node "nnn" in file named "FFF" located in the Directory "DDD" in the Structure "SSS".5d1d

Adding browsing/viewing functions to a special "AUGscope" Browser (hopefully, the actualy evolving HyperScope) for navigating and viewing these a2h translated files.6

NOTE: Special extensions to the AUGscope "Browser" 6a

  1. Involves adding controls/commands to the AUGscope // as is expected in the HyperScope >Ref-1>.6a1

  2. Also could benefit from separating Control Window from multiple, View-Only windows, as utilized in "Double-Click" Jumps. Cf. through . 6a2

All AUGMENT links, as translated into URLs, yield same Jump/View result in AUGscope as they do in AUGMENT (assuming the target files are in the "translated" form and location).6b

Establish URL syntax providing ASCII string designating a ViewSpec; accept all the AUGMENT Vspec characters/effects. 6b1

Example: -- jump to origin (Node 0) of AUGMENT Journal file "nnnn" -- viewing only top level (i.e. statemetns 1, 2, 3, ...), one line per statement, with no blank lines between, showing Location (statement) Numbers at Left.6b2

ViewSpec designators ... characters which can be combined into meaningful "View Specifications" 6b3

Blank lines Blank lines between statements on/off y/z6b3a

Statement numbers Statement numbers/SIDs on/off m/n
Statement numbers/SIDs right/left G/H
Show SIDs/statement numbers I/J6b3b

Statement names Show statement names yes/no C/D6b3c

Statement signatures Show statement signatures yes/no K/L6b3d

Level clipping Show first/+1/-1/all levels d/b/a/c
Show levels down to level of statement e
to be at top of file window6b3e

Line clipping Show first/+1/-1/all lines t/r/q/s6b3f

Outline/normal Show first level and first line only x
Show all levels and all lines w6b3g

Structure clipping Show branch only g
Show all branches h
Show plex only l6b3h

Content filtering Filter statements based on Set Content i
Don't filter statements j
Show next filtered statement k6b3i

Indenting Level indenting on/off A/B
Offsets indenting, with viewspec l or Q
g, to level of statement at top of
window; turn off with viewspec h or A6b3j

Frozen statements Show frozen statements o
Don't show frozen statements p6b3k

Screen refresh Put viewspecs into effect now f
Recreate display (incl. new viewspecs) F
Recreate window after each change u
Defer recreating window v6b3l

AUGMENT-Style, Double-Click Jumps: Also, equivalent Jump XXX capability -- with extra click required, allowing options for: (1) in between-click interval, enter characters stipulating what the end viewspec is to be; and (2) moving cursor to another window before final click, designating where the new location/view is to be displayed.6c

Note: The Jump commands are available in all subsystems. Cf. "Jumps" at 6c1

Jump (to) [MARK] VIEWSPECS6c2

Jump (to) Link CONTENT6c3

Jump (to) Origin (of file) (from) LOCATION VIEWSPECS6c4

Jump (to) Next/Back/Down/Up (from) LOCATION VIEWSPECS6c5

Jump (to) Successor/Predecessor (from) LOCATION VIEWSPECS6c6

Jump (to) Head/Tail (of plex at) LOCATION VIEWSPECS6c7

Jump (to) End (of) File/Branch/Plex (from) LOCATION VIEWSPECS6c8

Jump (to) Content/Word First/Next [RC]/CONTENT VIEWSPECS6c9

[TAB] command repeats a previous word or content search.6c9a

Jump (to) Name First/Next/Any CONTENT VIEWSPECS6c10

Jump (to) Return OK6c11

Jump (to) Return File OK6c12

Adding "Extended Addressing" ... including "Relative Addressing" -- see LINKS AND ADDRESSES at 7

A "link" is 7a

You may omit the angle brackets < > when you type a link in the command line. 7a1

ADDRESS = FILEADDRESS for origin statement of file
or INFILEADDRESS for location in current file
or omit entirely for current location7b

FILEADDRESS = FILENAME, at current site and directory
or DIRECTORY,FILENAME, at current site
or PART:DIRECTORY,FILENAME, on other partition

Note that every form of FILEADDRESS ends with a comma.7c1


[ESC] fills out file names and directory names.7d1

INFILEADDRESS is one or more of the elements below, separated by [SP]. [SP] is not required if the next element begins with punctuation. Use Help to get information about any of these elements (by typing its name) or about other elements (by typing "INFILEADDRESS"). (See ONLINE HELP .)7e

Element Name Example
------------ -------7e1


SID 0127e3

STATEMENTNAME statementname7e4

NEXTNAME *statementname7e5

SUBNAME !statementname7e6



WORDSEARCH "word"=w7e9

RELATIVE POSITION .n .b next and back statement
.u .d up or down statement
(can be strung .o .e origin, or end of branch
together, used .h .t head or tail of plex
with numbers, .s .p successor or predecessor
such as .5b or .c next occurrence of search pattern
.2usd) .l follow the link found there
.r .rf return to previous view, or file7e10

STRINGPOSITION +e +f last or first character of statement7e11

About the associated "Link Databases":8

"Back-Link Database" -- listing of two-link entries. Each entry points8a

  1. to the node in this DKR being cited by any other link, and8a1

  2. to the specific location of the citing link, whether within this DKR, or any other that has been executed. Also,8a2

  3. identity of the citing-link's author8a3

  4. date/time it was first authored8a4

  5. viewspec from the citing link8a5

"Forward-Link" Database -- A of two-link entries. Each entry points8b

  1. to the node in this DKR citing any other node, anywhere, and8b1

  2. to the specific location of the cited link, whether within this DKR, or any other. Also,8b2

  3. identity of the cited-node's author8b3

  4. date/time it was authored8b4

  5. viewspec in this citing link8b5

Automatic updating of the "Back-Link" Database whenever:8c

  1. a new file AUGMENT file is translated into this DKR.8c1

  2. any other link-executed access to any of the files in the DKR -- from anywhere on the Web.8c2

Special ViewSpecs associated with the Link Databases (Usage experience will undoubtedly spur evolution of more/better viewspec options.)8d

Show a specified set of info about links which8d1

  • point to designated portions of a given file within a specified DKR8d1a

  • and/or point to material authored by a specified person or set of people8d1b

  • and/or point to material authored in a given time period8d1c

  • and/or point to material containing/referencing specified substantive content8d1d



Ref-1: Basic design spec for HyperScoope: <BI,2120,>10a