23 Jun 1995 - Preliminary Information
This section will explain:
Object content, properties, and links
SpHyDir converts the document to a sequence of objects. Each object has three attributes: content, properties, and links.
For convenience, it is also possible to doubleclick other objects that have Headings, Titles, or Captions. This opens a dialog box that allows the heading to be changed. For example, doubleclicking the point in a Definition List allows the defined term to be edited. Although the Heading, Title, Caption, or Term can be opened as if it was contents, these features are really Properties and can also be viewed that way.
If the user doubleclicks a Property line in the Properties Table, a dialog box appears that allows the value to be changed. Selecting a property and clicking the Second Mouse Button pops up a list of the common values that the Property can take (if it is associated with a list of alternatives). The doubleclick dialog box allows a property to be set to values that are not in the popup list if the user is familiar with extended syntax.
Clicking with the Second Mouse Button in the unused part of the Properties Table pops up a list of Properties that are valid for the object. At this time, SpHyDir does not allow the user to add Property names to an Object, so if SpHyDir doesn't support an HTML attribute, send a note to the author .
The SpHyDir user interface has been modelled on the native behavior of the OS/2 Workplace. A document object can be deleted by dropping it on the OS/2 Shredder. Clicking the Second Mouse Button generates a Popup menu of operations on the object. However, SpHyDir document objects are not files, so they cannot be printed by dropping them on a printer, nor can they be moved to a folder.
Although SpHyDir is a big Rexx program, through the magic of the Watcom VX-Rexx Development Environment is it packaged as SPHYDIR.EXE. It can be placed in any program library. The VX-Rexx runtime module VROBJ.DLL must be located somewhere in the LIBPATH, but there are so many VX-Rexx programs in use that this step may have already been performed.
SpHyDir is distributed with a number of useful freeware utilities. The GBM package from IBM can be used to view and convert bitmaps files. The RCS package can be used to maintain a log of changes to the HTML files. Neither is required for SpHyDir to work, but they are helpful.
Make a copy of the production library of HTML files on the OS/2 machine that will be doing the editing. The PCLT library, which appears to be "http://pclt.cis.yale.edu/pclt/" to Web Browsers on the Internet, is "D:\HTTP\PCLT" on the NT machine that acts as the server. The "D:\HTTP" is configured to the server program as the starting point for all HTTP file references. The OS/2 machine on which the files are prepared stores a copy of the files in "F:\HTTP\PCLT" and establishes "F:\HTTP" as the "HTML Library" for SpHyDir editing. This is also configured to GOSERVE as the starting point for HTML service. Files are edited and tested on the OS/2 machine, then transferred to the production server.
The SpHyDir library can be specified with the SET HTMLLIB environment variable. Otherwise, it will be taken as the active directory when SpHyDir starts. SpHyDir can be configured to operate on several different file structures by creating several SpHyDir program objects, each with a different initial current directory.
SpHyDir remembers parameters such as window size and location in the file SPHYDIR.INI in the root directory of the library. Therefore, if there are several SpHyDir program objects with several directories, each will have its own version of the saved parameters.
There are three ways to start SpHyDir on an existing HTML file.
If the SpHyDir Workarea is open and is either empty or the previous file can now be discarded, then drag the WPS icon of the file over and drop it in the whitespace of the workarea (not on any individual icon or caption). SpHyDir will abandon any old file and will read in the new HTML.
If SpHyDir is not running, but a WPS Program Object has been constructed for it, then drop any WPS Icon for an HTML file on the SpHyDir program icon. SpHyDir will start up and read in the file.
It is possible to associate a Program Object for SpHyDir with files of the type *.HTM or *.HTML. Then SpHyDir will be automatically launched when any such file is opened. However, this is not always the right thing. Sometimes it is useful to launch Web Explorer to view the file after it has been formatted. It is also sometimes useful to read HTML files into the System Editor and few the raw tags. So SpHyDir is not the only tool that can be used to view such files.
There is also one common practice that will not work. The File pulldown menu does not have an Open option. This is a personal choice of the author and may be regarded as part of the program design. Choosing a file by name from the standard file dialog is a lot less attractive than drag and drop from the Workplace folders.
Drag the first tool (the one that looks like a book) from the upper left corner of the toolbar and drop it on the whitespace of the Workarea. SpHyDir clears the workarea to start a new document. A window pops up asking for the filename. Type the name as though it were a part of a URL. For example, type "sphydir/sample.htm" to create a new file in the "sphydir" subdirectory of the current library.
In the Workarea, the document is represented by icons. The text is displayed to the right of the paragraph icons as a "caption". OS/2 allows captions to be edited, but this doesn't provide a very nice environment. It is much simpler to "Open" the paragraph by doubleclicking on the icon or on the caption.
Opening the paragraph displays the Text Edit window. The paragraph text is loaded into a Multiline Edit control. Words wrap automatically to the next line. A very large paragraph will activate the vertical scroll bars. Within the Text Edit window, the text is just ordinary ASCII data. It can be Cut or Copied to the OS/2 Clipboard, and characters from other programs can be pasted into the paragraph. All the usual rules about selecting text and using special keys like Del and End hold within the Text Edit window.
Although word processors and the EPM editor can display text in multiple fonts and colors, a simple Multiline Edit control can use only one font. This is not a terribly serious problem, because HTML overpowers the ability of any WYSIWYG editor. Although it is fairly simple to do italics and bold, how can any simple editor distinguish formats labelled EM, STRONG, CODE, SAMP, KBD, VAR, CITE, DFN, PERSON, ACRONYM, ABBREV, BIG, and SMALL. These are the resonable named forms of character emphasis. HTML 3.0 threatens to add another dozen even more obscure types of character tagging.
Special functions are represented in the Text Edit window by special "dingbat" characters that are not part of any standard Web character set. There are four of these dingbat functions:
When a file or URL is linked to a "hotword" through the Link Manager, a pair of inward pointing triangle characters bracket the link. If SpHyDir could make the triangles Read-Only it would. Editing or deleting these characters can cause trouble, because the URL for the link is stored separately. To remove a link, display the Link Manager window, select the URL for the link, and delete it. However, if the two triangles are left alone, the text in the middle can be changed to alter the hotword phrase.
Character emphasis, and for that matter, any unrecognized tags in the original HTML, are embedded in the text. Because the "<" and ">" characters are presented as normal text, they must be replaced with dingbat characters. Thus "<CITE>Debt of Honor</CITE> by <PERSON>Tom Clancy</PERSON>" is going to appear pretty much as seen here, except that each "<" will be replaced by an upward pointing triangle and every ">" will be replaced by one that ponts down. The simplest way to apply character emphasis is to select text with the mouse and then use the "Emphasis" menu in the Text Edit window to generate the appropriate tag. Unlike the previous case of hotwords, character emphasis has no special structural significance. These tags can be edited to change the type of emphasis or the tag can be deleted entirely.
HTML defines named sets of foreign, math, and special use characters. In HTML, such a character is referenced by an Entity. An Entity reference starts with "&" and then continues with the name of the character. A semicolon delimits the end of the Entity if it is immediately followed by normal characters. For example, the copyright symbol © is represented as "©". SpHyDir wants to allow users to type the "&" character as needed, so when the HTML is read in the "&" is replaced by the special PC character that looks like a "smiley face" and has the numeric value 1. As with all special PC characters, it can be generated from the keyboard by holding down the Alt key and typing the number on the keypad. So to generate a copyright character, hold down Alt, press 1, release Alt. A smiley-face now appears on the screen. Type "copy;". When the paragraph is written out as HTML, the smiley-face will be turned into an "&" and the browsers will display the Entity correctly.
Small Images can be embedded in the middle of text. Normally this is used for icons. SpHyDir represents this with a dingbat that looks like a box with a circle in the middle, something like "[o]". To generate such a reference, hold down Alt, press "8" on the numeric pad, release Alt. Now type the file name of the icon/image. Optionally type a space and then alternate text. End by repeating the Alt "8" sequence.
All other information is a property of the object and appears in the properties table at the top right corner of the workarea. Each property has a name and current value. Properties are either character strings, numbers, or choices. To edit a string or number property, hold the ALT-key and click on the old value. When a property must have a value from a list, it may be faster to click on the property with the second mouse button. The list of available values will then popup as a menu and a new value can be selected.
The WPS approach is to drag the object to the desktop Shredder. The keyboard approach is to select the object and press Ctrl-D. The Mouse approach selects the object, presses the second mouse button to popup the menu, and selects "Delete to Clipboard".
It would be reasonable to expect the Del key to delete things. Unfortunately, Del is a character delete key and is used to correct mistyping in other windows. It is difficult to know exactly which window has the focus. A few bad experiences where an attempt to correct a mistyping accidentally deleted whole sections of a document suggested that Del was simply too dangerous as the Object Delete key.
The Delete operation applies to everything contained within the selected object. Delete a list and all the points and paragraphs are also deleted.
A user complained that the Second Mouse Button menu made it too easy to delete objects. To address this problem, a previous simple delete was converted to "Delete to Clipboard". As explained elsewhere, SpHyDir maintains a special Clipboard-like window that is able to hold the special document objects. Delete to Clipboard makes a copy of the objects in the clipboard window and deletes them from the Workarea. If a mistake was made, they can be restored by selecting a location and pressing Shift-Ins.
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.
Objects can also be inserted by pressing the Second Mouse Button and choosing Insert from the popup menu. The menu includes the most commonly used objects (paragraphs, points, and lists) and some less common objects for which there was no room in the toolbar.
When the paragraph tool is dropped, the Text Edit Window opens and you may type text. You can also paste text from the Clipboard. At the bottom of the Text Edit Window there are buttons. One is labelled "New". Pressing the New button saves the current text in the current paragraph and creates a new empty paragraph into which the next information can be typed.
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.
To create a hypertext link to another file in the HTML library, open the WPS folder to display the file object. Hold down Ctrl-Shift and drag the file as if you were going to make a shadow of it on the desktop. Drop the icon on a Paragraph or Image object.
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, 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 funny triangle characters or SpHyDir will get confused.
SpHyDir has a Link Manager in the list of Windows to handle other types of links. When the Link Manager window is visible, the top list box displays the URLs of links from the currently selected Workarea document object. The lower list box can be used to select other links. There are two buttons on the bottom. Pressing the button with a Web Explorer icon displays all the items in the current Web Explorer hotlist. Pressing the Target button displays all the target labels in the current document tree. Select an element from the list, drag and drop it to a paragraph or image in the workarea.
The Web Explorer will also produce URL objects in the Workplace. Dropping a WE URL object onto a Workplace Object will also create a link to the referenced object.
SpHyDir provides XSpO programs to form links. An eXternal Sphydir Object is a Rexx program that can be dropped on SpHyDir windows. XSpO's provide a way for Rexx-literate users to customize or extend SpHyDir without mucking in the source. One XSpO can be dropped on the lower Link Manager list box and duplicates the function of the Web Explorer button. It can be used as a model for programs that extract hotlists from other sources. Another XSpO is dropped on a Paragraph or Image. It searches through the windows on the destop to find Web Explorer and extracts the URL of the current document that WE is displaying. This provides a shortcut compared with creating a WE URL object and then dropping it on the SpHyDir workarea. Another XSpO shows how to generate a "Mailto" link.
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.
You can drag an individual paragraph around, but only within the visible window. To move more data, to move a greater distance, or to move between files, there is special support to mark a range of objects, copy them to a "clipboard" and paste them somewhere else.
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.
Copyright 1995 PCLT -- SpHyDir Web Document Manager -- H. Gilbert
May be distributed with SpHyDir program
This document generated by SpHyDir, another fine product of PC Lube and Tune.
Continue
Back
PCLT