19 Jun 1995 - Preliminary Information
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.
The Document Tool serves two functions. If it is dropped on the "whitespace" of the workarea, away from any existing document objects (or anywhere in an empty workarea), then this tool is treated as a request to start a new document. It replaces the more traditional New option on the File pulldown menu.
If there is an existing document in the Workarea, the user will be prompted whether it is alright to abandon that document. Pressing ESC returns to the previous document and cancels the request.
Otherwise, the Workarea is cleared and SpHyDir prompts for the name of the file. The name is relative to the start of the document library and it should be given with the "/" notation commonly used in Web documents. SpHyDir cannot force the user to act rationally, but it is generally a good idea to organize the local library with the same structure that documents have on the production server. Thus the document http://pclt.cis.yale.edu/pclt/sphydir/status.htm would have the name "pclt/sphydir/status.htm" on the editing machine, corresponding to the part of the URL that follows the server machine name.
The library on the editing machine may have some upper path components that are not visible. If HTMLLIB is set to "F:\HTTP" (or if there is no HTMLLIB variable and F:\HTTP is the current directory when SpHyDir starts) then this disk letter and upper directory will be inserted in front of the URL part to form the actual OS/2 file name.
After the file name has been supplied, the user is prompted for a Title. Whatever is entered becomes the initial caption of the Document object (used to set the <TITLE> tag in HTML) and of the first Section object (used to set the <H1> string). This seems to be redundant, but the two tags are used for different purposes in HTML. The <TITLE> describes the document (say in an index of the library). The <TITLE> text may not be displayed by some browsers, or it appears as the title bar of the window. The <H1> text appears in big letters.
SpHyDir doesn't go one step further and add an initial paragraph object. In some cases, the document might start with an IMG or other object instead. Drag the appropriate tool from the toolbar and drop it on the Section tool to start adding content.
Most of the Properties of the Document Object correspond to fields in the <HEAD> area of the HTML. This includes LINKs to other documents, and a BASE URL value. A few Properties are taken from HTML3/Netscape extensions to the <BODY> tag to assign a Background pattern and to control the color of text on top of that background.
If a GIF file is dropped on the Document Object of a file in the Workarea, that file name is set as the value of the Background property for the document.
If the Document tool is dropped on a previous document object, then it becomes a request to add a Subdocument link. Subdocument pointers are used to build a larger document out of many smaller Web files. A subdocument pointer to another file means that that file is a continuation of the current file. Any word or phrase can be hotlinked to another Web page. Ordinary hotlinks do not imply a relationship. Subdocument links indicate that the other file is a child belonging to the current Web page.
There are some rules to good document construction. SpHyDir chooses not to enforce them, but their proper use is highly recommended. Most importantly, a file should only be a subdocument of one other file. If two different parents try to claim the same file as a subdocument, things are going to get all messed up.
A Subdocument object can go anywhere, but best results will be obtained if all the Subdocument pointers are together at the end of a file.
Although it may be tempting to make everything a subdocument of the highest level index page, this produces a structure that is awkward to handle. The entire library should not be related pages. Restrict subdocument relationships to files that are really part of the same paper, article, subject, tutorial, or brochure. Use ordinary hyperlinks from the main page or library table of contents.
Drag the Document Tool over and drop it in the file as you would create a paragraph or point. The Subdocument definition is then completed by dragging the WPS icon for an HTM or HTML file over and dropping it on the newly created object. If the dropped file was previously processed by SpHyDir, the Title of that document can be extracted from the Extended Attributes of the file and will appear next to the Subdocument icon.
Within the current file, the Subdocument object behaves like a Paragraph whose entire contents is the TITLE of another HTML file and where that TITLE text is a hypertext link to the other file.
Every time SpHyDir loads a file with subdocument pointers, it checks each identified file to see what its current Title is. Title changes appear immediately in the caption of the Subdocument object and are written back when the parent document is regenerated.
The Subdocument structure is also stored as Extended Attributes of the files in the library. Each *.HTM or *.HTML file has pointers to the files that it claims as subdocuments and to its "parent" (a file that claims it as a subdocument). The order in which the Subdocument objects appear in the parent establishes a Next and Previous ordering to the sudocument HTML files, which SpHyDir maintains and can use to generate uniform Headers and Trailers.
Every ordinary paper document is organized into Chapters, Sections, and Subsections. That, after all, is what an Outline is all about. HTML has provision for Headings, but it is not all that clear about what exactly a Heading introduces.
HTML 3.0 addresses this by introducing a DIV tag. The concept is that large documents would be broken up into segments delimited by a <DIV CLASS=CHAPTER> or <DIV CLASS=APPENDIX> tag. However, these tags are not currently used. SpHyDir forms sections based on the appearance of an H1..H6 tag. Eventually, SpHyDir may automate the transition from HTML 2 to 3 and generate the DIV tags automatically.
SpHyDir will recognize a DIV tag when it is encountered, but there is no strong body of use to know what to do with it. The author would appreciate E-mail if any important use of DIV is discovered on the Net.
For it to be successful, SpHyDir has to determine where the Section ends. There is no explicit HTML marking, but it can reasonably assumed that the Section extends until there is a new Heading tag at the same or a higher logical level than the tag that started the Section. Lower level Headings are assumed to start subections of the current Section object.
The Properties of a Section Object come from the attributes of the H1..H6 headings tag in the HTML 3 proposed standard. This produces a small confusion. In all other document Objects that contain other objects, an attribute of the container applies to all the objects that it contains. However, attributes on a Section Object apply only to the Heading. For example, ALIGN=CENTER means that the Heading is centered and does not apply to the paragraphs in the Section.
The Paragraph Object contains text. In HTML, "text" is more broadly defined to contain ordinary characters, Entities, character emphasis tags (Bold, Italics, CITE, etc), hyperlink hotwords, line breaks, and embedded images.
SpHyDir is not currently prepared to break the paragraph down into any finer objects. So all this non-text "text" has to be encoded with special characters. The user can doubleclick a paragraph to display all the text in the Text Edit window. Special characters can be added to the document using the standard rule for special keyboard entry (hold down Alt, type a number in decimal notation on the numeric pad, and release the Alt key).
However, hotword links are only partially contained in the text. The rest of the hotword link is a URL that can be displayed in the Link Manager Window. Before deleting text containing a hotword, use Link Manager to delete the link and remove the inward pointing triangles.
Properties of the Paragraph Object are mostly derived from the attributes of the <P> tag in HTML 3.
The Image Tool represents a graphic insert. First, drag and drop the image tool to the location in the document where the image is logically positioned. Then finish the definition by dropping the WPS icon of a GIF file on top of the Image object. Currently SpHyDir requires the GIF data type (XBM and JPG may be added later). Since the IBM IPF system doesn't support GIF, generated IPF source uses the same file name and an extension of BMP. GIF files can be converted to BMP files using the GBM utilities or any of a number of other graphics programs.
HTML authors are reminded that there are still a number of disadvantaged users who try to surf the net using charcter mode Unix. To accomodate such people, an Image should have alternate text that describes the content or meaning of the image. This alternate text is entered as the value of the ALT Property. If an image has alternate text, it is displayed as the caption to the right of the icon for the object. Otherwise, the file name is the caption.
The Image Object was created by SpHyDir to provide an icon on which GIF files can be dropped and from which hyperlinks can be made. HTML doesn't really seem to regard Images as objects. Rather, HTML syntax seems to treat each image as an unusually large text character.
The SpHyDir Object will work if the image appears all by itself or at the beginning of a paragraph. If the image has to appear in the middle of a heading or paragraph text, then it cannot be promoted to full object status. SpHyDir calls such things embedded images. An embedded image is represented by a dingbat character corresponding to the value 0x08, followed by the name of the GIF file. Then optionally there is a blank and alternate text. The sequence ends with a second 0x08 dingbat. Embedded images have no properties, and the user cannot drop anything onto them. They can be part or all of a hotlink phrase.
When an image appears at the start of a paragraph, it could be rendered using the "inline image" syntax. However, SpHyDir extracts it from the paragraph an builds a separate object. The value of the ALIGN property for the Image Object determines how it will interact with the paragraph that follows it. ALIGN=NONE (a value made up by SpHyDir) displays the Image by itself. Other values of ALIGN position the following text to the right of the image, and in some cases the text flows around the image border.
HTML 3.0 introduces a FIG tag to extend the functions of the current IMG tag. Unfortunately, it is not widely supported and its use is currently not clear. A later version of SpHyDir may provide automatic migration of current IMG syntax to the preferred FIG syntax after it becomes a viable alternative.
An Ordered List Tool contains a sequence of numbered points. Although points are normally simple paragraphs, HTML allows a point to contain almost anything: paragraphs, images, even check boxes or radio buttons.
SpHyDir 1 tried to combine the functions of Points and paragraphs. This worked well 99% of the time. It caused trouble when the list item started with anything that wasn't ordinary text.
SpHyDir II views lists the way that the HTML standard views them. A list contains points. The points contain paragraphs. The paragraphs contain text.
HTML 3.0 allows a list to begin with a header. This is represented by a <LH>text</LH> sequence before the first point. Following the recommendation of the standard, SpHyDir takes any free text that is found in old HTML documents outside the list points and turns it into a list heading so it is legal.
The properties of an ordered list are taken from HTML 3.0. The properties allow a second list to resume numbers where a previous list left off. Netscape has some nifty ideas to control format, whether items are listed as 1 2 3, A B C, a b c, or i ii iii.
An unordered lists contains unnumbered points, generally delimited by a "bullet" character. Unordered lists follow the same rules as the previous discussion of Ordered Lists.
The properties of an Unordered list allow the bullet charcter to be replaced with another choice. The PLAIN attribute allows the bullet to be omitted entirely. SRC allows the bullet to be generated as a GIF image.
HTML has two obsolete list formats based on the <DIR> and <MENU> tag. SpHyDir will read such lists in, but will convert them to the preferred <UL COMPACT> tag.
A Definition List defines a set of terms. Each term is followed by an indented definition. In SpHyDir, the term is a Property of each point in the List. As with other lists, the Point then contains paragraphs that are the definition of the term.
With this structure, SpHyDir requires a propertly formed Definition list with alternating pairs of <DT> term <DD> definition.
The icon of a hand making a "point" represents the general list item. An Ordered, Unordered, or Definition List can contain only Points. Each point then contains paragraphs, images, and other document content objects. In an ordered or unordered list, the Properties of the Point object correspond to the attributes of the <LI> tag. In a definition list, the Point object also has a "Term" Property which is the text contained in the <DT> tag. The <DD> tag ends the term and begins the paragraphs which are contained within the Point.
The Form Tool creates an interactive area in which the Web user can enter data to submit a request or query. A Form can include all of the previous document objects, and data fields from the bottom row of the toolbar. To process a form, the server must execute a program written by the form designer. This makes the use of Forms an advanced topic that will be described in a separate section.
Less frequently needed Objects (and tools that have no particularly good icon and would look ugly on the Toolbar) can be inserted by selecting an object in the Workarea, pressing the Second Mouse Button, and choosing Insert from the popup menu. The most frequently used Tools (Paragraph and Image for example) can also be inserted this way. However, there are a few objects that can only be inserted from the menu.
The Horizontal Rule Object draws a horizontal line across the screen. Its thickness can be controlled with the SIZE property (a Netscape extension supported by Web Explorer).
SpHyDir has a BR object. Normally a simple line break is honorary text and appears embedded inside paragraphs. The idea of a special break was introduced by Netscape, which needed it to clear dangling images. The <BR CLEAR=ALL> stops flowing text to the right or left of an image and starts at the first line clear of all images. The BR object is also useful in Forms to put a line break between fields, boxes, buttons, and other non-text objects.
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.
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.
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