OS/2 Shareware BBS: 6 File/06-File.zip/sphydir3.zip/docs/sphydir.INF

OS/2 Help File | 1995-05-04 | 171KB | 2,117 lines

ΓòÉΓòÉΓòÉ 1. The SpHyDir Project ΓòÉΓòÉΓòÉ

 Use of the Internet and particularly of the World Wide Web has exploded in
recent months. However, the language in which Web documents is written (HTML)
is obscure. It is difficult to master even its simpler features, while experts
rush to add even more complicated new features to the language. Many documents
include mistakes that can produce various results on different viewing
programs. Getting the basic material right can be so difficult that users often
ignore recommended options that could improve the quality of the document.

 SpHyDir replaces the HTML syntax with a graphic view of the document
structure. Within the SpHyDir workarea, objects are created to represent
chapters, sections, paragraphs, images, lists, and data-entry forms elements.
The objects are arranged in a natural hierarchy: Sections contain subsections
which in turn contain paragraphs, images, and lists. Lists contain numbered or
unnumbered points. Forms contain entry fields and buttons.

 SpHyDir runs in OS/2 Warp and follows the Workplace model of its user
interface. The user drags a document into the workarea. New elements are added
to the document by dragging empty paragraph, image, list, or forms objects and
dropping them into the document. Hypertext links are created by dragging files
from the library or URL references from a Web Browser and dropping them on
existing text or images.

 Unlike "HTML Editors" SpHyDir concentrates on the entire library of related
files. The following links are to "subdocuments," separate Web files that are
logically part of a single logical document. Among subdocuments, SpHyDir
automatically generates links to the [Next] and [Previous] document and back
here to the root document. If a global change needs to be made, the entire
collection of related files can be regenerated.

 SpHyDir only reads Web (HTML) documents. However, after editing it produces
both a revised *.HTM file and a second *.IPF file that is input to the OS/2
Help compiler. IPF source can be used to generate INF documentation and HLP
program help files. INF files can be viewed in OS/2 and (with a tool from IBM)
in Windows. Viewing information from a local hypertext file is faster, and
there are additional keyword search functions not available through the Web.
The document you are now viewing (and its related files) are also available as
SPHYDIR.INF. Since this represents a useful example of many SpHyDir features,
the source is available for download along with the SpHyDir program.


ΓòÉΓòÉΓòÉ 2. Project Status ΓòÉΓòÉΓòÉ

 This section is provided for existing SpHyDir users to quickly review changes
in the most recent releases. It can also give new users a view of the pace of
change.


ΓòÉΓòÉΓòÉ 2.1. May 4 Release ΓòÉΓòÉΓòÉ

 This version should preserve the case of file names and directories (on HPFS
disks where lowercase is possible). The user is responsible for preserving case
during a transfer to a Unix server.

 SpHyDir was not backing up files unless the user created the BACKUP directory.
Now it will be created if it doesn't exist.

 SpHyDir would not create a new directory if the user typed it as part of the
name of a new document. Now SpHyDir will create one level of new directory
structure in the library.

 If SpHyDir cannot make a backup copy, it will generate a message. If it cannot
write the file, it will generate a message and give the user an opportunity to
correct the problem. For example, if the user is trying to create a new file
named "animals/birds/robins.htm" and there is no "animals" subdirectory of the
library, then SpHyDir will not be able to save the file (it will create one new
level of subdirectory structure, but it will not create both animals and
animals/birds). SpHyDir should in all cases return to the user after a popup
message. The user can (if the problem is understood) respond manually by
creating the extra directories outside SpHyDir and then retrying the Generate.

 Although it is intended as a test tool and not a backup, F5 will generate the
current HTML as TEMPDOC.HTM in the root of the HTMLLIB. If the file cannot be
saved to its intended location (say because the original file was marked
Read-Only) and the user cannot diagnose or fix the problem manually, it is
possible to generate the TEMPDOC.HTM, exit, fix the problem, and then copy the
contents of TEMPDOC to the originally intended location.

 F5 is now a Test key. Pressing it generates a temporary HTML file. SpHyDir
then launches Web Explorer to view it. It is intended in a future release that
SpHyDir should send keystrokes to WE if it is already launched to load or
refresh the file. For now, you have to exit and reload WE each test.

 A bug was fixed that "hid" the main SpHyDir window when there was no
SPHYDIR.INI file.

 Files should now be able to have more than one period. Previously, a filename
of "a.b.html" was not regarded as an HTML file.

 LINK REL=Up is now generated correctly.


ΓòÉΓòÉΓòÉ 2.2. Worklist (Still to Do) ΓòÉΓòÉΓòÉ

 Requests seem to come in faster than results go out.

     The BASE statement in the document HEAD identifies the directory in which
      the file is found and provides some protection against errors. It is
      desirable to generate a BASE, but it is undesirable for the BASE to be
      different on the users OS/2 test machine from the correct value that it
      should have on the final server. A single user may maintain several
      separate HTMLLIB roots for document development, yet mount several of
      them under different directories on the same server. This means that the
      BASE is related to HTMLLIB, but has to be configured explicitly and
      cannot be automatically generated based on the full path name that the
      file happens to have on OS/2.

     The requirements for centering have become clearer. The <CENTER> tag is
      widely supported in practice, though it is depricated in all of the
      documents. The HTML 3.0 standard will support <P ALIGN=CENTER>, but it is
      not widely supported today. It appears that SpHyDir should read in
      existing HTML and parse either kind of CENTER directive. It should then
      assign a "centered" attribute to objects that fall in the range of that
      directive. However, at the end of building the document object tree,
      SpHyDir will have "forgotten" if the file that was read in used old or
      new syntax. It will then generate either old or new syntax when the file
      is regenerated based on the user's configured preference.

     A <BR> object must be defined much like the current <HR> to separate
      Forms objects that should occur on separate lines. It is trivial to
      generate the object, and it is trivial to write it out as HTML. The
      problem is to recognize on input the <BR>-as-an-object from the
      <BR>-as-a-character-in-a-paragraph.

     The BLOCKQUOTE tag should be supported in some manner. Perhaps it is a
      special attribute on a Paragraph object.

     When an object is selected by dropping something on it (or by creating a
      new object by dropping a tool) then the entry areas at the top of the
      main window and the Links from the current object in the Link Manager
      window are not always updated to reflect the object that has actually
      been selected. Rather, information about the previously selected object
      can remain visible.

     There is a request to let the user define a table of META NAME fields,
      then allow those META items to be set for the document object and written
      to the <HEAD> area.

     Time permitting, it appears that ISMAP support (at least for rectangular
      selection areas on the image) is worth a shot and might be easily added.

     I tire of having to go back to the previous document and refresh the
      Subdocument object that points to this file because the date in the title
      is always changing. It seems like a good idea if when a Subdocument
      reference is processed in a parent file then SpHyDir should fetch the
      Doctitle Extended Attribute in the referenced file and update the Title
      text if the title has changed.

     If you generate one document, then drag a second HTML file over onto the
      workarea to replace the first document, SpHyDir occasionally crashes. I
      have not found a reproducable case, and since you are between files, the
      response is simply to reopen SpHyDir and drop the same file on a clean
      window.

  As a result of learning more HTML, as the language threatens to grow in HTML
 3, and as users request more obscure features, it becomes clear that the
 current Toolbar and Properties/EntryAreas at the top of the Workarea are not
 going to work forever. To add a Table tool or to support a Center property
 will just overload the limited space. Work has begun (and bugs have been
 created and fixed) to migrate to a more Visual Basic/Delphi-ish approach. The
 Toolbar should be detachable in its own window. The current limited properties
 need to be expandable to a table with lots more properties and clearer
 documentation. The current approach seemed easier in a simpler world, but
 things just don't want to stay simple.

  Longer term issues for study include support of other languages (an ISO
 8859-1 edit box), ISMAP, and the curious behavior when points are dragged out
 of lists and left in other places.


ΓòÉΓòÉΓòÉ 2.3. April 18 Release ΓòÉΓòÉΓòÉ

 A user reported that when a document had an HTML error, the HTML Edit Window
seemed to loop never correcting the problem. More precisely, if there is an
HTML error, and you edit the original file but do not correct the error, then
the Retry button parses the edited file but when the same error, or a second
error, or a new error is encountered then the first edit changes were lost and
the original file was redisplayed. This has been fixed.

 In response to a user request, the </LI> tag is now tolerated. It will be read
in without complaint from a raw HTML file, though it will not be regenerated
when the file is rewritten. The idea of </LI> may come as a shock, since it is
almost never actually used. However, technically the semantics of HTML hold
that a <UL> or <OL> contains only <LI> elements. The <LI> in turn contains
paragraphs and stuff. So while ordinary people write:
<OL>
<LI> One.
<LI> Two.
</OL>
A rigourous HTML would write it as:
<OL>
<LI><P>One.</P></LI>
<LI><P>Two.</P></LI>
<OL>
Of course </P> and </LI> are optional and usually omitted. The leading <P> is
also often omitted when it follows another "breaking" tag like <LI> or <Hn>.
SpHyDir has been rather obsessive about adding </P> where it belongs. However,
to grant structural significance to </LI> would mean rethinking the handling of
Point Objects. The implication is that Point objects should not themselves
contain text but they should contain a second redundant Paragraph Object that
should contain the text. This is more obsessive than I am willing to get at
this time.

 On 4/9 I noticed that the Web Explorer INI file with the hotlist was being
left open. I added some code to fix the problem, but it turned out that the
code was incomplete. Applologies to those who then reported the bug and were
told that "it was fixed in the 4/10 code."


ΓòÉΓòÉΓòÉ 2.4. April 13 Release ΓòÉΓòÉΓòÉ

 There was a bug deleting links. SpHyDir failed with a message about "start.0"
not 0 or 1. The test that a file was in the library was case sensitive,
producing error messages when working directly with an NFS mounted HTML
library.

 The HTMLLIB variable is now optional. If omitted, SpHyDir assumes that the
"current directory" is the HTML library. This allows you to configure several
SpHyDir Program Objects to process different libraries on different disks or
servers.


ΓòÉΓòÉΓòÉ 2.5. April 10 Release ΓòÉΓòÉΓòÉ

 XSpO's have been given icons and are put in a subdirectory of the distribution
file. XSpO files no longer have to be in the PATH.

 Although OS/2 is supposed to adjust windows for changes in screen resolution,
this didn't seem to work for the Vertical direction. SpHyDir now initializes
the Workarea window in a size that fits nicely on 640x480. This window is now
resizable (at least vertically). The size is now saved in SPHYDIR.INI and is
supposed to be restored when the program is next run.

 In response to a request from a user, SpHyDir now searches for "../header.htm"
if a "header.htm" file is not found in the current directory. The same for
"trailer.htm". This allows the library to generate headers and trailers out of
a common file.
Note: if the parent directory has a header.htm file, and you want no header in
a file in a subdirectory, it is now necessary to put an empty HEADER.HTM and/or
TRAILER.HTM file in the subdirectory to make sure that the parent files are not
included. This is a change from the previous releases.

 A user requested support for the 'Mailto' URL. Then the Web Explorer Beta
released last week added support for "mailto". I promised that it would be
added. However, when I started work on this code it became clear that this
should be External Rexx Code (an XSpO) and not buried inside the SpHyDir
source. The XSpO interface was already inserted in the right place, it just
needed sample code. So MAILTO.CMD is not in the XSpO library. It inserts a mail
link back to me. I would appreciate it if you edit this file and insert someone
else's E-MAIL address, or get the address from some database. If you have a
problem with it, send me a report (example Mailto generated by dropping the
XSpO on this paragraph).

 An uninitialized Subdocument object cause HTML generation to fail, when the
logic tried to search a null string for the file type of the subdocument file.

 The Next, Up, and Previous document variables were not being reset to a null
string when a new document was started by dragging the first icon off the
Toolbar and dropping it on the Workarea. This produced incorrect LINK tags in
the header of the new file the first time it was written to disk (though the
problem would be fixed automatically if the file was ever subsequently reedited
with SpHyDir).

 There was a bug in the March 27 code that generated inappropriate comments in
the HTML and poped up the "variable" name window for the first paragraph of a
section when reediting a SpHyDir HTM file more than a few weeks old. Older
SpHyDir files had dummy " target" information (A NAME= tags) inserted before
each header (Hn tag). When the file was reread, the tag was recognized as an
internal SpHyDir construct and was ignored. A few weeks ago, SpHyDir stopped
generating the dummy A NAME tags because it was decided that they would not be
used in the Table of Content project. However, older files still had the tags,
and a bug in the code that read them in left a value in the "name" variable
that fell through and was applied to the next object. The Name attribute wasn't
meaningful for Image or Paragraph objects, so this bug sat around for a month
with no effect. Then the March 27 code added support that would eventually
allow Paragraph objects to be assigned a Forms Variable name so that results of
a query could be returned as ordinary paragraph text and not just MLE contents.
No problem was noted since all the test files are actively used and had,
therefore, been rewritten in the previous weeks removing the dummy A NAME tags.
However, if an old file was processed, the bug assigned a "name" variable to
the next paragraph, which was now misinterpreted as a Forms Insert Variable
name generating a symbol table entry and an HTML comment. The bug has been
fixed, and any erroneous comments will be filtered out when the file is next
reprocessed.

 This brings up the general strategy for bugs. SpHyDir is constrained to
produce HTML good enough to pass a Validator program. There is also a view that
Extended Attributes are easily lost, so nothing of permanent importance can be
stored in them. SpHyDir elements are stored in one of several forms:

   1. Some structural elements are represented by constraints on ordinary HTML.
      For example, the convention that <Hn> header tags are used to start
      sections is such a constraint.

   2. Some elements use features of HTML 2.0 that are clearly valid but
      imprecise. The generation of a Subdocument as <A HREF="file"
      REL="SUBDOCUMENT"> falls in this category. REL and the value
      "SUBDOCUMENT" are in the 2.0 standard, but their use is treated largely
      as commentary. It is a SpHyDir convention that a link of this form has a
      special significance beyond other HREF hypertext links.

   3. If no HTML 2.0 feature is available, SpHyDir reserves the right to select
      syntax from the 3.0 standard. For example, if the IPF files are to be
      used to generate HLP files, then each <Hn> tag must have a numeric id
      (call the Resource number). The HTML 3.0 standard has an ID= attribute in
      the Hn tag. Thus SpHyDir is likely to generate
      <H2 ID=RES00103>The Answer to Everything</H2>
      as a compact way to add the resource into the file. Note that although
      SpHyDir may for its own internal processing purposes generate some HTML
      3.0 syntax, it doesn't have enough object attributes to store and
      regenerate all the new attributes that that standard supplies. Hense,
      SpHyDir currently only promises to support the HTML 2.0 subset of syntax
      for user-generated tag information. This is not ideal, but the problem
      can be fixed in a later cycle if a better solution comes along.

   4. The last option is to generate a real HTML comment. Such comments start
      with the word "SpHyDir" as in <!-- SpHyDir foo bar -->. This is certainly
      the cleanest choice, but it is an awkward syntax to parse and manage.

  If it is discovered that SpHyDir is generating something wong, or if a
 feature is changed or removed, then subsequent versions of SpHyDir are coded
 to recognize the old construct on input but to generate the newest version of
 the syntax on output. The particular syntax inside an HTML comment may, for
 example, change across such an update to distinuish old and corrected
 constructs. For example, if the ID=RES0xxxx syntax were inserted in headers
 for a while, and then were changed to something else, the use of an ID
 attribute beginning "RES0" might remain restricted indefinitely to be one form
 of defining a resource number.


ΓòÉΓòÉΓòÉ 2.6. March 27 Release ΓòÉΓòÉΓòÉ

 Perhaps in response to the recent burst of development, not much was done with
SpHyDir this weekend. Once you have Forms, the next thing to do is to connect
the forms processing programs to database. Thus the weekend was lost looking at
the database alternatives for Rexx in OS/2 and working on the currently
incomplete documentation of the GOSERVE filter and program development
environment.

 A few bugs were reported last week and are fixed. Some Emphasis keywords were
not supported. The ALT-H got messed up and has been restored.


ΓòÉΓòÉΓòÉ 2.7. March 20 Release ΓòÉΓòÉΓòÉ

 An enormous number of features have been added in the last four days. Forms
support is nearly complete. A lot of testing found a number of small bugs in
the forms code. A scheme to integrate SpHyDir forms and the IBM GOSERVE package
as been created.

     SpHyDir creates all the HTML 2.0 forms objects (excluding ISMAP, which is
      technically not a part of Forms).

     SpHyDir "compiles" into the external attributes of the file a symbol
      table of Forms variables and the location in the file where the
      corresponding character string is located.

     The SpHyDir_Extract helper routine can be used by a Rexx processing
      program running under the GOSERVE Web Server environment to extract the
      parameters of a Forms request and turn them into native Rexx variables.

     The SpHyDir_Reply help routine, running in the same environment, takes
      the name of a SpHyDir generated HTML file, copies it into a temporary
      dataset inserting the current values of Rexx variables (if they exist)
      for each correspondingly named Forms variable defined in the HTML file.

  Minor changes, often requested by users:

     SpHyDir now allows the Definition Term <DT> to be a hypertext link to
      some other document. This was patched in, so there is a restriction that
      if an <A HREF=> appears anywhere in the term, the entire term is treated
      as the hyperlink and, therefore, you cannot have two links from different
      words in the term.

     HREF=filename is now rather rigourously folded to lowercase to simplify
      the process of porting scripts to Unix servers. Again, I tried to sweep
      up all the loose ends, and if you can find any I missed I will be quite
      interested in examples of any filenames that still come out in uppercase.

     IPF files can get to be an annoyance if you don't want them. SpHyDir now
      will not build an IPF file unless something with that name already
      exists. If you have a file named, say, SOME.HTM and you want an IPF file
      created, then just
      [c:]copy some.htm some.ipf
      Then the next time SpHyDir processes SOME.HTM it will notice that the IPF
      file is present and will replace it with the corresponding IPF source.
      This seemed like the simplest way to handle the choice.

     The Icons are now all bound to the EXE as resources and are referenced as
      such. Therefore, SpHyDir no longer requires that the current directory
      have all the *.ICO files and they are no longer distributed in the ZIP
      file. If you wish, you can get rid of them in your directory as well.


ΓòÉΓòÉΓòÉ 2.8. March 16 Release ΓòÉΓòÉΓòÉ

 In a FORM, the HTML PASSWORD entry field is now supported. A Password
attribute can be assigned to the previous ENTRY field object.

 The toolbar has a Pushbutton object. With no parameters, a Pushbutton is named
SUBMIT and tranmits the form data. A Pushbutton can also be assigned a variable
name and value that will be transmitted with the rest of the form data. The
value sets the caption on the button.

 HTML supports a HIDDEN object that contains data (a userid, transaction ID, or
other handle). It is sent to the browser but is not displayed on the screen. It
is added to any forms input. This allows the server programs to carry
information from one transaction to the next. To support this without adding a
new tool to the toolbar, SpHyDir has added a "hidden" attribute to the
Pushbutton object.

 A new Extended Attribute named "Variables" has now been added to each HTML
file with FORMS. This EA identifies the location of any data in the HTML file
that is associated with a variable name associated with a FORMS object. For
example, if a Text Entry Field is associated with the variable name PHONENUM,
there will be an entry in the Variables EA indicating the type of field
(ENTRY), the variable name (PHONENUM), and the location in the HTML file where
a previous phone number value might be inserted. The field would be generated
as:
<INPUT TYPE="TEXT" NAME="PHONENUM" VALUE="">
and the EA would have the byte offset in the file of the first double quote
following VALUE.

 This form is perfectly valid as a static HTML file. Transmitted as is, the
phone number field would appear empty. However, if the form is sent out from
the server by a forms processing program that uses SpHyDir "helper routines",
and if the PHONENUM variable is also defined in the sending program, then the
current value of the variable will be inserted into the field. For example, if
a Rexx program had
PHONENUM="203-555-1234" and sent the form out with a helper program, then the
resulting HTML after the insertion would be:
<INPUT TYPE="TEXT" NAME="PHONENUM" VALUE="203-555-1234">

 Rexx is a particularly nice language for this purpose because the user program
doesn't have to specially identify the variables used in the Form. The helper
routine can query the EA, then check the Rexx symbol table for each variable
name found in the form to see if there is an existing Rexx variable of the same
name. To play the same trick with other langauges, such as C, the processing
program first has to pass the variable and name to the interface routine as in:
SpHyDir_define("PHONENUM",&phonenum);


ΓòÉΓòÉΓòÉ 2.9. March 14 Release ΓòÉΓòÉΓòÉ

 SpHyDir now generates HEIGHT and WIDTH tags for Image objects. Netscape
supports them and is much faster when they are present. HTML 3.0 also includes
them in the standard. Other browsers will ignore them. SpHyDir ignores these
attributes when reading HTML in, but when it goes to generate the IMG tag it
opens the GIF file and reads the image size from the header. If the size of an
image changes, the HTML can be updated by reading and rewriting any pages that
reference the image.

 In a related area, the Document Tree window (introduced two days ago) now has
a File menu with a Generate Tree item. Selecting this item will regenerate the
root document and all of the subdocuments of the current multi-file tree. This
makes it simple to change boilerplate (Header and Trailer line) globally or add
new features (like adding HEIGHT and WIDTH fields to all graphics.

 A user requested keyboard shortcuts for character emphasis. With the Text Edit
window, select a section of text and use:
Ctrl-B for Bold
Ctrl-I for Italics
Ctrl-E for EM
Ctrl-C for Cite
Ctrl-S for Strong


ΓòÉΓòÉΓòÉ 3. SpHyDir Project Objectives ΓòÉΓòÉΓòÉ

     Produce better quality HTML documents for the World Wide Web while
      exposing the author to as little HTML syntax as possible.

     Simplify the construction of large documents composed of many small,
      structurally interrelated hypertext files.

     Automatically generate navigational links, copyright notices, and other
      standard features at the beginning or end of every document.

     Provide a core set of functions, then allow the user to add features by
      coding simple external Rexx functions.

     Generate documents that can be published both on the network (in HTML
      format through the World Wide Web) and in hypertext file format (as INF
      files viewed under Windows or OS/2).

     Simplify the development of Web "forms." In particular, provide direct
      support that simplifies Rexx-based query programs running under GoServe
      2.0 (the free IBM Gopher/Web server for OS/2), although the forms can be
      used with any CGI program running on other servers.

  SpHyDir is the Structured Professional Hypertext Directory Manger. It is
 Structured because it views a Web not as a collection of ASCII files with
 format instructions, but rather as a collection of documents with chapters,
 sections, and subsections. It is Professional because it aims to manage a
 large block of material and not to help the novice design a single home page.
 It is Hypertext because it helps to manage links between documents, structure
 across documents, and links to remote information sources. It is a Directory
 manager because it simplifies the maintenance of logical documents composed of
 many small HTML files in the same directory.

  SpHyDir is also an experiment in using IBM's Workplace interface within an
 application program. Although IBM originally that the Workplace model be used
 to handle application data objects as well as System components, there are
 only a few examples of this use and they have not been entirely successful.
 Whenever possible, SpHyDir follows the Workplace model to decide how things
 should be done and how they should look. This makes SpHyDir a truly "native"
 OS/2 program.

  SpHyDir does not claim to understand or process all "valid" Web documents.
 There is a widely held view that the HTML language in which Web documents are
 expressed is intended to provide formatting information. SpHyDir tries to use
 it to extract document structure. In particular, SpHyDir assumes that a
 "heading" introduces a chapter, section, or subsection. When someone uses
 heading tags just to get big letters, SpHyDir will make all sorts of wrong
 assumptions. This is not a bug and it is unlikely to ever be changed. SpHyDir
 approaches the question of Web documents with an entirely different
 philosophy.

  The Web provides universal access to sophisticated information from all
 computers on the Internet. Of necessity, this involves some compromise in
 function and speed. There are also native hypertext formats (HLP, INF) that
 provide many of the same structural features, faster local performance, and
 extra features such as keyword search. SpHyDir also generates IPF source files
 that can be compiled into OS/2 HLP files and INF files. The primary purpose of
 this feature was to provide a version of this document that could double as
 HLP to the SpHyDir program.


ΓòÉΓòÉΓòÉ 4. The SpHyDir Idea ΓòÉΓòÉΓòÉ

 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 an Open File dialog. Such dialogs are rather ugly when
the same files can be more easily located in Workplace folders. SpHyDir opens a
file when a file icon is dropped into 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 a 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.

 IBM and Apple are working on a strategy called "OpenDoc."  A document is
viewed as a collection of parts with different types.  A Text Part has fonts
and a spelling checker.  An Image Part has cropping and color correction.  A
Table Part works as a spreadsheet.  Since Web documents are built from
different types of components, it seemed at first that OpenDoc might be
directly useful. 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.


ΓòÉΓòÉΓòÉ 5. SpHyDir is not for Everyone ΓòÉΓòÉΓòÉ

 SpHyDir was written after many months of frustration dealing with other Web
authoring environments. It will develop to meet the needs of PC Lube and Tune
and potentially a large group of other Web authors. It was not written to be a
"product" in the usual sense of that word because the environment of the Web is
changing too rapidly. When someone talks about HTML, is that Version 1, Version
2, Version 3, or Netscape extensions? It isn't possible to really build a
"product" against a target that changes and is vaguely defined.

 The purpose of SpHyDir is to improve the quality and scope of the HTML
generated by ordinary users, not to meet the exacting requirement of the HTML
expert. SpHyDir can encourage the user to add extra features that might
otherwise be ignored (such as ALT text for an image) and it can automatically
generate features that would be tedious to code manually (such as HEIGHT and
WIDTH on an image). Because the HTML is generated automatically, the user
cannot make simple typographic or syntax errors in the HTML tags. However,
SpHyDir doesn't claim to make errors impossible.

 The author develops SpHyDir during spare time. Mostly, this means over
weekends. The SpHyDir project aims to deliver updates each Monday. When bugs
are reported, and assuming that there are no major updates under way, fixes may
be posted to the server in midweek. There are no plans to have formal releases,
so a version of SpHyDir is typically known by the date on the EXE file after it
is unzipped. To know if there is a new version, use FTP to check the date of
the ZIP file on the server.

 SpHyDir can be dangerous. When it begins to generate HTML from the edited
data, it copies the previous file to a backup directory. However, save the file
twice and the original data is lost.

 This is important because SpHyDir is not an HTML Editor. It reads HTML and
proposes a structural representation of the original data. When done, it writes
a new file containing its own HTML to reflect this structure and any changes.
If the original file used constructs that SpHyDir doesn't support, the
resulting file can lose information. Keep the original data. Compare it to the
output of SpHyDir before discarding the old files.

 SpHyDir is not written tightly enough to trap its own syntax errors and
recover. Rexx simply stops the program when it encounters a problem. Since Rexx
is an interpreted language, syntax errors may only be detected during
execution. When the program aborts, it can leave the output file half-written.
This is the primary reason for making a backup of the previous copy of the file
before generating a new copy.


ΓòÉΓòÉΓòÉ 6. How to Get SpHyDir ΓòÉΓòÉΓòÉ

 SpHyDir is a copyrighted program which is a personal project and property of
the author. It is made available on the network and may be used free of charge
under a license terms distributed with the package. Essentially, you agree to
leave in all HTML documents produced by SpHyDir the credit that appears at the
bottom of all of these Web pages: "This document generated by SpHyDir, another
fine product of PC Lube and Tune."

 This arrangement is called "Personal SpHyDir." If a large organization wants
to generate more professional looking documents and omit the credit, other
licensing arrangements can be made with the author.

 The following references are correct. They work with Web Explorer and Netscape
and conform to current HTTP and HTML standards. If they don't work on your
Browser, get a better Browser. Otherwise, you can fetch the files with FTP from
pclt.cis.yale.edu. They are in the SPHYDIR subdirectory of PUB. If you have
trouble with your browser, then read the trailing tutorial on Web handling of
binary files to figure what went wrong.

 With a good browser, just select the name of any desired files and save them
to disk on your machine.  All are compressed with the ZIP utility from the
INFOZIP project.

     SPHYDIR.ZIP - The basic SpHyDir package. Includes the program, some
      sample External Rexx "XSpO" scripts, a proposed starting point for the
      GOFILTER needed by the GOSERVE server on OS/2, and the shared code Rexx
      segments for easy forms processing.

     VROBJ21B.ZIP - The VX-Rexx 2.1B runtime library, VROBJ.DLL. This file
      must be in your LIBPATH for SpHyDir and many other freeware and shareware
      packages to run. You may already have this file. SpHyDir will run on 2.1B
      and later versions of this runtime module.

     SPHYDOC.ZIP - A copy of all these HTML pages and their associated GIF
      files. Unlike other PCLT documents, the SpHyDir documents may be
      downloaded and copied. This provides a good example of lots of SpHyDir
      use.

     GBM.ZIP - A freeware package written by an IBM employee and distributed
      through a number of sources. This OS/2 program converts between a number
      of popular image formats (GIF, TIFF, XBM, BMP, etc.) and can crop or
      resize images. Use this package to convert BMP or Clipboard images into
      GIF suitable for including in a Web document.


ΓòÉΓòÉΓòÉ 6.1. Distributing Binaries through the Web ΓòÉΓòÉΓòÉ

 Fetching a ZIP file through the Web should be a trivial matter. Unfortunately,
a number of popular Browsers (particularly NCSA Mosaic) don't do a reasonable
job of handling such files.

 Web Servers support the HTTP (HyperText Transfer) Protocol. The first version
of HTTP (0.9) simply transmitted Web files back to the reader. The current
standard (1.0) preceeds each file with a statement of its data type in Internet
MIME style. This allows the Browser to distinguish between HTML, plain Text,
ZIP binaries, and MPEG movies.

 Web Browsers can also read files using the FTP protocol. With FTP, the server
doesn't provide any indication of the data type, but the file name contains an
extension that usually indicates the type of data (*.ZIP, *.JPG, *.GIF, etc.).
In the early days of the Web, HTTP was generally used to distribute HTML files,
and FTP was generally used to distribute other binary formats.

 No Operating Systems record the MIME file type in the disk directory.  So most
HTTP servers look at the file type and create a MIME data type based on the
extension of the file requested.  Thus if a browser fetches SPHYDIR.ZIP using
FTP, it will decide that it is a ZIP file because of the *.ZIP extension, but
it it fetches the same file using HTTP from the same server, the the Server
will look at the *.ZIP extension, decide that it is a ZIP file, send the MIME
header with that information, and the Browser will react accordingly.

 The problem is that a lot of Web Browsers have developed the convention that
anything that comes over HTTP protocol should be either displayed on the screen
or played through the speakers, while files that come over FTP can be saved to
disk if they have a file extension that makes that seem right.  Nothing in the
standards says any such thing.  Architecturally, a URL can call up ftp:,
gopher:, or http: protocols to fetch a file.  What you do with the file should
then be determined by the type of data and not by the protocol used to fetch
it.  But it is hard to convince some Browsers to save a ZIP file to disk if it
came over HTTP protocol.  In most cases, the ZIP file is actually on disk in
the Browser's CACHE directory, but it may be hard to find.  When it doubt, fall
back on plain FTP.


ΓòÉΓòÉΓòÉ 7. Using SpHyDir ΓòÉΓòÉΓòÉ

 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.


ΓòÉΓòÉΓòÉ 7.1. How do I edit an HTML document? ΓòÉΓòÉΓòÉ

 There are three ways to start SpHyDir on an existing HTML file.

   1. 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.

   2. 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.

   3. 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.


ΓòÉΓòÉΓòÉ 7.2. How do I start a new HTML file? ΓòÉΓòÉΓòÉ

 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
name that the file will be assigned in the HTML library (the set of directories
under the starting point configured in the SET HTMLLIB= environment variable).
Do not retype the disk letter or upper directories.  Just type the Unix style
(forward slashes "/") name of that the new file will have relative to the top
of the library.  SpHyDir will create a new Document object and a new Section.


ΓòÉΓòÉΓòÉ 7.3. 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.


ΓòÉΓòÉΓòÉ 7.4. How do I enter special characters? ΓòÉΓòÉΓòÉ

 If the question applies to the three ordinary ASCII characters ("&", "<", and
">") that HTML uses to delimit control features, just type them. SpHyDir
removes the HTML control features when the document is read in and recreates it
when the document is regenerated.

 For foreign language (ISO 8859-1) characters, SpHyDir currently doesn't have
explict support. The author is in search of an appropriate entry area control
or simple text editor that will allow these characters to be displayed and
edited directly.

 Because the paragraph boundaries are represented by objects, the user can
enter a line break (<BR>) by simply typing Return to split the current text.


ΓòÉΓòÉΓòÉ 7.5. How do I delete objects? ΓòÉΓòÉΓòÉ

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


ΓòÉΓòÉΓòÉ 7.6. 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. Dropping an
      external file on the Text Editor window is ambiguous. Some files have
      long lines with CR-LF at the paragraph boundaries, some have blank lines
      at paragraph boundaries and CR-LF is a line break. SpHyDir will shortly
      be extended to support an XSpO (external Rexx program) interface to
      handling files dropped on the Text Edit window.

     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.


ΓòÉΓòÉΓòÉ 7.7. 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 funny triangle characters
or SpHyDir will get confused.

 SpHyDir has a Link Manager window to handle URL links to Web documents out
there somewhere in the network. The Link Manager displays documents in a
browser hotlist. A supplied XSpO (an external Rexx program) can be dropped on a
paragraph, point, or image to create a link to whatever network document the
IBM Web Explorer is currently displaying.


ΓòÉΓòÉΓòÉ 7.8. 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.


ΓòÉΓòÉΓòÉ 7.9. How do I move paragraphs around? ΓòÉΓòÉΓòÉ

 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.


ΓòÉΓòÉΓòÉ 8. The Toolbar ΓòÉΓòÉΓòÉ

 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.


ΓòÉΓòÉΓòÉ 8.1. The Document Tool ΓòÉΓòÉΓòÉ

 If the workarea is empty, then dropping the document tool in it creates a new
document. SpHyDir prompts for the name of the new file (which should be in the
library and should end in HTM or HTML).

 Within an existing document, the DOC tool creates a subdocument link to
another HTML file. The user can always link another HTML file to any hotword in
any paragraph or point in the text. However, a Subdocument link is used to
build a single large logical document out of a sequence of smaller files.

 A Subdocument object can go anywhere, but it will not make much sense or
produce good results unless all the Subdocument are at the end of a file.

 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.

 However, 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.


ΓòÉΓòÉΓòÉ 8.2. The Section Tool ΓòÉΓòÉΓòÉ

 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. SpHyDir will probably
work best if the entire HTML file is contained in a single top level (H1)
section.


ΓòÉΓòÉΓòÉ 8.3. The Paragraph Tool ΓòÉΓòÉΓòÉ

 The Paragraph Tool produces an ordinary paragraph of text. Actually,
paragraphs contain text, formatting tags (bold, italics,etc.), and hypertext
links to other files and documents keyed to hotword phrases.


ΓòÉΓòÉΓòÉ 8.4. The Image Tool ΓòÉΓòÉΓòÉ

 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 (represented by the ALT attribute). The entry
area at the top of the workarea can be used to type a phrase that will be
displayed as alternate text.

 By default, an Image object will be displayed by itself. This is probably the
best choice for large images. An icon, on the other hand, should be displayed
inline (as is the Image icon itself at the start of this section). When an
Image object is selected, a "spin field" appears under the entry area at the
top of the work area. Within this field, the selection "None" for alignment,
places the image by itself. Otherwise, the text of a subsequent paragraph will
appear to the right of the image. Top, Middle, and Bottom are standard HTML
alignments. Left is an alignment option supported by Netscape.


ΓòÉΓòÉΓòÉ 8.5. The Ordered List Tool ΓòÉΓòÉΓòÉ

 An Ordered List Tool contains a sequence of numbered points. The list pushes
down the tree structure one level. Drag the Point Tool and drop it in the list.
Each Point acts much like a paragraph. Lists may also include Paragraph Objects
(unexpected but widely used) and Subdocument Objects (useful when you want to
number the chapters). A list may not contain a Section object!


ΓòÉΓòÉΓòÉ 8.6. The Unordered List Tool ΓòÉΓòÉΓòÉ

 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.


ΓòÉΓòÉΓòÉ 8.7. The Definition (Glossary) List Tool ΓòÉΓòÉΓòÉ

 A Definition List defines a set of terms. Each item in the list is preceeded
by the term to be defined, set off from the definition by different levels of
indentation. The Point Tool is used for definition lists as well. The Point
Tool changes its behavior depending on the type of list in which it is placed.


ΓòÉΓòÉΓòÉ 8.8. The Point Tool ΓòÉΓòÉΓòÉ

 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.


ΓòÉΓòÉΓòÉ 8.9. The Target Tool ΓòÉΓòÉΓòÉ

 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.

 There are three views about hypertext targets. HTML allows any word, even any
letter, to be the target of a hypertext link. This level of precision is
meanless to the viewer. IPF requires a hypertext link to jump to a header that
generates its own Window. In HTML terms, the IPF strategy would only allow HTML
files to be targets and not individual subsections. This explains why OS/2 HLP
and INF files seem to be fragmented into silly, unmanagably small individual
panels.

 SpHyDir tries to split the difference. A Target is an object, so it can only
go in front of Section, Paragraph, Image, List, or Point objects. When SpHyDir
encounters a target while reading HTML, it moves in in front of the paragraph
or point in which it was found. When SpHyDir generates IPF, however, it will
probably have to move the reference back to the start of the current Section.


ΓòÉΓòÉΓòÉ 8.10. The Preformatted Text Tool ΓòÉΓòÉΓòÉ

 Within an ordinary paragraph, line breaks and multiple blanks are ignored. The
Preformatted Text object is used for examples where the lines and spaces are
important. In most browsers, Preformatted Text is rendered in a font with
characters of equal width.


ΓòÉΓòÉΓòÉ 8.11. The Forms Tools ΓòÉΓòÉΓòÉ

 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.


ΓòÉΓòÉΓòÉ 8.12. Missing Tools ΓòÉΓòÉΓòÉ

 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.


ΓòÉΓòÉΓòÉ 9. The Problem of Position ΓòÉΓòÉΓòÉ

 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.


ΓòÉΓòÉΓòÉ 10. Managing Links ΓòÉΓòÉΓòÉ

 Most HTML editors expect the user to type in the document referenced (the URL)
in order to create a hypertext link. Since it is easy to make a mistake,
authors are urged to test their documents thoroughly. SpHyDir provides a
simpler and more reliable method of constructing links.

 Links to other files in the same library can be constructed using standard
Workplace Shell behavior. Hold down Cntrl and Shift and drag the icon of
another file in the library to a paragraph, point, or image object in the
SpHyDir Workarea. If the link is made to a text object, the Hotword Selection
window opens to select the particular phrase in the paragraph or point that
will be used to form the link.

 Links to remote documents should be managed with the aid of a Web Browser. In
particular, in the OS/2 Warp environment in which SpHyDir operates the IBM Web
Explorer program is an obvious choice. SpHyDir can extract the URL for
frequenly used Web documents from the Web Explorer Hotlist, or an XSpO
(external Rexx Program) can be used to extract from the active Web Explorer
window the URL of the document currently being displayed. SpHyDir eliminates
the opportunity for typing errors when entering the URL.

 SpHyDir has a separate Link Manager Window that can be displayed by choosing
it from the Window pulldown menu on the main SpHyDir workarea.

 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 Web Explorer.

 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.


ΓòÉΓòÉΓòÉ 11. The Subdocument Tree ΓòÉΓòÉΓòÉ

 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.


ΓòÉΓòÉΓòÉ 11.1. The Library ΓòÉΓòÉΓòÉ

 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.

 Although it is possible to dump all the files in one directory, the library
becomes more managable if each major subject has its own directory. Any large
collection of related files can be collected in the same subdirectory.


ΓòÉΓòÉΓòÉ 11.2. Chapter and Verse ΓòÉΓòÉΓòÉ

 It is possible for a collection of random short documents to be collected
together in some free-form association. No structure would be needed for such a
grouping. However, most collections of hypertext files actually started as a
larger paper document. The material was broken into smaller files because it is
best if each file on the Web is only a few screens long. However, the original
logical structure of chapters, sections, and subsections is still logically
present.

 To accomodate this, SpHyDir supports the concept of a Subdocument. A
Subdocument is a special kind of "paragraph" object in a file. Any word in an
ordinary paragraph or point can be a hypertext link to another file. However,
such links do not establish a relationship between the file containing the link
and the file to which the link points.

 A Subdocument link, however, claims that the other file is logically a part of
the file that references it. When one file claims another as a Subdocument,
then the first file is said to be the "parent" of the claimed file. A thousand
different files can have ordinary hypertext links to the same Web page, but
only one file can claim to be its parent. (This is a restriction that the user
should obey. SpHyDir is not currently in a position to enforce it).

 Just as each library generally has a "front door" or "home page", so any
collection of subdocument has a starting point. The "root" document is the one
member of the group that has no parent. It points to subdocuments, and they in
turn can point to other subdocuments.


ΓòÉΓòÉΓòÉ 11.3. Objects and Attributes ΓòÉΓòÉΓòÉ

 Physically, a Subdocument Object produces a paragraph whose only content is
the TITLE of the Subdocument. This TITLE is a hypertext link to the
Subdocument. In addtion, however, the Subdocument object has a structural
effect upon the parent, the named document, and other subdocuments that are
also claimed by the same parent.

 Subdocuments are normally a series of chapters or sections. If the text were
printed out, they would be printed and read in order. The order in which the
Subdocument objects appear in the parent produces a Next/Previous relationship
between the subdocuments themselves. HTML 2.0 doesn't have a formal method of
expressing this relationship. HTML 3.0 will have syntax for Next and Previous
links. Until this becomes widely available, SpHyDir manages the relationships
itself.

 In OS/2 a file can have Extended Attributes. The normal attributes are things
like Date and Size. Extended Attributes are maintained by the application that
creates the file. SpHyDir creates Extended Attributes for the HTML files to
manage the larger logical document structure within the subdocument tree.

 One EA provides quick external access to the document TITLE without having to
read through the HTML. Another lists all the Subdocuments that the current
document claims. Another lists the parent, if any, of the current document.
Another lists all the Header text and levels of all the Sections contained
within the document.

 To create a Subdocument link, first drag the "Book" tool (the first one in the
Toolbar) and drop it anywhere a paragraph or list point can go. The definition
is completed by dragging the Workplace icon of another HTML file from the
library and dropping it on the newly created object. If the dragged file was
previously generated by SpHyDir, then when it is dropped on the Subdocument
object, SpHyDir will extract is TITLE (from the EA) and display it as the
caption of the object. This title will appear in the final page on a line by
itself hypertext linked to the referenced file.

 When HTML is generated for the current file, the list of Subdocument objects
in the order that they appear will be stored as an Extended Attribute of the
current file, and an Extended Attribute will be created on each of the
referenced files pointing back to the current file as the parent.

 Subdocument objects are not a formal construct of HTML 2.0, but there is some
fully documented syntax that comes very close. When the Subdocument object is
converted to HTML, it is generated in one of two forms (a paragraph or a list
item):
<P><A HREF="xxx.htm" REL="Subdocument"> ...title...</A></P>
or
<LI><A HREF="xxx.htm" REL="Subdocument"> ...title...</A>
If SpHyDir processes an existing HTML document with the REL="Subdocument"
attribute it will try to convert it back to a subdocument object.


ΓòÉΓòÉΓòÉ 11.4. Next and Previous ΓòÉΓòÉΓòÉ

 HEADER and TRAILER can contain variables which are replaced with current
information. Variable names are enclosed in "[" and "]" characters.
[Date] is replaced by the current date.
[Doctitle] is replaced by the TITLE of the document.
[Up] is replaced by the file that claims this as a subdocument.
[Previous] and [Next] are replaced by the files that appear before and after
this file in the Subdocument list of the Parent.

 The [Up], [Next], and [Prevous] relationships don't always exist. For example,
the document at the top of the tree has no Up. The first document listed as a
Subdocument has no Previous, and the last document has no Next. To accomodate
this, any line in HEADER or TRAILER that references a non-existant variable is
entirely deleted. The idea is that you put on one line all the stuff that would
relate to a relationship, and when it doesn't exist then the entire package is
deleted.

 An example HEADER might include the lines:
<P>
[<A HREF="[Up]">Up</A>]
[<A HREF="[Previous]">Previous</A>]
[<A HREF="[Next]">Next</A>]
</P>
<P><I> [Date] </I></P>

 Every document gets a line containing the current date in italics. Above that
line there may be 0-3 hyperlinks depending on the number of available
relationships. If all three links are generated, then the line looks like:
[Up] [Previous] [Next]
with each word acting as a link.


ΓòÉΓòÉΓòÉ 11.5. The Document Tree Window ΓòÉΓòÉΓòÉ

 The Window pulldown menu of the SpHyDir Workarea includes an option to display
the Document Tree for whatever HTML file is currently in the Workarea.

 To build this window, SpHyDir checks for the Parent of the current file, and
then for the parent of the parent, until it finally reaches the Root document.
It then proceeds down through the Extended Attributes of the Root and all the
subdocuments and sub-subdocuments. For each file, the TOC Extended Attribute
lists all of the Headers in that file.

 The Document Tree window displays a complete cumulative Table of Contents for
all of the files in the document tree structure. It is intended to eventually
create a TOC file and simplify the creation of references from one part of the
tree to a section in another file.

 Currently, the major feature of this window is the ability, from the File
pulldown menu, to trigger SpHyDir to regenerate HTML for all of the files in
the tree. This is a convenient way to clean things up if the HEADER or TRAILER
files have been changed or when the logical order of files has been rearranged.


ΓòÉΓòÉΓòÉ 12. XSpO - External SpHyDir Rexx Code ΓòÉΓòÉΓòÉ

 It is nice to have code that understands Web Explorer, but other people use
Netscape, Mosaic, or other browsers. SpHyDir can't handle every type of hotlist
file. The solution to this and other problems is an External SpHyDir Object.
These are called XSpO's (pronounced "expo") but given that they are written in
Rexx, it is acceptable to roll an "R" in front of the name and call it a
"Rexx-spo".

 An XSpO is an external Rexx program that resides as a CMD file on disk. If you
click on the file with the second mouse button, open its Settings, and change
the icon, you can give it some meaninful icon. Then you put a shadow of the
file in a desktop folder, probably along with your program object for SpHyDir.

 An XSpO acts something like a Tool. You drag it from its workplace folder and
drop it somewhere in the SpHyDir program. The nature of the XSpO decides where
it can be dropped. Unlike the Tools, an XSpO could be dropped on an entry area
or list.

 The XSpO interface will be extended whenever an idea comes to mind. Currently,
the two supported uses of an XSpO are to fill the New Links list box in the
Link Manager window and to add a URL Link to an object in the work area. Sample
XSpO files are supplied with SpHyDir for both purposes and will be discussed
here.

 SpHyDir assumes that it has an XSpO whenever the user drops a CMD file on an
object. When the object accepts XSpO, it generates a Rexx Call to the file as
an external procedure. Since the caller is running in the VX-Rexx environment,
all of the VX-Rexx functions are available to the XSpO. However, it will be
difficult to make use of them without 1) a copy of the VX-Rexx manual and 2)
some hints from me about the environment. An XSpO that uses VX-Rexx function
calls to manipulate objects is said to be "dirty." The internal implimentation
of SpHyDir may change in the future, and such files may need to be changed. An
object that supports XSpO will generally provide a convention using only
arguments, the return value, and the stack. Details may differ from object to
object. An XSpO that does not directly call VX-Rexx functions is said to be
"clean." The terms are relative, and it may be convenient to use "quick and
dirty" techniques from time to time.

 When an XSpO is called, it is always passed as an argument the name of the
object on which it was dropped. There is no good way (currently) for XSpO's to
declare a type, so the XSpO itself has to make sure it has been dropped in the
right place and return without doing anything if it is called by the wrong
object. Objects that call XSpO's should ignore any null return.

 When an XSpO is dropped on the New Links listbox of the Link Manager window,
it is passed no arguments other than the "New_Links" object name. The XSpO puts
new list entries on the Rexx stack. Each entry begins with a URL (no blanks are
allowed by SpHyDir in a URL) and then a Title (blanks are OK in the tile). Each
line in the Rexx queue is one list entry. Only the title will show up in the
list box, the URL is kept as user data and is presented later on when the title
is dragged to create a link. If the XSpO returns the word "CLEAR" from the
function call, then the list box is cleared and the new list becomes its only
contents. Otherwise, the new links are added in front of the existing links.

 The following is the complete text of an XSpO that duplicates the existing Web
Explorer Link Manager function. This file is distributed with SpHyDir and may
be adapted to support other quicklist formats.

/* XSpO version of Web Explorer Links */
arg object
if object<>"NEW_LINKS" then return

exploreini=Value("ETC",,"OS2ENVIRONMENT")"\EXPLORE.INI"
strm_status = Stream( exploreini, "Command", "Open Read" )
if strm_status="READY:" then
  do while lines(exploreini)>0
  line=linein(exploreini)
  if line="[quicklist]" then leave
  end
  do while lines(exploreini)>0
  line=linein(exploreini)
  parse var line "quicklist=" title
  if title="" then return
  url=linein(exploreini)
  queue url title
  end
return "CLEAR"

 The Workarea also supports XSpO's, but the only function currently supported
is to add a Link to an object. Dropping this type of XSpO on a Workarea object
is simpler than adding the link to the Link Manager list and then dragging the
list item over and dropping it on the object. A supplied XSpO uses some rather
"dirty" logic to find the current URL in Web Explorer (you have to enable the
WE option that displays the URL in a box at the top of the window). Dropping
this XSpO on a paragraph, point, or image puts a link to whatever page is
currently being displayed in WE (without requiring that the page be added to
the Quicklist).

arg object
  if wordpos(object, "NEW_LINKS WORKAREA")=0 then return

  desktop = "?HWND1"
  app = VRGet( desktop, "FirstChild" )
    do while app<>""
    title=VRGet(app,"Caption")
    if substr(title,1,16 )="IBM WebExplorer " then
      do
      title=strip(substr(title,19),"B")
      kid= VRGet(app,"FirstChild")
      url=Searcher(kid)
      if url<>"" then queue url title
     if object="WORKAREA" then return "LINK"
      return "ADD"
      end
    app = VRGet( app, "Sibling" )
    end
return ""

Searcher: procedure
  parse arg w
  do while w <> ""
    if VRGet( w, "Visible" ) = 1 then do
      class = VRGet( w, "ClassName" )
      caption = VRGet( w, "Caption" )
      if class="WC_ENTRYFIELD" then return caption
      subkid = VRGet( w, "FirstChild" )
      url= searcher(subkid)
      if url<>"" then return url
      end
    w = VRGet( w, "Sibling" )
  end

return ""


ΓòÉΓòÉΓòÉ 13. Forms Support ΓòÉΓòÉΓòÉ

 Modern HTML and Web Browser programs allow the user to enter data and make
selections with standard GUI Boxes, Buttons, and Lists. Collectively, these
features are know as "forms" support. There are two steps. First, the author
must design the data entry form using HTML language elements. Secondly, a
program must be written in some supported language to process the data that the
user enters.

 HTML forms provide a subset of the standard GUI dialog features that will be
familiar to users of Visual Basic or other visual programming languages. The
user is presented with a set of single line and multiline text entry fields,
checkboxes, radio buttons, selection lists, and push buttons. The user makes
selections and enters data. Then a push button (or the Enter key) transmits
data to the server.


ΓòÉΓòÉΓòÉ 13.1. Forms Handling Programs ΓòÉΓòÉΓòÉ

 The data entered in a form has to be passed to locally written code that runs
on the Web server machine. For a Unix machine, this program receives data
through the "CGI" protocol. CGI specifies a particular way to pass information
about the request, the remote machine, and the local server environment. Most
CGI programs are written in either C or Perl.

 However, SpHyDir runs in OS/2 and is written in Rexx. IBM has a very nice Web
server package for this environment called GOSERVE. Each arriving request is
passed to a locally customized Rexx filter program running as a subthread of
the server. Whatever efficiency is lost using an interpreted language like Rexx
is gained back by using threads instead of creating a new process for each
request.  Although GOSERVE provides all the necessary forms support, it doesn't
use precisely the same conventions as the CGI interface.  SpHyDir will talk
more generically about a "forms processing program" while other sources would
probably call the same thing a "CGI program" without assuming that there could
be any other kind of server.

 Each GUI object in the HTML form is associated with a variable name. The data
and selections are transmitted as a sequence of "name = value" pairs, where
name is the variable name associated with a field or button and value is the
data typed or the alternative selected. This sequence of name and value pair
must be processed by program that processes the request.

 After the request is processed, the results are sent back to the remote user.
Normally, the format of this result is another HTML file. Frequently, the
response will also have Forms objects. The contents of the response file will
include some insertions based on the results of the previous request.

 Thus a comprehensive tool to simplify Form processing has to solve three
problems:

   1. It must provide the user with an easy way to specify the GUI objects
      (entry fields, buttons, check boxes, and selection lists). SpHyDir does
      this by providing Toolbar of GUI objects just as Visual Basic and VX-Rexx
      solve the same problem with similar toolbars.

   2. It must provide a simple way to decode the incoming "variable=value"
      pairs. The Rexx language (along with some helper functions provided by
      GOSERVE) makes this a trivial task, but it is not a very difficult
      problem in any language.  SpHyDir provides a Rexx "helper" routine named
      SpHyDir_Decode in the SPHYHLPR.VRS file that provides this service.

   3. It must provide a way to insert data into the reply sent back to the
      user.

       Some existing programs generate the entire response with program
      statements:
      SAMPprintf("<TITLE>Response to Your Request</TITLE>\n");/SAMP
      This is tedious, difficult to read, and impossible to validate.

       A second approach scans an HTML file and inserts data:
      SAMP<TITLE>
      %insert TITLETEXT
      </TITLE>/SAMP
      This is slow because it requires a syntax scan during every reply.

       SpHyDir provides (IMHO) a better solution.  The programmer uses SpHyDir
      to create a ordinary HTML file with text and forms objects.  As SpHyDir
      generates the HTML, it separately tabulates the location of strings or
      insertion points that correspond to the various forms variable names.  If
      the file is fetched as a *.HTM file, then everything goes out as it was
      designed. However, if a forms processing program wants to send the file
      back as a reply to a previous query, then it can call a helper routine
      (SpHyDir_Reply in the supplied Rexx-GOSERVE example) that extracts from
      the program the current value of all variables whose names correspond to
      the variable names assigned to the forms objects in the HTML file.  These
      current values from the program are inserted into the file as it is sent
      back to the user and populate the fields, boxes, buttons, and lists that
      are available for the next reply.

  Rexx is a particularly attractive language in which to do this kind of
 programming because access to its variable names and symbol table is simple
 and flexible. The combination of SpHyDir, Web Explorer, GOSERVE, and
 Rexx-based Forms processing programs provides a simple but powerful Web
 development environment. However, local requirements will soon make it
 necessary to extend this development environment to real CGI programs running
 on Windows NT or Unix servers.


ΓòÉΓòÉΓòÉ 13.2. Forms are poorly Form-matted ΓòÉΓòÉΓòÉ

 The ambiguities of HTML that cause problems for SpHyDir in normal text are
made worse when Forms are processed. Consider a simple example:

 The top line is a simple entry area for typed characters. The second line
presents three alternatives using the "radio button" metaphor (only one can be
selected, and choosing one deselects the others). The last line is a check box
that can be set or cleared by clicking it.

 In visual programming languages, such as Visual Basic, each radio button or
check box has a "caption" defining the text that follows the box or button and
describes the option. In this example, the captions are "HTTP", "Gopher",
"FTP", and "BINARY". Occasionally, but less frequently, a Text Entry object
would also have a caption (in this case "Identify a Server Machine:"). In any
case, the Caption is an attribute of the object and is part of the object
definition.

 However, in HTML a box or button object is just the box or button itself. Any
caption text is just ordinary "paragraph" text. There is no limit on its size,
contents, or structure. Just as SpHyDir had to invent a chapter and section
structure by looking at Heading tags, it must also construct GUI programming
objects by assuming that the captions are reasonable and obvious.

 All GUI objects (entry areas, buttons, boxes, and selection lists) must be
inside a FORM area. However, the form can also contain ordinary text, images,
ordered and unordered lists, sections, and everything else that is valid in a
document. Unlike a paper form, where the instructions are usually separate so
that the input can be easily processed, an HTML form can have the input widely
scattered through the text. When the form is submitted, only the values of the
entry fields and the selections made by the user are transmitted, not the
captions and text.

 A user will become confused, however, if each Radio Button option is
accompanied with three screens full of explanation. The relationship between
the buttons would be lost. Therefore, it is probably best if each field or
button has a short clean caption. Furthermore, based on a universal GUI
practice, the caption of a data entry area would ususally come in front of the
entry field (as the example "Identify a Server Machine:"), while the label of a
check box or radio button comes right after it.

 In normal text, most of the SpHyDir objects start a new line. This is not true
of Form Objects. If a browser can fit the next button on the same line, it will
do so. The only way to be sure that there is a line break is to create a
paragraph (<P>) tag.

 In normal text, every SpHyDir object is "paragraph sized" or larger. SpHyDir
knows to create a line break when paragraphs, ordered lists, and headers are
encountered. But several forms objects may have to go on the same line. One
idea would be to create a higher "grouping" object to which they might all
belong, but SpHyDir is based on the principle that format should follow from
document structure, and it seems wrong to create artificial structure to
duplicate a format feature.

 It has always been possible to create an empty paragraph. Simply drag the
Paragraph tool to the document to create a new paragraph, then type nothing in
it. When the HTML is generated, this creates a line of the form:
<P> </P>
in the output. The problem is that SpHyDir ignores empty paragraphs when
reading in normal text, so this structural element is lost when the document is
re-edited. SpHyDir relaxes this rule, and will preserve empty paragraphs when
they are encountered inside a Form structure. A form designer should drop an
empty paragraph object between any two buttons, fields, or boxes that are
supposed to appear on different lines.


ΓòÉΓòÉΓòÉ 13.3. Form Tools ΓòÉΓòÉΓòÉ

 The Toolbar contains template objects for all the GUI elements that HTML
supports. If this document is viewed using a Web Browser, examples of the Forms
objects will appear in the document. They are not connected to any processing
program at this time. Attempting to submit anything from these form objects
will return an error message. Just go back to the document and continue. Forms
examples will not appear in the INF version of this material, because forms are
not supported in IPF.


ΓòÉΓòÉΓòÉ 13.3.1. The Forms Tool ΓòÉΓòÉΓòÉ

 Interactive form elements are valid only within a section of a document maked
as a Form. The Form Tool creates such a section. Drag the Form Tool over and
drop it anywhere in a document except within another Form. This creates a new
level in the document tree. All other form objects, and all ordinary document
objects, are valid within a Form section.

 Each form must be associated with the name of a program that the server will
run to process the data from the form. When the form object is created or
selected, an entry area becomes visible into which a program identifier can be
typed. The exact format for program identifiers depends on the type of server
being used. On a Unix server, this is usually the name of a program in the
"cgi-bin" subdirectory, as in "/cgi-bin/program". On other systems, this may be
any program name.


ΓòÉΓòÉΓòÉ 13.3.2. The Single Line Text Entry Field ΓòÉΓòÉΓòÉ

 The Entry Field Tool creates a "single line" text entry area. This is the type
of field that would be used to read simple data like a name, phone number,
E-Mail address, or book title.

 The caption for the Entry Field Object is treated like paragraph text. When
the field is created, or when the object is double-clicked, the standard Text
Edit window opens. Although the user can type an arbitrary amount of text into
the window, the caption should generally be short. When the object is closed,
it is the caption and not the default field contents that appears next to the
Entry Field Object in the SpHyDir Workarea.

 An Entry Field object has attributes. When the object is created or is
selected by clicking with the first mouse button, a set of fields becomes
visible in the upper right section of the Workarea. Yes, these are also "entry
fields", but they are part of the VX-Rexx application and not the HTML Forms.
Many of these attributes are common or similar across all the Forms objects.
For each type of object, the appropriate set of fields becomes visible.

 The first (top) attribute is a variable name. When the form is submitted, the
text entered into the field will be transmitted as the value of a "name=value"
sequence. For example, entering "Yale University" into a field with this
definition would transmit the sequence:
SAMPsampentry=Yale University/SAMP
to the Web Server. This value, along with any other values from other fields in
the form, will be passed to the program designated by the FORM object to handle
the data.

 In many cases, the Text Entry field will be initially empty and the user will
be expected to type a value in. HTML allows an initial value to be transmitted
from the server. This string will appear in the Text Entry field and will be
transmitted back as its value if the user doesn't change it. A static default
value can be entered in the second (long middle) field.

 A default value can also be generated dynamically from a previous Web Server
program that requested transmission of the current page. To allow this, SpHyDir
creates a "symbol table" external but connected to the HTML source for the
page. This table is attached as an Extended Attribute of the file in the OS/2
or NT file system, and is stored less elegantly as a separate file in Unix. For
this field, the table would contain a line of the form:
ENTRY SAMPENTRY nnnn 18
Where "ENTRY" is the type of forms object, "SAMPENTRY" is the name of the
variable associated with the field, "nnnn" will be replaced with the byte
offset in the field of the default value (in this example, the offset of the
"S" in "Sample Entry Field"), and 18 is the length of the static default value.

 An Entry field generates HTML text of the form:
<INPUT TYPE="TEXT" NAME="SAMPENTRY" VALUE="Sample Entry Field" SIZE="30"
MAXLENGTH="30">
If no static default text is provided, a VALUE="" is generated to simplify the
insertion of a dynamic default text from the symbol table. SpHyDir helper
routines simplify the insertion of dynamic default text from forms processing
programs.

 The last attributes of an Entry Field include a checkbox to declare that this
is a Password field (so the data typed in should be masked out) and two length
fields. The first length specifies the size of the box, the second field is the
maximum amount of data that can be typed into the box. If the maximum amount is
larger than the size of the box, or is omitted all together, then when the user
gets to the end of the box the previous characters shift left to make room.


ΓòÉΓòÉΓòÉ 13.3.3. The Multiline Entry Field ΓòÉΓòÉΓòÉ

 A Multiline Entry (MLE) Object generates an area with scroll bars into which
the user can type an arbitrary amount of text. This is ususally used for
freeform feedback (to send comments, suggestions, or complaints to the author).
It can also be used to annotate information.

 An MLE is a large object, so it has no formal caption. If you want to describe
it, do so in the paragraph that preceeds or follows it. The contents of the MLE
object, which can be edited by double clicking the object and opening the Text
Edit window, is the static data that will appear as a default within the MLE
window when it is displayed on the remote screen.

 An MLE field in a Web Browser will not support font changes or hypertext
links. SpHyDir may eventually get around to disabling these options in the Text
Edit window. Meanwhile, when editing default text for an MLE, don't use
italics, bold, or any of the other format tags.

 An MLE is associated with a variable name. When the form is submitted, the new
content of the MLE will be assigned as a value to that variable name. SpHyDir
creates a entry in the Variables Extended Attribute with the type of "MLE", the
name of the variable, the location of the start of the default text, and the
length of the static default text. This can be used by the helper routine to
insert an alternate string dynamically into the form as it is being
transmitted. The content of such a string would be whatever HTML declares to be
valid between the <TEXTAREA> and </TEXTAREA> tags.

 An MLE also has a size specified as rows and columns. They appear in the two
lower numeric boxes and can be changed to fit the application needs.


ΓòÉΓòÉΓòÉ 13.3.4. The Checkbox Tool ΓòÉΓòÉΓòÉ

 The Checkbox Tool creates a standard GUI Checkbox object. A caption follows
the Checkbox to describe the option. The caption is regarded as the "contents"
of the object and may be edited by double-clicking the checkbox object to open
the Text Edit window. Unlike the MLE, the checkbox caption is ordinary text and
may contain emphasis (bold, italics) or hypertext links.

 The Checkbox is associated with a variable name. When the checkbox is seleted,
a "name=ON" pair is returned. A static default value can be set by clicking the
"Checked" option when the checkbox object is currently selected.

 A Checkbox has a variable name. It can also be statically assigned an initial
value by checking the "Checked" checkbox for the Checkbox object. [This is
about the fourth pass through this document, and it just gets worse as it gets
more precise.]

 There are different ways to express the value of a Checkbox variable. As a
number it would be 0 or 1. In other contexts it might be "YES" and "NO" or
"TRUE" and "FALSE". In HTML, the checkbox is turned on by adding the keyword
"CHECKED" to the tag that defines it:
SAMP<INPUT TYPE="CHECKBOX" NAME="NOMAYO" CHECKED>/SAMP
However, when the user submits the form and the box is checked, the variable
name is returned with the value "ON" as in:
SAMPNOMAYO=ON/SAMP
Clearly this is a muddy area and may be subject to further refinement.

 When SpHyDir generates the Variables EA for this field, the entry will have
the form:
CHECKBOX NOMAYO nnnn 7
Where the type is CHECKBOX, the variable name is NOMAYO, nnnn is the byte
offset in the file of the blank following the variable name, and the length is
either 0 or 7 since the word "CHECKED" has seven letters and is either present
or omitted.


ΓòÉΓòÉΓòÉ 13.3.5. The Radio Button Tool ΓòÉΓòÉΓòÉ

 The RadioButton Tool is used to specifiy one of a set of mutually exclusive
alternatives. Only one can be selected, and selecting that option automatically
turns off the other alternatives.

 The Web server is:

 The caption of the RadioButton, which can be edited by doubleclicking the
object to open the Text Edit Window, is ordinary text and may have emphasis and
hyperlinks. However, if the captions are large enough so that the alternatives
cannot all fit on the same line, the user must provide additional HTML markup
(such as the <HR> tag) to group related buttons together.

 When a RadioButton Object is created or selected, three fields become visible
at the top of the Workarea. The first field provides the variable name for this
button (and implicitly all other buttons that are part of the same grouping).
The second field contains a string that will be assigned to the variable when
this particular button is selected. Under these fields, a Checkbox allows this
particular button to be selected as the default for the group. To be
meaningful, only one button in each group can be checked as the default.

 In Visual Basic and VX-Rexx, radio buttons have to be collected in a Group Box
to be related to each other. In HTML forms, radio buttons are related by having
the same variable name. The value assigned to that variable name distinguishes
one button from another.

 Radio Buttons pose a problem for the symbol table in the Extended Attribute.
Up to this point, every HTML object produced one entry with its own variable
name, and there was one insertion point for the value of that variable.
However, each Radio Button has a tag location, and to override a static default
with dynamic information from a program, the "CHECKED" attribute in all of the
tags has to be manipulated. So for every radio button, the Variables EA gets a
separate entry:
SAMPRADIOBUT SERVER=UNIX nnnn 0
RADIOBUT SERVER=OS2 nnnn 0
RADIOBUT SERVER=NT nnnn 0/SAMP
The "nnnn" in each line is the offset in the file of the blank that follows the
name and either preceeds ">" (if the length is 0) or "CHECKED>" (if the length
is 7). An acceptable strategy is to process these entries in order, checking
the current value of the program's "SERVER" variable against the possible
matching strings "UNIX", "OS2", and "NT". If a match is made, then "CHECKED" is
inserted into the HTML file, if not and the length is 7 then the old "CHECKED"
string is removed.


ΓòÉΓòÉΓòÉ 13.3.6. The Spin and Listbox Objects ΓòÉΓòÉΓòÉ

 A Spin field displays a sequence of alternatives within a single window. CUA
rules suggest that the Spin choice is appropriate when the alternatives are
ordered, but the Spin object also allows a small number of alternatives to be
meaningfully displayed in a small space. In HTML terms, a Spin object
corresponds to a SELECT tag with no SIZE parameter.

 Get a dozen eggs:

 An interesting feature here is that Web Explorer seems to mess up the order
and selection rules. It defaults to the last alternative chosen, when the
standard clearly says that the first is the default, and it seems to get
"bigger" and "smaller" reversed.

 A Listbox provides another way to display alternatives. It is probably more
suitable if the number of options is large. This Object is also a SELECT list,
but with the SIZE parameter specified.

 For both selection objects, a static list of alternatives can be entered
through the Text Edit window by doubleclicking the object. Each alternative is
typed on a separate line. Press Enter between alternatives. Do not use
character emphasis or try to assign links to the alternatives.

 List alternatives can be assigned dynamically by creating an array of
character strings. For example, in Rexx a set of alternatives might be
specified by the sequence:
account.0=3
account.1="Checking"
account.2="Savings"
account.3="Money Market"
If the user chose the second option, this would then feed back as the string
"account=Savings" which the Rexx helper routines would use to assign the string
"Savings" to the variable ACCOUNT in the next program. [A note to those who are
not Rexx wizards, the scalar variable ACCOUNT is completely independent of the
"stem" ACCOUNT. (with the trailing period). This strategy uses the stem to hold
the list of alternatives, and uses the scalar to designate which alternative
was selected.]


ΓòÉΓòÉΓòÉ 13.3.7. Pushbuttons ΓòÉΓòÉΓòÉ

 After filling in the required fields, the user triggers an action on the
server by pressing a Pushbutton. If no Pushbutton object appears in the form,
pressing the Enter key may also transmit data.

 A default Pushbutton with no options is labelled "SUBMIT". It will trigger
transmission of the data, but will add nothing to the datastream itself.
Multiple "SUBMIT" buttons would be indistinguishable from each other.

 Each Pushbutton has attributes:

 The left entry box is the name of a variable. The right box is both the value
assigned to the variable when the button is pushed and also the label placed on
the face of the button.

 When an explicit variable name is assigned to a Pushbutton object, an entry is
also made in the Variable Extended Attribute. It identifies a type of
"PUSHBUT", the variable name, the offset of the static value string, and its
length. If the helper functions are used, they will check for a variable of the
same name in the calling program and will substitute its current value in the
Pushbutton definition. This means that the caption of the Pushbutton can be
dynamically changed by the calling program.

 A special version of the Pushbutton control is established if the Hidden
attribute is checked when the button object is selected. A Hidden field doesn't
appear on the user's screen, but it is passed back as part of the data stream
to the next program. This can be used to pass a handle, transaction ID, or
other state information from one screen to the next.


ΓòÉΓòÉΓòÉ 14. Bugs and Restrictions ΓòÉΓòÉΓòÉ

 SpHyDir currently ignores tags nested within a Heading and may lose characters
after the start of such a tag. It is important for Headings to remain pretty
much plain text so that they can appear reasonably in a Table of Contents.
There is a move in HTML 3.0 to allow an IMG SRC to appear as part of the Hn tag
instead of as part of its contents. This seems a more reasonable direction.

 The current design may require you to perform several operations to completely
initialize a new object. After dropping a SECTION from the toolbar, you should
type in a Header. The Section itself is a SpHyDir concept, HTML only recognizes
the Header text. If you type nothing, then SpHyDir might generate "<H2> </H2>"
which makes little sense and might be invalid. But currently SpHyDir doesn't
force you to actually type a header, and it may not go back later on and
"sanity check" the document to detect errors before generating HTML. So be sure
to finish what you start. This includes remembering to drag a GIF file over to
associate something with every Image object you create.

 VX-Rexx 2.1B has a bug when moving a tree of records in a container. Suppose,
for example, you decide to move one section in front of another. You can click
on the sections to collapse the tree so that just the two icons are showing.
You can then drag the second icon in front of the first. However, when you
re-expand the tree, you will see that elements two or three levels down in the
tree have been incorrectly reorganized. For now, the safe way to move large
sections of the document is to mark them with Alt-L and move them through the
SpHyDir special "Clipboard" window.

 You cannot drag the contents of the Web Explorer screen directly into the
SpHyDir workarea. This is not a big problem, because SpHyDir requires that HTML
files be inside the HTMLLIB anyway. So first drag the WE screen to one of the
folders inside the library, then probably rename it to something useful, and
then edit it with SpHyDir.

 SpHyDir saves the position and size of its subwindows.  SpHyDir currently
doesn't save font or color changes for windows, so it should not be
reconfigured by dropping System Setup Palette objects.

 Two types of object go in front of things: the Horizontal Rule (HR) and a
Target. However, when you put either in front of a section, the tree structure
shows the objects as if they were part of the previous section and not an
introducer to the new section. That wan't intended, but it would be almost
impossible to change. Treat it as a permanent feature.


ΓòÉΓòÉΓòÉ 15. Supported and Unsupported HTML ΓòÉΓòÉΓòÉ

 SpHyDir explicitly supports the HTML, HEAD, and BODY document structure tags.
SpHyDir reads, remembers, and recreates the TITLE. SpHyDir will generate LINK
tags that reflect relationships between documents in the tree. Except for
TITLE, all information in other HEAD tags (ISINDEX, NEXTID, LINK, BASE, META)
would be lost.

 SpHyDir supports H1...H6 when they are really used as the heading of a section
and not just to get big characters.

 SpHyDir will normally generate paragraphs within a formal pair of <P> and </P>
tags. Since many existing documents do not contain ending </P> tags, SpHyDir
does not expect or require them.

 UL, OL, and DL lists are supported along with LI, DT, and DD elements. Nested
lists are fine. It is not entirely clear just what other structural elements
are reasonable inside lists. A lot of NCSA documents seem to mix in ordinary
paragraphs along with the expected LI tags. Currently, SpHyDir lets you put
lots of stuff in a list, but it will absolutely refuse to generate a document
if it finds a Section nested inside any List alternative.

 It is possible to have any number of hypertext links from a Paragraph,
preformatted text, a list point (in an ordered or unorded list), or the body of
a definition.  It is possible for the Definition Term (<DT>) to have one
hypertext link linking the entire term to another location or document.  No
hypertext link can be made from a section heading.

 The Horizontal Rule <HR> tag is supported. There is no icon or tool for it.
This is not because it is hard to come up with an icon for a horizontal line.
About ten seconds with the icon editor will produce it. To add an HR tag to a
document, select the object you want it to proceed in the workarea and press
Alt-H.

 The PRE tag is recognized. The WIDTH attribute is not scanned and will not be
regenerated. Preformatted text is similar to ordinary paragraphs, except that
line breaks and multiple embedded spaces are preserved.

 Hypertext labels pose a problem for SpHyDir and for HTML and IPF. First, HTML
is changing the syntax. The current approach <A NAME=xxx> assigns a label to a
string. The HTML 3.0 standard changes NAME to ID and allows the "ID=name"
attribute to occur inside the H1..H6 and P tags as well as in an A tag. IPF
only allows headings to be the target of a jump, and in a HLP file the ID has
to be a number (the Resource ID). SpHyDir has decided to split the difference.
When a current HTML <A NAME=xxx> tag is encountered, it is used to construct a
Target object. However, the Target is moved to the front of the current
Paragraph or section. It is then generated as an <A NAME=xxx> prefix to the <P>
or < Hn> tag (a construct supported by current HTML 2.0 browsers). Later on,
when HTML 3.0 is established, the label can migrate inside the P or Hn tag as
the new ID attribute. Meanwhile, the IPF Resources are handled outside of HTML
syntax because they are not a part of HTML.

 A Hypertext link is created from any <A HREF=...> tag encountered. SpHyDir
requires that the filename or URL not contain any blanks. Other attributes
(REL, REV, TITLE) are ignored.

 The IMG tag may have SRC, ALIGN, and ALT attributes. Currently, only the LEFT
Netscape extended alignment is supported, and that is just a test. An IMG file
must have a type of GIF for HTML and BMP for IPF. The free IBM utility GBM can
be used to convert GIF to BMP.

 ADDRESS is not explicitly supported. When encountered, it is currently
embedded in the text of a paragraph as if it were character emphasis. When
SpHyDir generates HTML, it includes boilerplate from the HEADER and TRAILER
files, and that will generally be the source of the author's name, E-mail, etc.
The ADDRESS tag would typically be used in these files and not in the body of
the text.

 BLOCKQUOTE is sometimes documented as obsolete, and sometimes as current. The
HTML 3.0 standard wants to rename it BQ. Previously it was unsupported as a
questionable feature.  Now its omission is regarded as a bug that must be
shortly fixed.

 The &, <, and > entities are converted to ordinary characters on input
and are regenerated on output. Currently no other entities are supported. It is
the direction of SpHyDir to find a way to support direct editing of ISO 8859-1
characters rather than requiring them to be edited. SpHyDir uses some PC-only
graphic characters as delimiters for hypertext links and character emphasis.

 Forms support is under development. The following information about forms is
tentative (as of March 1) and represents work in progress.

 The FORM and /FORM tags generate a section of the document represented by the
FORM object. Only the more generate POST method will be supported (using GET
with forms is sometimes possible, but there are length restrictions that appear
to be more trouble than they are worth). The ACTION can be the name of a CGI
program for a Unix server, or a name that GOSERVE will recognize as a supported
operation on OS/2.

 At the moment, there is a shortage of room on the toolbar, the SUBMIT and
RESET buttons are ignored on input and are generated automatically on output at
the end of the FORM.

 Within the FORM area, one can include any other document objects, including
Sections, Images, Lists, and links. There is one change to SpHyDir document
management. All the previously discussed document objects operate at the level
of a Paragraph or larger. Form objects have an integrity of their own, but
several check boxes or radio buttons can appear together on the same line. To
accomodate this behavior, SpHyDir allows empty paragraphs to exist within a
FORM.

 A user has always been able to generate an empty paragraph (<P></P>) by
dragging a paragraph object to the workarea but then adding no text to it.
However, empty paragraphs read in during the HTML scan would be ignored.
Essentially, the empty paragraph was treated as a user error that SpHyDir might
choose to ignore. However, it turns out that there is no more acceptable way to
delimit line breaks in a form. During the HTML scan of an externally generated
FORM, SpHyDir will create empty paragraph elements when <P> tags are
encountered between form elements, and it will then generate them as:
<P></P>
<INPUT TYPE="RADIO" NAME="PROT" VALUE="HTTP"> HTTP
<INPUT TYPE="RADIO" NAME="PROT" VALUE="GOPHER"> Gopher
<INPUT TYPE="RADIO" NAME="PROT" VALUE="FTP"> FTP
<P></P>
<INPUT TYPE="CHECKBOX" NAME="BIN"> BINARY
<P></P>
In this example, the three radio buttons will appear on one line, and the
checkbox will appear on a separate line following them. Graphically, each line
of this HTML appears in SpHyDir as an object, with three empty Paragraph
objects, three RadioButton objects, and one CheckBox object in the order given
above.

 Now we get to one of those wild generalizations on which the whole concept of
SpHyDir depends. Forms items have captions. You know that, and I know that, but
HTML doesn't know it. In HTML, a check box is just the box:
<INPUT TYPE="CHECKBOX" NAME="BIN"> BINARY
Syntatically, the last word "BINARY" is outsize the tag. It is just text. If
SpHyDir didn't make any stuctural assumptions, it would just appear as ordinary
paragraph text. Now we want it to have all the freedom of text (so you edit it
with the Text Editor Window, and you can link to it by dropping Link Manager
links on it, and it opens the Hotword Window). But, the document view becomes
terribly fragmented if this line generates two objects (a CheckBox object for
the tag, and a Paragraph object for the caption).

 So SpHyDir makes the unsupported generalization that the caption for an Entry
Field goes in front of the field, and the caption for a CheckBox or RadioButton
goes after the button. Multiline text input areas and Selection Lists don't
have a caption (or if they do, it appears as a paragraph above or below the
larger areas). Thus Entry, CheckBox, and RadioButton objects have a text
component that appears in the SpHyDir work area like paragraph text to the
right of the object. The text of the caption can be edited or linked exactly as
if it were in a Paragraph object. When the HTML is generated, however, the
Entry object text goes in front of the <INPUT> tag, and the CheckBox and
RadiButton text goes after it.