WWW LINE MODE BROWSER USER GUIDE This document is a short user's guide to the WWW Line Mode Browser. It has been generated automatically from the online hypertext documentation, so the considerations "Paper from Hypertext" below apply. The Line Mode Browser, called "www", is a program whoch allows you to access a wealth of information on the global internet. This document contains details of How to use www if you have it How to customize www for your site How to install www if you don't have it Technical details of how www works, including protocols and data formats, are not covered here but in the online documentation and other printed manuals. About documents generated from hypertext Paper manuals generated from hypertext are made for convenience, for example for reading when one has no computer to turn to. We have tried to make the hypertext into fairly conventional paper documents, but they may seem a little strange in some ways. All the links have been removed. Therefore, it is worth looking at the table of contents to see what there is in the manual. Something which is not explained in place may be explained in detail elsewhere. We have tried to keep related matter together, but sometimes necessarily you might have to check the table of contents to find it. Please remember that these are for the most part "living documents". That is, they are constantly changing to reflect current knowledge. If you see a statement such as "Product xxx does not support this feature", remember that it was the case when the document was generated, and may not be the same now. So if in doubt, check the online version. Of course, the living document may be out of date too, in which case it is helpful to mail its author. Tim BL 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 T. Berners-Lee 1 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 Line Mode Browser Status This program gives WWW readership to anyone with a dumb terminal. Although it cannot be as flashy as a windows implementation, it covers a wide class of users who do still not have window facilities. Authors NP , TBL Status: Undergoing steady feature addition, but basically stable. Try it by telnet info.cern.ch (no user or password) Platforms Almost anything. All unix systems, VMS with any flavour of TCP/IP, VM/CMS, PC (any reasonable socket library), MVS, (even the Mac). Next target: See features list for ongoing history. More information: User Documentation , Prioritzed list of things to be done , Internals . 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:- T. Berners-Lee 2 -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: T. Berners-Lee 3 www -a \<%d\> www -a " (Type %d)" -version Prints out the version number of the software, and 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 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. Just hitting Return displays the next page of the current document. Typing a number by itself follows the corresponding reference from the currently displayed document. Find 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. T. Berners-Lee 4 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
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 . 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 T. Berners-Lee 5 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 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. T. Berners-Lee 6 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. 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. VMS SHORTCUT COMMAND On VMS, to make a shortcut command , use a symbol: T. Berners-Lee 7 $ 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 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/defaul t.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 T. Berners-Lee 8 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. setenv WWW_PRINT_COMMAND "www -n -na -p66 '%s' | lpr" Tim BL 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 T. Berners-Lee 9 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). 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. 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 T. Berners-Lee 10 GLOBALV SELECT CENV SET WWW_HOME http://info.cern.ch/j unk.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 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 T. Berners-Lee 11 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 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 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. T. Berners-Lee 12 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 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 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. T. Berners-Lee 13 [Remember that ls -a displays also filenames which start with a dot, whereas ls normally hides them...] 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.htm l" 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 T. Berners-Lee 14 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 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 T. Berners-Lee 15 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). T. Berners-Lee 16 Tim BL Getting the WWW files Read this if you have not yet got the WWW files you need, and you cann ot NFS mount a directory on which they reside. The source and binary of CERN WWW project files are currently availab le (see copyright ) by anonymous FTP from node info.cern.ch. This nod e is currently 128.141.201.74 but THIS MAY CHANGE. The files are compr essed 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 ve rsion number of the software. Once you have the compressed tar file, you must uncompress it and unwr ap 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 , in stall Viola , etc. Tim BL Porting to a new machine Read this secion if the browser has not already been ported to a binar y-compatible machine.We assume you have a unix-like environment, inclu ding some sort of C (either Kernigan and Ritchie or ANSI) compiler, an d a socket library supporting TCP/IP communications. The browser has been ported to many systems, and so you should not have much trouble w ith 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 T. Berners-Lee 17 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 MACHINE TYPES The W3 code is distributed with machine-specific files for certain pla tforms. 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 T. Berners-Lee 18 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 T. Berners-Lee 19