HPG 1.3 (c)Robert S Harris 1998.

The Home page generator.

This is a simple, web page line editor. That is not as limiting
as it might first appear.  If you have a lot of text to write for
your page, use a real text editor/word-processor, then come back
to this when your text is ready.  The various file insertion
options, make producing the final page, a breeze.

For those it concerns, most output to screen is via the BIOS
calls, so "speaks" by default.

The list of functions and succinct comments on how to access/use
them are as follows.


Contents;

New in this version;

1   Command line:
   1.1  File name;
   1.2  Colour scheme;

2   The display layout;

3   Main menu options:
   3.1  Text attributes and other toggles;
   3.2  Accessing other menu facilities;
   3.3  Help level;
   3.4  Line breaks;

4   "Others" sub-menu;
   4.1  Headline text sizes;
   4.2  List types;
   4.3  Menu list, special case;
   4.4  Finishing lists;
   4.5  Centred lists;

5   The line editor;
   5.1  Edit line character prompts;
   5.2  Line editor controls;
   5.3  Block marking with Shifted arrow keys;
   5.4  F10: Text attribute selection;
   5.5  Input line expansion;

6   File insertion;
   6.1  Insert a text file;
   6.2  Insert code sample;
   6.3  Insert a link-list;
   6.4  Insert selected files;

Disclaimer;

References; (Tutorials).

Contacting the author;


New in this version;

#	Multiple file selection, produce complete multi-part
document with internal navigation links and anchors, from a
single dialogue and file menu. 

#	^J or ^return on an input line, to save text and go
directly to the menu, saves a keystroke.  i.e. ^anything is
ctrl-anything in this context.

#	shifted arrow keys for text block marking.

#	Additional F10 text attribute selection within line
editor, works on marked text blocks.

I am still asking for useful additions I can add to this utility,
these are what I find useful so far.

Comments to - hugsl@bobsh.demon.co.uk.

(c)Robert S Harris 1998.



1   Command line:

1.1  File name;

You can put a filename on the command line as first argument, but
you will be prompted through this if omitted. 


1.2  Colour scheme;

You can also offer a colour scheme for the page as second
argument, but you will be prompted through this if omitted. You
can force default colours if - you put "D" as second argument on
the command line or press enter/esc in the dialogue when
prompted.

To specify colours on the command line, you will have to go
through the manual setting a time or two in order to establish
which digits set which colours, then put these as a two digit
number as second parameter on the command line.


2   The display layout;

There are three main areas of the screen, so that each can scroll
separately.  The bottom three lines are for menu options to be
displayed and to use for input, when menu options require user
input.

The second block above this, is the edit window, just three
lines, which is the capacity of the line editor.

The main block of the screen, from the top, down to line 19 (of a
default 25 line display) is for output of a listing of what user
has input to the page.

Note:     once it appears on this listing, it is also commited to
the page, currently in production.


3   Main menu options:

3.1  Text attributes and other toggles;

Centre, Bold, Italic and Underlined text attributes, as well as
expand URLs; are toggles, press return on an empty imput line for
the menu to change them.  You are notified of operating
attributes for each input line, at the bottom of the screen. 

You can also press either ctrl-return or ctrl-J, which are
functionally the same, to get to the menu without having to do it
on an empty line.

Note:     you can now select text attributes from within the line
editor, for marked text blocks within it.  See section 5 for
details.


3.2  Accessing other menu facilities;

Press enter on an empty imput line for the menu, for all other
functions, such as: Anchor, Graphic, Help off, link, mailtab,
Rule line separator, paragraph, "Others", line break and quit. 

To reiterate from the section above - You can also press either
ctrl-return or ctrl-J, which are functionally the same, to get to
the menu without having to do it on an empty line. 


3.3  Help level;

The help/menu window at the bottom of the screen, is in verbose
mode by default.  The "H" option reduces this to a single line of
hot keys to reduce chatter.  A switch to toggle BIOS output may
be added to reduce this further. 


3.4  Line breaks;

It is also worth noting the distinction between a forced line
break and forcing a blank line in the displayed page.  The "P"
option on the menu means "Paragraph", so will force a blank
line.  However, pressing return on the menu line, will force a
line break to ensure that the next input will be on the next
displayed line, rather than with an intervening blank line.

i.e.    you wish to write your address as follows:

Bob Harris 
12 three street 
Fourton 
Fyfe  FY5 78N. 
Scotland 
U.K.

        You will now see that you would force a line break to
achieve this.  The possible irritation is as follows; from text
input of the first line, when you press return once, you get to
the next input line with the "+" prompt.  When you press return
again, you get to the menu line/screen, so press return again, to
achieve a forced line break.  You have spotted that it requires 3
successive presses of return to achieve a simple operation.

This is precisely why the ctrl-J/ctrl-return were added.  It is
also worth noting at this point, that ctrl-M is functionally the
same as pressing return/enter on its own.
So now it is a great deal easier to force a new line by holding
ctrl and pressing J and M successively.  This is a great deal
easier as one can hold the left ctrl key and use the first finger
of the right hand to hit the J and M since they are directly
adjacent to each other.

Note:	this only works if there is no smart TSR software loaded,
that uses these as hot keys, since this would trap them and they
would not then be passed to this program.


4   "Others" sub-menu;

The "Others" option gives access to styling, such as - Headline
text sizes, sorted/unsorted/menu lists, more as I think of and
add them. There are also "Insertion" options, which are
facilities to insert external files, directly into the current
page, at the current position. This is to allow the production of
text bodies, in editors/word-processors which are better tailored
to the job.  Note that these _must_ be in plain ascii, if they
are to have any chance of displaying properly.

Note:  Headline text size and lists are mutually exclusive, as
are other combinations such as putting rule line separators,
graphics and anchors in lists.  Anything that is not allowed will
be prompted and not done. 


4.1  Headline text sizes;

These are accessed from the - "others" sub-menu, H - and it will
prompt user  for a size from 0-6, where 1=largest, 6=smallest,
0/esc is to switch it off altogether.  This returns display to
the browsers default size/font settings (if any).

Note:     character based browsers such as all variations of Lynx
or Nettamer, will not render these attributes in any case.

Size 1 is very large, so a single term like "Contents", is about
as much as is likely to fit across the display.  One would also
likely have this centred for effect.

Size 6 is the smallest and only half useful for the purposes of a
discrete disclaimer notice.

As previously stated, Headline text sizes are mutually exclusive
with other options, to prevent seriously flawed formatting, such
as anchor or link text, that might wrap down several lines of
display.

e.g. A long URL in H1 is not likely to fit across the display at
all and I don't know how the browser would go about trying to
wrap it, the best it could do is fragment it.


4.2  List types;

There are three list types, though are fairly similar.  They are
- Ordered, Unordered and Menu.
From the "Others" sub-menu, they are - O, U and M respectively.

The unordered list will accept typed text, links and mailtags,
each will be displayed on a separate line with a bullet point to
identify it as a list item.

An ordered list is pretty well as above, except that the browser
will number the items, rather than simply displaying a bullet
point.

Note:     Anchors and graphics are not allowed in lists.


4.3  Menu list, special case;

A menu list is a special case, as some browsers will offer the
user, a moving highlight bar on screen, for selection of the
items within such a list.  Therefore, a menu does _NOT_ accept
text input at all.

When producing a menu list, one keeps returning to the menu line,
for adding links/mailtags to this list.


4.4  Finishing lists;

From the menu line, the option is "others", "end list" to finish
a list.  The user is prevented from changing list types, without
finishing an existing list.


4.5  Centred lists;

Tip:  Centred lists do not present very well.  Go to the main
menu to switch Centre off, before starting a list.  I will make
this automatic if required by popular demand.


5   The line editor;

5.1  Edit line character prompts;

It should be understood, that browsers do not respect the normal
end of line combinations of cr/lf pairs/singles, so pressing
return even in an ordinary editor, would not cause the effect
when displayed through the browser, they just reflow the text to
fit within the screen window.

For this reason, the edit line has four single character prompts
on the input line. These change according to the effect of your
input.

e.g.  The initial prompt is "=".  This always means that your
text will start on a new line when displayed by a browser. The
second is "+", which means that your current line of text will
reflow to the predecessor, according to the window size/font size
of the browser. The third is "#" which is to represent a bullet
point and only occurs when producing an ordered list.  The fourth
is a "*" which represents items going into an unordered list.

These latter two are the cases where each input line will be
displayed separately, without having to force it.


5.2  Line editor controls;

The line editor does have fairly comprehensive editor like
editing facilities, which are summarised as follows.

a:  Max line length is 240 characters, so enough for a reasonable
sentence or more.

Remember to press return regularly at convenient positions,
rather than get caught with an incomplete line when you try to
type past this limit. Any incomplete word(s) you have if you type
right up to this limit, will appear as a partially complete line,
when you hit return and start typing again where you last got to.

                                 Remember, the text is re-flowed
by the displaying browser, so all the text bits will get put back
together, even if you put a single word on every line. 

p.s.  I tried this for the purposes of bolding a single word,
though I do not recommend this as an efficient way to work.

b:  As a line of this length, will stretch down 3 of an 80 column
screen lines, you can use up/down as well as left/right arrow
keys to move about. Home/End keys go to either end of the screen
input line. ctrl-home/end go to the absolute ends of the input
line.  PGUP/PGDN do the same. Ctrl-left/right arrow keys move by
word.  Word is defined as moving from any alpha-numeric to a
non-alpha-numeric character, or the reverse of this. Do this a
few times to get the full hang of it.

c:  Input is strictly "insert" mode, so del/backspace work as
normal, ctrl-T is del word, ctrl-backspace is to clear the entire
line. Ctrl-T deletes a "word" by the definition above. i.e. it
would not delete an entire URL if you tried it, but block by
block. e.g.  Starting with the cursor on the "H" of
http://www.blab.com, the first ctrl-T would lose the http, the
second would lose the ://, so now it's down to www.blab.com; and
so on.

For completeness, if you missed the comment in the menu section
of this document; pressing ctrl-J or ctrl-return would both save
this line and go directly to the menu, for making a selection.
I have not tried it yet, but this would also apply, if you were
giving user input for one of the menu options, so this would take
you straight back after completing the one function and giving
the opportunity to do another directly, without going to the
input line first.
e.g. producing a whole series of mailtags or links successively,
though it would be quicker to use the linklist facility,
described below.


5.3  Block marking with Shifted arrow keys;

There is a common protocol in popular editors, so as to mark a
block using shifted arrow or cursor movement keys.  These have
been implemented as far as possible in the line editor.

i.e.	If you hold the shift key and move the cursor with any of
the keys described for the purpose, a block will be marked from
the position from which you started holding the shift key, until
you release it. Once a cursor movement key is pressed without the
shift key, any defined block will be undefined.

Thus, if you want to mark a word or phrase for setting attributes
on, you have to hold the shift key while moving across the word
or phrase, then release the shift and do _not_ press any keys
except for the attribute selection.  This is described in the
next section.

Shift-Del will cut text to clipboard, shift-Insert will paste
from clipboard.  I have not managed to implement the ctrl-insert
as copy to clipboard, this is a peculiarity of the compiler I am
using.

e.g.	To replicate a phrase more than once in the same line, or
use it again elsewhere, mark with shifted arrow keys, then press
shift-del and shift-ins consecutively. This puts a copy in
clipboard and restores it to the current line.


5.4  F10: Text attribute selection;

The F10 key from within the line editor, will give you text
attribute selection, so long as there is a block of text marked.
The purpose here is to be able to highlight text, without
committing the entire line, by setting such attributes from the
main menu.

Some examples:

I want a line reading "Headlines" that is in largest character
size and centred.  So I type that phrase, use the home key to go
to the start of this short line, hold shift and press the end key
to go to the other end of the line and mark it as a block. Now I
press the F10 key to get the selection menu and press C to have
it marked as centred, then press the F10 key again to get back to
the selection menu and press 1 this time as 1 happens to be the
largest size.  Pressing enter on this complete line will save it
to the file and not have changed any of the default attributes.
This can be noted from the output at the bottom of the screen
where current attributes are listed.

Note:	Attributes are noted by the insertion of high-bit
characters in the positions representing the marked text.  e.g.
using the example as above, the line would have two high-bit
characters at each end of the line, before pressing return on it.

The important point is - if you then deliberately or
inadvertently delete any of these, the attributes will no longer
be in matched pairs, so the display of this page would not be as
intended.  e.g.  taking the example above, you could have an
attribute starting centred text, but not to switch it off again,
so all remaining text would be centred until such time as another
centre tag or appropriate high-bit character was encountered.

Tip:	write all the text required on the line, including any
corrections; then only when satisfied that this is correct, to do
the word/phrase marking to set attributes on them.

P.S.	The high-bit characters used are #246-#255, representing
bold, centre, italic, underlined, and headline text sizes 1-6
respectively. You could chance using these in your text editor
when producing page bodies for single or multiple file insertion.
Remember though, that unmatched pairs, make for rubbish HTML
code.  HPG always inserts matched pairs, unless accidentally or
deliberately deleted first.


5.5  Input line expansion;

It must be recognised that if all character input, were put
directly in the new page, they could be confused as HTML tags and
confuse the browser somewhat.  All characters outside the normal
printable range, as well as those most likely to confuse a
browser, are converted to a special ascii interpretation, so that
the browser knows to show the characters themselves.  This would
allow the typing of sample HTML statements if required and they
would be displayed as such.

Further to this, there is a toggle in the main menu, to allow the
expansion of URLS so as to appear automatically in the page, as
working hyper-text links.  This is off by default, so switch it
on if required. The URL has to start with the "http://" to be
recognised as such.


6   File insertion;

Under the "others" menu, there are four file insertion
possibilities. You can enter a wildcard filespec, you will be put
in a selection menu regardless.  Up/down arrow keys to select,
return to accept, esc to cancel.

Further to this, the list of files is sorted and there are simple
search facilities, to make finding the required file from amongst
a long list, much easier and faster.

It works like as follows:
start pressing the first few (4) letters of the required
filename, if a filename exists with these few latter's at the
start of their name, then the highlight or pointer will go to
that entry in the list; otherwise, it beeps and the pointer stays
where it was.  To start searching for a file with a different few
letters at the start of their name, press the space-bar to clear
the current set and start typing the new few letters.


6.1  Insert a text file;

To insert a text file (ascii of course), which will display
more-or-less as-is: you need to press return on a blank input
line to get to the main menu, O for the "others" submenu and then
T for text file.

Remember that all text is reflowed in a browser.  Blank lines in
the text file, have the "<p>" tag added to retain the blank
line.  The text itself is put through the converter to change
possibly confusing characters in it, to avoid confusing the
browser.

e.g.  You could insert HTML code samples so that they are
displayed as such.


6.2  Insert code sample;

"Others" sub-menu, C is to insert a "raw" HTML code sample, which
is put in as-is and will be a working part of the HTML code in
the current page.  Useful if you have such a sample, such as a
complicated reference to a hit counter or the like.  The effect
on the finished page is entirely at the users risk, since it
could hold other attributes that might conflict with those
currently in operation at the time of insertion.


6.3  Insert a link-list;

"Others" sub-menu, L is to insert a link-list of predefined URLS
and have them presented as an actual list of such, when displayed
by the browser.  The list is a simply formatted text file which
shall be described below.  The effect will depend on the current
mode this editor is in at the time.  If an ordered or unordered
list is in progress at the time, the list of URLS will be added
to it.  Otherwise, a "Menu" is created and all the list of URLS
with their associated comments, will be inserted into that and
the "Menu" will be closed when they have all been done.

The format of the file is as simple as follows:-

URL comments....  (note the space between the URL and comments).

For example:

http://www.bobsh.demon.co.uk/ads.htm This is my ad's page.
mailto:ads@bobsh.demon.co.uk Put an Ad on the Web!
http://www.rnib.org.uk/ The RNIB of the UK.

Etc. and so on.  The key details to remember are that a reference
to go in the link has to be the first thing on the line and be in
the first column.  After the first space to separate it from the
rest of the text, the remainder of the line will form the link
text.  Note that these have to be on a single line for each
reference, so be careful in the editor you use to create this
list, that a long text does not word-wrap to the next line, where
it will get treated as another reference and probably confuse
either the browser that is reading it, or the user of that
browser. In short, it could screw up your lovely page!

One could use local references in this case, so a list of other
pages could be as follows:-

personal.htm  My personal bio. 
ads.htm The Ad's page. 
fun.htm All the fun stuff! 
itg.htm The International Thyroid Group. 
bliss/index.htm Baby LIfe Support Systems (Charity).

And so on.  One could create a contents section using this method
and put the list near the top of the page.


6.4  Insert selected files;

This is where the fastest complete page generation takes place.

Let us assume for a moment or two, that you have a longish
document to produce, which includes an introduction, several
sections, an index and glossary.  You could have these
pre-written in your favourite editor/word-processor for the job,
saving them individually as ascii text files, with such names as
- intro.txt, sect1.txt, sect2.txt,....   sect#.txt, index.txt and
glossary.txt.

The first lines of these files will reflect the title of these
document parts, so the first line of intro.txt would likely say
"Introduction:".

The page you wish to produce is meant to have a link list at the
top to point to all these internal document sections, it will
require an anchor with a name like "Contents" above this list, as
somewhere to return to.  Further, you want a rule-line separator
between each insertion, but have a return link back to the
"Contents" anchor after the inserted text.

In short, you require an extended page with internal navigation
between the contents header and the various document
sub-sections.

So to achieve this, "Others" sub-menu, S; is to select files.

The user is asked for an anchor name, this is where they put
"Contents" or something appropriate. The next step is to enter a
filespec, "*.txt" seems appropriate for our example.

The user is then in the file menu, much as with any of the file
insertion options, but with one key difference.  Pressing the tab
key, will mark the currently highlighted or referenced file, for
inclusion in the selection of files they wish to insert. The key
point to remember here, is that the order they are selected, is
the order they will be inserted into the current working page.
So, there is little pointing going down the list alphabetically,
tagging as they go. This is where the simple search capabilities
really come in useful.

e.g. start typing "int" which would be enough to ensure getting
to intro.txt, unless there was something else in there that I
don't know about, and press the tab key on it to tag it.
Next: hit space-bar and start typing"sec", though it is likely to
get to sect1.txt before typing that many letters. So now the user
can go down the list sequentially, pressing the tab key to tag
them, until they are all done.  Now hit space-bar again and start
typing "ind" this time to find the index.txt to tag and finally,
space-bar and type "glo", or as much of it as it takes to find
glossary.txt and press the tab key on that to complete the
selection.  

If there is any doubt about the number of files selected or the
order they have been selected in, it is better to press [esc] and
start again, as pressing enter/return at this point, will produce
the entire document as described above.

This may be as much as you need to do, to produce the entire page
you required, though perhaps a link-list of related pages (as
described in the previous section) might be useful too.


Disclaimer;

The author, Robert S Harris; accepts no liability or
responsibility, for the use of this product or the effects of
such use; regardless of the nature of such effects or how they
were caused.


References; (Tutorials).

These are the two best reference works I have found for analysing
and adding to ones knowledge of the HTML language.


*	Download The Complete Idiot's Guide to Creating an HTML
Web Page     -- an extensive book
http://www.empowermentzone.com/htmldumb.zip

*	Download Using HTML -- an extensive book 
http://www.empowermentzone.com/html_use.zip


Contacting the author;

This program was based on a good idea From: Oscar Sosa
<ososa@brokersys.com>

This is the fourth prototype version: comments, suggestions and
improvements; are welcome to - hugsl@bobsh.demon.co.uk.

p.s.	HUG-SL used to mean - Hal User Group Software Library. 
This is now defunct.

        Robert S Harris.  
