                                       User Guide for the WWW Line Mode Browser
                             WWW LINE MODE BROWSER
                                       
   The World-Wide Web line-mode browser allows you to find information by
   following references and/or by using keywords.
   
   References are numbers in [brackets] after particular phrases. Type the
   number and RETURN for more information on the phrase.
   
   Some documents are indexes. These contain little text, but allow you to
   search for information with keywords. Type "find" or "f" (space) and the
   keywords. For example, "f sgml examples" searches the index for items with
   keywords SGML and EXAMPLE. You can only use the "find" command when it is
   present in the prompt. You can omit the "f" if the first keyword doesn't
   conflict with existing commands .
   
   Futher information:  command line syntax , shortcuts , installation ,
   customization , deeper details .
   
   Please send any bugs and suggestions to www-bug@info.cern.ch.
   
                                                                         Tim BL
                                                                               
   
                                                          Commands -- /LineMode
                                   COMMANDS
                                       
   The following commands are available at the prompt within www . Some are
   disabled when not applicable. All commands may be abbreviated. Case is not
   significant.
   
  Help                    Gives a list of available commands depending on the
                         context, the version number of the www program, and
                         the hypertext address , (or UDI) of the document you
                         are reading.
                         
  Manual                 Jumps directly to the master source of the online
                         manual.
                         
  <Return>                Just hitting Return displays the next page of the
                         current document.
                         
  <number>                Typing a number by itself follows the corresponding
                         reference from the currently displayed document.
                         
  Find <keywords>         Queries the current index with the supplied keywords
                         (separated by blanks). The interpretation of the
                         keywords depends on the particular information server
                         you're looking at. In most cases, it will search a
                         database for entries matching the keywords, and will
                         display the results with possibly links to further
                         details. For more complex queries, instructions should
                         be present in the cover page. The "Find" command can
                         be omitted if the first keyword does not conflict with
                         another www command.
                         
  Back                    Goes back to the document you were reading before.
                         
  Home                    Goes back to the first document you were reading.
                         
  Recall                  Without a parameter, gives a numbered list of the
                         documents you have visited.  To select one, type
                         "Recall" followed by the number.
                         
  List                    Gives a numbered list of the links from the current
                         document, giving the title of the target documents (or
                         addresses if no title). To follow a link, type the
                         number by itself as above.
                         
  Next, Previous          Goes to the next or previous document in the list of
                         pointers from the document that led to the current
                         one. This is better explained with an example: suppose
                         you are reading a document which looks like a menu,
                         and you want to read all entries in turn. You first
                         type "1" to read the first referred document (by
                         following the first link), and then you type "next" or
                         just "n" to read the next one from the menu, without
                         actually coming back to the menu and typing "2", etc.
                         
  Go <address>            Goes to the document represented by the given
                         hypertext address , which is interpreted relatively to
                         the current document.
                         
  Up, Down                Scrolls up or down one page in the current document.
                         
  Source                  Followed by another command, causes raw source to be
                         generated for that command. Useful for printing
                         postscript files without formatting, with SOURCE
                         PRINT.  See examples .

                                                  Commands -- /LineMode (66/67)
  Top, Bottom             Goes to the top or the bottom of the current
                         document.
                         
  Verbose                 Toggles verbose mode (for maintenance purposes).
                         
  Quit                    Leaves the application.
                         
   On Unix versions, the following extra commands are available:
   
  Print                   Prints the current document, without the numbered
                         document references. A background www is launched to
                         do that, and its output is piped to the command
                         defined by the environment variable WWW_PRINT_COMMAND
                         ("lpr" by default).
                         
  > file, >> file         Saves or appends the current document to the given
                         file, without the numbered document references. A
                         background www is launched to do that.
                         
  | command               Pipes the current document to the given command,
                         without the numbered document references. A background
                         www is launched to do that.
                         
  ! command               Executes the given shell command without leaving www.
                         
  CD (or LCD) directory   Changes the local working directory. "! cd directory"
                         won't do this because it applies to a subshell.
                         
                                                                         Tim BL
                                                                               
   
                                                    SourceExamples -- /Defaults
                           USING THE "SOURCE" PREFIX
                                       
   Note: Version 1.3 and later.  The SOURCE (S) prefix to a command within www
   qualifies the execution of that command.  It make the command generate raw
   unformatted text instead of formatting it. Som examples of use are:
   
Printing Poscscript documents

   Currently, a postscript document comes up on the screen in its postscript
   form.  Printing the display from the screen, formatted, is not a good idea
   as the postscript is damages by being formatted. Use with PRInt to send the
   document to the printer directly:
   
                        SOURCE PRINT

   You must have a postscript printer for this to work.
   
Looking at SGML source code

   If you want to see the SGML source of a document, prefix the FIND or jump
   command with SOURCE.
   

                        SOURCE > temp.html

   saves the current document in a file temp.html.
   
                        SOURCE 1

   Follows the first link from the current document, displaying the source of
   the destination document.   Note that while the raw data is retrieved
   without interpretation, it is formatted for display on your terminal in this
   case.
   
What it won't do

   SOURCE won't change the format of a document already loaded, so SOURCE by
   itself won't display the source of the current document.
   
   SOURCE only works for documents from W3 servers and, to a certain extent,
   news articles. You can't get original source for for example file
   directories.
   
                                                                         Tim BL
                                  Command Line Syntax for the Line Mode browser
                              COMMAND LINE SYNTAX
                                       
   The syntax is:
   

                www [options]  [docaddress [keywords]]

   With no arguments, the www shell command allows you to browse from the
   system default page, /usr/local/lib/WWW/default.html.
   
   Options should be specified before other arguments. Currently available
   options are:-
   
  -n                     Non-interactive mode.  Outputs the formatted document
                         to the standard output, then exits.  Pages are
                         delimited with form feed (FF) characters.
                         
  -                       A minus sign with no trailing characters indicates
                         that the program will accept HTML format input from
                         the standard input. This allows www to be used as a
                         filter from html to plain text for example. Relative
                         links in the input are parsed as though the address of
                         the document was that of the home page (or  docaddress
                         if specified). Implies non-interactive mode.
                         
  -listrefs               Implies non-interactive. Adds a list of the addresses
                         of all documents references to the end.
                         
  -pn                     where n is a number, specifies the page length.
                         Without a number, makes the page length infinite.
                         Default is 24.
                         
  -r file                Rule file (configuration file).  If this is specified,
                         a rule file may be used to map URLs, and to set up
                         other aspects of the behaviour of the browser.  Many
                         rule files may be given with successive -r options.
                         One rule file name may be given using the WWW_CONFIG
                         environment variable.
                         
  -source                 Display the original source of a document instead of
                         parsing it. Has effect for HTML from w3 servers, and
                         news articles. (v1.2a or later)
                         
  -v                      Verbose mode: Gives a running commentary on the
                         program's attempts to read data in various ways.
                         
  -wn                     where n is a number, specifies the page width in
                         columns. The default is 78, 79 or 80 depending on the
                         system. (v1.0 or later)
                         
  -na                     Hides anchor positions in the text. Useful, when
                         printing out the document.
                         
  -a  format              Specifies the printf-style format string to be used
                         when printing references. Must contain the two
                         characters "%d" where the numbers should occur.  Be
                         sure to escape or quote any special characters you
                         use.  For example under unix:
                         

                                www -a \<%d\>
                                www -a " (Type %d)"

  -version                Prints out the version number of the software, and

                          Command Line Syntax for the Line Mode browser (65/66)
                         the version number of the WWW library, and exits.
                         
   If present, the next argument (docaddress) is the hypertext address , of
   the document at which you want to start browsing. You may want to define an
   alias for www followed by name of your favourite index.
   
   Any further command line arguments are taken as keywords. The first argument
   must refer to an index in this case. The index is searched for entries
   matching the keywords, and a list of matching entries is displayed.
   
                                                                         Tim BL
                                                                               
   
                                                         Shortcuts -- /LineMode
                                   SHORTCUTS
                                       
   To save having always to go through the www default page, you can use a
   shortcut to get to an index. On the central CERN nodes for example, the
   following shell commands are predefined:
   
  yellow                  The CERN yellow pages telephone directory.
                         
  xfind                   The CERN computer center documentation keyword index
                         
  vmnews                  The CERN computer centre news service: all news
                         articles, in reverse chronological order.
                         
   You can search an index which has a shortcut command by giving the keywords
   as parameters, e.g.
   

                        yellow taxes


   To make your own shortcuts, you can define your own commands. On Unix (with
   csh), use an alias (see VMS equivalent ) :
   

                        alias  z  www  address

   where address is the hypertext address of the document you want to jump
   into. You can find the hypertext address of a node from HELP command when
   you are in www.
   
   An alternative method uses a shell script.
   
                                                                         Tim BL
                                                     VMS_Shortcuts -- /LineMode
                             VMS SHORTCUT COMMAND
                                       
   On VMS, to make a shortcut command , use a symbol:
   
                $ Z :== 'WWW'  """address"""


   substituting Z with the shortcut command name, and the word "address" with
   the actual hypertext address.
   
   Note that you MUST use single quotes around WWW, and THREE DOUBLE QUOTE
   CHARACTERS each side of the address. (That's DCL syntax for you!)
   
                                                                         Tim BL
                                                                               
   
                                                      Installation -- /LineMode
                                INSTALLING WWW
                                       
   This section describes how to install the World-Wide Web line-mode browser
   called "www". First of all,
   
      If you have a VAX/VMS machine, then see the special instuctions for VMS
      
      If you have not already got hold of the files, see the section on getting
      them .
      
      If you have a VM mainframe, see special instructions .
      
   The browser has already been ported to many machines. Check the list of
   machine types for your machine. If your machine is not one of those, see the
   section on porting .
   
If the binary is available

   If you found your machine type, check in the anonymous FTP archive for the
   subdirectory of /pub/www/bin for your machine. If that directory exists and
   contains a file named www with some version number appended, then select
   binary mode and take the file, calling your copy www. Otherwise, go to
   "compiling from source " .
   
      Copy www into an apropriate directory which appears in your path. If you
      can be superuser, this can be /usr/local/bin/www (typically) so that
      everyone can use www. If you cannot be superuser, see how to use www
      without being superuser ).
      
      If you type "rehash", you will be able to use www. It will start at a
      default home page which is at CERN.
      
      To make your own home page, take the tar file WWWLineModeDefaults.tar.Z.
      Unwrap it and put the files into a directory /usr/local/lib/WWW. Now skip
      to make yourself at home below.
      
Compiling from source

   If a binary is not available, see instructions for compiling from source.
   
      You must get, uncompress and untar BOTH the WWWLineMode* product AND the
      WWWLibrary* product source tar files.
      
      Find the subdirectory of WWW/LineMode named after your machine type. cd
      to it.
      
      Check the directory definitions in the Makefile, and change them if
      necessary. See the definition of the macros in the file
      Implementation/CommonMakefile .
      
      Type "make lib". You should get a file WWW/Library/libwww.a
      
      Type "make". You should get a binary of WWW/LineMode/www.
      
Installing

      Become superuser (su root).  If you can't do this, see how to do it
      without being superuser ).
      
      Type "make install". A reference copy of the executable is made and
      copied into the system.
      
   The "make install" step creates a copy in your system directories of the www
   executable and the basic documenattion. If you wish to just soft link them

                                              Installation -- /LineMode (65/66)
   to the files on the WWW tree, say "make link" instead. After either of
   these, "make clean" will remove intermediate files.
   
Make yourself at home

   You must now check that the default "Home" page works, and customize it if
   it is not what you want. The default home page just a place to start. The
   cern.html file (distributed at the same time) is an example of a customized
   home page. You may wish to chose one of these as a basis.
   
Setting up news

   To read Internet news, you must have first defined the news server's address
   .
   
                                                                         Tim BL
                                                                               
   
                                                  Installation_VMS -- /LineMode
                            INSTALLATION UNDER VMS
                                       
   To install under VMS, get the files WWW.EXE and SETUP.COM from sources
   described below. To set up the commands, put the command
   
                        $ @[...]SETUP

   into your LOGIN.COM, or the system SYLOGIN.COM.  This command file assumes
   you have left all the distributed files  in the same directory as itself.
   
Customization using logical names

   Under VMS,  the home page may be defined using the logical name WWW_HOME.
   You should define this to be the full address of the document which you want
   to be displayed when www is invoked without parameters. For example,
   
        $ DEFINE/SYSTEM WWW_HOME "file://myvax/sys$library/default.html"

   Note that the www address you must set it to is still in unix-like format
   (with slashes instead of :: : [.])Users may of course override the system
   logical name with their own. If no logical name is defined, the VMS browser
   will default to picking up the default page from our server,  document
   http://info.cern.ch./default.html.
   
   The other customization variables may be defined in the same way.
   
   Accessing VMS files
   
   If you are making you own home page, or any other documentation, you will
   probably want to store it on your VMS machine. The www program has the
   ability, if running under VMS,  to access VMS files. the document name for a
   VMS file is simply the filename, but:
   
   The host name must be the name of the machine WITHOUT any domain name on it,
   e.g. //vxcrna/
   
   The filename is written with each punctuation converted into a single slash.
   Examples are
   
 Document identifier                            Filename

 file://vxcrna/sys$www_home                     vxcrna::sys$home

Availability of .EXE files

   Versions are available for any of the following implementations of TCP/IP
   which you may have installed on your system: Digital's UCX, Wollongongs's
   WIN/TCP, or SRI's Multinet.  If you are on the High Energy Physics DECnet,
   the versions are currently (Jan 92) available compiled in directories as
   follows:
   
  Wollongong WIN_TCP      none - see recompiling .
                         
  Multinet                vxcrna::disk$oc1:[timbl.www.multinet.works]
                         
  Digital's UCX           vxcrna::disk$oc1:[timbl.www.ucx.works]
                         
  CMU TCP                 none - see recompiling .
                         
   If you are not on HEPnet, but can pick up binary files from info.cern.ch
   using FTP,  then you will find executables in the /pub/www/bin/vms, as files
   www_ucx.exe or www_multinet.exe. Remember to transfer in binary mode. Pick
   one and rename it to www.exe
   

                                          Installation_VMS -- /LineMode (65/66)
Rebuilding from source

   You may have to do this if your sharable libraries are not compatible with
   those for which the .EXE file was built. If there is a version
   incompatability, then you get an explicit message about sharable library
   versions when you try to run www.
   
   If you have utilities for uncompressing and untarring the main source file,
   then you could remake the distribution from source.
   
   Another way of getting the sources up can be used if you happen to have
   access to an untrix machine on the same DECnet as your vax. FTP the source
   tar file over to the ultrix machine, uncompress it and untar it, then copy
   over the descrip.mms in LineMode/Implementation/vms. In there you'll find
   all the commands to copy the sources from a unix machine (PRIAM:: in that
   instance -- you'll have to edit it) and rebuild the .exe.
   
   When you remake the exe, you must specifify
   

                        MMS/MACRO=(MULTINET=1)
                or

                        MMS/MACRO=(WIN_TCP=1)
                or

                        MMS/MACRO=(UCX=1)

   to get the right version for Multinet, Wollongong TCP or DEC/UCX
   respectively.
   
                                                                         Tim BL
                                                                               
   
                                           Installation_VMS_NewTCP -- /Defaults
                             RECOMPILING  FOR VMS
                                       
   This is how to get the sources for www and recompile them.  You need to do
   this if you have a shareable library incompatibility with the distributed
   executable. The tar file is, on info.cern.ch,
   /pub/www/src/WWWLineMode_v.vv.tar.Z,  v.vv being the version - get the
   latest.  If you are on the HEP DECnet, then the files can be found under
   
                        vxcrna::disk$oc1:[timbl.www.*]

Changing to a new TCP/IP version

   Do this bit if your TCP/IP system is not  SRI/Multinet, DEC/UCX or whatever
   they call it now, or Wollongong TCP/IP.
   
   You might need to change something in tcp.h which is the system specific
   include file, and in descrip.mms, the makefile. If you do, please mail me
   the changes.
   
   Look for all occurences of "MULTINET", "UCX" or "WIN_TCP" and add a
   "CMU_TEK" or whatever where necessary.  The same goes for decsrip.mms. This
   will need to pass the CMU_TEK option onto the c compiler in the CFLAGS
   macro, and also use different libraries for the link. Changes to other files
   will probably not be necessary.
   
   [The program uses the socket library in a very standard way - no tricks. You
   just have to get the include files from the right place and fix the macros
   for NETREAD etc to whatever CMU-TEK calls the socket read() function. It
   can't call it read() because that's in the VMS unix library already for file
   access. You notice that under some systems the read does a socket_read or a
   real read depending on whether the socket number is small (unix) or large
   (VMS channel=socket).  I don't know what CMU-TEK does but I'm interested to
   know  If you don't know either, try compiling for say WIN_TCP and see what's
   undefined and mail me]
   
   If you do this, let me know how you get on, please!
   
Compiling

   One way, if you have a unix (sultrix?) system with DECnet is to unwrap the
   tar file on that system.
   
   Then copy WWW/LineMode/Implementation/vms/descrip.mms across to VMS. Edit
   descrip.mms so that all the references to $(U)"/userd/tbl/hypertext are
   changed to point to the decnet address of the files you have unwrapped on
   the unix system. Then run mms with /macro=(u=HOST::, cmu_tek=1) -- whatever
   your unix HOST is -- and it will pickup all the files from your unix system.
   
   The other way is to uncompress/untar it on under VMS, if you have a tool to
   do that, and just run mms/macro=(cmu_tek=1).
   
                                                                         Tim BL
                                                                               
   
                                                      Distribution -- /LineMode
                             GETTING THE WWW FILES
                                       
   Read this if you have not yet got the WWW files you need, and you cannot NFS
   mount a directory on which they reside.
   
    The source and binary of CERN WWW project files are currently available
   (see copyright ) by anonymous FTP from node info.cern.ch.  This node is
   currently 128.141.201.74 but THIS MAY CHANGE. The files are compressed tape
   archive files (.tar.Z).  To get  a file using anonymous FTP, use user name
   "anonymous", and your email address as a password:-
   
                        > ftp info.cern.ch
                        Enter user name: anonymous
                        Password: me@myhost.edu
                        ftp> cd /pub/www/src
                        ftp> binary
                        ftp> get WWWLineMode_vvv.tar.Z
                        ftp> quit
                        >

   The file name will depend on the product you want.  Here vvv is the version
   number of the software.
   
   Once you have the compressed tar file, you must uncompress it and unwrap it.
   
                        uncompress WWWLineMode_vvv.tar.Z

   This will make a rather larger file with the name without the ".Z". To
   unwrap it,
   
                        tar xvf WWWLineMode_vvv.tar

   Now you should install the line mode browser , install the server , install
   Viola , etc.
   
                                                                         Tim BL
                                                                               
   
                                                           Porting -- /LineMode
                           PORTING TO A NEW MACHINE
                                       
   Read this secion if the browser has not already been ported to a
   binary-compatible machine.We assume you have a unix-like environment,
   including some sort of C (either Kernigan and Ritchie or ANSI) compiler, and
   a socket library supporting TCP/IP communications.  The browser has been
   ported to many systems, and so you should not have much trouble with a new
   one.
   
      Make a new subdirectory under WWW/LineMode for your combination of
      machine and operating system.
      
      Copy the Makefile from another (similar) machine's subdirectory.
      
      Modify the Makefile as necessary to compile and install on your system.
      This involves selecting the compiler command, flags, etc, to be used, and
      specifying directory names. See the file Implementation/CommonMakefile
      which is included in the Makefile. Type  "make" to generate an executable
      file.
      
      Mail the Makefile, and any other changes you found were necessary, back
      to us for the use of others. This is mandatory
      
   Now install the software .
   
                                                                         Tim BL
                                                                               
   
                                                      MachineTypes -- /Defaults
                                 MACHINE TYPES
                                       
   The W3 code is distributed with machine-specific files for certain
   platforms.
   
      Binaries, where they exists, are in subdirectories of the /pub/www/bin
      distribution directory.
      
      Machine-specific Makefiles and other sources are in subdirectories of the
      Implementation (src) directory for a product.
      
   The subdirectory names are as follows.  Please consider all trademarks to be
   acknowledged as such.
   
  apollo_m68k             Apollo unix machines based on the M680x0 series CPU.
                         (i.e. not HP snake)
                         
  decstation              Digital DECstations.  (MIPS-based workstations)
                         
  mac                     The Macintosh range from Apple.
                         
  next                    NeXT -- all machines (non-RISC)
                         
  pc-nfs                  IBM-PC compatible, with socket library from the
                         PC-NFS product.
                         
  rs6000                  IBM's rs6000 range of AIX workstations
                         
  sgi                     Silicon Graphics Inc's workstations.
                         
  snake                   HP700 and HP800 series.
                         
  sun3                    The sun-3 (M68k based) series of workstations.
                         
  sun4                    The sun4 (RISC) series of worksations.
                         
  vax_ultrix              VAX machines running ultix for which gcc exists.
                         
  vax_ultrix_cc           VAX machines tunning ultrix, using the native cc
                         compiler.
                         
  vms                     The VMS operating system for DEC's VAX range.
                         
  unix                    Generic unix source: if your machine is not listed,
                         check these Makefiles for necessary changes fro yoru
                         system then run them. If you need to make changes
                         please mail back the new file to www-bug@info.cern.ch
                         for inclusions in future releases.
                         
                                                                         Tim BL
                                                                               
   
                                                      InstallNotSU -- /Defaults
                    INSTALLING WWW IF YOU ARE NOT SUPERUSER
                                       
   So you want to install www, but you do not have the privilege to become
   super-user.   No problem: you can install it for your own use.
   
   You have found (or built if it did not exist ) a subdirectory of
   WWW/LineMode/Implementation for your type of machine.
   
   You have modified the Makefile in that directory to reflect the directory
   name. Don't worry about BINDIR, the name of the installation directory,
   because you aren't making a system-wide installation.
   
   Type
   
                        make


   This should generate the executable file called "www". There are two ways
   you can make this available.
   
   One is, if in your " path " there is a directory to wrich you do have write
   access, then you put move www into that directory. You may have to then
   "rehash" to regenerate the list of commands.
   
   If there isn't a writable directory on your path, then you can put an alias
   command into a login shell script (.login or .cshrc) to define www as being
   a file in the directory where it is.
   
   Now if you run www it will complain that it can't find the default home
   page, /usr/local/bin/WWW/default.html.  You will find a copy of a default
   page in the distribution WWW/LineMode/Defaults/default.html.
   
   In your login shell script ,  set the environment variable WWW_HOME to  the
   full pathname of default.html as distributed, or to the w3 address of the
   copy on our server. See customization about how to set environment
   variables.
   
                                                                         Tim BL
                                                                               
   
                                                              Path -- /Defaults
                                  UNIX "PATH"
                                       
   This is the set of directories which the system looks in for executable
   files.  You can find out what your path is by the command
   
                        echo $path

   Normally the path is set by a command in your login shell script . Remember
   that if you change your path, then you must type
   
                        rehash

   so that the shell rebuilds the set of executable files which it will accept
   as commands.
   
                                                                         Tim BL
                                                                               
   
                                                       LoginScript -- /Defaults
                               YOUR LOGIN SCRIPT
                                       
   Under unix, when you start your shell, a login script is executed. Use the
   manual page for your shell to find out more about this.  If you are using
   csh, then files .login and .cshrc in your home directory are both executed.
   
   [Remember that ls -a displays also filenames which start with a dot, whereas
   ls normally hides them...]
                                  Customizing  WWW line mode browser operation 
                                CUSTOMIZING WWW
                                       
   Customizing www 's behaviour is done with environment variables or their
   equivalent.
   
   " Environment variable " is a unix term. On VMS you should use a logical
   name . Under VM/CMS use a global variable .
   
   You can also customise www by defining your own "www" command to invoke www
   with certain command line options set, such as the page length. See also how
   to make shortcut commands (aliases) , and how to set up gateways.
   
   A list of things you can customize with environment variables (or local
   equivalents) are as follows:-
   
WWW_HOME

   The address of the first document to start with if you run www without a
   document name on the command line. For example, you can set it to
   

            http://info.cern.ch/hypertext/WWW/LineMode/Defaults/default.html

   if you want to always use the home page on the CERN information server.
   
   As the line mode browser is installed, it comes with a default copy of that
   home page, frozen at the time when the distribution was made. That page has
   (right at the bottom) a link back to the current version on our server.  If
   you are installing www without privileges, you may not be able to install
   the home page, and so you will have to set WWW_HOME to point to a local copy
   of the file, or to our server.
   
   You can customize www to start at a page of your choice. You can write your
   own page, or use someone else's. All you have to do is to set the
   environment variable WWW_HOME to the www address of your preferred home
   page. (When you are using www, you can see what an address looks like by
   typing help when you are reading a document - it tells you the address of
   that node).
   
WWW_CONFIG

   If defined, must be the name of a local file which contains configuration
   information including rules, presentation recipes, etc.  If  configuration
   files are also specified using the -r option, they are loaded first.
   
NNTPSERVER

   See how to set up the news server's address .
   
WWW_PRINT_COMMAND

   Unix only. A quoted printf-style format string for the system command you
   wish to invoke with the www PRINT command.  This should contain one %s
   marker where www should put the name of the document to be printed. The
   default is
   

                        www -n -na -p66 '%s' | lpr

   (The single quotes around the %s are necessary in case the address contains
   shell metacharacters. When you define this variable, you may of course have
   to enclose the whole thing in double quotes, e.g.
   


                          Customizing  WWW line mode browser operation  (65/66)
        setenv WWW_PRINT_COMMAND "www -n -na -p66 '%s' | lpr"

                                                                         Tim BL
                                                                               
   
                                                      EnvVariables -- /Defaults
                            ENVIRONMENT VARIABALES
                                       
   Under unix, environment variables are used to pass information to programs
   to modify how they should run.  They are used for customizing www for a
   particular user's requirements.
   
   See also:  VMS logical names, VM/CMS globalv.
                                                           GlobalV -- /Defaults
                         GLOBAL VARIABLES UNDER VM/CMS
                                       
   (These are the equivalent of environment variables under unix.)
   
    A particular GLOBALV table (CENV) is used to hold the C environment. The
   command to set a variable VVVV to a value XXXX is
   
                GLOBALV SELECT CENV SET VVVV XXXX

   for example
   
                GLOBALV SELECT CENV SET WWW_HOME http://info.cern.ch/junk.html

   Beware of the fact that CMS puts everything into upper case.  It is not
   obvious how to get around this problem without writing a little REXX exec to
   do what you want.
                                                        NewsServer -- /Defaults
                              NEWS SERVER ADDRESS
                                       
   To be able to read news, the www program needs the address of a news server.
   This is a machine which runs the NNTP protocol.  If you already use internet
   news on your site, you will have one of these. There are several ways you
   can tell www which news server to use.
   
   Note you may also have your machine enabled as being authorised to pick up
   news from the news server by that server's system manager.
   
Exception

  On a NeXT               The NeXT defaults are read, looking for a value for
                         "NewsHost" for application name "WorldWideWeb", then
                         for a global default, then for application named
                         "News".
                         
All other cases

  SET AN ENVIRONMENT VARIABLE
  
   You can set the environment variable NNTPSERVER to be the internet address
   of the server. You can do this in your .login file. (On VMS, use a logical
   name, on  VM/CMS, the CENV globalv table).
   
  USE A FILE
  
   The file /usr/local/lib/rn/server will be read if it exists and no
   environment variable is defined.  It should contain the single line
   containing the name of the news server.  This filename may be overridden at
   compile time by defining the SERVER_FILE symbol to be the quoted string.
   
  AT COMPILE TIME
  
   If you are installing www for several people, you can set the default by
   defining the variable DEFAULT_NEWS_HOST to be the quoted string of the
   server name on the command line fo the compilation of the HTNews.c module
   For example, use the option (check your own compiler's command line syntax)
   

                        -DDEFAULT_NEWS_HOST="mynewshost.domain"

  USE A DOMAIN NAME ALIAS
  
   If  no other deafult news host is found, the software looks for a machine
   with name or alias "news" in the local domain. If your domain has a single
   news server which you would like to use as a default, and the person in
   charge of the domain name registration agrees, then make an alias "news" for
   the server. This will have the managemnt advantage that the administration
   can move the news server without any trouble later.  (This is the way it is
   done at CERN).
   
                                                                         Tim BL
                                                         Line Mode Browser bugs
                         BUGS, AND IMPROVEMENTS NEEDED
                                       
   The following are known bugs in the line-mode browser , and improvements
   which we have in mind. See also the list of features added.
   
   
   
Known Bugs

   Spacing is not very intelligent around anchors.
   
   Save to file, print, etc.  Don't  use systm(), just set up a stream.  Will
   then work on VMS too.  Judy Nicholls nicholls@fnal.gov
   
   Telnet problem:  If one visits a telnet node and then revisits it, an empty
   page is displayed.
   
   When saving a file with ">", should ask confirmation if the file already
   exists.
   
Improvements for the near future

   Paragraph numbering option (Gene Oleynik, Oleynik@fndaut.fnal.gov) for long
   documents or serialisations.
   
   Style sheet load from disk.
   
   A command line option to print out the version of the software. Currently
   one has to start it and type "help". (--JP Matheys)
   
   While connecting, if timeout is long, how can we make it less painful for
   the user -- if necessary in a non-portable way? Variation of "Connect" whih
   displays a message? Allow user to quit or keep trying? Change the underlying
   timeout?
   
   Should we always put a CR/LF after the prompt, to allow a long list of
   keywords (Peter Dobberstein and DESY colleagues: yes)? Advantage: one can
   always type in many keywords. Disadvantage: one less line of text on the
   screen. The NEWLINE_PROMPT compile switch lets you choose.
   
   Better error reporting. Difficult when many possible paths have been tried.
   Save log of attempts? Portability of error message generation?
   
   Command: Append to a given file a hypertext reference to the document.
   
   In UNIX a document address given as a command line argument is parsed
   relative to the current directory. A similar thing needs to be applied for
   VMS and MVS environments.
   
   Keep all anchor information, in case user returns to a previous node, then
   the information is automatically available.
   
   Try to use ^z key and predefined keys like F10 to exit from the program
   under VMS.
   
   Ask user about strange formats. Unable to deal with anything other than HTML
   and plaintext files (now just displays it as plaintext). Offer to display it
   as plaintext, store the file somewhere, or print out on a default printer.
   
   Create a new tag
   

            <OUTLINE> and </OUTLINE>.


                                                 Line Mode Browser bugs (65/66)
   These are placed around a paragraph and effects any headings contained
   within them, removing all blank lines above and below, and not allowing
   capitalization. Also, maybe use this tag to indicate that the position of
   the anchors should be at the start of the line, in front of the sensitive
   text.
   
   Compare LineMode Parser and the NeXT Parser, and produce with a common
   module that can be used by both browsers, and maybe for the Mac version
   aswell. Also will provide access to the Internet News.
   
Other Improvements

   Pick up the size of a file before trying to store in a buffer. If too large
   only read in part of the file, and then only call up the file again if the
   user requires more data. For example in the case of
   'http://crnvmc/FIND/DESY?NNEWS8' and then reference number [3].
   
   If the user needs to print out documents when following links, instead of
   inserting anchor numbers, insert page numbers of the destination nodes, as
   they would appear in the printed document. Do this by first following the
   links with no output on the screen, reading all the files into the buffer
   and calculating the page numbers. Then go through the path again, with
   output directed to the printer, inserting the correspondng page numbers
   rather than the anchor numbers.
   
   Apply glossary first line indent code to produce ordered lists.
   
   Deal with lists within lists.
   
   At the end of a document, produce the last page if the user presses return.
   
   Put some form of paging into reference and recall lists.
   
   Offer a no blank line spacing option. User defined style sheet?
   
   Use cursor functions (termcap or curses).
   
   Add a search facility within the document for when a long document is
   returned.  -- jackson@stsci.edu
   
   Change code to look like a 'more' or 'less' program. Public copies of this
   program may be available from Antonio Pastore or Roberto Divia.
   
   Offer some kind of editing of the style sheet to the user.
   
Users Comments

   Highlight headings.
   
   Maybe move anchor numbers to the left hand side, rather than after the
   sensitive text. (Not really a good idea with VMNEWS or YELLOW PAGES because
   the anchors will be next to other numbers and may look confusing). If
   numbers are going to be left justified and the anchor text is in a heading,
   maybe rewrite the HTML as follows to indicate the change in the position of
   the anchor numbers. Where we use now
   
          <H2><A HREF=.....>......</A></H2>

   we could use
   
          <H2 HREF=.......>.....</H2>.

   In YELLOW PAGES, when looking to find out more details of a number of a
   person by selecting the anchor, the number does not go through with it.

                                                Line Mode Browser bugs (65/130)
   Maybe invent a new tag which tells the parser to take the sensitive text
   through with it to the top of the next document or maybe Bernd should change
   the files.
   
   Be careful of keyword searches inside FIND as they can be confusing as to
   whether the search is the whole of FIND or just a sub-section of it.
                                        Features added to www line-mode browser
                                FEATURES ADDED
                                       
   Improvements made to the line-mode browser are listed in reverse
   chronological order. (See also the bug list ).
   
   Note: Many changes to this product stem directly from changes tothe common
   code, and are documented in the common code change list.
   
2.10

      Millions of things which seem to have slipped past this list in versions
      2.x to s.09, inclduing the rule file, firing off X applications for
      graphics files, etc etc. See the library change list.
      
1.4a

      REFRESH command refreshes current document
      
11 Dec 92: 1.4

      -version command line option included .
      
      Compiled for many machines with library version 1.1 .
      
Dec 92 1.3c

      Makefile for rs6000 fixed. (rs6000 cc does not have good -o flag). Binary
      available for rs6000 again.
      
      -version option on command line for quick version check
      
16 Oct  92: Version 1.3a

      SOURCE command prefix allows printing, pipiping etc postscript source
      without formatting. SOURCE PRINT prints a postscript file. SOURCE >
      allows the original source to be saved.
      
      -listrefs option allow noninteractive output to be followed by lists of
      addresses of documents referred to.
      
      MANUAL command takes a hypertext jump straight to the latest version of
      the online manual. (HELP is still local slightly context-sensitive help).
      
      
Oct 92 version 1.2l

      Bug in Gopher access removed.
      
      Now uses common code library
      
version 1.2k

      Default port number changed to 80 ****.
      
18 May 92 version 1.2h

      PS command added to print document on local printer attached to a
      terminal. Special compilation flag SLAVE_PRINTER.
      
      BUG FIX:   Crashes on some machines only fixed (malloc length error on
      HTTP.c.)
      
version 1.2f


                                Features added to www line-mode browser (65/66)
      Bug fix: telnet under unix: -l option was put AFTER the host name. Fixed
      27-Mar-92.
      
Version 1.2e

      New command: 'Verbose' toggles verbose mode on/off as per '-v' command
      switch.
      
      New command: for Unix, 'cd' or 'lcd' changes the local working directory
      (as in FTP clients).
      
      Command input handled more efficiently. Should use readline() in the
      future, with completion on anchor names..
      
      Some minor bug fixes.
      
Version 1.2d

      COMMENT tag introduced for future use only.
      
      Speed improvement: Use of a hash table for document names improves load
      time especially of documents with many links.
      
Version 1.2c

      Bug fix: unknown tags without attributes caused text to be skipped until
      the end of the next tag.  This lead to missing information (like phone
      numbers! ) in CERN yellow pages listing and a strange format for the
      xfind server.
      
Version 1.2b

   Release includes a few strict C bug fixes for the Mac, and adds makefile for
   pc-nfs.
   
Version 1.2a

      Feature: the -source option makes www load the unparsed source from HTML
      servers.  See details ...
      
      Tags MENU and DIR introduced for future use.
      
      Bug fix: The style was not set until a style change occured: therefore,
      formatting of any text before a heading etc was wrong (no paragraph
      spacing, indents, etc).
      
      Bug fix: Newlines in HTML source are not taken as blanks if they follow
      other white space. This caused initial blanks on some paragraphs when a
      newline followed a tag.
      
Feb 12 1992: Version 1.2

      Binaries generated for unix and vms hosts, for general announcement. Code
      fixes for compilation on the various platforms.
      
Version 1.1c

      www can be used as a filter: The - option (a dash by itself) makes it
      take HTML data from stdin.  See details
      
      FTP directories contain pointers back to their parent directory.
      
      Bug fix: News access didn't work on little-endian machines (VAX etc).
      

                               Features added to www line-mode browser (65/130)
      Bug fix: VMS descrip.mms file was not complete.
      
Version 1.1b

      Bug fix: when using the ">" and "|" commands in www on a document whose
      name contained shell metacharacters, it failed.
      
      Bug fix: HTBrowse.h missing from source release.
      
Version 1.1a

      Bug fix: news server address always taken as "cernvax" : see
      documentation
      
January 1992 Version 1.1

      "Gopher" protocol added to allow access to those campus-wide systems
      using that protocol.
      
      "Telnet:" access added for information system which don't have a server
      at all;
      
      Allows gateways to be defined for arbitrary new (or old) naming schemes,
      eg setenv WWW_wais_GATEWAY //node:port/
      
      Bug fixes: the -n option didn't work properly in v1.0
      
Version 1.0 (released as alpha test only)

      New archiecture, more modularity.
      
      "News" access added: picks up news using NNTP as the NeXT W3 browser
      does.
      
      Forward and reverse scrolling.
      
      "Next" and "Previous" commands added to allow to move to next article in
      a list.
      
      Bug fix: Searches are now only allowed on indexes.
      
Version 14a

      Logfile option -l, and -h allows remote usage to be logged. (Existed in
      version 14, but bug in that log file was all one line!)
      
      If telnet used, default logfile /usr/adm/www-log- is used even though no
      -l logfileroot is specified.
      
November 1991 version 0.14

      The `Recall' command now displays references as `R 1', `R 2', etc.
      instead of just `1', `2', etc. so the user is reminded to type `R
      <number>'.
      
      An out-of-range reference number will launch a keyword search if
      applicable. For instance, in the phone book, you can now type directly
      `3755' instead of `K 3755'.
      
      New command : `(G)OTO <address>' jumps to the document specified by its
      hypertext address. The address may be absolute or relative to the current
      node.
      
      Clear screen after user input for NEWLIB and VM. NEWLIB-special source

                               Features added to www line-mode browser (65/194)
      put in. VM version defaults to home page on //info.cern.ch.
      
      Entity handling ., . and . put in for text and TITLE fields.
      
      Bug fix: CR now ignored in remote FTP files which used to be displayed
      double-spaced.
      
      Bug fix: tabs in plain text were displayed as newlines! Now to next
      multiple of 8 columns.
      
version 0.12

      -a  xxx option now allows the anchor format to be specified. The old -a
      option for anchor supression is renamed -na.
      
      Bug fix: occasional crash when going "back".
      
      Bug fix with the -n command line option. In non interactive mode the
      prompt was still produced.
      
      Now treats '\r' characters as '\n' characters.
      
      Reproduces last line of page at the top of the next page if a paragraph
      is  split between them.
      
      Bug fix in FTP handling as for NeXTStep editor . (Could not access some
      sites).
      
      HTTP host addresses may now contain a port number after a colon to
      override the default.
      
15 August 1991 version 0.11

      You can read the address of the current document in the HELP information.
      
      MVS and VM only: Line width reduced to 78 characters.
      
July 91 version 0.10

      Bug fix for TOP commmand.  Now functions correctly, and data is only
      buffered and formatted when the user requires more text,  hence saving
      time.
      
      Can pick up on the users home environment, to display a certain intial
      page. Set variable (on VMS, logical name) WWW_HOME to the full hypertext
      of the file or index you want to start with.
      
      Keyword search accepts longer strings.
      
      On VMS, VMS files may be accessed. The WWW address is still unix-like,
      with slashes, and is converted into VMS syntax by the browser.  VMS users
      can now write their own hypertext and keep it on VMS, though it will only
      be readable (at the moment) from VMS machines.
      
June 91 version 0.9

      Bug fix in anonymous FTP. The first version with a-ftp access.
      
24 May 91 version 0.8

      Page size selection now works with -p (bug in version 0.7)
      
      Styles have been made more compact, plain text uses all 80 columns.
      

                               Features added to www line-mode browser (65/258)
      Bug fix: Missing loop end condidtion caused crash when listing some
      documents
      
      Files with suffixes other than .HTML are treated as plain text.
      
21 May 91 version 0.7

      Parameters avaliable on the command line :-
      
  -v                      Shows trace comments, including the pathways taken to
                         locate a file.
                         
  -n                      Makes the program non interactive with the user. No
                         prompts are shown, and after the node is displayed it
                         exits the program
                         
  -p                      Turns off the paging. The page size can be selected
                         by adding the value immediately after the 'p'.
                         
  -a                      Stops positions of anchors being shown in the text.
                         
      These options are particulary useful when redirecting the input into
      either a file or to the printer. They can also be used in any order on
      the command line, as long as 'WWW' is the first arguement.
      
      When the recall command is used to view what files have been visited, the
      titles of the files are used, rather than the file name. If there is no
      title then the file name is used.
      
14 May 91

      The function HTOpen() called from HTAccess has been changed so that it
      takes two parameters instead of one. This extra one being a pointer to an
      address where the format style is stored as an integer. The translations
      of the integers to the formats can be seen in WWW.h. At the momment this
      extra parameter is not used but will be in the near future so that more
      files can be accessed.
      
10 May 91

      WWW now reads the formatted text into a double linked buffer one screen
      full at a time and then produces it on the screen. This enables checking
      of documents so that splitting of small paragraphs or titles does not
      occur at the bottom of the screen.
      
      An option is offered to return to the top of the present document being
      viewed.
      
      Tim added the necessary code so that WWW can now access remote files
      using anonymous FTP.
      
17 April 91

      Modified WWW so that it is also executable on the SUN machines., i.e.
      using ordinary C.
      
      First version realeased on PRIAM, for testing by a few users, to gain
      feedback.
      
      Accepts keywords with the execute command.
      
8 April 91

      Keywords can be entered on the command line.

                               Features added to www line-mode browser (66/323)
      The input file is copied into a buffer as soon as it is opened, so that
      the input channel is closed as soon as possible and the server freed. The
      first 23 lines of the document are read into the buffer and produced onto
      the screen. As soon as this is done, the remaining file is read into the
      buffer so the input channel is closed.
      
7 March 91

      Created an array called 'string_space' which is filled with blank spaces
      to be used for printing out margins etc. This method of printing a string
      was found to be faster than individually printing spaces.
      
      A history mechanism has been included so that a list of all the documents
      viewed are stored so that the user can refer  back to them using the
      BACK, HOME and RECALL commands.
      
      Changed code so that the browser can handle text which contains long
      words which exceed the allowed line length on their own. This is just
      done by continuing the word on the following line.
      
      Read titles and headings into a buffer before outputting so that in cases
      where the title has a word longer than the allowed line length can be
      dealt with (for example above).This could also be useful in helping to
      solve the above problem. Maybe extend the length of headings.
      
5 March 91

      Handles a  "LISTING" tag by treating it in the same way as an "XMP" tag.
      This is because, in the case of the line mode browser, the screen is
      limited to 80 columns and so the browser is unable to work with the 132
      columns which the "LISTING" tag normally expects.
      
      Handles an "ADDRESS" tag, which left justifies the text.
      
27 Feb 91

      Lists and the help menu are not so spread out, as before.
      
      The browser works with file numbers rather than the file pointers.
      
      Tidied up paging, with the last line of a page repeated at top of next.
      
      Deals with tags within anchors.
      
11 Feb 91

      HTTP access to cernvm server, including FIND and NEWS tested.
      
      Browser can be executed by 'WWW' , 'YP' (yellow pages), 'XNEWS', or
      'FIND'.
      
      "PLAINTEXT" tag added. Prints out the node exactly as it finds it in the
      file.
      
      Prompt only contains appropriate options, as does the help message.
      
      Keyword search option added.
      
Before Feb 91

      Text formatting and line wrapping completed to a reasonable standard.
      
      Removed section of program where 'r' has to be entered in order to select
      a reference.

                               Features added to www line-mode browser (67/388)
      When no hypertext references have been found, the browser informs the
      user, and doesn't offer the list option in the help menu.
      
      Produces an error message if the user tries to select a reference or
      menu, when no references have been found.
      
      Records whether an anchor is a NAME or an HREF.
      
      Stop **** END **** (now [End]) appearing in the wrong places. This
      problem appears due to the lines in the html file being too long, so this
      causes an error in the 'C' run time.
      
      Handles a glossary.
      
      __________________________________________________________
      
                                                        Nicola P , Tim BL , JFG
                                                                               
   
