Using HTML -- GN as a WWW Server

   Starting with release 1.0, the _gn_ server became a multi-protocol
   server. It will accept either gopher requests or HTTP requests and
   respond appropriately. To the maintainer this takes place
   automatically with no action necessary or his or her part.
   
   HTTP stands for Hyper Text Transfer Protocol and it is the underlying
   protocol used by WWW (World Wide Web) browsers such as the Mosaic
   family. Gopher and HTTP each have some advantages not shared by the
   other. Making _gn_ a multi-protocol server is an attempt to let us
   have our cake and eat it too.
   
   While it is correct that as soon as you start up _gn_ you are serving
   documents via HTTP, in order to take advantage of some of the really
   nice features, like images in menus, you do have to put some
   information in your menu file.
   
   HTTP is a protocol designed for use with HTML (Hyper Text Markup
   Language) and the usual HTTP server consists of a collection of
   documents written in this markup language with internal hypertext
   links between them rather than any menus, as such. The _gn_ server
   works with HTTP clients by translating menus into HTML and serving
   them in accordance with protocol that HTTP browsers understand.
   
   In addition you can, of course, create your own HTML documents and
   make them available on your server. You can learn about the format of
   an HTML document from an online beginners guide by Marc Andreessen at
   http://www.ncsa.uiuc.edu/General/Internet/WWW/HTMLPrimer.html (This is
   a URL or Universal Resource Locator which says the document is
   available via HTTP at www.ncsa.uiuc.edu in the file with the path
   given). This document is an excellent introduction to HTML documents
   and gives references for further reading.
   
   Once you have created a document you can serve it with _gn_ by giving
   it a file name ending in .html and making it available in the usual
   way as a text document. For example,

     Name=A Sample of Hypertext Markup
     Path=0/dir/dir2/sample.html

   
   
   If this document is viewed with an HTTP browser it will be displayed
   with the capabilities of that browser (i.e. nicely formatted in the
   ways prescribed by your HTML document). If it is viewed by a gopher
   client the HTML source, i.e. the unformatted document with markup
   tags, will be displayed. If you want to create two versions of a
   document -- one in plain text and the other in HTML, this is easily
   handled by _gn_. Simply give the plain text file a name, say "sample,"
   and use the name "sample.html" for the HTML version. Then use the
   plain text name, but with a Path starting with "0h" (that's zero h).
   For example a menu entry like

     Name=A Sample of Plain/Hyper text
     Path=0h/dir/dir2/sample

   
   
   will provide the file "sample" to gopher clients and "sample.html" to
   HTTP clients. You can also name the plaintext file sample.txt and _gn_
   will automatically change the name to sample.html when putting it on a
   menu for an HTTP browser. This is only true for the suffix ".txt"
   though. If you name the plain version foo.tex then the html version
   must be named foo.tex.html. There is also a "1h" which works
   similarly. If a directory has path field 1h/dir/foo then gopher
   clients will see it in the usual way but for HTTP clients an html file
   /dir/foo.html will be served instead. However, the method described in
   the following paragraph is a better way to deal with putting HTML text
   into menus for most situations.
   
   Adding HTML text to menus works slightly differently. You simply
   include the source in the menu file beginning with the keyword
   "httpText=" on a line by itself and ending with the keyword "endText="
   on a line by itself. Here is an example from the main menu of the _gn_
   server at hopf.math.nwu.edu. It illustrates how to put graphic images
   into a menu.

     httpText=
     <title>The GN Server</title>
     <img src="http:/I/image/fract2.gif">
     <p>
     This is the home of the <i>gn</i> Gopher/HTTP server.  It contains
     documentation on <i>gn</i>, the source, and several examples of how <i>gn<
/i>
     can be used.  To get the source distribution select the compressed
     tar file listed below.
     <p>
     endText=

     Name=Announcement of GN version 1.0
     Path=0/announce-1.0

     etc.

   
   
   After the keyword httpText=, the first line creates a title for the
   document. All HTML "tags" which do the markup are contained in angle
   brackets <>. The line starting <img src=... says to insert the graphic
   image on hopf at port 70 with Path=I/image/fract2.gif at this point in
   the document. The tag <P> indicates a paragraph break. See the
   document mentioned above for more details on HTML. Any HTML text can
   be inserted in this way in a menu. There can be multiple insertions
   and they can be anywhere in the text.
   
   If you use the keyword Text= in place of httpText= then _gn_ will
   serve the text to HTTP clients exactly as with httpText=, but will
   also put the text (with all HTML tags deleted) in the gopher menus
   using the 'i' or comment type supported by many clients. For the
   gopher clients no text formatting is done. The lines will have the
   same length they do in your menu file.
   
   Sometimes it is desirable to actually put HTML constructs into a menu
   line itself. This can be accomplished by using Hname= instead of
   Name=. For example the menu entry

     Hname=Sample</A> of <A HREF="http://host/hyper.html">Hyper text</A>
     Path=0h/dir/sample

   
   
   will produce a menu item for gopher clients linked to /dir/sample, but
   for HTTP clients there will be two links the first with anchor
   "Sample" to /dir/sample.html, and the second with anchor "Hypertext"
   to /hyper.html. In an Hname line there must always be at least one
   closing anchor to close the anchor automatically opened at the start
   of the line which provides a link to the item in the Path field.
   
   HTML documents normally have a title given at the beginning of the
   document and set off by the tags <TITLE> and </TITLE>. This is
   displayed by most browsers. When _gn_ menus are converted to HTML
   documents the Name= entry from the parent menu is used as the title
   except for the root menu (which has no parent). The default root menu
   title is set in the config.h #define ROOT_MENU_NAME, but this can be
   changed executing _gn_ or _sgn_ with the -t option followed by a
   quoted title. For example the command

     sgn -t "My Server"

   will set the title to My Server.
   
   Finally, it is possible to use _gn_ as server to serve only HTTP
   clients and have no menus. Well, there would have to be one menu, the
   root menu, but it could contain nothing but HTML surrounded by the
   keywords httpText= and endText=. This document could have hypertext
   links to other HTML documents which in turn have hypertext links, etc.
   It will still be necessary to create "dummy" menu files in each
   directory with the Path of each of the HTML files and to run mkcache
   to create .cache files. This is for security reasons.
   
.