7 Feb 1995 - Preliminary Information

SpHyDir is designed to behave like the OS/2 Workplace, and to interact with it. However, SpHyDir is an ordinary application program written in VX-Rexx, not a DLL written to extend the Workplace environment. SpHyDir objects are created while the application is running and they disappear when the program ends. They cannot be dragged out of the SpHyDir windows to the desktop (except to the "Shredder" which signals SpHyDir to delete them).

SpHyDir doesn't have a File menu or an Open dialog. When you need to select a file, you open the usual Drives, Disks, Folders, and drag the file over and drop it in the workarea.

The OS/2 Workplace Shell folders that contain files and other folders. This view stops at the individual file. Normally when you open a file you run the system editor, a word processor, or a spreadsheet. However, when an HTML file is dragged over and dropped on the open SpHyDir workarea window, it opens up and presents a tree of document elements. This gives the impression that the HTML File was itself some kind of Folder that contained internal components.

The document is presented as an ordered sequence of components organized in a logical tree. There are different icons for each type of component: Sections, Paragraphs, Images, Numbered and Unnumbered Lists, Preformatted Example, and so on. The tree structure reflects the view that some components "contain" other components. For example, a chapter or section contains all the other elements that fall within a particular topic. Each list contains a sequence of points.

SpHyDir was influenced by some of the discussion about compound documents and OpenDoc. OpenDoc views a document as a collection of component parts. There are text parts, image parts, table parts, and so on. At first it seemed that OpenDoc technology would be the right tool to use. However, OpenDoc assumes that each part can be precisely positioned in two dimensions on the viewing area. Web documents, however, have to be filtered through HTML which only allows the linear definition of the document as an ordered sequence of components.

The SpHyDir presentation of the document as an ordered, but structured, sequence of component objects seems to be the best compromise between HTML constraints and modern object-oriented compound document thinking. Making the object behavior consistent with the OS/2 Workplace, and then interacting with real Workplace objects, simplifies the user interface.

If you begin by expecting every document element (every paragraph, image, list, or point) to act like a Workplace file, then you have a fairly good starting view of how to use SpHyDir. The only complex point is positioning new elements in the tree, since OS/2 objects don't have an order.

How do I edit an HTML document?

Drag the *.HTM file object over from a WPS folder and drop it on the workarea window. SpHyDir opens the file, parses the HTML, and builds the tree representing the document structure. After a small amount of experimentation, it appears to be least confusing if there is only one document in the workarea at a time. Therefore, dropping a second HTML file onto the workarea will popup a message asking for permission to save or discard the previous file before loading the new one.

How do I make changes?

The text in a paragraph, list point, or definition is treated like the "contents" of the document object. Double-click on the paragraph or point object and it appears to "open", presenting the Text Edit window in which changes can be typed. To speed things up, the text edit window also has buttons to go forward to the next paragraph, back to the previous one, and to insert a new paragraph after the current one and begin editing it. Section titles, the alternate text of images, and the term being defined in a definition list are treated as if they were object Names (like the file name under a Workplace file icon). In some cases you can use WPS file renaming conventions (point to a Section title, hold down Alt while clicking on the text, then change the text in place and click somewhere else at the end). However, is rather awkward in practice. There is an entry area at the top right of the workarea window. It can be used to edit the "name" of the currently selected document element in the tree below.

How do I enter special characters?

HTML uses three rather ordinary ASCII characters ("&", "<", and ">") to delimit control features. Typing ordinary text like "PC Lube & Tune" or "A<B" in HTML can be awkward. SpHyDir translates the special character sequences back to ordinary text, then generates the HTML when the final file is required. During editing, any remaining control functions are displayed on the screen using special PC-only characters that are not part of normal ASCII or HTML and cannot cause confusion. To add a line break, simply hit Return in the middle of the paragraph.

How do I delete objects?

Drag the object to the WPS shredder. Alternately, select the object and press Ctrl-D.

How do I add new elements to the document?

At the top left of the workarea window there are a set of icons alternately viewed as the "Toolbar" and as "Templates". They act to the document much like the OS/2 Template folder acts to the rest of the workplace. Drag the icon for a Section, Paragraph, Image, List, or other tool and drop it where you want the new element to go. This creates an empty element that needs to be filled in.

• When the paragraph tool is dropped, the edit window opens and you may type text. You can also paste text from the Clipboard. There is currently no way to drag-drop an ASCII file on a paragraph to add text.
• When the image tool is dropped, it creates an empty Image object. Drag a GIF file over from one of the OS/2 disk folders and drop it on the object to assign a file. Add alternate text in the entry field at the top of the workarea. Pushbuttons allow you to select the alignment of the image with any trailing text.

How do I create links to other files?

To create a hypertext link to a file in the local library, open the Workplace folder containing the target file. Now hold Ctrl-Shift down and drag the icon of the file over and drop it on the paragraph, point, or image from which the link is to be made. If you drop on an image, then there is no further work. Images can have only one hypertext link and the entire image is the link. If you drop on a paragraph or point, then the Hotword Selection window opens displaying the available text. Drag the mouse to "select" the word or phrase that will represent the link. Click the OK button. Hotwords are delimited in the text by an opening and closing triangle character. You may change the contents of the hotword area, but do not delete the delimiter characters or SpHyDir will get confused.

How do I save the file and quit?

When the workarea has the input focus, press F2 to generate HTML and continue editing, F3 to quit without generating, and F4 to generate HTML and then quit. The status message at the bottom of the window will indicate that HTML is being generated and then has been written. If you press F2 and nothing happens, then click once on the workarea to make sure it has the focus. If you try to quit and have modified the file in the Workarea, a message will pop up asking whether you want to Generate or Discard the file. SpHyDir is very reluctant to use the term "Save" for HTML files because it implies that if you read a file in and then save it out you will end up with the same data that you started with. If the file was generated originally with another HTML editor, it may contain constructs that SpHyDir will ignore or reorganize. Therefore, SpHyDir talks about Generating HTML out of its structural representation of the file. Generally, however, once a file has been through the initial SpHyDir conversion, what comes out the second time will be pretty much exactly what went in (except for edit changes and boilerplate like inserting a current date).

How do I move paragraphs around?

Given all the previous points, you might think that you select the paragraphs or points that you want to move and then just drag them to another part of the file. There are problems with this view. A purely technical limitation of a VX-Rexx container in Tree-Name mode is that you can only select one object at a time. This technical restriction has a logical foundation. When objects have a tree structure, there have to be some limitations on how they are selected. For example, selecting the start of an ordered list without selecting all the points would leave some objects with a type of "List Point" behind. Yet Points are not allowed to exist on their own outside a list. So selection has to be controlled by the program's view of logical consistency. The last problem is that VX-Rexx 2.1B has important bugs moving trees around inside a container.

SpHyDir wants to create the image of selecting a range of objects, moving them around, copying them to the clipboard, and pasting them back into the file. However, the native support for selection, movement, and the real OS/2 clipboard are not able to handle this problem correctly. Reluctantly, SpHyDir has been forced to reinvent some of this infrastructure.

The user can select a range of objects to move within a document or to copy to another document. First select one object and press Alt-L as if you were establishing a "line mark" in the EPM or Kedit editors. Once you begin to mark a section of the document, you may extend the marked area forward or backward, but only within the current level of the document tree. The mark can be extended over but not into lists or subsections. Nor can the start or end of the mark be extended outside the section or list in which it is started.

Marking creates two new objects: Mark Start and Mark End. Initially these objects are placed around the currently selected object when Alt-L is pressed. The Mark objects can then be "slid" forward or backward along the line that represents the current level of the tree. They cannot be slid into a subsection or list (to a lower level) nor can they be slid outside the section or list in which they started. The Mark can also be automatically adjusted by selecting another object at the same level of the tree and pressing Alt-L again (expanding the scope of the Mark just as additional lines are added in the EPM editor when you move to another line and press Alt-L a second time).

Once a section has been marked, you can copy it to the Clipboard by pressing Ctrl-Ins (the standard OS/2 keyboard sequence for Copy). However, the OS/2 Clipboard really doesn't know how to hold SpHyDir objects, so the same effect is achieved by opening a new Window and copying all of the objects between the two marks (including all the objects contained in subsections and lists) from the workarea window to a second container that SpHyDir calls "The Clipboard". In the current release, the Clipboard window becomes visible (for debugging) though it can be minimized or can be dragged over to the side of the desktop.

The objects in the Clipboard can then be moved to another part of the original document by selecting a destination object and pressing Shift-Ins (the OS/2 standard for Paste). They can be copied to another file by dragging another HTM file to the workarea (replacing the original source document) and then pasting from the Clipboard to a second document.

However, Clipboard objects cannot be copied to another part of the same document. This fell out from the way the Clipboard got coded and, at the moment, it seems to be a useful feature. When the user marks objects and presses Ctrl-Ins, there were two programming choices. One choice copies all of the objects to the Clipboard. The alternative creates what is essentially a Shadow of the original record in the clipboard (what VX-Rexx calls a "shared record"). Like the Workplace shadow, the two objects are actually different views of the same data. If you were to edit the text of a paragraph after copying it to the SpHyDir Clipboard, the text of the Clipboard copy would also change. However, while a Workplace shadow cannot exist when the original is deleted, a VX-REXX shared record continues to exist until all of its related objects have been deleted. Thus the Clipboard copy of the data continues to exist after the original object in the workarea has been deleted or the entire document has been replaced.

A shared record can exist in two different containers, but there can be only one copy of the record per container. By choosing to use Shadows in the Clipboard instead of full copies, SpHyDir does not support duplicating large blocks of text within the same Hypertext document.

When you select another location and press Ctrl-Ins, the SpHyDir Paste tries to copy the shared record from the Clipboard back to the original document. However, since there is already a copy of the record in the workarea and no container can have two copies of the same record, the Paste operation actually moves the old record from its previous location to the new position. If you delete the document in the workarea and load a new document (even a new copy of the original document) then a new set of records are created. Now the Clipboard has the only copy of the old records and Paste copies the information into the new document.

I am a bit suspicious of any feature that takes this much time to explain. On the other hand, a hypertext document should be short and it doesn't make a lot of sense to duplicate large blocks of text within such a file. There is a strong sense that the way this Mark and Clipboard logic works is probably the Right Way to handle this particular problem with this particular set of data. Only by gaining experience with this technique will it become clear if this is really the best approach.

Note that the SpHyDir specialized Clipboard, Cut, and Paste apply only to the management of objects from the Workarea. Within the Text Edit window opened by double-clicking a paragraph or point, the behavior of text selection, Cut, Copy, and Paste is completely normal and operates through the normal OS/2 clipboard. Text data can be exchanged between another OS/2 program and the Text Edit window through the ordinary cut and paste mechanisms.

At the top of the Workarea there are a collection of icons that represent the Toolbar (or Template) area. These items can be dragged into the document to create new elements. In some cases, the tool can also be double-clicked to open a secondary window. The tools are arranged in six columns of two rows. They will be discussed in the order:
1 3 5 7 9 11
2 4 6 8 10 12

1. The book icon introduces a document. Normally, a document is created in the workarea by dragging in an external HTML file. If the Toolbar Document tool is dropped on the workarea, this creates a new empty document (and prompts for a file name within the library). This tool will also be used to create Subdocuments (described later).
2. The notebook icon represents a Section. Sections correspond to document elements introduced by an H1...H6 HTML tag. Although SpHyDir recognizes these tags on input, it discards their original level number. When HTML is generated, the highest level section is given an H1 tag, then next level becomes H2, and so on. Sections have no explicit ending delimiter, so a section extends till the end of the document or until a new section of the same or a higher level is encountered or started.
3. The icon of a writing page represents a Paragraph item. Paragraphs contain ordinary text, formatting tags (bold, italics,etc.), and hypertext links to other files and documents keyed to hotword phrases.
4. The picture icon represents an Image object. After the tool has been used to create an empty Image object, drag and drop the Workplace object for a GIF file in the library to assign a file name. The entry area at the top of the workarea can be used to type alternate text that will be displayed when the remote user chooses not to load images. An Image object also presents a set of radio buttons to choose the alignment of the image with the text of the next paragraph. Choosing None means that the image will stand on its own. Top, Middle, and Bottom are standard HTML alignments. Left is an alignment option supported by Netscape.
5. An ordered list presents numbered points. Each point is similar to a paragraph.
6. An unordered lists contains unnumbered points, generally delimited by a "bullet" character.
7. A Definition List (represented by the dictionary icon) defines a set of terms.
8. The icon of a hand making a "point" represents the general list item. An item in a numbered or unnumbered list simply has text. An item in a Definition List also has the term or phrase being defined. This term can be entered in the Entry area at the top right of the workarea.
9. The Table of Contents (TOC) does not exist in normal HTML. There is limited support for it in the first release of SpHyDir. Double-clicking on the TOC tool brings up the Table of Contents window listing the headings of all Section objects in the document. When subdocuments are fully implemented, the TOC window will also list headers in the subdocuments and the TOC object will expand a standard Table of Contents listing with hyperlinks to all the subdocument sections in the composite document.
10. The Target object generates a permanent public hypertext target. Type a name (preferably without blanks) in the entry area at the top of the workarea. This name can then be used in hypertext links from other documents in the library. Although SpHyDir may generate internal targets for section headers (to make the TOC work), these names will change if the section is renamed. A Target object is only renamed if the user changes it, so it becomes a more reliable target for long term use.
11. The PRE-formatted text item is used to hold examples . Currently, SpHyDir doesn't allow Preformatted text to contain tags.
12. The Goto tool provides an interface to manage hyperlinks. Double-click on this icon to open the Link Manager window (described below).

There are other document elements that are not used frequently enough to warrant a place on the Toolbar. In particular, the Horizontal Rule <HR> tag is generated by positioning at a section or paragraph, holding Alt and pressing H. The line goes in front of the selected object.

SpHyDir would be simple if the VX-Rexx and OS/2 programming interface allowed the user to drop tools and components in between two existing document elements. This would clearly indicate where the new element is to go. However, the environment requires the tools, files, and other objects to be dropped on top of existing components. This forces SpHyDir to invent some rules about positioning.

A Target is a label for the thing that follows it. If you drop a Target on a paragraph or section, then it makes sense to assume that the Target should go in front of whatever you drop it on. When a hypertext reference is made to the target name, the following document component will be what shows up on the screen after the jump. You may not drop a Target on the Document object that is the first object in the tree, since there is no "before" to place the Target and because the start of the document doesn't need any label, the filename will do fine to identify it.

Sections and Lists contain things. In the Workplace, if you drop a file on the icon of a folder, the file goes into the folder. So the normal behavior is that if you drop anything (other than a Target) on a Section or a List, then the new element is added inside that Section or List in front of anything already there.

If you drop something on a Paragraph, Image, or Point then the new item goes after the thing you dropped it on. Thus to add a new Point to the end of an existing list, drop the Point tool on the last Point in the list. To add a new Point to the beginning of a list, drop the Point tool on the parent List object.

These rules seem to cover all but two cases. Lists can be nested inside other lists. When this occurs, there is no way to add a new outer point after the end of a nested inner list because every time you try to drop a point on the inner list icon the new point is positioned inside the inner list instead of after it in the outer list. Similarly, there is no way to add one section after another because whenever you drop something on a section it goes inside it and not behind it. So there is an extra rule that if you hold down Ctrl when dropping a Point on a List the Point goes after the list, and if you hold down Ctrl when dropping the Section tool on an existing Section, the new Section goes behind the current section. This is not entirely satisfactory. A section can go on for many screens, and it it somewhat unexpected to have to go many screens back to the start of a section in order to drop something on the section object and add it many screens down after the section end. I am waiting for a better idea to come to mind.

Originally, the idea would be that Ctrl-dropping a tool placed the tool after the thing on which you dropped it. That seemed like a good rule, but it doesn't work with Sections because you can't put a paragraph, image, or list after a Section. Sections don't end, you see, until a new Section begins (in HTML terms, a section ends when a new H1...H6 header is encountered). The only thing that you can put behind a section is another Section. Everything else that you try to put behind the section ends up inside it anyway.

Most of the other HTML editors provide very limited support for hyperlinks. Generally, one can link to another point in the document by selecting a bookmark, link to another file by running through the standard File Selection dialog, or manually type in a URL to a remote information source.

Because SpHyDir is programmable, and because it can be closely integrated into a particular operating system environment, it can provide better tools. Consider the Link Manager window which opens when the GO icon is double-clicked:

There is a button at the bottom of the window with the icon of the IBM Web Explorer. Click on this button and the list box fills with the current Quicklist from WE. The normal sequence, then is to use WE to search through the Web for an interesting document source. When it is found, add it to the Quicklist. Then click the button in the SpHyDir Link Manager and the URL is automatically displayed in the list of selectable links. Drag any item from the list over and drop it on a paragraph, image, or point. It establishes a hypertext link from the image, or opens the Hotword Selection window to select the word or phrase in the text of the paragraph or point from which the link is to be made.

The top of the Link Manager window lists hyperlinks out of the currently selected document element in the main workarea window. In the workarea, hotwords are delimited by two special triangle characters. The Link Manager window shows the URL or file name of the links in the order that the hotwords appear in the paragraph or point. To delete a hotword link, select the URL in the Link Manager window list and press Ctrl-D. This will remove the triangle characters from the hotwords in the text. It is an error to delete the triangle characters in the text, because SpHyDir uses them to correlate hotwords to URLs.

Most HTML editor tools operate on a single text file. However, good practice holds that hypertext documents should be divided into a large number of small files. Managing all these files and maintaining a consistent overall structure then becomes a serious problem.

PC Lube and Tune has developed into a library structure that seems generally applicable. Because no one application can assume to own the entire server, the files fall under a common starting directory. During development, this is x:\PCLT on the author's machine. In distribution, the same structure becomes http://pclt.cis.yale.edu/pclt/ on the server.

SpHyDir gets the local library name from the HTMLLIB environment variable. In this case, "SET HTMLLIB=F:\PCLT" is put in CONFIG.SYS. All of the HTML and GIF files that SpHyDir processes have to fall on this disk under this directory. SpHyDir is then programmed to moderate between the native OS/2 file naming conventions (with "\") and the more general file naming conventions used in most hypertext links (with "/"). In concept, it should be possible to move the entire structure from OS/2 to a Unix server. In practice, it is still necessary to do some thinking about whether file names are uppercase or lowercase. However, in the short term SpHyDir files will certainly work correctly on an OS/2 or NT server.

Subdocuments are not supported in the first release. In concept, a Subdocument is a document element that contains nothing but a hypertext link to another HTM file in the same directory or in a subdirectory. For example, Windows on the World becomes a complex document in which the starting point is WINWORLD/WINWORLD.HTM. It then contains subdocument links to the other files in the WINWORLD directory.

The next release of SpHyDir will, when it goes to generate HTML, also save some control information about the file in the OS/2 Extended Attributes of the resulting *.HTM file. These EA's will include the explicit Target object names, the Headers generated for all Section objects, the Subdocument links from this file to other files, and the status of a TOC object (if any). Minimally, if all the subdocuments have been previously processed and stored their EA's, then reprocessing the parent document should be able to generate a complete Table of Contents with hyperlinks to all of the subsections across all the files. Later on, it may be possible to update the parent TOC automatically when the structure of a subdocument is changed.

The current release of SpHyDir has limited support for the automatic insertion of Boilerplate. When a document is generate, SpHyDir searches the same directory for a HEADER.HTM and a TRAILER.HTM file. If the header is found, it is copied into the generated document after the BODY tag but before any other generated data. If the trailer is found it is copied at the end. The tag structure of the header and trailer is never examined in detail, so these files can contain obscure HTML conventions that SpHyDir would not understand or permit in the main body of the document. SpHyDir searches for special names enclosed in "[" and "]". It replaced "[Date]" with the current date, and "[Doctitle]" with the Title tag of the current document. Once subdocument structure is supported, the intent is to automatically generate substitutions for [Next], [Previous], and [Parent] documents.

Copyright 1995 PCLT -- SpHyDir Web Document Manager -- H. Gilbert

This document generated by SpHyDir another fine product of PC Lube and Tune.