.\"
.\"	World Wide Web Package
.\"	WWW.3
.\"
.\"	Copyright (C) 1998  Paul J. Lucas
.\"
.\"	This program is free software; you can redistribute it and/or modify
.\"	it under the terms of the GNU General Public License as published by
.\"	the Free Software Foundation; either version 2 of the License, or
.\"	(at your option) any later version.
.\"
.\"	This program is distributed in the hope that it will be useful,
.\"	but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"	GNU General Public License for more details.
.\"
.\"	You should have received a copy of the GNU General Public License
.\"	along with this program; if not, write to the Free Software
.\"	Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
.\"
.\" ---------------------------------------------------------------------------
.\" define code-start macro
.de cS
.sp
.nf
.RS 5
.ft CW
.ta .5i 1i 1.5i 2i 2.5i 3i 3.5i 4i 4.5i 5i 5.5i
..
.\" define code-end macro
.de cE
.ft 1
.RE
.fi
.if !'\\$1'0' .sp
..
.\" ---------------------------------------------------------------------------
.tr ~
.TH \f3WWW\f1 3 "February 12, 2000" "WWW"
.SH NAME
WWW \- World Wide Web Package
.SH SYNOPSIS
.ft CW
.nf
extract_description( \f2FILE\fP )
extract_meta( \f2FILE\fP, \f2NAME\fP )
hyperlink( \f2LIST\fP )
.fi
.ft 1
.SH DESCRIPTION
This package provides a utility functions for the World Wide Web
to extract descriptions of or meta information from files,
and hyperlink text.
.SH SUBROUTINES
The following Perl subroutines are defined and available:
.IP "\f(CWextract_description( \f2FILE\fP )\f1"
Extracts a description from an HTML or plain text file given by the
.I FILE
name;
.I FILE
should be an absolute path.
The first \f(CW$description::chars\f1 (default: 2048) characters are read.
If the file ends in one of the extensions
\f(CWhtm\f1, \f(CWhtml\f1, or \f(CWshtml\f1,
it is presumed to be an HTML file;
if the file ends in \f(CWtxt\f1, it is presumed to be a plain text file.
Other extensions are not recognized and no description is returned for them.
.IP ""
For HTML files, first,
if a \f(CW<META NAME="description" CONTENT="\f1...\f(CW">\f1
or a \f(CW<META NAME="DC.description" CONTENT="\f1...\f(CW">\f1
(Dublin Core) element is found,
then the words specified as the value of the \f(CWCONTENT\f1 attribute
is returned as the description.
.IP ""
Otherwise, all HTML comments, text between
\f(CW<SCRIPT>\f1, \f(CW<STYLE>\f1, and \f(CW<TITLE>\f1 tags,
and all other HTML tags are stripped.
If \f(CW<AREA\f1 ... \f(CWALT="\f1...\f(CW">\f1
or \f(CW<IMG\f1 ... \f(CWALT="...">\f1 elements are found,
then the words specified as the value of the \f(CWALT\f1 attributes
are extracted.
.IP  ""
Finally, for either HTML or plain text files,
at most \f(CW$description::words\fP (default: 50) are returned.
.IP "\f(CWextract_meta( \f2FILE\fP, \f2NAME\fP )\f1"
Extracts the value of the \f(CWCONTENT\f1 attribute from a \f(CWMETA\f1 element
having the given \f(CWNAME\f1 attribute
from an HTML file given by the
.I FILE
name;
.I FILE
should be an absolute path.
The file must end in one of the extensions
\f(CWhtm\f1, \f(CWhtml\f1, or \f(CWshtml\f1
to be considered an HTML file.
The first \f(CW$description::chars\f1 (default: 2048) characters are read.
The characters are cached between consecutive calls using the same filename.
.IP "\f(CWhyperlink( \f2LIST\fP )\f1"
Adds hyperlinks to strings:
that is strings that contain substrings that are valid URLs
(according to RFC 1630)
have the appropriate HTML tags ``wrapped'' around them so that they will be
selectable when displayed in a browser.
The \f(CWftp\f1, \f(CWgopher\f1, \f(CWhttp\f1, \f(CWhttps\f1, \f(CWmailto\f1,
\f(CWnews\f1, \f(CWtelnet\f1, and \f(CWwais\f1 URLs are recognized.
Example:
.cS
	Read all about it at
	http://www.usatoday.com/

\f1becomes:\fP

	Read all about it at
	<A HREF="http://www.usatoday.com/">http://www.usatoday.com/</A>
.cE
.SH SEE ALSO
.BR perl (1)
.PP
Tim Berners-Lee.
``Universal Resource Identifiers in WWW,''
.IR "Request for Comments 1630" ,
Network Working Group of the Internet Engineering Task Force,
June 1994.
.PP
Tim Berners-Lee, Larry Masinter, and Mark McCahill.
``Uniform Resource Locators (URL),''
.IR "Request for Comments 1738" ,
Network Working Group,
1994.
.PP
Dave Raggett, Arnaud Le Hors, and Ian Jacobs.
``Notes on helping search engines index your Web site,''
.IR "HTML 4.0 Specification, Appendix B: Performance, Implementation, and Design Notes" ,
World Wide Web Consortium,
April 1998.
.PP
\-\-.
``Objects, Images, and Applets: How to specify alternate text,''
.IR "HTML 4.0 Specification, \(sc13.8" ,
World Wide Web Consortium,
April 1998.
.PP
Dublin Core Directorate.
``The Dublin Core: A Simple Content Description Model for Electronic Resources.''
.PP
Larry Wall, et al.
.IR "Programming Perl, 3rd ed." ,
O'Reilly & Associates, Inc.,
Sebastopol, CA,
2000.
.SH AUTHOR
Paul J. Lucas
.RI < pauljlucas@mac.com >