../../../hyperscope/docs/HYARCH.AUG.112

<BI5, USER2:NEUBERG, HYARCH.AUG.112,>, 6-Dec-2006 21:47-PST BKN ;;;;
  Start: <Overview:gwnBy>
  Overview
    Use the following links to gain various levels of detail and information about the HyperScope design :
      View all modules : <04:gebbzA>
      View all classes and files: <04:gebbbbzA>
      View indepth class method information: <04:gwzA>
      View control flow overview: <05:gnAzeb>
      View full control flow section: <05:gnAzw>
      View file format information: <06:Anyw>
      View third-party library information: <011:Anyw>
      View all sections: <1:zAxnh>
  Modules, Classes, and Files
    Back to Overview : <Overview:gwnBy>
    Client
      Module: hs.ui
        index.html
          Our main HTML file for the UI
        hs.ui
          Main entry point for the UI; initializes system
            Stereotype: static singleton
            document : hs.model.Document
            status : hs.ui.StatusArea
            commandHelper : hs.ui.CommandHelper
            currentHyDoc : hs.model.Document
            commandBar : hs.ui.CommandBar
            currentRenderedDoc : hs.ui.RenderedDocument
            initialize()
            printStatus(message : String)
            clearStatus()
            fadeStatus()
            reportError(exception : Exception)
            resolveLocation(url : String, customMethod : String)
              Note: 'customMethod' is a string to eval, such as a call to a specific hs.command to execute
        hs.ui.JumpOverlay
          A Dojo Widget that implements our jump overlay window that appears when the user presses the Jump button in the toolbar
            Stereotype: Dojo widget
        hs.ui.HyperScopeToolbar
          A Dojo Widget that implements our toolbar
            initializePowerUserSettings()
        hs.ui.RenderedDocument
          A class that renders our result hs.model.Document
            focusContextNode()
            write(doc : hs.model.Document)
            displayDocument(iframe : DOMDocument, contextNodeNumber : String)
            clearSelection()
        hs.ui.ResultWriter
          Writes our HTML results after XSLT to display to the user in a fast way
            hasScrollBars() : Boolean
        hs.ui.Mark
          Dereferences a mouse mark click into an hs.address.Address that can be worked with
            new hs.ui.Mark(evt : DOMEvent)
            row : DOMRow
            address : hs.address.Address
            invalidMark : Boolean
        hs.ui.ViewspecOverlay
          A Dojo Widget that implements our viewspec overlay
            Stereotype: dojo widget
            reset()
        hs.ui.LineClipper
          A class that performs line clipping on a rendered document
            applyChunk(doc : hs.model.Document, iframeDoc : IFrameDoc, container : DOMElement, rowChunk : TR[])
              Note: iframeDoc - The document object for the iframe our results were written into
              Note: container - The DOM object for our container that has our rendered node rows
              Note: rowChunk - Array of TR rows - our rows to line clip
        hs.ui.CommandBar
          Implements our Augment-style command bar
            visible : Boolean
            reset()
            isShowing() : Boolean
            show()
            hide()
            Note: This class is driven by the file commands.xml, which contains a special XML formatted description of our commands that is machine processable
        hs.ui.HelpOverlay
          Implements the help dialog displayed when the Help button is pressed on the main toolbar
            Stereotype: dojo widget
      Module: hs.commands
        hs.commands
          Singleton facade that exposes all of our commands as simple methods
            Stereotype: static singleton
            jumpItem(readyHandler : Function, address : hs.address.Address, relativeTo : hs.model.Document, viewspecs : String) throws hs.exception.Jump
              Notes:
                readyHandler = function(address : hs.address.Address, document : hs.model.Document, error : InvalidAddressException)
                All jump methods should filter out the parts of Location they need and throw the rest away
            jumpFile(readyHandler : Function, file : hs.address.FileInfo, relativeTo : hs.model.Document, typein : String (URL address), viewspecs : String) throws hs.exception.Jump
            jumpOrigin(readyHandler : Function, address : hs.address.Address, relativeTo : hs.model.Document, viewspecs : String) throws hs.exception.Jump
            jumpEndBranch(readyHandler : Function, address : hs.address.Address, relativeTo : hs.model.Document, viewspecs : String) throws hs.exception.Jump
            jumpEndPlex(readyHandler : Function, address : hs.address.Address, relativeTo : hs.model.Document) throws hs.exception.Jump
            jumpNext(readyHandler : Function, address : hs.address.Address, relativeTo : hs.model.Document, viewspecs : String) throws hs.exception.Jump
            jumpBack(readyHandler : Function, address : hs.address.Address, relativeTo : hs.model.Document, viewspecs : String) throws hs.exception.Jump
            jumpSuccessor(readyHandler : Function, address : hs.address.Address, relativeTo : hs.model.Document, viewspecs : String) throws hs.exception.Jump
            jumpPredecessor(readyHandler : Function, address : hs.address.Address, relativeTo : hs.model.Document, viewspecs : String) throws hs.exception.Jump
            jumpUp(readyHandler : Function, address : hs.address.Address, relativeTo : hs.model.Document, viewspecs : String) throws hs.exception.Jump
            jumpDown(readyHandler : Function, address : hs.address.Address, relativeTo : hs.model.Document, viewspecs : String) throws hs.exception.Jump
            jumpHead(readyHandler : Function, address : hs.address.Address, relativeTo : hs.model.Document, viewspecs : String) throws hs.exception.Jump
            jumpTail(readyHandler : Function, address : hs.address.Address, relativeTo : hs.model.Document, viewspecs : String) throws hs.exception.Jump
            jumpLink(readyHandler : Function, address : hs.address.Address, relativeTo : hs.model.Document, typein : String) throws hs.exception.Jump
            jumpLabel(readyHandler : Function, address : hs.address.Address, relativeTo : hs.model.Document, typein : String, viewspecs : String, jumpType : hs.commands.JumpConstants) throws hs.exception.Jump
            jumpContent(readyHandler : Function, address : hs.address.Address, relativeTo : hs.model.Document, jumpType : hs.commands.JumpConstants) throws hs.exception.Jump
            jumpWord(readyHandler : Function, address : hs.address.Address, relativeTo : hs.model.Document, typein : String, viewspecs : String, jumpType : hs.commands.JumpConstants) throws hs.exception.Jump
            resetViewspecs(readyHandler : Function, address : hs.address.Address, relativeTo : hs.model.Document)
            setViewspecs(readyHandler : Function, address : hs.address.Address, relativeTo : hs.model.Document, viewspecs : String)
        hs.commands.JumpConstants
          Constants that can be used with hs.commands to control commands, such as for jumping
            FIRST
            NEXT
            LAST
            ANY
      Module: hs.model
        hs.model
          Package level methods
            addOnLoad(myListener : Function)
        hs.model.Node
          Represents a node in an hs.model.Document
            new hs.model.Node(domNode : DOMNode, doc : hs.model.Document)
            doc : hs.model.Document
            number : String
            ID : String
            level : Integer
            cursor : hs.model.NodeCursor
            data : Object
              Note: This is the data of this node; for right now it is always text because that is what we currently support.
            domNode : DOMNode
            getChildNodes() : hs.model.Node[]
            jumpUp(offset : Integer) : hs.model.Node throws hs.exception.Jump
            jumpDown(offset : Integer) : hs.model.Node throws hs.exception.Jump
            jumpBack(offset : Integer) : hs.model.Node throws hs.exception.Jump
            jumpNext(offset : Integer) : hs.model.Node throws hs.exception.Jump
            jumpBranchEnd() : hs.model.Node throws hs.exception.Jump
            jumpPlexHead() : hs.model.Node throws hs.exception.Jump
            jumpPlexTail() : hs.model.Node throws hs.exception.Jump
            jumpSuccessor(offset : Integer) : hs.model.Node throws hs.exception.Jump
            jumpPredecessor(offset : Integer) : hs.model.Node throws hs.exception.Jump
            jumpBranchSearch(label : String) : hs.model.Node throws hs.exception.Jump
            jumpOffset(number : String) : hs.model.Node throws hs.exception.Jump
            test(expression : RegExp or String) : Boolean
              Note: 'expression' can be a JavaScript regular expression or a String
            getParent() : hs.model.Node
        hs.model.Document
          Represents a HyperScope outline document that can be interacted with and jumped through
            new hs.model.Document(address, dom)
            DEFAULT_FILE_EXTENSION: "opml"
              Note: The default file extension for document's of this type
            address : hs.address.Address
              Note: This address is unexpanded
            dom : XMLDOM
            origDom : XMLDom
            nodeCtxt : hs.model.Node
            currentViewspecs : hs.filter.CurrentViewspecs
            renderedHtml : String
            renderedHtmlDom : DOM
            normalize() throws hs.exception.Filter
            jumpOrigin() : hs.model.Node throws hs.exception.Jump
            jumpNumber(number : String, isOffset : Boolean) : hs.model.Node throws hs.exception.Jump
              Note: isOffset is optional and defaults to false.
            jumpId(id : String) : hs.model.Node throws hs.exception.Jump
            jumpMarker(marker : String) : hs.model.Node throws hs.exception.Jump
            jumpLabel(label : String,jumpType : hs.commands.JumpConstants) : hs.model.Node throws hs.exception.Jump
            jumpWord(word : String, jumpType : hs.commands.JumpConstants) : hs.model.Node throws hs.exception.Jump
            jumpContent(content : String, jumpType : hs.commands.JumpConstants) : hs.model.Node throws hs.exception.Jump
            jumpExternal(label : String) : hs.model.Node throws hs.exception.Jump
              Note: External labels are not supported yet
            render() : String throws hs.exception.Render
            getRenderXSLT() : XSLTProcessor
              Note: XSLTProcessor is this platform's XSLT processor
            toURL() : String
            getOriginDomNode() : DOMNode
              Note: Returns the DOMNode of the origin; used by some filters
        hs.model.NodeCursor
          A 'cursor' in an hs.model.Node that can jump through the textual contents of a node to perform string positioning by character, word, link, etc.
            new hs.model.NodeCursor(node : hs.model.Node)
              Note: This is the node to apply the cursor to
            position : Integer
              Note: Starts at zero by default
            toEnd()
            toBeginning()
            jumpWords(numWords : Integer) throws hs.exception.Jump
              Note: all jump* methods in this class can take either positive or negative values
            jumpCharacters(numChars : Integer) throws hs.exception.Jump
            jumpVisible(numVisible : Integer) throws hs.exception.Jump
            jumpInvisible(numInvisible : Integer) throws hs.exception.Jump
            jumpLink(numLinks : Integer) throws hs.exception.Jump
            getCharacter() : Character
              Note: Scans from position until it finds returnable character (i.e. no HTML or XML tags); returns null if none found
            getRest() : String
              Note: Returns everything forwards from current position
            getWord() : String
            getLink() : String
              Note: Returns just link text
            getAnchor() : String
              Note: Returns full A HREF anchor including link text
      Module: hs.address
        hs.address.Address
          A HyperScope address that can be resolved and manipulated
            new hs.address.Address(URL : String) throws hs.exception.InvalidAddress
            fileInfo : hs.address.FileInfo
            nodeAddresses : hs.address.NodeAddress[]
            viewspecs : hs.address.Viewspecs[]
            contentFilter : hs.address.ContentFilter
            resolve(handler : Function, replacePage : Boolean, relativeTo : hs.model.Document, inclusion : Boolean)
              Notes:
                handler = function(address : hs.address.Address, document : hs.model.Document, error : hs.exception.InvalidAddress)
                'inclusion' is an optional parameter that indicates that we are doing a resolution for a file that we be included; defaults to false
            equals(address : hs.address.Address) : Boolean
            equals(address : String) : Boolean
            toString()
              Note: Our address turned into a string; if relative, returns relative; if a full address, returns the full address as a string
            clone() : hs.address.Address
            isRelative() : Boolean
              Note: Whether this address is a full, non-relative address, such as http://foobar.com, or whether it is just relative with no scheme, host, path, etc., such as #2A:x or foobar.com/
            replaceResolution(newAddr : hs.address.Address, doc : hs.model.Document)
              Note: Causes one address resolution to stop, passing on its callback for the new address which begins its own resolution to take over - needed for indirect links
        hs.address.Piece
          Abstract superclass for all of the kinds of components that can make up an hs.address.Address, such as file information (hs.address.FileInfo), addressing (hs.address.NodeAddress), etc.
            Stereotype: abstract
            abstract toString() : String
            abstract isPieceType(className : String) : Boolean
        hs.address.FileInfo
          An hs.address.Piece that holds the file information for this Location, such as the path, port, URL scheme, etc.
            extends hs.address.Piece
            scheme : String
            host : String
            port : Integer
            path : String
              Note: Contains both path and file
            query : String
            hasFullPath() : Boolean
              Note: This returns whether there is a full, non-relative path, such as /neuberg/arch.opml, rather than a relative one, such as foobar/arch.opml
            expand(relativeTo : hs.address.FileInfo) : hs.address.FileInfo throws hs.exception.InvalidAddress
              Note: Expands and makes this FileInfo be non-relative, relative to the given document.
            toString() : String
              Note: Unexpanded string version of this FileInfo.
            clone() : hs.address.FileInfo
            isRelative() : Boolean
              Note: Returns whether we have a fully non-relative FileInfo, with scheme, port, host, path, etc.
            equals(obj : Object) : Boolean
            consolidateRelativeDots()
              Note: Consolidates .. and . dots that might be in the address into their non-relative paths. For example, dir1/dir2/../foobar.html would become dir1/foobar.html
        hs.address.NodeAddress
          The abstract superclass of all node addressing types, which can address specific portions of a document either directly or indirectly
            Stereotype: abstract
            extends hs.address.Piece, mixes in hs.filter.Filter
        hs.address.Viewspec
          Represents a specific viewspec letter in an hs.address.Address
            extends hs.address.Piece
            letter : String
        hs.address.ContentFilter
          Represents a content filter at the end of an hs.address.Address, such as ;"foobar";
            extends hs.address.Piece, mixes in hs.filter.Filter
            search : String
            toString() : String
            clone() : hs.address.ContentFilter
        hs.address.NodeNumber
          An hs.address.NodeAddress that is a node number, such as 2A3
            extends hs.address.NodeAddress
            new hs.address.NodeNumber(number : String, isOffset : Boolean) throws hs.exception.InvalidAddress
            number : String
              Example : 2A
            isOffset : Boolean
              Example : !2A
            static toNodeNumber(parentNodeNumber : String, nodeOffset : Integer)
              Note: Factory method that takes a parent node number, such as "2A5BB2" and a node offset, and returns a NodeNumber initialized to be the correct node number child with this number, such as "2A5BB2C" if the node offset were 3.
        hs.address.NodeID
          An hs.address.NodeAddress that is a node ID, such as 023
            extends hs.address.NodeAddress
            new hs.address.NodeID(id : String) throws hs.exception.InvalidAddress
            id : String
        hs.address.NodeLabel
          An hs.address.NodeAddress that is a node label, such as foobar
            extends hs.address.NodeAddress
            new hs.address.NodeLabel(label : String) throws hs.exception.InvalidAddress
            static START_AT_FIRST : String
              Example : label
            static BRANCH_SEARCH : String
              Example : !label
            static MOVE_TO_NEXT : String
              Example : *label
            static EXTERNAL : String
              Example : $label
            label : String
            type
              Note: One of the constants defined on hs.address.NodeLabel, such as hs.address.NodeLabel.START_AT_FIRST
        hs.address.Marker
          An hs.address.NodeAddress that is a marker, such as @someMarker
            extends hs.address.NodeAddress
            new hs.address.NodeMarker(marker : String) throws hs.exception.InvalidAddress
            name : String
              Example : @marker
        hs.address.Relative
          An hs.address.NodeAddress that is a single relative address, such as .2u
            extends hs.address.NodeAddress
            new hs.address.Relative(type, offset : Integer)
              Note: 'type' is one of the constants defined on this class, hs.address.Relative
            NODE_NEXT
            NODE_BACK
            NODE_UP
            NODE_DOWN
            ORIGIN
            BRANCH_END
            PLEX_HEAD
            PLEX_TAIL
            NODE_SUCCESSOR
            NODE_PREDECESSOR
            CONTENT_SEARCH
            RETURN_NODE
            RETURN_FILE
            type
            offset : Integer
        hs.address.IndirectLink
          An hs.address.NodeAddress that is an indirect link, such as .l
            extends hs.address.NodeAddress
            offset : Integer
        hs.address.StringSearch
          An hs.address.NodeAddress that is a string search forwards from the present location through the following nodes, such as "foobar"
            extends hs.address.NodeAddress
            search : String
              Note: We have normalized string searches to look like content filters
            toString() : String
        hs.address.StringPosition
          An hs.address.NodeAddress that jumps through a single node's textual contents, such as -2w
            extends hs.address.NodeAddress
            new hs.address.StringPosition(type, offset : Integer) throws hs.exception.InvalidAddress
            offset : Integer
              Note: Can be negative
            type
              Note: One of the constants defined on hs.address.StringPosition, such as LAST_CHAR
            LAST_CHAR
            FIRST_CHAR
            CHARACTER
            WORD
            VISIBLE
            INVISIBLE
      Module: hs.filter
        hs.filter.Filter
          A consistent API for applying filters and transformers to an hs.model.Document, changing the underlying hs.model.Document in some filter specific way; many objects are filters, including the hs.address.NodeAddress.
            Stereotype: mixin
            apply(document : hs.model.Document, readyHandler : Function, address : hs.address.Address) throws hs.exception.Filter
              Notes
                readyHandler is optional, and only needs to be given if this filter is asychronous (i.e. isAsynch() returns true)
                readyHandler = function(document : hs.model.Document, error : hs.exception.Filter)
            isAsynch() : Boolean
        hs.filter.Normalizer
          A Filter that normalizes an hs.model.Document into a consistent form before working with it; specifically, the Normalizer strips out everything but DOM Elements from the underlying hs.model.Document, and adds in node number information
            mixes in hs.filter.Filter
            new hs.filter.Normalizer()
        hs.filter.CurrentViewspecs
          A Filter that holds our currently applied viewspecs; reduces them into a form that can be worked with; and applies them in the final rendering phase
            mixes in hs.filter.Filter
            new hs.filter.CurrentViewspecs(letters : String, docCtxt : hs.model.Document) throws hs.exception.Filter
            new hs.filter.CurrentViewspecs(viewspecs : hs.address.Viewspecs[], docCtxt : hs.model.Document) throws hs.exception.Filter
            toString() : String
            add(view : String) throws hs.exception.Filter
            add(view : Viewspec) throws hs.exception.Filter
            getLevelClipping() : int
              Note: Returns from 0 to hs.filter.ViewspecConstants.MAX_LEVEL_CLIPPING
            getLineClipping() : int
              Note: Returns from 1 to hs.filter.ViewspecConstants.MAX_LINE_CLIPPING
            getStructuralClippingType() : hs.filter.ViewspecConstants
            showBlankLines() : Boolean
            showNodeAddressing() : Boolean
            getNodeAddressingPlacement() : hs.filter.ViewspecConstants
            getNodeAddressingType() : hs.filter.ViewspecConstants
            showNodeLabels() : Boolean
            getContentFilterType() : hs.filter.ViewspecConstants
            getLevelIndentingType() : hs.filter.ViewspecConstants
            showFrozenNodes() : Boolean
            showNodeSignatures() : Boolean
            runSequenceGenerators() : Boolean
        hs.filter.ViewspecConstants
          Viewspec constants useful for working with hs.filter.CurrentViewspecs
            Stereotype: static
            static DEFAULT_VIEWSPECS ="hjmpuwyACHJLP"
            static LEFT = "left"
            static RIGHT = "right"
            static SHOW_NODE_ID = "id"
            static SHOW_NODE_NUMBER = "number"
            static BRANCH_ONLY = "branch"
            static PLEX_ONLY = "plex"
            static NO_STRUCTURAL_CLIPPING = "none"
            static NO_FILTERING = "none"
            static FILTER_ALL = "all"
            static NEXT_FILTERED_NODE = "next_node"
            static INDENT_ON = "on"
            static INDENT_OFF = "off"
            static INDENT_TO_CONTENT = "to_context_node"
            static MAX_LEVEL_CLIPPING = 63
            static MAX_LINE_CLIPPING = 63
            static DEFAULT_LEVEL_CLIPPING = 1
            static DEFAULT_LINE_CLIPPING = 1
            static NO_PLEX_PARENT = "none"
              Note: Used for structural plexing
        hs.filter.Transcluder
          A Filter that walks the hs.model.Document tree, replacing INCLUDE statements with their resolved locations
            mixes in hs.filter.Filter
            static INCLUDE_NODE
            static INCLUDE_BRANCH
            static INCLUDE_PLEX
            new hs.filter.Transcluder(parentAddress : hs.address.Address)
              Note: 'parentAddress' is the parent address that is running this transclusion; this is the address of the root document that is being displayed to the end user
            currentNode : hs.model.Node
            nodeWalker : hs.util.NodeWalker
            metadataDirty : Boolean
              Note: Whether our metadata is dirty; if so, we must renormalize our document
      Module: hs.exception
        hs.exception.Jump
          Thrown if an error occurs during jumping; thrown by all jump* commands and methods
            message : String
            document : hs.model.Document
            address : hs.address.Address
        hs.exception.Filter
          Thrown if an error occurs during a filter process; thrown by all Filter.apply() methods
            message : String
            document : hs.model.Document
            address : hs.address.Address
        hs.exception.InvalidAddress
          Thrown if an error occurs while Location parsing or resolution
            message : String
            document : hs.model.Document
            address : hs.address.Address
        hs.exception.Render
          Thrown if an error occurs during the rendering phase
            message : String
            document : hs.model.Document
            address : hs.address.Address
      Module: hs.util
        hs.util.AddressSerializer
          Can serialize an hs.address.Address into a string or URL
            new hs.util.AddressSerializer(address : hs.address.Address) throws hs.exception.InvalidAddress
            serialize() : String
        hs.util.AddressTokenizer
          Parses a string or URL into a collection of hs.address.Pieces and can return them one by one, left to right
            new hs.util.AddressTokenizer(pageURL : String) throws hs.exception.InvalidAddress
            hasNext() : Boolean
            next() : hs.address.Piece
        hs.util.XMLFetcher
          Returns an hs.model.Document for the given address, either fetched remotely or from it's local cache
            static PROXY_URL = "/get/"
            load(URL : String or hs.address.Address, handler : Function)
              Note:
                handler = function(address : hs.address.Address, document : hs.model.Document, error : InvalidAddressException
        hs.util.NodeWalker
          Walks the tree of hs.model.Nodes in an hs.model.Document, performing some action or test on each node
            new hs.util.NodeWalker(ctxtNode : hs.model.Node, includeCtxt : Boolean)
            Note: 'includeCtxt' is optional, and controls whether to include the context node in the walk; defaults to true, which means we include the ctxtNode in the walk.
            hasNext() : Boolean
            next() : hs.model.Node
        hs.util.NodeNumberTokenizer
          Tokenizes a node number, such as 1B22C2A, and returns each level as a single number to easily step through a hierarchical node number
            new hs.util.NodeNumberTokenizer(nodeNumber : String) throws hs.exception.InvalidAddress
            hasNext() : Boolean
            next() : Integer
        hs.util.XSLTLoader
          Will asychronously load a set of XSLT files, tell you when they are loaded, transform them into XML DOMs, and return them by name
            new hs.util.XSLTLoader(files : Object[], loadedHandler : Function)
              Note: 'files' is an Array of Object literals, where each object has a member named 'name' that has the unique name of this XSLT, and 'url' is a member which has the URL to this XSLT file.
              Note: 'loadedHandler' is a Function pointer to a JavaScript function that will receive two arguments: function(success : Boolean, error : hs.util.InvalidAddress)
            load()
            getXSLT(name : String) : XSLTProcessor
              Note: XSLTProcessor is the particular platform's underlying XSLT processor
      Module: Rendering
        render.xsl
          XSLT file that renders our final, processed OPML into HTML suitable for displaying
            Our JavaScript code invokes render.xsl with a number of XSLT parameters using XSLTProcessor.setParameter; these are documented here:
              hs-internal:context-node-number
                Possible Values: string node number, such as 2A
              hs-internal:lineClipping
                Possible Values: none or number
              hs-internal:levelClipping
                Possible Values: none or number
              hs-internal:show-blank-lines
                Possible Values: true, false
              hs-internal:show-node-addressing
                Possible Values: true, false
              hs-internal:node-addressing-placement
                Possible Values: left, right
              hs-internal:show-node-signatures
                Possible Values: true, false
              hs-internal:show-frozen-nodes
                Possible Values: true, false
              hs-internal:node-addressing-type
                Possible Values: id, number
              hs-internal:show-node-labels
                Possible Values: true, false
              hs-internal:structure-clipping
                Possible Values: none, branch, plex
              hs-internal:content-filtering-type
                Possible Values: none, all, next_node
              hs-internal:level-indenting-type
                Possible Values: on, off, to_context_node
              hs-internal:plex-parent-number
                Possible Values: a number (ex: 2A) or "none"
                Note: Used to record the parent of our branch that we want to plex to
              hs-internal:included-from
                Possible Values: String URL
              hs-internal:included-type
                Possible Values: node, plex, branches
      Module: External Links
        bootstrap.xsl
          All OPML files include a single line, <?xml-stylesheet type="test/xsl" href="bootstrap.xsl"?>
          This line will load the bootstrap.xsl stylesheet, which will cause the opml to load in our UI chrome.
          This means a user can give an OPML url, such as http://foobar.com/hydesign.opml, and instead of returning XML we will transform it into an HTML file with our Ajax UI.
          This allows us to not need a server side for phase 1.
    Server
      Module: proxy.php
        PHP file that does cross-host inclusions
          This is a simple PHP file that securely proxies requests to third party hosts when fetching foreign OPML files - an optional file, HyperScope will run without this, it just can not do cross-host inclusions.
      Module: Mod_Rewrite
        An Apache module that can create 'friendlier' URLs on a website, versus their logical locations
          We use mod_rewrite in two cases:
            /get/ - We rewrite the proxy.php URL to be at /get/ so it is at a cleaner address and independent of the backend technology
            /hyperscope/ - We 'host' hyperscope at this address to have a consistent URL for getting hyperscope resources
  Control Flow
    Back to Overview: <Overview:gwnBy>
    Note: This section will not be maintained as the system is developed; only the class area, the file format info, and so on will be maintained.
    User action is transformed into an address (hs.address.Address)
      if page just loaded
        var address = new hs.address.Address(window.location.href)
          inside hs.address.Address constructor
            tokenize the URL we've been given
              var tk = new hs.util.AddressTokenizer(url)
                inside hs.util.AddressTokenizer constructor
                parse url from left to right, building up internal hs.address.Pieces as we do so
              while tk.hasNext()
                var piece = tk.next()
                if piece.isPieceType("FileInfo")
                set our fileInfo value
                else if we are an hs.address.NodeAddress
                add to our nodeAddresses array
                etc. for other hs.address.Piece parts
      if jump command
        get a location
          if mouse marks with click of button
            var address = hs.ui.Marker.toAddress(evt)
          if text entry into jump field
            create address from field text
        call correct hs.commands facade method
          for jumping up
            hs.commands.jumpUp(address)
              internally, all commands are transformed into form suitable for hs.commands.jumpItem
      if Set Viewspecs
        get viewspecs and content filter from viewspec text field
        turn them into hs.address.Addresses
        call hs.commands.jumpItem with the hs.address.Address
    Resolve the address
      execute address.resolve(handler, replacePage, relativeTo)
        inside hs.address.Address.resolve
          fully expand this hs.address.Address first
            this.expandFileInfo(relativeTo)
              fully expands out our file information so it is no longer relative, using the hs.model.Document given by relativeTo to do so
            this.expandNodeAddress()
              Adds a default address if one is not given (which is 0)
            this.expandViewspecs(relativeTo)
              expands our viewspecs, adding in the default and current viewspecs before this hs.address.Addresses viewspecs so they are parsed when we get to the rendering phase
          should we fully reload the page (if replacePage is true and we are not an address working with the current visible page)?
            reload the page
              window.location.href = this.toURL()
          else ask the hs.util.XMLFetcher for this page
            hs.util.XMLFetcher.load(url, handler)
              hs.util.XMLFetcher either remotely retrieves the document if not seen before, or it fetches it from its cache
              when the document is returned, it transforms it into an XML document using Sarissa
              it also asserts that the document is OPML and OPML version 2
              it then creates an hs.model.Document and returns it to the handler function passed into load()
          when the hs.model.Document is loaded and returned to our hs.address.Address...
            normalize the document
              document.normalize()
                internally calls new hs.filter.Normalizer().apply(document)
                hs.filter.Normalizer strips out all elements except for DOM nodes, and adds in numbering metadata
            setup our starting context node
              document.jumpOrigin()
            resolve each of our infile addresses
              for each hs.address.NodeAddress
                call its apply() method
                currentAddress[i].apply(this)
                internally, each hs.address.NodeAddress works differently and uses the hs.model.Document to jump to that node, then sets the hs.model.Documents nodeCtxt to this new hs.model.Node that we have at the top of the screen (our context)
                examples :
                hs.address.NodeNumber.apply - 2A4C
                doc.jumpNumber(this.number)
                inside hs.model.Document.jumpNumber()
                uses XPath to resolve desired node number (most jumps uses XPath)
                hs.address.Label.apply - *label
                doc.jumpLabel(this.label, hs.commands.JumpConstants.NEXT)
                inside jumpLabel uses XPath
                hs.address.Relative.apply - .2u
                doc.nodeCtxt.jumpUp(2)
                hs.address.IndirectLink.apply - .l
                doc.nodeCtxt.cursor.jumpLink(this.offset)
                var link = doc.nodeCtxt.cursor.getLink()
                link = new hs.address.Address(link)
                now merge the master document's remaining infile addresses _before_ this link's addresses
                merge the master document's viewspecs _before_ this links viewspecs
                call link.resolve(handler, true, doc)
                simply return - we are done, since the indirect link now takes over recursively
                hs.address.StringPosition.apply - -2w
                doc.nodeCtxt.cursor.jumpWord(-2)
                hs.addressStringSearch.apply - "foo"
                make a hs.util.NodeWalker starting at doc.nodeCtxt
                new hs.util.NodeWalker(doc.nodeCtxt)
                turn our address into a regular expression
                this.toRegularExpression()
                walk the tree, applying our expression at every node
                while walker.hasNext()
                walker.next().test(regExp)
            if sequence generators are on (doc.currentViewspecs.runSequenceGenerators()), then run the hs.filter.Transcluder
              hs.filter.Transcluder.apply(doc)
                hs.filter.Transcluder uses XPath to find all OPML nodes with 'type=include'
                for each matching node
                extract the transclude type (custom attribute hs:include-type)
                extract the hs.address.Address
                merge our current document's viewspecs _before_ the include link's viewspecs
                address.resolve() is called so as to not replace the current page
                include.resolve(handler, false, doc)
                when address resolver is done and calls our callback
                we take the HTML returned and simply write it into the data for this OPML node
                currentNode.domNode.data = includedDoc.render()
            apply viewspecs
              consolidate our viewspecs
                doc.currentViewspecs = new hs.filter.CurrentViewspecs(doc.expandedLocation.viewspecs, doc)
              apply the viewspecs
                doc.currentViewspecs.apply(doc)
                inside hs.filter.CurrentViewspecs.apply
                hs.filter.CurrentViewspecs uses its boolean methods, such as showBlankLines(), to set corresponding custom attributes on the OPML root node, such as hs-internal : show-blank-lines="true". These will be used in the rendering phase with XSLT to control output
          if content filters are to be shown, apply them
            address.contentFilter.apply
              write hs-internal : content-filtering-type to root OPML node, used to control j and k filtering types
              turn our content filter address into a regular expression
              create a hs.util.NodeWalker starting at the node after the current document's context node
              test each node for passing
              if it passes, write out the custom attribute hs-internal : passes-content-filter to this hs.model.Node; this is used in the rendering phase to eliminate other nodes
          render document into HTML
            doc.render()
              applies XSLT script, render.xslt, to OPML DOM
                inside render.xslt
                draws viewspecs, content filters, OPML data, etc.
                write's out class names to root HTML div element which we can use to toggle different visual things, such as the class .show-signatures to show signatures
                writes out class info for each node's level, for such things as correct indenting, for example
                do a final hs.util.NodeWalker pass to apply line clipping (if on)
                for each node, render its data offscreen to determine its line height
                scale div's height appropriately, using computed line height and setting this hs.model.Node's domNode style manually
    Display our rendered hs.model.Document's rendered HTML in the UI
      document.write our hs.model.Document's rendered HTML string into our display iframe
    Back to Overview: <Overview:gwnBy>
  File Format
    Back to Overview: <Overview:gwnBy>
    Our native file format is OPML 2.0, documented at http://www.opml.org/2006/03/04#a278
    OPML is a simple XML-based file format the has existed for several years, and which can model an outline document with HTML and hyperlinks mixed into the outline nodes. It was created by Dave Weiner, author of RSS and XML-RPC, two successful standards.
    OPML is very easy to work with using XPath, XSLT, and the DOM, and is simple and easy.
    Public Markup
      We add a number of custom attributes and tags to OPML 2.0 that are specific to HyperScope; these are all in the namespace http://www.hyperscope.org/hyperscope/opml/public/2006/05/09, usually preceded with the namespace identifier "hs:", such as "hs:nid"
        Custom tags added to the opml:head section
          hs:left-label-delim
            Possible Values: char | the string "null"
          hs:right-label-delim
            Possible Values: char | the string "null"
          hs:markers and hs:marker
            Possible Values: (see-- 0658)
        Custom attributes inside opml : body area
          hs:nid
          hs:createdBy
          hs:createdOn
          hs:lastEditedBy
          hs:lastEditedOn
          hs:transcluded
            Note: Whether this node had an INCLUDE in it, and it's contents were replaced with the remote include's contents
          hs:left-label-delim
          hs:right-label-delim
          hs:label
          hs:include-type
    Include Links
      We will use OPML 2.0s 'include' link type for include links. The 'text' attribute must be empty.
      We will add one custom attribute: hs:include-type, which can be of three values: branch, plex, node
        If this attribute is left off, it defaults to node.
      See http://www.opml.org/spec2#inclusion for details on how OPML 2.0 inclusion works and is specified.
      Server-side transforms will need to convert Augment include links into this OPML type (type=inclusion)
    Embedded Links
      Augment-style links must be fully transformed when they reach the client-side.
      The Augment server-side transformer must change the following Augment-style links into their full HTML style:
        <link>
        [link]
        (link)
        (see--)
          Note: Anything that begins with a word, and is followed by --, is ignored when surrounded by parentheses
      These must be transformed into embedded HTML links, with their Augment style delimiters left:
        &lt;link&gt;</a>
    Markers
      We need to support Augment markers in OPML.
      This is done simply by using embedded A NAME anchors in our HTML:
        f</a>
      These embedded links must be generated by the server-side transformers, surrounding the letter that was marked.
    Private Markup
      We also have a number of private attributes that are added to the OPML DOM during Location resolution, specifically on opml:outline elements; these are used in the final rendering and jumping phases to display a document. These values should never appear in public OPML documents. They are located in the namespace http://www.hyperscope.org/hyperscope/opml/private/2006/05/09, usually preceded with the namespace identifier "hs-internal:"
        hs-internal:number
        hs-internal:level
        hs-internal:passes-content-filter
        hs-internal:node-offset
          Note: This is this nodes offset from the top of the document, starting from 1. If you were to be viewing this document, for example, then this would be the ordering of nodes from top to bottom independent of hierarchy. This is used for implementing jumping back and forward from a given node.
        hs-internal:included
          Note: Added to any included nodes; value is "yes"
        hs-internal:include-failed
          Note: Added if an include failed on some node so we can highlight it differently; value will be "yes" if present
    Back to Overview: <Overview:gwnBy>
  Third-Party Libraries
    Back to Overview: <Overview:gwnBy>
    We will be using two open source libraries :
      The Dojo Toolkit - general DHTML framework
      Sarissa - Utility library for working with XML, XPath, and XSLT in a cross-browser manner
    Back to Overview: <Overview:gwnBy>