\begindata{hlptext,538421000}
\textdsversion{12}
\template{help}
\define{xxx

attr:[Flags Underline Int Clear]
attr:[Flags Underline Int Clear]
attr:[FontFace Bold Int Clear]
attr:[FontFace Italic Int Clear]
attr:[FontFace FixedFace Int Clear]
attr:[FontSize ConstantFontSize Point 8]
attr:['color' 'Red']}
\chapter{\xxx{XXX-still under construction; don a hard hat before 
proceeding}

htmltext: an editing package for HTML+ documents

}
\section{What htmltext is

}
\leftindent{Htmltext is an editing package used by EZ when editing HTML+ 
documents.  HTML+ is a tag format used for files that are put on the World 
Wide Web (WWW or "the Web").  Htmltext is intended primarily for creating 
and modifying documents.  For instructions on actually browsing the World 
Wide Web, see the  \helptopic{Mosaic}  help file.

}
\section{Starting htmltext

}
\leftindent{At the Typescript prompt, type "ez file.html" and press Enter. 
 Use of a .html extension tells EZ to load the htmltext editing package, 
according to the specifications in the global initialization file for EZ, 
/usr/andrew/lib/global.ezinit.


If you create your own .ezinit file, you can override the global.ezinit 
file or add other file extensions that will load the htmltext package.  You 
can also set various parameters of htmltext, which are listed below in the 
section "Customizing htmltext in your .ezinit file."  For details about 
initialization files, see the  \helptopic{initfiles}  help file.

}
\section{Warnings

}
\leftindent{\bold{IMPORTANT:}

Since HTML+ only supports some, but not all the arbitrary multimedia insets 
that EZ does, insertion of unsupported insets (e.g. "fad" or "zip" insets) 
will result in them being discarded.


\bold{Less Important:}

Htmltext is not guaranteed to produce HTML+ documents that will be 
interpreted correctly by all possible HTML and HTML+ browser applications.

The document, when viewed with EZ, will usually have a slightly different 
appearance than when viewed with Mosaic.

If you edit an HTML+ document that was created by hand, and then save it, 
the format and arrangement of the tags may differ slightly from the 
original.  However, these differences will not affect the appearance of the 
interpreted document, only its "raw" content.

At this time, htmltext is not a complete implementation of the HTML+ spec. 
 However, any tags that are not recognized will be hidden in an inset 
during the editing session, so that when the file is saved, those 
unrecognized tags will remain intact.

\xxx{XXX- HTML+ as a document markup standard is defunct.  HTML 3.0 is its 
new name, and htmltext will be updated to follow any changes in the HTML 
3.0 standard as they occur (and as resource permits).}

\xxx{XXX(techie)- A separate and distinct HTML edit view for EZ was created 
earlier by a different unrelated party. Its class name is html[view] (this 
one is htmltext[view]), so they can peacefully coexist, except they use the 
same template name (html.tpl).  If you have your own copy of html.tpl 
copied from the first html dataobject, remove it from your TEMPLATEPATH.}

}
\section{Intro to HTML+ document format

}
\leftindent{HTML+ documents (in their raw format) look something like this:

\example{<TITLE>Rob's home page</TITLE>

<H1>This is my home page</H1>

<HR>

<IMG SRC="face.gif">

<P ALIGN=CENTER>This is the

stuff I'm working on:

<PRE>Help files

Other stuff

</PRE>

...

}Htmltext reads those <>-delimited tags, interprets them, and turns them 
into (as appropriate) styles or insets.  These styles and insets can be 
edited the same way as in other EZ documents.  If you are unfamiliar with 
how EZ works, see the  \helptopic{EZ}  help file.

}
\section{Pop-up menu meanings

}\leftindent{
}\italic{Front menu card

Search/Spell menu card

}\leftindent{See  \helptopic{EZ}  help file.

}
\italic{Page menu card

}\leftindent{\bold{Insert Horiz Rule:}  Inserts a page-wide horizontal line 
at the position of the text caret.  (\typewriter{<HR>} tag in HTML+)


\bold{Inset raw HTML+:}  Inserts a \bold{hidden} inset, which will output 
its contents verbatim.  This is a feature for experts who wish to add HTML+ 
markup that EZ does not support directly.


\bold{Hide HTML+ insets:}  This makes all \bold{hidden} insets invisible, 
for better readability (this is their default appearance when a readonly 
HTML+ file is loaded).


\bold{Expose HTML+ insets:}  This makes all \bold{hidden} insets visible, 
for experts who wish to browse or edit existing unsupported HTML+ markup 
(this is their default appearance when editing an HTML+ file you have write 
access to).


See  \helptopic{EZ}  help file for other entries.

}
\italic{Font menu card

Emphasis menu card

Header menu card

}\leftindent{These contain straightforward styles, which are explained in 
the  \helptopic{ez-styles}  help file.

Note that the "Header" styles are numbered in increasing order from major 
to minor, to coincide with the HTML+ tag names \typewriter{<H1>} (major) 
through \typewriter{<H6>} (minor).

}
\italic{Region menu card

}\leftindent{Most of these menu items simply insert a style. 
 "Preformatted" is used most often, for large regions of text where 
whitespace is significant and a fixed-width (\typewriter{typewriter}) font 
is desired.

The "Edit Attributes" and "Add Link" menus are explained in separate 
sections below.

}
\italic{List menu card

}\leftindent{Htmltext supports three kinds of lists:

\description{    1.	Ordered lists, which have a number associated with each 
item in the list.

    \symbola{7}	Unordered lists, which have a round "bullet" in front of 
each item in the list.

    \bold{Definition lists}	contain terms and definitions of those terms.

}
There are two ways to create an ordered or unordered list.  To create a 
list out of items that have already been entered, simply select all the 
items and then choose "Ordered List" or "Unordered List" from the "List" 
menu card.  To start a new list from scratch, place the caret where you 
want the list, then choose one of the "... List" menus.


You can add more items to any type of list by selecting the "Add List Item" 
menu or pressing Tab when the cursor is at the start of a line.  Or, 
instead of pressing Enter then Tab for each new item, you can just press 
Ctrl-J, which will add a new line with the appropriate number or bullet on 
it.


Definition lists are a bit different.  After creating a new list or adding 
another item via Ctrl-J, the text that is entered will be the boldfaced 
"term", until the Tab key is pressed.  After Tab is pressed, any text 
entered is the "description" of that term.  (If no boldfaced term was there 
when Tab is pressed, pressing Tab will turn all preceding text on that line 
into the term, and you can then proceed to type the description, as usual.)


If the numbers in an ordered list become discontinuous (due to a Cut or 
Paste or Insert File), place the caret anywhere within the ordered list and 
select the "Renumber List" menu.  (This is actually unnecessary, since the 
numbers themselves are generated at the time the file is edited or 
browsed).

}
\italic{Media menu card

}\leftindent{This menu contains various insets that can be properly 
translated into HTML+ tags.  To insert one, position the caret at the 
desired location and select the menu.


\bold{Table:}  This uses the  \helptopic{table}  inset, and outputs the 
HTML+ \typewriter{<TABLE>} tag.  You can combine cells, put styles inside 
the cells, and add and remove cells.

\smaller{Warning:  although you can use table's "spreadsheet" calculation 
abilities, the \italic{formulae} will NOT be saved in the file; only its 
value at the time of the save.

Warning:  table allows precise control over which borders are drawn and 
which borders are not.  In HTML+, either \italic{all} the borders are drawn 
or \italic{none} of the borders are drawn, so don't get fancy because the 
individual border settings will be lost.

}
\bold{Image:}  This uses the  \helptopic{image}  inset, and outputs the 
HTML+ \typewriter{<IMG>} tag.  It typically contains a reference to a local 
.gif file, or a URL.  When inserting one, it will prompt for a 
filename/URL, and load the image in as an inset.  \xxx{XXX-only local files 
will actually be displayed inline; remote URLs can't be fetched by EZ yet}


\bold{Figure:}  This uses the  \helptopic{figure}  inset, and outputs the 
HTML+ \typewriter{<FIG>} tag.  \xxx{XXX-not implemented}


\bold{Fill-out Form:}  \xxx{XXX-not implemented; use "Page, Inset raw 
HTML+" and type the <FORM> markup manually}


\bold{Equation:}  This uses the  \helptopic{eq}  inset, and outputs the 
HTML+ \typewriter{<MATH>} tag.  \xxx{XXX-not implemented; use "Page, Inset 
raw HTML+" and type the <MATH> markup manually}

}
\section{Special Keys

}
\description{\leftindent{\bold{Tab}	This is used in lists to add a new list 
item, usually to a blank line.  Tab is the same as "Add List Item" on the 
"List" menu card.


\bold{Ctrl-J}	This is a shortcut key, equivalent to pressing Enter then 
Tab, inside a list.

	\italic{Customization tip:}  since Ctrl-J acts like a normal Enter key 
outside of lists, it's safe to re-bind the Enter key to do what Ctrl-J 
does.  The advantage is that you don't need to press Tab for new list 
items, but the disadvantage is that adding regular unbulleted paragraphs to 
a list will become more difficult.  See "Customizing htmltext in your 
.ezinit" below.


\bold{Alt-a}	This is used to edit the attributes of a style.  See the 
section below entitled "Attributes of individual styles".


\bold{Alt-'-r}	This is used to renumber an ordered list, and is basically 
unnecessary.  See the description of the "\italic{List menu card}" above.


Many of the styles on the "Font" menu have key equivalents.  \bold{Alt-'-b} 
for the Bold style, for example.

See the  \helptopic{ez-keys}  help for a list.

}}
\section{Adding Hyperlinks

}
\leftindent{"Hyperlinks" are also known as "anchors" in HTML+.  A 
"hyperlink" is a specially-marked area of text that, when viewed with a WWW 
browser such as  \helptopic{Mosaic} , allows the viewer to click the mouse 
on that text to jump elsewhere in the same document, or even a completely 
different document available elsewhere on the Web.


Hyperlinks are not functional when editing a document with EZ, since it 
would make positioning the caret with the mouse somewhat troublesome! 
 \xxx{XXX-someday, after some built-in client support is added, EZ will be 
able to provide a menu that lets you position the cursor inside a hyperlink 
and select a menu to fetch that document from a remote Web server into 
another window/buffer.  It may also be able to act on mouse-button clicks, 
but only when the buffer is readonly (thereby making EZ a Web browser 
itself)}


\bold{To add a hyperlink manually:

}\description{  - Highlight the word or phrase that will become the 
hyperlink.

  - Choose the "Add Link (prompt)" item from the "Region" menu card.

  - At the ``URL to link to:'' prompt, enter the Universal Resource 
Location string to be hyperlinked TO.

      Examples of typical URLs are:

\indent{\typewriter{http://www.rchland.ibm.com/    }(IBM Rochester home 
page)

\typewriter{http://www.rchland.ibm.com/~userid/    }(userid's personal home 
page)

\typewriter{#stuff    }(a location in this same document with the attribute 
``\typewriter{ID="stuff"}'')

}}
\bold{To add a hyperlink automatically:  \xxx{XXX-not implemented, needs 
buffer<=>URL support}

}\description{  - Highlight the word or phrase that will become the 
hyperlink.

  - Choose the "Add Link.." item from the "Region" menu card.

  - Position the caret in this document (or any other HTML+ document in the 
same EZ session) at the place to be hyperlinked TO.

  - In the \italic{target} window, choose the "..Set Target" item from the 
"Region" menu card.

}EZ will automatically determine the target URL (if it's a different 
buffer), and the target ID in the target buffer closest to the caret, and 
set the hyperlink in the original location to point to that. 
 \xxx{XXX-heck, EZ could \italic{MAKE} an ID in the target document if it 
had to, assuming the target buffer isn't readonly}

}
\section{Attributes of individual styles (for experts) \xxx{XXX-or anyone 
who needs hyperlink targets, because ID="_" generation isn't automatic yet}

}
\leftindent{In HTML+ documents, certain tags can have "attributes".  Almost 
all tags, for example, can have an ``\typewriter{ID=}"_"'' attribute.  The 
ID given in quotes is the name used in hyperlinks to that part of the 
document.  Hyperlinks themselves, in their raw form, are an \typewriter{<A>} 
tag with an ``\typewriter{HREF="_"}'' attribute, where the target ID is 
given in quotes.


When the HTML+ document is read by EZ, the tags (and their attributes) are 
no longer visible, because they are converted into styles.  The HTML+ 
markup ``\typewriter{This is <B ID="myexample">bold</B>.}''  appears as 
simply  ``This is \bold{bold}''.


If the need arises to manually edit the attributes of a tag, position the 
caret inside the style to be edited (optionally pressing Alt-s until the 
desired style is highlighted), and then choose the "Edit Attributes" item 
on the "Region" menu card, or press Alt-a.  The existing attributes of that 
style will be displayed in the message line, where they can be deleted, 
changed, or added to.


This is basically a manual process that requires a bit of HTML+ knowhow, 
but is usually unnecessary. \xxx{XXX-yah, well, since EZ doesn't 
automatically generate ID's for you yet, you pretty much HAVE TO learn how 
to do this if you want to be able to hyperlink to specific parts of your 
document}


For a complete list of tags and their attibutes, see the HTML+ spec.  At 
this time, it is still "work in progress"; a \italic{draft} of an HTML+ 
spec. \xxx{XXX-that's defunct, and is now named HTML3.0; presently 
available (16-Aug-94) as ftp://15.254.100.100/pub/www94_htmlplus.ps.Z} 
 HTML2.0 tags and attributes (which are mostly the same) can be found in 
 \helptopic{Mosaic} 's online help.

}
\section{Customizing htmltext in your .ezinit file

}
\leftindent{See the  \helptopic{initfiles}  help for complete instructions.


The most common customization would probably be to bind the Enter key to do 
what Ctrl-J normally does.  Recall the "List menu card" section above.  If 
you would rather make the Enter key insert new list items inside a list, 
rather than using Ctrl-J or the "Add list item" menu, add this to your 
~/.ezinit:

\example{addkey htmltextview-newline-add-item ^M htmltextview

}But be forewarned that this customization makes it more difficult to add 
an unbulleted paragraph in the middle of a list (that is the Enter key's 
\italic{default} function).

}
\section{Customizing htmltext in your preferences file

}
\leftindent{See the  \helptopic{preferences}  help for complete 
instructions and a more comprehensive list of available customizations.


\bold{ez.DefaultImage:} \italic{(usually set in 
/usr/andrew/lib/global.preferences)}

This preference is the full pathname of an image (usually a .gif file) to 
use when the URL referenced by an embedded \typewriter{<IMG>} tag cannot be 
found.

}
\section{Related tools

}
\leftindent{Move your mouse cursor to one of the following names and click 
your left mouse button to see the help file for:

\leftindent{\helptopic{ez}

\helptopic{ez2html}

\helptopic{Mosaic}

}}\enddata{hlptext,538421000}
