Sandbox Seven

Automatic Site-Map Construction Software

This is a functional specification for ASMC software.

Overview: ASMC software can automatically generate a site-map from the Up One Level links. There are a few auxiliary data structures involved, and they would occasionally have to be modified. Automatic generation can help debug the Up One Link structures. Nevertheless, inserting Up One Level links for new pages and then manually updating the site map is simple and has to be done rather infrequently. There are three problems with ASMC. First, more sub-pages than currently exist need to be defined. Second, some existing Up Level Links need to be re-pointed. Third, the ASMCS needs to be written, or, at least, existing ASMC software needs to be modified to fit into the KGS help-editor tools. Automatic generation would be nice to have, but, is it worth the effort required to implement it?

Idea: The site map structure is defined by the existence of Up One Level links in pages that are to be included in the site map. Pages linked to by the Up One Level links are also included. The title of the XTML code provides the names of the nodes in the site map. These are the same titles that appear in browser tabs (at least in the Firefox browser). There is a PrimaryRootAddresses help-file that lists the addresses of the help-pages that are roots of the disjoint trees in the site-map structure. To add a help-page to the site-map, all the help-page editor has to do is add an Up One Level link in that page. If the Up One Level target page is not already in the site-map, it will be added to the site-map, its address will be added to the PRA, and its name will be added to the DisplayedRootNames help-file. The DRN controls the format of the site map display. The DRN lists the names of the nodes that appear in the top level of the site map dispay and specifies the order in which they appear. The names of the pages in the PRA are included in the DRN. There is a separate help-file that specifies the names and the addresses of the *.jsp files that are to be included in the site map and how they are to be linked in. In other words, the *jsp files are manually linked into the site map, for all intents and purposes.

Inputs
- Up One Level links that define the structure of the site map. Every page and every sub-page must contain one and only one up one level link, if that page is intended to be included in the site map. An Up One Level link can be in a comment - in the special syntax defined below.
- PrimaryRootAddresses - PRA: List of the nodes of the primary trees in the site-map structure. For example, in the above site map, this list would be
  - Welcome to KGS
  - Main KGS Window
  - Main CGoban Window
  Up One Level links in the PRA pages are ignored by the ASMC software.
- DisplayedRootNames - DRN: List of tree and sub-tree names whose roots are to appear in the top level of the site-map display. The names of the root nodes are displayed in the order given in the list.
- These two lists can be given as one (structured) list if desired.
- Sub-page definition language given in comment blocks. For example,
  - ASMC START SUBPAGE {node name, nodelinkname}
  - ASMC UP ONE LEVEL LINK {pointer (URL) of target page - can contain a # suffix - i.e., can be a link to the interior of a page}
  - ASMC END SUBPAGE {node name}
  There needs to be a <a href=name"nodelinkname;"></a> statement inside the sub-page for the Up One Level links to point to.
- HiddenNodes - A list of nodes in the DRN that are not to be displayed. This would include Help Editor Resources.
- Definition file for *.jsp file site map linkages.
Outputs
- A site map display - the SMD.
- Updated PRA and DRN lists containing the root names of any trees discovered by the DSM construction S/W.
- An updated version of the previous site map.
- A list of orphaned pages. (pages in the /help directory that are linked to from the site map but do not have an Up One Level Link, except for pages in the PRA data structure)
Functions
- Build a collection of trees that define the site map structure.
  - The page titles in the XHTML code provide the node names.
  - For subpages, the node names are given in the syntax.
  - If a subpage contains an Up One Level link that links to the page the containing the subpage,
  - Put the root names of any isolated trees at the end of the updated PRN and at the end of the updated DRN
- Display the site map.
Implementation Notes
- In these notes the term "site map" refers to the tree structure of the site map only, not the structure of the displayed site map.
- Search through all the XHTML code looking for Up One Level links in the standard syntax for Up One Level links.
  - Ignore pages with no Up One Level links.
  - Ignore Up One Level links in pages in the PRA
  - Ignore Up One Level links in comment blocks and in sub-pages
- Repeat the Up One Level link search for sub-pages (Iterate).
- If an Up One Level link points to the interior of a page (or sub-page) link the name of that page (or sub-page) in the site-map.
- Move any help-page editor changes to from the previous SMD into a copy of the old site map. Updated with any new uplinks that are found during the Up One Level link search.
- Check that there is at least one downlink for every Up One Level link
- Check for broken links.
- Error Messages
  - More than one Up One Level link in a page (or in a subpage)
  - Invalid Up One Level link URL.
  - No downlink associated with an Up One Level link
  - Broken link
- Display the site map.
  - If the target of the Up Level Link for a sub-page is the top of the page, then no link is given for that node corresponding to that sub-page. An example is the General Information sub-page of the Newbie FAQ. That sub-page needs to be defined when the DSMC is available, and the Up One Level links to it need to be modified to point to #generalinformation and not to #generalquestions.
  - New Topic: Determining an intuitively natural order in which to display the nodes in the sub-levels is a potentially difficult problem.
  - One possible solution is to demand that every Up One Level link target appear in the Related Links section of the target page, and then use the Related Links order. This encourages the help-page editor to order the related links in a natural fashion.
  - For sub-pages, the order could be the same as the order that the links appear in the sub-page. This is reasonable because sub-pages normally have a lot fewer links than pages.
  - This solution generates an error message if an Up Level Link target is not in a Related Links section. This error messages ensures that the user remembers to think about exactly where a new page is to inserted in the site map. This helps preserve an intuitively natural site-map structure.
- *.jsp files are treated as a special case.
- The PRA and DRN files should be available for modification for by the help-page editors. Perhaps editable helpfiles (similar to "toc.html") could be created to hold these files.
- The ASMC software should not execute when the input files are being edited.
- The file content search mechanism and other components of the current KGS List All Files software are potentially useful in building ASMC software.
Summary
- Adequate ASMC is complex and probably not desirable.
- If any of the above functional requirements are deleted, the ASMC is less user-friendly. Their absence causes behavior that makes the user think that their bug in the software.
- Some of the implementation notes contain functional requirements.
- Therefore, most of the complexity in the above functional specification is desirable.
- Using the ASMC causes the user to be less familiar with the site map structure. This makes it more difficult to recover when something unexpected happens.
- The ASMC saves the help-page editor (the user) more time than it costs, but there is also a cost to using it. Although the need is infrequent, there are the PRA and DRN data structures to be maintained, and there are more sub-pages to deal with.

Edit this page (requires admin or translator privilege)