    README for dwww version 1.0-1
                             ``To baldly go where no doc has before''
---------------------------------------------------------------------------

dwww is a web interface to all on-line documentation on a Debian
system.  It builds some web pages that list all installed documents,
and converts all documents to HTML.  A future version will support several
ways of searching for documents.

dwww requires a web server (httpd; Debian has packaged versions of
cern-httpd and Apache, both of which work fine with dwww).

For more information, read the manual page dwww(8), and the other
manual pages it refers to.

	 _					 _
	| 					  |
	    dwww is still under development!
	|_   					 _|


Only manual pages and plain text are converted, and there's some quirks
with the manual pages, which makes them sometimes work not so well.  
Conversions of Info files are badly needed.  I have been directed to
a info2www, a Perl script that does the conversions on-line, which is
what is needed, but it needs some hacking.  I don't know Perl, so I need
help.  Specifically, info2www does not support gzipped info files.

dwww is already quite usable, however.  Please use it, and report
bugs via the Debian bug tracking system so that they can be fixed.

Changes from version 0.3-1 to 0.4-1:

	Added an extended description to control file.
	Removed dependency on info.
	dwww-cache checks that the cache'd version is not older than
		the original.
	Added configuration variables for converters (man/info/text/dir
		to HTML).
	Added support for compessed documents in the cache.
	Fixed file type guessing bug (guess_type called with wrong 
		argument).
	Postinst now checks for $DWWW_HTMLDIR/dwww.html, not 
		just the directory, to determine if it needs to turn
		dwww-build.
	Moved /usr/etc/* to /etc/* (stupid installation bug).
	Fixed removal of old files in /var/spool/dwww (security bug).
	Added feature to find docs related to program.

Changes from version 0.1-0 to 0.3-1:

	First public release (i.e., first release uploaded to the usual
		Debian ftp site).
	Added realpath program, which uses realpath(2).  This is faster 
		than the previous shell script kludge.  Might be safer, too.
	Added a first draft version of dwww-cache.  The database
		handling may have to be rewritten (it reads and writes
		the whole database, but the database is pretty small).
		Also, there is no locking yet.
	Changed name of cgi-bin from dwww2HTML.cgi to dwww.
		This makes the URLs a bit shorter.
	Added support for /etc/default/dwww for configuration data.
		All configuration is read from this file, with somewhat
		suitable defaults if it is missing.
	Added support for Apache: postinst now ask for document and 
		cgi-bin directories.  It checks if cern-httpd or Apache is 
		installed, and offers appropriate defaults.  Saves answers
		to /etc/default/dwww.
	Changed dependencies to httpd (provided by both cern-httpd and
		Apache).  Removed dependency on rman.
	Added /usr/local/man to list of default-approved directories.
	Added support for .debian.index.html in a directory.  It doesn't
		work well enough (requires absolute links), but we'll see.
	Added/changed manual pages.  Whee.  dwww, the self documenting,
		converting, caching, splicing, mincing, twisting, tweaking
		monster document viewing system.
	Added /etc/cron.daily/dwww to re-build the web pages and
		clean up the cache from old docs.
	
Changes from version 0.0-0 to 0.1-0:

	Fixed the security bug which allowed access to any file.
	No longer uses rman (since it is in non-free), but uses a simple
		built-in man2html conversion.  Not really smart enough,
		but good enough for a prototype.
	Due to previous, references to manual pages inside manual pages
		work.
	Added a couple of manual pages.

To Do

	info2www needs to support gzipped files; it also needs to be
	packaged for debian (I can do that, if you can hack so that
	it works and will maintain at least the Perl parts).
		got newest version (1.2.2.9) from author; seems to work

	error reporting is abysmal
	
	package existing, not easily convertable documentation as HTML:
		native Debian docs, Howtos, FAQs (not just Linux/Debian),
		LDP books, Python, many other packages, RFCs

	someone should spend a lot of time building the link pages...

	fix line breaks for man page references:
		muble muble mumble mumble mubmle manual-
		page(1) mumble mumble

	.debian.index.html should be able to use relative links:
		<a href="README">README</a>
	now they must be absolute; this is useless
	
	make some document types non-cacheable.  this should be 
	configurable.  currently on html is uncached.

	implement permanent flag (dwww-{convert,cache} option
	--permanent; honoring the permanent flag belongs to the cleanup
	script)

	restrict keyword searches to one program's documentation or other
	useful subclasses, maybe "general keyword" -> "further searches
	of previously returned documents only"

	use "dpkg --search '*'" instead of "find /var/lib/dpgk"

	current method of selecting the package is imperfect, sometimes
	gives completely wrong package (ar -> sharutils); package building
	stage problem, I presume

	remove empty lines at end of manual page
	
	dwww-find should find copyright files as well
	
	create toc for long manpages

	links to faq, howto from frontpage
	
	copyright list not sorted
	
	compressed manual pages show as section gz
	
	man page references that are italic or bold
