<COMMENT>(--------------------------------------------------------------------)

<FRONT_MATTER>
<TITLE_PAGE>

<TITLE>(HFRD Hypertext\Menu Primer)

<LINE>

<HEAD>(22nd September 1994\head_date)

<P>
This is a new <EMPHASIS>(and DRAFT\BOLD) document. 

<HEAD>(Abstract\head_abstract)

<P>
This document is a basic guide to the management of HFRD Hypertext data. It
provides a quick overview of the use of Hypertext resources within the 
Division, how to organise information in this environment, a simple 
<EMPHASIS>(presentation menuing system\BOLD) for those not required, or
wishing, to be involved in HTML (the native markup language), as well as an
introduction to other aspects of the enviroment.

<COMMENT>(HTML/OFF)
<P>
It is strongly suggested those using printed versions of this document also
access the Hypertext version.  It provides online demonstrations of some
concepts.
<COMMENT>(HTML/ON)

<HEAD>(Contact\head_contact)

<P>
M.G.Daniel 

<COMMENT>(HTML=
<H2>Other Formats</H2>

<P>
For Hypertext browsers a PostScript version of this document is available for 
 <A HREF="/ht_root/doc/hfrd_primer/hfrd_primer.ps">viewing</A>
 and for
 <A HREF="/print/ht_root/doc/hfrd_primer/hfrd_primer.ps">printing</A>.
)

<COMMENT>(HTML/OFF)
<HEAD>(Printed Copy\head_printed_copy)

<P>
This book is available for printing to a PostScript printer.  At the VMS 
command line enter <QUOTE>(PrintBook), the facility is menu driven.  For 
multiple copies it is better to print once, then <EMPHASIS>(photo-copy). 
<COMMENT>(HTML/ON)

<LINE>

<ENDTITLE_PAGE>

<CONTENTS_FILE>

<ENDFRONT_MATTER>

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Introduction\chapter_introduction)

<P>
Having similar requirements, HFRD has adopted technologies developed on the 
global Internet for the provision, access and navigation of distributed 
information.  This project is known as the World Wide Web (WWW or W3) and the 
technologies are generally described as implementing a distributed 
<EMPHASIS>(Hypertext) environment. 

<P>
The probable reason for your reading this is you being tasked with the 
management of some aspect of HFRD online information.  You can accomplish your 
objectives using the <EMPHASIS>(raw) capabilities of the Hypertext 
environment, or using the facilities described in this document.  It just 
depends on what is required and how much time can be given to this activity.

<P>
This document endeavours to provide you with a basic understanding of how to 
organise (or at least represent) <EMPHASIS>(Hyper-Information) and how to 
present this so that users can readily access it in a meaningful fashion.  It 
concentrates on a simple menuing system, implemented using a plain-text file, 
and maintainable using the text editor of <EMPHASIS>(your\BOLD) choice (see 
<REFERENCE>(chapter_menus)).  The document avoids most of the intricacies of 
the Hypertext environment (discussions of HTML, HTTP and other protocols, 
etc.) but must provide basic information URL file specification.

<NOTE>
This document is <EMPHASIS>(not\BOLD) a tutorial on writing HTML documents.  
If you want to write in HTML see the references in 
<REFERENCE>(chapter_references).
<ENDNOTE>

<COMMENT>(HTML/OFF)
<P>
It is strongly suggested those using printed versions of this document also
access the Hypertext version.  It provides online demonstrations of some
concepts.
<COMMENT>(HTML/ON)

<HEAD>(File Content\head_file_content)

<P>
Generally the most universal, and therefore accessable, file content type is 
<EMPHASIS>(plain-text).  Within the Hypertext environment the other universal
type is <EMPHASIS>(HTML).  All browsers support these.  Providing any other
file type assumes that the client's browser supports it or can activate a
suitable external viewer. 

<P>
It is therefore proposed that for the intermediate future, unless there are 
over-riding reasons otherwise, all documents be provided as plain-text or 
HTML.  All common document processors (word processors, text editors) should 
be capable of producing a plain-text output, and an increasing number of 
formats can be converted to HTML 

<COMMENT>(....................................................................)

<COMMENT>(this next "<COMMENT>(HTML=...)" construct causes only the Hypertext 
document to contain this text) 

<COMMENT>(HTML=
(HFRD will endeavour to make as many of these 
 <A HREF="/hyperdata/html/technical/html.html">tools available</A> as 
practical).
) 

<COMMENT>(....................................................................)

<COMMENT>(the "<COMMENT>(HTML/OFF)...<COMMENT>(HTML/ON)" construct cause this 
section to appear in printed and Bookreader but not Hypertext documents) 

<COMMENT>(HTML/OFF)
(HFRD will endeavour to make as many of these tools available as practical
<BOX>(online document available).
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

  If the document source is in another format it can be provided in parallel, 
and viewed by those capable or saved locally, as appropriate. 

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Data Organisation\chapter_data_organisation)

<P>
Organisation of Hypertext information falls naturally into two aspects:

<LIST>(NUMBERED)
<LE> The physical organisation of the files.
<LE> The logical organisation of the information (structure, relationships, 
interrelationships, etc.)
<ENDLIST> 

<CP>
As this document is a <EMPHASIS>(primer), this section will mainly concern 
itself with the physical organisation of data, which coupled with an emphasis 
on the <EMPHASIS>(menuing) capability within  HFRD (see
<REFERENCE>(chapter_menus)), naturally results in a somewhat hierarchical
logical organisation.  Discussion of inter-document referencing is best left 
to texts on HTML.  Basic references are provided in 
<REFERENCE>(chapter_references). 

<HEAD>(Physical Organisation\head_phys_org)

<P>
HFRD online information resources will have VMS file space provided for them.  
This will comprise a single top level directory under which data files and 
subdirectories can be organised by the manager(s) as required.  PC users will 
be able to <EMPHASIS>(USE\SMALLCAPS) to their area. 

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(File Paths\head_file_paths)

<P>
The information in this section contains some technical information on 
Hypertext referencing and links.  This is directly applicable to specifying 
files in <EMPHASIS>(menus) (see <REFERENCE>(chapter_menus)). 

<P>
File and directory locations are specified using URL syntax (see 
<REFERENCE>(chapter_glossary)), where slash-separated (<QUOTE>(/)) elements 
delineate a hierarchy leading to a data item.  Anyone familiar with the syntax 
of the Unix file system, or the MS-DOS file system (where back-slashes are 
hierarchy delimiters), will feel at home with URL syntax.  File specifications 
under VMS are not case-sensitive.

<P>
A VMS directory specification 

<CODE_EXAMPLE>
  HYPERDATA:[HTML.HTML-PRIMER]
<ENDCODE_EXAMPLE>

<CP>
would be represented in URL syntax as

<CODE_EXAMPLE>
  /hyperdata/html/html-primer/
<ENDCODE_EXAMPLE>

<CP>
and a VMS file specification 

<CODE_EXAMPLE>
  HYPERDATA:[HTML.HTML-PRIMER]HTML-PRIMER.HTML
<ENDCODE_EXAMPLE>

<CP>
represented as

<CODE_EXAMPLE>
  /hyperdata/html/html-primer/html-primer.html
<ENDCODE_EXAMPLE>

<NOTE>

It is not required (although not forbidden) to supply a VMS <EMPHASIS>(master 
file directory) component (<QUOTE>([000000]), <QUOTE>([000000.), etc.) in a 
URL specification.  Hence the file specification 

<CODE_EXAMPLE>
  HYPERDATA:[000000]HOME.HTML
<ENDCODE_EXAMPLE>

<CP>
should be represented as

<CODE_EXAMPLE>
  /hyperdata/home.html
<ENDCODE_EXAMPLE>

<ENDNOTE> 

<HEAD2>(Absolute File Path\head_absolute_file_path)

<P>
A file may be specified using an <EMPHASIS>(absolute), or full path.  
This must specify the location of the file exactly.  Absolute paths 
<EMPHASIS>(always\BOLD) begin with a forward-slash (<QUOTE>(/)).  
For example: 

<CODE_EXAMPLE>
  /hyperdata/committee/minutes/1994/1994-09-27.txt
  /hyperdata/committee/constitution.txt
  /hyperdata/committee/membership/fred-bloggs.txt
<ENDCODE_EXAMPLE>

<HEAD2>(Partial (or Relative) File Path\head_partial_file_path)

<P>
A file may be specified <EMPHASIS>(relative) to its current location.  That 
is, a current document (or menu) may specify another document file relative 
to itself.  This may be at the current level, a subdirectory, or in another 
part of the directory tree related to the current.  Relative paths 
<EMPHASIS>(never\BOLD) begin with forward-slash (<QUOTE>(/)). 

<P>
For example, documents at the same level as the current may be specified 
without any hierachy being indicated:

<CODE_EXAMPLE>
  1994-07-22.txt
  1994-08-24.txt
  1994-09-27.txt
<ENDCODE_EXAMPLE>

<P>
Documents at an inferior point in the hierarchy may be specified as in the 
following example:

<CODE_EXAMPLE>
  1993/1993-02-17.txt
  1993/reports/membership.txt
  other/etc.txt
<ENDCODE_EXAMPLE>

<P>
Documents in a related part of the hierarchy may be referenced using the 
<QUOTE>(<EMPHASIS>(../\BOLD)) construct.  As with MS-DOS and Unix this syntax
indicates the immediately superior directory. 

<CODE_EXAMPLE>
  ../other_committee/1993/1993-02-17.txt
  ../other_committee/1993/reports/balance-sheet.txt
  ../../other_section/committee/constitution.txt
<ENDCODE_EXAMPLE>

<HEAD2>(HYPERDATA Root\head_hyperdata_root)

<P>
<EMPHASIS>(Arbitrary files may not be accessed.\BOLD)

<P>
The Basic HyperText Server (BHTS, see <REFERENCE>(chapter_glossary)) will only 
access files where the path begins with the string 
<EMPHASIS>(HYPERDATA\SMALLCAPS).  This is done as a security measure, 
preventing clients requesting the server to <EMPHASIS>(roam) all through the 
file system.  It is effectively constrained to specified hierarchies using 
this mechanism.

<P>
If a new hierarchy is required contact VMS systems management. 

<NOTE>
The server executes as a normally privileged process and cannot be used to 
subvert security.  It only has access to files are world-readable.  Preventing 
it from roaming the file system keeps the number of security alarms at an 
acceptable level!
<ENDNOTE> 

<HEAD2>(File Permissions\head_file_permissions1)

<P>
As the server executes as a normally privileged process, files it accesses must 
be world-readable, or specifically have the server account granted access in 
an ACL. 

<P>
A protected file results in the server returning an error message and aborting 
the request.

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Menus\chapter_menus)

<P>
The purpose of this menuing system is to provide a simple interface to 
required files. 

<P>
To allow the easy management of information by users not needing to explore 
the relative complexities of HTML a simple menuing system makes a clearly 
presented page available to the client, allowing versatile document retrieval 
and searching.  This is provided through the maintenance of a simple, plain-
text file, which may be edited on any platform (PC, VMS, Unix) and then just 
placed into the appropriate data area. 

<P>
This plain-text file is essentially made up of a series of lines that comprise 
a file name followed by a description (series of words to the end of line).  
Each of these lines is presented to the client <EMPHASIS>(as an item in a list 
that can be selected for access\BOLD).  In its simplest form:

<CODE_EXAMPLE>
  FILE1.TXT   This is the First File
  FILE2.TXT   This is the Second File
  FILE3.GIF   This is an Image (and the third) File
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(this next "<COMMENT>(HTML=...)" construct causes only the Hypertext 
document to contain this text) 

<COMMENT>(HTML=
<P>
An online example:

<UL>
<LI> <A HREF="example1.menu">How it appears to the user.</A>
<LI> <A HREF="example1.txt"><I>Source</I> file.</A>
</UL>
)

<COMMENT>(....................................................................)

<COMMENT>(HTML/OFF)
<P><BOX>(online hypertext demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<P>
When specifying the file items within a menu the file name may not contain
spaces (not unreasonably!).  The first space encountered terminates the file 
name.  Spaces between the end of the file name and the next non-space 
character are ignored.  All characters from the first non-space are included 
in the item description.  The description cannot be continued on the following 
line.  It is reported as an error if no description accompanies a file name. 

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(Providing a Menu Title\head_menu_title)

<P>
To allow a title to be placed on the menu (large, bold font) the plain-text 
file may comprise two blank-line separated sections.  The first section, which 
should be only a single line, is interpreted as the title and presented as 
such.  The blank line indicates that the next section of lines represent the 
list of items (files for access) to be presented to the user.  An example 
would be:

<CODE_EXAMPLE>
  This is an Example Menu

  FILE1.TXT   This is the First File
  FILE2.TXT   This is the Second File
  FILE3.GIF   This is an Image (and the third) File
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(this next "<COMMENT>(HTML=...)" construct causes only the Hypertext 
document to contain this text) 

<COMMENT>(HTML=
<P>
An online example:

<UL>
<LI> <A HREF="example2.menu">How it appears to the user.</A>
<LI> <A HREF="example2.txt"><I>Source</I> file.</A>
</UL>
)

<COMMENT>(....................................................................)

<COMMENT>(HTML/OFF)
<P><BOX>(online hypertext demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(Providing a Menu Description\head_menu_description)

<P>
In addition to a title it is often desirable to provide a brief introduction 
to, or description of, the menu and its purpose, etc.  This may be accomplished 
by adding another blank-line delimited section.  It must follow the title 
line and precede the menu items, and may comprise as many lines as required.
For example:

<CODE_EXAMPLE>
  This is an Example Menu

  This is an example menu.  It has a fairly
  simple structure, yet provides a elegantly
  presented user menu.

  FILE1.TXT   This is the First File
  FILE2.TXT   This is the Second File
  FILE3.GIF   This is an Image (and the third) File
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(this next "<COMMENT>(HTML=...)" construct causes only the Hypertext 
document to contain this text) 

<COMMENT>(HTML=
<P>
An online example:

<UL>
<LI> <A HREF="example3.menu">How it appears to the user.</A>
<LI> <A HREF="example3.txt"><I>Source</I> file.</A>
</UL>
)

<COMMENT>(....................................................................)

<COMMENT>(HTML/OFF)
<P><BOX>(online hypertext demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(File Specification\head_file_specification)

<P>
File are specified using URL syntax. See <REFERENCE>(chapter_data_organisation).

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(Menu File Requirements\head_menu_file_requirements)

<P>
The menu file, being simple plain-text, may be maintained using the text 
editor of choice on the platform of choice (PC, VMS or Unix), and subsequently 
placed into the appropriate data area.  For instance, a PC Pathworks user may 
<EMPHASIS>(USE\SMALLCAPS) to the appropriate VMS data area, then according to 
preference, copy the file to a local disk, edit it, and copy it back to the 
data area, or may edit directly on the network drive.  The former is probably 
safer, allowing intermediate editing to be saved locally without affecting the 
actual online menu. 

<COMMENT>(--------------------------------------------------------------------)

<HEAD2>(Menu File Naming\head_menu_file_naming)

<P>
A menu file may have any name acceptable to VMS, but must have the extension 
<EMPHASIS>(.MENU\SMALLCAPS) or <EMPHASIS>(.MNU\SMALLCAPS) (MS-DOS compliant)
for the server to recognise it.  It is recommended to name a directory-based 
menu <EMPHASIS>(HOME.MENU\SMALLCAPS) (or <EMPHASIS>(HOME.MNU\SMALLCAPS)) for
the following reason.

<P>
If the server is given a URL comprising only a directory name it attempts to
open a <EMPHASIS>(home page) for that directory.  It tries to open one of four 
files in the following order: 

<LIST>(NUMBERED)
<LE> <EMPHASIS>(HOME.HTML\SMALLCAPS)
<LE> <EMPHASIS>(HOME.HTM\SMALLCAPS)
<LE> <EMPHASIS>(HOME.MENU\SMALLCAPS)
<LE> <EMPHASIS>(HOME.MNU\SMALLCAPS)
<ENDLIST>

<CP>
In this way directory access may be transparently supported by either HTML or 
MENU files.  Any directory meant to made accessable to a user need only 
contain one of these files, and if the client specifies only the directory 
name a home page will be found.  If none of these files can be opened the 
server returns an error. 

<COMMENT>(....................................................................)

<COMMENT>(this next "<COMMENT>(HTML=...)" construct causes only the Hypertext 
document to contain this text) 

<COMMENT>(HTML=
<P>
The following are example URLs:

<PRE>  /hyperdata/  This one exists (home page for HFRD)
  /hyperdata/html/  This one does not exist (at least at time of writing!)
</PRE>

<P>
The following provides an online demonstration:

<UL>
<LI>
<A HREF="/hyperdata/">This one exists (home page for HFRD)</A>
<LI>
<A HREF="/hyperdata/html/">This one does not exist 
(at least at time of writing!)</A>
</UL>

<P>
Note that the URL directory specification has a final "/".  This indicates it
is a directory not a file.
)

<COMMENT>(....................................................................)

<COMMENT>(HTML/OFF)
<P><BOX>(online hypertext demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

<HEAD2>(Restrictions\menus_title_restrictions)

<P>
The menu text is interpreted by the browser as HTML.  This allows the menu 
file to contain HTML tags to enrich the presentation if desired.  It also 
means that <EMPHASIS>(some characters cannot be used\BOLD) within the text 
(due to HTML restrictions).  These are few and easily substituted:

<LIST>(UNNUMBERED)
<LE> <LITERAL>(&) <HELLIPSIS> the ampersand.  Substitute <QUOTE>(&amp;).
<LE> <LITERAL>(<) <HELLIPSIS> less than symbol. Substitute <QUOTE>(&lt;).
<LE> <LITERAL>(>) <HELLIPSIS> greater than symbol. Substitute <QUOTE>(&gt;).
<ENDLIST>

<NOTE>
Although allowed, extensive HTML markup of a MENU file is <EMPHASIS>(counter-
productive\BOLD) and is discouraged.  If this is desired, then the file is 
better considered an HTML file and not a MENU file.  Rename it to 
<EMPHASIS>(<EMPHASIS>(filename).HTML\SMALLCAPS) and forget the menuing 
functionality.
<ENDNOTE> 

<HEAD>(Blank Lines\head_blank_lines)

<P>
Please remember the purpose of a blank line within a MENU file file is to 
separate the functional sections (title, description, items).  Arbitrary blank 
lines cannot be included.

<COMMENT>(--------------------------------------------------------------------)

<HEAD2>(File Permissions\head_file_permissions2)

<P>
As the server executes as a normally privileged process, files it accesses must 
be world-readable, or specifically have the server account granted access in 
an ACL. 

<P>
A protected file results in the server returning an error message and aborting 
the request.

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(Online Menu Example\head_online_menu_example)

<COMMENT>(....................................................................)

<COMMENT>(this next "<COMMENT>(HTML=...)" construct causes the only the 
Hypertext document to contain this text)

<COMMENT>(HTML=
<P>
The first of these links retrieves an larger example menu containing some of 
the features described in the section on additional functionality, the second 
is a copy of its plain-text source.  There are actually two files with 
<B>identical content</B> here.  As with other similar examples in this 
document, the reason for the difference in presentation is the first has a 
<TT>.TXT</TT> file type (and is treated by the server as plain-text), while 
the second has a <TT>.MENU</TT> file type (and is interpreted as a menu). 

<UL>
<LI> <A HREF="example4.menu">Formatted menu, as it appears to the user.</A>
<LI> <A HREF="example4.txt"><I>Source</I> file.</A>
</UL>
)

<COMMENT>(....................................................................)

<COMMENT>(HTML/OFF)
<P><BOX>(online hypertext demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Additional Functionality\chapter_additional_function)

<P>
The features described in this section allow functionality other that merely
retrieving and displaying files, and can be easily and effectively employed 
from the menuing system. 

<P>
These features largely depend on the underlying BHTS (see 
<REFERENCE>(chapter_glossary)).  For a document on BHTS, see 
<REFERENCE>(chapter_references)). 

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(Search Items In Menus\head_search_items)

<P>
The menuing system provides a simple text-search capability.  The search is 
for plain-text or HTML-text documents (searches on other types are not 
supported).  For an HTML-text file a hit requires the selecting and reading of 
the entire file, whereas with plain-text a section around the line in which 
the hit occured can also be selectively extracted. 

<NOTE>
Searching is a notoriously CPU and I/O intensive activity.  Longer searches 
progressively decrease scheduling priority by one every 10 seconds, from 
normal to zero, helping to reduce impact on any interactive users of the 
server system.  The search algorithm itself is efficient, but searching will 
take longer on a more heavily loaded system because of this mechanism. 
<ENDNOTE> 

<P>
A search item is produced by simply appending a question-mark to the file 
specification.  Include no intervening white-space.  The description is 
then included as for any other item, as in the following example: 

<CODE_EXAMPLE>
  *.TXT?   Search all TEXT files in this directory
  LAST_YEAR/*.TXT?   Search last year's files
<ENDCODE_EXAMPLE>

<P>
For GUI browsers (such as Mosaic) this will produce an elegant text entry box 
into which the search string can be entered, and an <BOX>([execute]) button 
that may be clicked on (or moved to and activated for text-mode browsers). 

<COMMENT>(....................................................................)

<COMMENT>(this next "<COMMENT>(HTML=...)" construct causes the only the 
Hypertext document to contain this text)

<COMMENT>(HTML=
<P>
The following example illustrates a search item (that is also a live 
demonstration) that would be created using the following construct:

<PRE> HFRD_PRIMER_*.HTML?  Search this document for:
</PRE>

<FORM ACTION="HFRD_PRIMER_*.HTML">
Search this document for:
<INPUT TYPE=text NAME="search">
<INPUT TYPE=submit VALUE="[execute]">
</FORM>
)

<COMMENT>(....................................................................)

<COMMENT>(HTML/OFF)
<P><BOX>(online hypertext demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<HEAD>(Search Options\head_search_options)

<P>
Additional characters may be appended after the question-mark providing 
additional control over the search.

<LIST>(UNNUMBERED)

<LE>
<EMPHASIS>(<QUOTE>(C)  \BOLD) Case-Sensitivity.  A <EMPHASIS>(radio-box) 
selector allows a case-sensitive or case-insensitive (the default) search to 
be selected.

<COMMENT>(....................................................................)

<COMMENT>(this next "<COMMENT>(HTML=...)" construct causes the only the 
Hypertext document to contain this text)

<COMMENT>(HTML=
<P>
The following example provides a live demonstration, that would be created 
using the following construct: 

<PRE> HFRD_PRIMER_*.HTML?C  Search this document for:
</PRE>

<FORM ACTION="HFRD_PRIMER_*.HTML">
Search this document for:
<INPUT TYPE=text NAME="search">
<INPUT TYPE=submit VALUE="[execute]">
<BR><TT>Case Sensitive:
 no<INPUT TYPE=radio NAME="case" VALUE="no" CHECKED>
 yes<INPUT TYPE=radio NAME="case" VALUE="yes"></TT>
</FORM>
)

<COMMENT>(....................................................................)

<COMMENT>(HTML/OFF)
<P><BOX>(online hypertext demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<LE>
<EMPHASIS>(<QUOTE>(O)  \BOLD) Search-Result Output.  A <EMPHASIS>(radio-box) 
selector allows the search results to be listed on a <EMPHASIS>(per-hit) or 
<EMPHASIS>(per-document) basis.  With <EMPHASIS>(per-hit) (the default) each 
line of each file the search string is found in is itemised, allowing its 
immediate context to be assessed and that selectively extracted and viewed.  
For <EMPHASIS>(per-document) only the file is itemised when a hit occurs. 

<COMMENT>(....................................................................)

<COMMENT>(this next "<COMMENT>(HTML=...)" construct causes the only the 
Hypertext document to contain this text)

<COMMENT>(HTML=
<P>
The following example provides a live demonstration, that would be created 
using the following construct: 

<PRE> HFRD_PRIMER_*.HTML?O  Search this document for:
</PRE>

<FORM ACTION="HFRD_PRIMER_*.HTML">
Search this document for:
<INPUT TYPE=text NAME="search">
<INPUT TYPE=submit VALUE="[execute]">
<BR><TT>Output By:
 line<INPUT TYPE=radio NAME="hits" VALUE="line" CHECKED>
 document<INPUT TYPE=radio NAME="hits" VALUE="document"></TT>
</FORM>
)

<COMMENT>(....................................................................)

<COMMENT>(HTML/OFF)
<P><BOX>(online hypertext demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<LE>
<EMPHASIS>(<QUOTE>(A)  \BOLD) Provides information <EMPHASIS>(about) the search.

<COMMENT>(....................................................................)

<COMMENT>(this next "<COMMENT>(HTML=...)" construct causes the only the 
Hypertext document to contain this text)

<COMMENT>(HTML=
<P>
The following example provides a live demonstration, that would be created 
using the following construct: 

<PRE> HFRD_PRIMER_*.HTML?A  Search this document for:
</PRE>

<FORM ACTION="HFRD_PRIMER_*.HTML">
Search this document for:
<INPUT TYPE=text NAME="search">
<INPUT TYPE=submit VALUE="[execute]">
<BR><TT><A HREF="?about=search">About</A> this search.</TT>
</FORM>
)

<COMMENT>(....................................................................)

<COMMENT>(HTML/OFF)
<P><BOX>(online hypertext demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<ENDLIST>

<NOTE>
These may all be selectively applied to a single
search by appending the required character(s) to the file specification.

<COMMENT>(....................................................................)

<COMMENT>(this next "<COMMENT>(HTML=...)" construct causes the only the 
Hypertext document to contain this text)

<COMMENT>(HTML=
<P>
The following example provides a live example, that would be created using the 
following construct: 

<PRE> HFRD_PRIMER_*.HTML?AOC  Search this document for:
</PRE>

<FORM ACTION="HFRD_PRIMER_*.HTML">
Search this document for:
<INPUT TYPE=text NAME="search">
<INPUT TYPE=submit VALUE="[execute]">
<BR><TT>Case Sensitive:
 no<INPUT TYPE=radio NAME="case" VALUE="no" CHECKED>
 yes<INPUT TYPE=radio NAME="case" VALUE="yes"></TT>
<BR><TT>Output By:
 line<INPUT TYPE=radio NAME="hits" VALUE="line" CHECKED>
 document<INPUT TYPE=radio NAME="hits" VALUE="document"></TT>
<BR><TT><A HREF="?about=search">About</A> this search.</TT>
</FORM>
)

<COMMENT>(....................................................................)

<COMMENT>(HTML/OFF)
<P><BOX>(online hypertext demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<ENDNOTE>

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(Directory Listings in Menus\head_dir_listings_in_menus)

<P>
A menu can be used to provide a directory listing.  The server returns a 
directory listing whenever a wildcard is present in a specification.

<CODE_EXAMPLE>
  *.*  The directory this document is in!
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(this next "<COMMENT>(HTML=...)" construct causes the only the 
Hypertext document to contain this text)

<COMMENT>(HTML=
<P>
The following provides an online demonstration:

<UL>
<LI> <A HREF="*.*">The directory this document is in!</A>
</UL>
)

<COMMENT>(....................................................................)

<COMMENT>(HTML/OFF)
<P><BOX>(online hypertext demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(Full URLs in Menus\head_full_url_in_menus)

<P>
In place of a file specification a full URL can be supplied.  It must be 
enclosed by quotation marks.  This allows an item within a menu to specify any 
link acceptable within the Hypertext environment.  For example, the HFRD 
Hypertext Teledex could be included in a menu using: 

<CODE_EXAMPLE>
  "http://host/teledex"  HFRD/DSTOS Hyper-Teledex
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(this next "<COMMENT>(HTML=...)" construct causes the only the 
Hypertext document to contain this text)

<COMMENT>(HTML=
<P>
The following provides an online demonstration:

<UL>
<LI> <A HREF="/teledex">HFRD/DSTOS Hyper-Teledex</A>
</UL>
)

<COMMENT>(....................................................................)

<COMMENT>(HTML/OFF)
<P><BOX>(online hypertext demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Glossary\chapter_glossary)

<P>
This section defines some common terms and acronyms used within this document.

<LIST>(UNNUMBERED)

<LE>
<EMPHASIS>(BHTS  \BOLD) An acronym for Basic HyperText Server, the
HFRD-written server used within HFRD.  It provides unique features such as the 
menuing system. 

<LE>
<EMPHASIS>(Browser  \BOLD) A software application used to navigate, access and 
display Hyper-Information.  See <EMPHASIS>(client).

<LE>
<EMPHASIS>(Client  \BOLD) A software application accessing information 
provided by a separate application executing on another system.  In context, 
the client is a program such as Mosaic, being used to view data stored 
non-locally, and retrieved by a <EMPHASIS>(server) elsewhere.  The client 
application makes a request to the server via the network which returns an 
appropriate response via the same network. 

<LE>
<EMPHASIS>(HTML  \BOLD) HyperText Markup Language is a method of providing 
document formatting information (headings, paragraphs, lists, bold text, etc.) 
within what is essentially plain-text.  It is done by embedding 
<EMPHASIS>(tags) within the text that provide directives to the display 
application indicating the text's function, and by implication how it should 
look.  For instance, a major heading with an italicized word would be
marked-up as follows: 

<CODE_EXAMPLE>
  <LITERAL>(<h1>This is a <i>Chapter</i> Heading</h1>)
<ENDCODE_EXAMPLE>

<CP>
For futher information on HTML see <REFERENCE>(chapter_references).

<LE>
<EMPHASIS>(Home Page  \BOLD) A hypertext page providing access to grouped 
data, often representing a host, directory or directory hierarchy.

<LE>
<EMPHASIS>(Hypertext  \BOLD) Literally <EMPHASIS>(above) or <EMPHASIS>(beyond) 
text.  Encompasses information in all forms, textual, graphical, auditory, 
relational.  Currently organised and accessed using a <EMPHASIS>(rich) textual 
language, HTML. 

<LE>
<EMPHASIS>(Server  \BOLD) A software application that listens on a network 
for a request from an independent <EMPHASIS>(client), and provides an 
appropriate response, usually the return of the data requested.

<LE>
<EMPHASIS>(URL  \BOLD) Uniform Resource Locator, a unique identification 
mechanism for data; the syntax specifying by which protocol (interaction when 
accessing the data), from which host (it is a distributed - read 
<EMPHASIS>(networked) - environment), and an identifier for the required 
datum.  Looks like: <EMPHASIS>(protocol://host/identifier\SMALLCAPS) 

<ENDLIST>

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(References\chapter_references)

<COMMENT>(....................................................................)

<COMMENT>(this next "<COMMENT>(HTML=...)" construct causes only the Hypertext 
document to contain this text) 

<COMMENT>(HTML=
<P>
Available online within HFRD:

<UL>
<LI> <A HREF="/hyperdata/html/html-primer/html-primer.html">A Beginner's Guide
to HTML</A>
<LI> <A HREF="/hyperdata/html/url/url_guide.html">Beginner's Buide to URLs</A>
<LI> <A HREF="/hyperdata/html/bhts/bhts_0000.html">BHTS, The Basic HyperText Server</A>
<LI> <A HREF="/hyperdata/html/uri/uri-spec.html">URI Specification</A>
</UL>
)

<COMMENT>(....................................................................)

<COMMENT>(the "<COMMENT>(HTML/OFF)...<COMMENT>(HTML/ON)" construct cause this 
section to appear in printed and Bookreader but not Hypertext documents) 

<COMMENT>(HTML/OFF)

<P>
The following Hypertext documents can be found online within HFRD:

<LIST>(UNNUMBERED)
<LE> A beginner's Guide to HTML
<LE> Beginner's Guide to URLs
<LE> BHTS, The Basic HyperText Server
<LE> URI Specification
<ENDLIST>

<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

