═══ 1. The SpHyDir Project ═══
SpHyDir is an Object Oriented tool that builds documents for Web Browsers such
as Netscape, Mosaic, and Web Explorer. With SpHyDir the user concentrates on
the important issues of content and overall document structure. Since SpHyDir
automatically generates the HTML (Hypertext Markup Language), it is possible to
generate flawless Web documents without studying obscure syntax diagrams.
A Web document is an ordinary text file that contains formatting instructions
in the form of HTML "tags". Normally, these tags are processed by a Web Browser
(such as Netscape Navigator) and are then viewed on a computer screen. If the
final image "looks right" then many authors are satisfied. This is resonable
when producing a single personal home page.
A library of information should adopt a common document structure. Similar
information should have a common format. The same type of information should be
presented in the same way on all files. The reader should be able to jump to
releated information, or to view a sequence of documents covering a larger
topic. Traditional printed books solve this problem with chapters, page
numbers, a table of contents, an index, and the editorial control of a
professional publisher.
SpHyDir is the Structured Professional Hypertext Directory Manager.
It is Structured because it sees a Library that contains Documents that
are made up of interlinked HTML Files. Each File contains Sections
(Chapter, Topic, Appendix) which in turn contain figures, paragraphs,
lists, and tables. Each of these document elements is presented as an
Object and the overall document is structured as a tree of such Objects.
It is Professional because it makes it easy for the author to control
more of the advanced Web features than any other tool. Simple HTML
editors and Word Processing packages insert only the most basic tag
options. A professional job requires more: alternate text should be
provided if the user chooses not to fetch images automatically, image
sizes should be included in each reference so the browser can operate at
maximum efficiency, parameters should be used to generate special effects
efficiently rather than transmitting images, etc.
It is Hypertext because links between documents and to other files can be
made through simple Drag-and-Drop. To build a link to a remote Web
resource, just display the resource in Web Explorer. SpHyDir will pick
the URL reference out of the WE window and attach it to text or to an
image in the document under construction.
The Directories of an HTML library contain related files. An editor or
word processor handles one file at a time. SpHyDir manages the structure
of interrelated files and automatically generates navigational
information such as Next and Previous pointers.
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.
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 ═══
SpHyDir is updated irregularly. Generally something is posted at the start of
the week and critical bug fixes can be posted at any time. Check here for the
latest information.
═══ 2.1. June 26 ═══
On request, the IPF generation has been brought back to its prior level of
support. SpHyDir should be able to generate INF files for HTML 2.0 constructs.
At this time there is no attempt to map HTML 3.0 attributes to IPF or to try to
deal with Tables and other new features. The SpHyDir.INF file is now up to
date.
Characters that are in the Latin-1 set (and therefore in Code Page 850) should
display correctly in the INF file. If someone configures the ENTITIES, CHARIN,
and CHAROUT tables for another code page, sets CODEPAGE in CONFIG.SYS, runs
IPFC, and does not get proper display of characters in any standard Latin IBM
code page, please report back to the author.
═══ 2.2. June 21 ═══
[Note: a defective version of the June 21 code was posted between Midnight and
11:00 EDT on that date. Please replace it with the corrected version]
═══ 2.2.1. Editing Internation Character Sets ═══
A World Wide Web has to deal with international character sets. Unfortunately,
there are more characters in the World than can be easily handled in any simple
one-byte encoding. Three solutions are available.
1. Unicode provides a two-byte character set that can handle all the Western
languages and Chinese, Japanese, and Korean. This is the ultimate
solution, but it is new and there are no good tools available.
2. There are a family of one-byte character sets that provide coverage for
most languages. Since no single code can include the Western "Latin"
alphabet and Hebrew, Arabic, and Cyrillic, the ISO proposed a set of
8859-x (where x=1...n) character sets covering each major alphabet group.
The 8859-1 (also called "Latin 1") character set covers all the languages
of Western Europe (and America, Australia, etc.). Starting with HTML 2.0,
the Web standards hold that an HTML document is assumed to be in 8859-1
unless stated otherwise. The HTTP and some of the HTML
", the SpHyDir approach to HTML
migration is to do the thing "every which way" it can be done so that every
browser must precisely what is intended. Of course, there is no way to fake the
advanced features that caused FIG to be invented in the first place. The
browsers will just have to catch up. However, it is possible right now to
generate a FIG that can replace standalone and text-wraparound images:
CODE/CODE
1. An HTML 3.0 graphical browser will understand FIG, display the GIF file,
and ignore the contents.
2. An HTML 2.0 graphical browser will not understand FIG and will ignore it.
It will not ignore the contents, and so will process the IMG tag. Again
the GIF file is displayed.
3. A non-graphical browser may or may not understand FIG, but in any case
will ignore it because the browser doesn't display images. It will then
look at the IMG tag and again decide not to display the GIF, but it will
print the ALT text.
Although the GIF file appears in both the FIG and IMG tags, the two are
mutually exclusive. One or the other will be processed, but not both. As to
the ALIGN=LEFT, this is valid for a FIG in HTML3 and is a widely supported
Netscape extension of IMG in HTML 2.
SpHyDir 1 did not deal with IMG tags that were embedded in the middle of a
paragraph or Heading. SpHyDir II accomodated such IMG tags by creating another
"dingbat" sequence in the text. The 0x08 character, which looks like a box
with a hole, or roughly "[o]", is used to start and end an IMG reference.
Between these two dingbats are the name of the GIF file, then optionally a
blank and the alternate text.
However, in the first cut SpHyDir II continued to extract IMG tags from the
start of a paragraph (or when they form a paragraph by themselves). They
become IMG objects. Later on, SpHyDir II tries to decide if they should be
merged back into the paragraph that follows them.
The intent is to change this. Images that are contained in a paragraph of
their own, or that have ALIGN values LEFT or RIGHT will be extracted as before
to for a separate object. However, the object will then be regenerated as a
FIG+IMG construct as described above. This will allow the Image Object to
begin to have Properties derived from the more powerful FIG tag, instead of
limiting it to the current IMG Properties. Conversely, IMG tags that fall at
the start of a paragraph containing other text, and that have ALIGN values of
TOP, MIDDLE, or BOTTOM, will be treated as embedded images and will be
represented by the 0x08 dingbat character sequence.
═══ 2.6. June 14 Update ═══
The Text Edit Window now allows drag and drop. Position the cursor or select a
phrase of text. Now
Drag and Drop a GIF file anywhere on the Text Edit Window. This will
generate an "embedded IMG". If no text is selected, the dingbat character
and file name will be placed at the cursor position. If text is selected,
then the selected text will become ALT alternate text within the
dingbats.
Select some text. Hold down Ctrl-Shift and drop any file from the HTML
library on the Text Edit Window. The previously selected text becomes a
hypertext link to the file. Previously it was necessary to save the text,
Link-Drop a file on the Paragraph Object in the workarea, and then select
the text from the Hotword Selection window. Allowing links to be formed
directly in the Text Edit window simplifies this process. Note that links
created this way are saved only if the rest of the edited text is saved.
Pressing the Cancel Button or closing the Text Edit window cancells the
new Links as well.
Select text and drop a URL Object created by Web Explorer from the
Workplace on the Text Edit Window. The selected text will be converted to
a Link to the remote resource represented by the URL.
Do not select text. Leave the cursor at an insertion point in the
paragraph (usually after a blank). Drop a URL Object created by WE on the
Text Edit Window. The title of the remote resource is inserted at the
point of the cursor and becomes a hotlink to the document itself.
Unfortunately, it is not possible to drop Link Manager list items on the
Text Edit Window. To maintain the integrity of the data being edited, the
Text Edit Window locks up the underlying Workarea until the edit
completes. This also blocks the Link Manager from functioning. So links
have to come from the WPS environment, or save the text and use the Link
Manager as it has traditionally been used.
Extra blank spaces and lines after the
,
, and
tags were removed.
They were errors picked up by Netscape producing undesired results.
SpHyDir now declines to insert some of ending tags that nobody else bothers to
generate. Tables generated too many ,
, and tags. It made the
HTML ugly and hard to read.
The temporary dialog for new Tables has been replaced by a more polished
dialog box. Enter the number of rows and columns and select by a checkbox if
they are to be labelled.
Select a Table Row Object. Click the Second Mouse Button. Select Create
Another from the popup menu. A new row is created with the same number of
label and cell objects as the previous row. [Adding a new column is harder and
is left to a later date.]
When generating an Ordered or Unordered list, SpHyDir II has added an extra
step because List Points no longer contain text. One might have to drop a new
Point on the list, then go back and drop a new Paragraph on the Point. A
shortcut is to popup the Second Mouse Button window for the previous Point and
choose Create Another. This not only creates another Point object, but it also
creates another Paragraph under it and opens the Text Edit window directly.
More generally, Create Another populates the new Point with another object of
the same type as the first object contained in the old point, so the trick
works for Points of Images as well.
Forms bugs caused by rewrite: TYPE did not default to TEXT, NAME attribute
generate twice, SUBMIT incorrectly genned as HIDDEN.
═══ 2.7. June 12 SpHyDir II ═══
SpHyDir II now appears stable enough to remove some of the disclaimers. There
are certain to be problems with the new HTML 3.0 tags that nobody is using, but
more bugs have been fixed in the old code than seem to be problems with the
new. SpHyDir II is now the "standard" distribution. Where the old code is
mentioned, it is called "SpHyDir 1". The documentation has been updated.
A user had problems with the small characters. SpHyDir now remembers the WPS
font that has been dropped on the Workpace, Properties Table, Edit Windows, and
Link Manager. The Link manager window can now be widened.
═══ 2.7.1. Entity Syntax ═══
Newer versions of the HTML standards pointed out a number of details about
Entities. An ampersand is only regarded as a possible entity if it is followed
by letters or numbers. The sequence "A & P" is legal. An entity doesn't require
an ending ";" except to separate it from characters that could be part of the
entity name. "A & P" is also valid. SpHyDir now recognizes these forms,
though on output it always generates the full "A & P" in the output HTML.
═══ 2.7.2. Target Objects become ID Property ═══
After an initial false start, SpHyDir 1 support for Targets (the object
corresponding to the HTML tag) became stalled. The problem is that
HTML standards and use permitted the tag to include text and Headings.
Unfortunately, this might mean a construct of the form:
CODEthe end of one topic.
On a completely unrelated matter, /CODE
This is perfectly legal HTML, but any attempt to make structural sense out of
it is hopeless.
HTML 3.0 presented a much better idea. Labels can be assigned to headers or
paragraphs with the ID attribute. This presents a Hypertext label whose
location and purpose is unambiguous. Unfortunately, ID is not widely supported.
SpHyDir II takes its inspiration from the "Recommended" syntax of HTML 2 and 3.
"Recommended" practice holds that an anchor should go inside a Header rather
than including the header. This would produce
CODE
/CODE
One big advantage is that this syntax is effectively interchangeable with the
preferred (but currently not widely supported) HTML 3 construct:
CODE
Now For Something Completely Different
/CODE
Now a reasonable strategy appears. It eliminates ambiguity, gets rid of the
Target object (which was cute but a problem), and provides for the sane
migration from HTML 2 to 3. First, ambiguous structure is resolved by asserting
that legacy HTML should have been following the Recommended practice. The tag is logically associated with the very next thing that follows it
no matter where the is located. The Name, however, becomes an attribute of
the object that contains the next thing that follows the .
"CODEFred.
One can imagine creating this with an XSpO (an external Rexx
program dropped onto the Workarea), but it would then lose its identity. HTML
3.0 provides the solution with the CLASS attribute.
...
CLASS allows most block tags to be assigned a user specified category name.
CLASS definitions are intended to be hierarchical and there is some implication
in the standard of one class being derived from another with inheritance.
SpHyDir can also make object distinctions based on the value of other
attributes in the tag. For example, the current code distinguishes between
, which is treated as part of paragraph text, and which is
treated as an document object like .
The proposal, then, is to allow new SpHyDir objects to be defined externally.
The new objects would appear in the ToolChest Container window (maybe in the
menu popup if it can be changed dynamically). New objects would be recognized
as the HTML is read in by a new Tag name, the presence of an attribute or a
special value assigned to an attribute on an existing tag, or a CLASS attribute
specification. This is not designed to allow SpHyDir to assign user defined
objects to raw HTML from external sources. The only claim is that SpHyDir
should be able to read back HTML that it had previously written and recognize
and redisplay extended constructions.
Simple user objects could be defined based on the fundamental attributes that
SpHyDir currently potentially assigns to each object (an icon, caption, text
content, name, variable name, variable value, etc.). Objects could also be
define that contain other objects from a certain set of types. In its simplest
version, this will be used to create "macros". For example, a SECTION-like
object could be created named CHAPTER. It would be managed like an ordinary
SECTION, but it would generate something more complicated:
This is the ordinary Section title
[ordinary section contents]
The second time through, SpHyDir II will recognize its own construction by the
DIV tag with the CHAPTER class. It will match up the
ender to determine
the scope. It then has to suck up and discard the boilerplate tags (the HR
SIZE=6 in this case). Although there is a HR object in the SpHyDir vocabulary,
this particular HR is part of the formal expansion of a CHAPTER object and
should not generate a separate object. Except in the HTML that it generates,
the CHAPTER object would then behave in every way as if it were the existing
SECTION object.
Now comes the trickey part. Programmers should instantly recognize that, in
object oriented lingo, this example creates the CHAPTER class as a subclass of
the SECTION class inheriting SECTION's methods (mostly the way to edit titles
and its behavior as a container) but overriding a few methods (HTML parsing and
generation). It seems likely that many new objects will have behavior exactly
modelled on Paragraph, Section, or Image objects. SpHyDir might add a few new
built-in objects on which new things can be constructed. However, full
implementation of the concept will require that everything be rewitten in
Object Rexx, and that will be disruptive enough to be put off until it is
unavoidable.
SpHyDir has not dependencies on other programs, through it is distributed with
a few utilities (GBM, RCS) that have proven useful. However, the new release of
GOSERVE (2.30) is getting too slick to ignore. Since GOSERVE uses Rexx, and
SpHyDir is written in Rexx, a closer relationship should be worked out between
the two programs.
Currently, when SpHyDir wants to test a document, it calls Web Explorer or
Netscape with its local file name. However, hyperlinks from this first document
will not work if they are designed for another server and have fully qualified
URL's or if the document contains a BASE statement with the production server's
name. This made support for BASE a long requested but seemingly impossible
objective.
Any machine running SpHyDir can probably run GOSERVE in the background. GOSERVE
can be told to serve documents out of the HTMLLIB directory tree. The final
trick is to override the name of the production server machine with a pointer
to the local loopback IP address. This can be accomplished by adding an entry
in the \TCPIP\ETC\HOSTS file with values like:
127.0.0.1 sphydir
127.0.0.1 pclt.cis.yale.edu
If TCP/IP is set to check the HOSTS file first, then with this entry any URL
for "http://pclt.cis.yale.edu/pclt/sphydir/status.htm" will be redirected to
the GOSERVE running on the local machine, which will then fetch
pclt/sphydir/status.htm out of the HTMLLIB directory. BASE will then work, and
all the URL's that point back to PCLT work. Of course, to FTP files to the real
PCLT server I need to use a different alias for that machine (or temporarily
change the HOSTS file).
GOSERVE also provides an environment to test FORMS and CGI-like programming.
Some days it seems like an HTML form displayed on the Web Explorer window would
be a more flexible way to choose options and configure SpHyDir or document
objects than popup VX-Rexx windows.
In any event, future releases of SpHyDir may move toward almost requiring that
GOSERVE and either Web Explorer or seamless Netscape be running.
═══ 2.11. May 15 Release ═══
Document Objects now have a popup menu. Click the second mouse button to
display Open, Settings, Insert, Create Another, Mark, Delete, etc. Insert
provides a quick way to add a new Paragraph, Image, Point, or List without
going to the Toolbar. You can also Insert a Horizontal Rule for which there is
no tool (though you have been able to generate it with ALT-H for quite some
time). Create Another creates a second object like the current object (say
another paragraph or point). Mark duplicates the old Alt-L. Delete duplicates
the old Ctrl-D. Currently you can only Open the contents of the object
(duplicates current DoubleClick function). Settings is under construction.
═══ 2.12. May 8 Release ═══
SpHyDir now refreshes the title of a subdocument as it reads the parent file
in. Thus if you change the title of a subdocument, the pointer to it will be
changed the next time that the parent (or the entire tree) is processed.
═══ 2.12.1. Test (F5) ═══
The File-Test (F5) operation now dynamically communicates to running copies of
popular browsers. SpHyDir first generates a temporary copy of the document in
TEMPDOC.HTM in the HTMLLIB root directory. In previous releases it then started
Web Explorer to view the document. Now this is the last alternative. Before
launching a new WE, SpHyDir now tries two things:
1. SpHyDir first attempts to establish a DDE link with a running copy of
Netscape. For this to be useful, Netscape should be running in seamless
WINOS2 mode. SpHyDir passes Netscape a request to display the Tempdoc
file.
2. If Netscape is not found, then SpHyDir looks through the windows on the
screen for a running version of Web Explorer. If one is found and it is
already viewing an older version of TEMPDOC, then SpHyDir sends it a F5
to refresh the document. If it is running and viewing something else,
SpHyDir enters the name and path of TEMPDOC in its entry area and sends
an Enter key.
Netscape has known problems running seamless on OS/2. Fortunately, the most
serious issues involve user interaction with the menus. By controlling
Netscape from SpHyDir, interaction is minimized. However, the code to control
both Netscape and WE is new and may require some fine tuning.
═══ 2.12.2. The BR Object ═══
The design of a object finally became clear when a user reported by EMail
that he was having trouble with Netscape extensions. Normally, an Image either
appears by itself or is aligned with a single line of text. The Netscape
ALIGN=LEFT (which SpHyDir has "supported" from the start) causes multiple lines
of text to flow through the space left to the right of the image.
Unfortunately, this option doesn't just flow text. it also "sucks up" any
following images. The Netscapism for breaking this pattern and starting the
next line under the image is to add a tag.
I have previously noted the need for a object to separate buttons in a
form. The problem ws to distinguish when reading in the HTML a acting as
an object from a in the middle of a paragraph that acts instead like a
character or as a CR/LF pair. Although SpHyDir has tried to avoid non-standard
HTML, it seems very compact to declare that would be
recognized as the Object and plain as the character.
Browsers should ignore attributes they don't understand. The only problem
occurs if you try to validate HTML that contains Netscape extensions with a
validator looking for HTML 2.0. If you don't want , then don't
create the object. Incidentally, to create such a tag, position at the next
object and press Alt-B. The BR Object will be positioned in front of the
currently selected object. For the most part, the BR and HR objects are very
similar. Neither has a specific icon at the moment.
═══ 2.12.3. Backup using RCS ═══
Backup of HTML files has been a serious issue. First, SpHyDir cannot be subject
to terribly aggressive testing between weekly releases. If a syntax error
occurs, SpHyDir can abort in the middle of writing a file. If SpHyDir
encounters HTML that it doesn't recognize, information can be lost. The
previous strategy of saving the old copy of the file in the BACKUP directory
addressed only part of the problem. SpHyDir now introduces the heavy artillery.
For other text files, the most powerful free software system is the RCS version
control package from Unix. When fully exploited, it allows several people to
check out and work on files in a shared library. It remembers changes to the
file and who made the changes. It is possible to reconstruct older versions of
the data if something goes wrong.
Use of RCS is optional. If it is not used, SpHyDir continues to make a copy of
the previous version of the file in the BACKUP subdirectory.
For each original data file, RCS builds a control file that keeps a copy of its
current contents and the information needed to recover any previous versions.
The first version is "1.1" and each time the file is changed a new version
number is generated.
By default, RCS will archive f:\pclt\sphydir\status.htm in a control file named
f:\pclt\sphydir\RCS\status.htmv. That is, it stores files in the RCS
subdirectory of the path where the data file is found, and it adds the suffix
character "v" to the file type.
Some future version of SpHyDir may maintain enough variables for a document to
allow individual decisions about what to manage under RCS. Currently, however,
if you use RCS at all you have to use it as the backup for the entire library.
SpHyDir is triggered to use it if there is an RCS subdirectory under the
HTMLLIB root. On my machine, "f:\pclt" is the the HTMLIB for PCLT articles, so
SpHyDir looks for "f:\pclt\RCS" to decide to use RCS, for all of the documents
in all of the directories under f:\pclt.
Unexpectedly, RCS will not create the needed subdirectory automatically, and it
will not quite work correctly if the subdirectory doesn't exist. A future
version of SpHyDir may fix this, once I develop more confidence about the best
arrangement. For now, manually create RCS subdirectories throughout your
HTMLLIB tree if you intend to use this facility. If you forget, RCS will create
the control file in the same directory as the data file and you can create the
RCS subdirectory and move the file to it later on. This is not a problem on
HPFS volumes, but it could present an issue on FAT directories where "HTMV"
might get truncated to "HTM". RCS backup is probably not a good idea for
SpHyDir users with only FAT directories.
Before generating new HTML, SpHyDir backs up the previous version of a file by
issuing the command:
ci -xv -l - m"backup" -t-"backup" xxxx.htm(l)
This runs CI.EXE (Check In) of the RCS version control system. The -m and -t
parameters provide dummy log messages so the program does not prompt for a
description of changes or of the file. The -l parameter checks the file back
out immediately (so that it remains in the library and can be rewritten). The
-xv adds a "v" letter on the end of the file type (htmv or htmlv) to provide
the file type of the RCS control file.
SpHyDir does not check the PATH for a copy of the RCS executables. It tries to
use RCS based on the existence of a directory in HTMLLIB. It is the user's
responsibility to install RCS on the OS/2 system before using this facility.
Unzip the RCS567PC.ZIP distribution file and copy the contents of the BIN32
subdirectory to a library in your PATH. RCS is now available on the same FTP
file servers as SpHyDir itself.
SpHyDir is using RCS to provide a super safe backup, not to do true version
control. There is no provision to check out locked files, or to check in and
unlock a final version. However, the user can build real version control
outside SpHyDir by issuing RCS commands before or after running SpHyDir to
provide real parameters and version numbers.
RCS is a serious system with some heavy duty manuals. SpHyDir's only direction
function is to call CI.EXE to generate the backup. Comparing different versions
of a file, or recovering old versions from the backup, requires direct use of
the other RCS commands. RTFM. If RCS appears to be too complicated, feel free
to continue to use the old SpHyDir BACKUP.
Use of RCS was requested in E-mail by a user several weeks ago. Initially it
seemed like a really bad idea. The problem is that RCS and all the other
version control systems have this view of tracking changes by line. Since
SpHyDir only puts a CR/LF line break at the end of paragraphs, it appears to
have really, really long lines. Change one word, and RCS regards the entire
paragraph as changed. Flowing the text into 80 character lines would not make
much difference, because any change in one section will flow changes onto all
the subsequent lines of the paragraph. However, there are no better version
control mechanisms, and after some consideration the long lines do not appear
to be unworkable.
Before reporting any bugs, please realize that the version being "checked in"
to RCS is not the version on the screen. What is being checked in is the old
version on disk from before the current edit session. So if you read a file in,
make a ton of changes, press F2 to save it, and look at the Console window, do
not be surprised it it reads:
F:\PCLT\sphydir\RCS/STATUS.HTMv <-- F:\PCLT\sphydir\STATUS.HTM
file is unchanged; reverting to previous revision 1.3
It is not saying that there are no changes in the current version, just that
there were no changes in the old version that you are just about to replace.
RCS is a Unix utility that has been ported to the OS/2 environment using the
EMX package. EMX is a version of the GNU development tools and the GCC
complier. These tools are normally found in the /unix subdirectory of the OS/2
files at ftp.cdrom.com and ftp-os2.nmsu.edu. The minimum files needed are the
EXM runtime DLL library (emxrt.zip) and the RCS distribution (rcs567pc.zip).
They will also be added to the SpHyDir FTP directory.
This facility is currently more "experimental" than the rest of SpHyDir, so its
output is not captured. The CI command writes to "standard output" and VX-Rexx
captures that file and displays it in the VX-Rexx Console window. If the
service seems to work well, this output will be supressed in a future release.
Meanwhile, the Console window will have to be manually closed when SpHyDir
ends.
═══ 3. SpHyDir Project Objectives ═══
Produce the highest quality HTML documents automatically. Upgrade
obsolete syntax to current "Recommended" practice. Add additional markup
to get the best possible results on all known viewers. Provide a
transition to new standard features.
Build larger documents from many small, structurally interrelated
hypertext files. Easily generate links to other files, to target lables
in certain files, and to remote documents (by extracting URL references
while a Browser displays the remote file).
Present an entirely different approach to Web document construction.
Microsoft and Word Perfect have interfaces from their Word Processors.
Oracle promises an interface from Oracle Book. HTML editors are being
written all the time. If SpHyDir isn't completely different (and IMHO
better) then it isn't worth the effort.
Automatically generate navigational links, copyright notices, and other
standard features at the beginning or end of every document.
Support all the features of HTML 3.0 and common Netscape extensions.
Provide for user extensions both to document structure and library
management.
Provide direct links to Netscape and Web Explorer to test document
changes. SpHyDir is not WYSIWYG, but you can immediately format what you
are structurally editing to see how it will look.
Simplify the construction of data entry forms (entry fields, check
boxes, radio buttons, push buttons) and tables.
SpHyDir II supports all the tags and attributes of the current HTML 3.0 draft
standard. SpHyDir should be able to process any Web document that uses these
features correctly and in context. However, HTML is a formatting language and
SpHyDir is a document structure tool. Incorrect syntax, or the use of a tag
out of context to achieve a particular effect, can confuse the analysis. In
particular, the use of
to get "fine print" where no heading is actually
intended will certainly produce bad results.
SpHyDir II is Object Oriented. It examines an input HTML document and
produces a tree of Objects that corresponds to the apparent document
structure. The simplest Object is a paragraph that contains text. Other
objects include the Image (for inserted graphics), order and unordered Lists,
Tables, Forms, Horizontal Rules, etc.
Each object has properties. There is a fairly close tie between the
Properties of an Object (in SpHyDir) and the Attributes of a Tag (in HTML).
When an object is selected in the tree, its properties are displayed in the
Properties Table. This behavior is intentionally modelled on tools like Visual
Basic and Delphi. However, since most HTML attributes have default values that
can be ignored, the SpHyDir properties table only shows the items that have
been assigned an explict value.
The casual user can concentrate on text, graphics, and basic document
structure (sections, lists of points, hypertext links). If more advanced
features become needed, SpHyDir can display all the legal properties that any
object is permitted. For example, any Paragraph can have an ID (jump-to
label), ALIGN (LEFT|CENTER|RIGHT|JUSTIFY), CLEAR (LEFT|RIGHT|ALL), and NOWRAP.
SpHyDir will list the common standard values but allows the user to type in
other values (such as entering "100 pixels" as the value of the CLEAR
property).
With this approach, SpHyDir doesn't require the user to be familiar with
HTML, but it also doesn't prevent the HTML expert from using the more obscure
language options. The author can "ease into" advanced features.
═══ 4. The SpHyDir Idea ═══
To create a personal home page or an ad layout, one must concentrate on
graphic layout. To publish a large body of useful, interrelated information on
the Web, it is more important to focus on content and the organization of the
entire library. This is the purpose of PC Lube & Tune and so it is the design
objective of SpHyDir.
The SpHyDir program icon is configured with the path to a library of Web
files. SpHyDir will only edit files and build links to the subdirectories that
fall under that starting point (the "HTML Library"). To edit a file, drop its
icon into the SpHyDir workarea window.
SpHyDir reads in the HTML and converts it to a sequence of Document Objects.
These Objects correspond to paragraphs, images, sections (chapters, topics),
numbered lists, bullet lists, tables, and so on. The Objects are arranged in a
tree, because the document contains chapters, the chapters contain paragraphs,
images, and lists, the lists contain points, and so on.
Most of the objects that SpHyDir creates correspond directly with elements of
the HTML language. A few have to be invented and several more have to be
guessed. The future HTML standard (3.0) will include Divisions that break the
document up into chapters. Current HTML (2.0) doesn't support this, and few Web
documents include the HTML 3 features. So SpHyDir has to invent the "Section"
object by looking for Header tags that are part of the 2.0 standard. The
assumption is that a Header normally starts something. Therefore, everything
after a Header (up to the next Header of the same type) must be a Section of
the document.
At first the SpHyDir objects may seem a bit awkward. Dividing everything up
formally into paragraph objects and list objects is more precise than normal
word processing. However, once SpHyDir has decomposed the original HTML into
document objects, and those objects have been updated, SpHyDir is now in a
position to generate a document with flawless, precise HTML syntax. There are a
lot of erroneous documents in the Web. Some documents display correctly on one
browser but are wrong on another browser. Few Web authors are HTML experts, and
there are many misunderstandings. SpHyDir converts the HTML to something that
most people instinctively understand (chapters, paragraphs). In many cases it
will upgrade obsolete or "deprecated" HTML elements to current "recommended"
use.
═══ 5. SpHyDir is not for Everyone ═══
HTML marks up documents so that they look good. SpHyDir assumes that the
markup corresponds to valid document structure. Some things display nicely but
are impossible to structure. For example, because
produces very tiny text,
it is sometimes used to get "fine print":
Lease a new car for $200 a month
engine not included
SpHyDir requires that all H1..H6 tags be used to start sections. Also SpHyDir
doesn't preserve the heading numbers, just their relative position compared to
each other. In the previous example, SpHyDir would change the H6 to an H3
because that is the next number down from H2.
A large number of Web documents have invalid HTML. They display as intended
because the browsers don't complain about errors that do not effect formatting.
For example, when someone wants to print in big letter, they frequenly use
heading tags:
Get Rich Quick
Act Now
Limited Time Offer
tags are not permitted inside a header, but most browsers tolerate this
construction, using H1 to change font and /H1 to revert back to normal size.
SpHyDir expects Headings to be a simple character string as the standard
specifies. Paragraphs are other types of objects, and headings cannot contain
objects.
SpHyDir II attempts to include almost all the valid syntax in HTML 3.0 and
Netscape. The Math support will be omitted for a very long time. The FIG
structure will be supported when it is more widely used by browsers. Netscape
extensions will not be supported when they seem to directly overlap more
appropriate HTML 3.0 constructs.
HTML goes through revisions. Old constructions that have been replaced are
called "deprecated" in the standard. An even tighter reading of the standard is
called "recommended." SpHyDir reads the HTML in, understands it, and then
generates new HTML based on the structure. It can automatically upgrade old
"deprecated" files to "recommended". For example, it will automatically convert
and will convert and to
. If you
want to keep the old stuff as is, then SpHyDir is not the right choice.
There are some constructions that the HTML standard permits, but maybe only
because the DTD language in which the standard is written cannot express
certain rules well. SpHyDir requires that a Definition List have sequences of
one term (DT) and one definition (DD). The Definition can have multiple
paragraphs. The sequence:
canned
packaged in a can
fired from a job
appears to be techically valid. It even has a certain obvious meaning (one term
with two definitions). The HTML DTD standard says that a
tag can only have
or
contents, but it doesn't specify how many or in what order. Some
very bad HTML uses
...title...
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:
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("Response to Your Request\n");/SAMP
This is tedious, difficult to read, and impossible to validate.
A second approach scans an HTML file and inserts data:
SAMP
%insert TITLETEXT
/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 (
) 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:
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:
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 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/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 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 ═══
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.
Web Explorer creates unusual objects that cannot be directly dropped on the
SpHyDir windows. To process a document, drag the document from the WE window to
a folder in the HTML library on the current machine. SpHyDir can only process
files that are in the library. Drop a URL object on the desktop or in a folder
first, then use it to build a link.
═══ 15. Supported and Unsupported HTML ═══
SpHyDir II was restructured to simplify extensions. Most of the HTML 3.0 and
Netscape tags and attributes are now supported, or will be shortly.
SpHyDir generates LINK tags for Subdocument relationships (Next, Previous,
Up). It preserves, as properties of the Document Object, LINKs mentioned in the
current HTML 3.0 draft (Home, TOC, Index, Glossary, Copyright, Help, and
Bookmark). It plans to support Header and Trailer links for document specific
boilerplate files. Other LINK tags are not preserved.
The SpHyDir objects have a place for every valid construction, but they may
not support constructions that are invalid, even when frequenlty used. If there
is a reasonable strategy, current incorrect markup may be "upgraded" to valid
status. For example, lists may not contain any data outside the list items:
Text here is illegal, but there is a lot of it in practice.
This is an implied paragraph
This is an explicit paragraph
Text here is nominally illegal.
SpHyDir will take one text string outside the points and "upgrade" it to the
HTML 3.0 List Header contents. In other places, loose text may be upgraded
to a
or . However, when there is no place to put it, the text
may get lost.
SpHyDir needs where possible to convert HTML constructs to the properties of
an Object. A particular problem is created by hypertext labels generated by word. Since SpHyDir cannot manage properties for individual words,
it assigns the NAME to the ID property of the Paragraph, Section, or other
object in which the labelled word appears. It is the intention of SpHyDir to
migrate this to the preferred