   This file documents the Emacs-w3 World Wide Web browser.

   Copyright (C) 1993, 1994, 1995 William M. Perry

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Data Structures
===============

   Form objects are used to store information about a FORM data entry
area.
  1. `'w3form'

  2. A cons pair of (METHOD . URL), where METHOD specifies what method
     to use to retrieve the form when it is submitted (e.g., `GET') and
     URL is a fully specified URL pointing at where to submit the FORM
     data to.

  3. The type of input area this is.  (e.g., `CHECKBOX' or `RADIO')

  4. The name of the input tag.  This is used when sending the form to
     the server, so that the server can tell what data is what.

  5. The default value of the input area.  Gotten from the INPUT tag at
     creation time.

  6. The current value of the input area.

  7. Whether the item is checked or not.  Only used for RADIO or
     CHECKBOX items.

  8. The size (in characters) of the input area.  Not used for CHECKBOX,
     RADIO, or TEXTAREA input areas.

  9. The maximum length of the input.  Only used for TEXT or PASSWORD
     input areas.

 10. The form that this input area belongs to.  Each form in the same
     buffer has a unique identifier assigned when the document is
     parsed.  It is used when the form is submitted to get only the
     data for the correct form.

 11. A list of strings that represent the choices for this input area.
     Only used for SELECT tags.

 12. A string or `nil', specifying the ID attribute on this input tag.

   A new development in the World Wide Web is the concept of collapsible
areas of text.  If a zone controls one of these regions, it is marked
with the w3expandlist property.  The format of this structure is:

  1. `'w3expandlist'

  2. A marker representing the start of the hidden text as a buffer
     position.

  3. A marker representing the end of the hidden text as a buffer
     position.

   A zone with the w3graphic property is a link to an inlined image's
source file.
  1. `'w3graphic'

  2. The full URL of the inlined image.  This is only ever returned if
     the inlined image is the only extent under point, or
     `w3-follow-inlined-image' is invoked.

   A zone with the w3 property is a full-fledged hypertext link to
another document.
  1. `'w3'

  2. The ID attribute of this link.  Used for resolving references to
     specific points within a document (e.g., `file.html#sectionA'.

  3. The HREF attribute of this link.  This is a fully specified URL
     pointing at a network resource.  All relative directory references
     should have been removed before being stored in this structure.

  4. The text between the <A> and </A> tags.  This is used to build
     menus or to get the text of a link without doing a
     buffer-substring.

  5. The URN attribute of this link.  Currently not used for anything,
     waiting for the URN specification to be hammered out.

  6. The REL attribute of this link.  Specifies the links relevance to
     the current document.

  7. The REV attribute of this link.  Specifies the current documents
     relevance to the link.

  8. The METHODS attribute, which tells what methods can be used on this
     link.  (e.g., `GET, HEAD, PUT'.

Miscellaneous Functions
=======================

   I have done quite a bit of work trying to make a clean interface to
the internals of Emacs-w3.  Here is a list of functions that you can
use to take advantage of the World Wide Web.

`url-clear-tmp-buffer'
     Sets the current buffer to be `url-working-buffer', creating it if
     necessary, and erase it.  This should usually be called before
     retrieving URLs.

`w3-convert-html-to-latex'
     Takes a buffer of HTML markup (which should be in
     `w3-working-buffer'), and convert it into LaTeX.  This is an
     adaptation of the simple sed scripts from Cern.  Does as good a
     job as the html2latex program, and I usually prefer its formatting
     over html2latex's.

`w3-fetch'
     This function takes a URL as its only argument. It then attempts to
     retrieve the URL.  For example: `(w3-fetch
     "http://cs.indiana.edu/")' would retrieve the Indiana University
     CS home page and parse it as HTML.

`w3-fix-entities-in-string'
     This function takes a string, and removes all HTML[+] entity
     references from it, replacing them with the correct character(s).
     It consults the variable `w3-html-entities' for the entity names
     and translations.  For example, `(w3-fix-entities-in-string
     "&gt;testing&lt;&amp;")' would return `">testing<&"'.

`url-generate-new-buffer-name'
     This function takes a string, and returns the first unique buffer
     name using that string as a base.  For example
     `(url-generate-new-buffer-name "new-buff")' would return
     `"new-buff<1>"' if buffer `new-buff' already existed.

`url-generate-unique-filename'
     This functions returns a string that represents a unique filename
     in the /tmp directory.  For example,
     `(url-generate-unique-filename)' would return
     `"/tmp/url-tmp129440"'.  The filename is arrived at by using a
     unique prefix (url-tmp), the uid of the current user (12944 in my
     case), and a number that is incremented if a file already exists.

`url-buffer-visiting (url)'
     Return the name of a buffer (if any) that is visiting URL.

`url-create-mime-request (fname ref-url)'
     Create a MIME request for the file fname.  The Referer: field of
     the HTTP/1.0 request is set to the value of ref-url if necessary.
     Returns a string that can be sent to an HTTP server.  The request
     uses several variables that control how the request looks.

     If the value of `url-request-extra-headers' is non-`nil', then it
     is used as extra MIME headers when an HTTP/1.0 request is created.

`url-get-url-at-point'
     This function returns the url at a point specified by an optional
     argument.  If no argument is given to the function (point) is used.
     Tries to find the url closest to that point, but does not change
     the users position in the buffer.  Has a preference for looking
     backward when not directly on a URL.

`url-hexify-string'
     This function takes a string and replaces any characters that are
     not acceptable in a URL with the "escaped" encoding that is
     standard for URLs (replaces the character with a % followed by the
     hexadecimal representation of the ASCII value of the character).
     For example, `(url-hexify-string "this is a test")' would return
     `"this%20is%20a%20test"'.

`url-open-stream'
     This function takes the same parameters as `open-network-stream',
     and functions similarly.  It takes a process name, a buffer name,
     a host name, and a port number or server name.  It attempts to
     open a network connection to the remote host on the specified
     port/service name, with output going to the buffer.  It returns
     the process object that is the network connection.

`url-retrieve'
     This function takes 3 arguments, a URL, a method type, and a data
     block.  It then attempts to retrieve the URL using the specified
     method, using data (if any) as the body of the MIME request.  For
     example: `(url-retrieve "http://cs.indiana.edu/")' would retrieve
     the Computer Science home page from Indiana University.  This
     function does no parsing of the retrieved page, and leaves you in
     the buffer containing the document you requested.  Any HTTP/1.0
     redirection/authorization is done before this function exits.

`url-unhex-string'
     This is the opposite of `w3-hexify-string'.  It removes any %XXX
     encoded characters in a string.  For example `(url-unhex-string
     "this%20is%20a%20test")' would return `"this is a test"'.

`w3-view-this-url'
     This function returns the URL of the zone under point (if no zone
     is under point, then it returns `nil').  If the optional argument
     is `nil', then the URL is also displayed in the minibuffer.

`url-view-url'
     This function returns the URL of current document.  If the optional
     argument is `nil', then the URL is also displayed in the
     minibuffer.

MIME Functions
==============

`mm-compose-type(TYPE)'
     Compose a body section of MIME-type TYPE.  This uses the compose
     field of a mailcap entry to generate the data, and returns a
     string that contains the data, with a correct content-type header.

`mm-extension-to-mime(EXTN)'
     Return the MIME content-type of the file extension EXTN

`mm-mime-info(ST ND REQUEST)'
     Get the mime viewer command for a specific MIME type.  If ST is a
     number, then the MIME type is the `buffer-substring' between ST
     and ND, otherwise ST should be a string specifying the MIME type
     and associated data.  Returns `nil' if the specified type is not
     found.

     Expects a complete content-type header line as its argument.  This
     can be simple like text/html, or complex like text/plain;
     charset=blah; foo=bar

     Third argument REQUEST specifies what information to return.  If
     it is `nil' or the empty string, the viewer (second field of the
     mailcap entry) is returned.  If it is a string, then the mailcap
     field corresponding to that string is returned (print,
     description, whatever).  If a number, then all the information for
     this specific viewer is returned.

`mm-parse-mailcap(FILE)'
     Parse the mailcap file specified by FILE.

`mm-parse-mailcaps(PATH)'
     Parse the default mailcap files.  Optional argument PATH specifies
     a UNIX-style path of where to find the mailcap files.  This
     function must be run before the rest of the mm-* functions.

`mm-parse-mimetype-file(FILE)'
     Parse out a mime-types file specified by FILE.

`mm-parse-mimetypes(PATH)'
     Parse the default mimetypes files.  Optional argument PATH
     specifies a UNIX-style path of where to find the mimetypes files.