htnews 0.6.6 by Thomas Linden
-----------------------------





INTRODUCTION
------------

	This is the README for the program htnews.
	htnews is an email-robot, which one can use to 
	add and to maintain news items on a web-page.
	
	htnews has many features (see FEATURES!) and it
	is easy to use. The first steps could be a little
	complicated, espessially the configuration of the
	HTML-output. But once done - it will be very easy!
	
	htnews is distributed with complete sources for free.
	Read the file COPYING for more informations about the
	GPL.





FEATURES
--------

	o support the use of templates
	o highly customizable via configuration-file
	o supports Multipart-MIME messages (TEXT/HTML)
	o can translate quoted-printable encoded messages
	  to html-encoding
	o archiv functionality
	o also possible to run as cronjob to archive last
	  month's news items
	o can create a separate detail-page for every item
	o basic authentication, with a password in the 
	  subject line (which will be removed before parsing)
	  and with a access-file, that contains email-addresses.

	see the complete list in the man-page.





REQUIREMENTS
------------

	o autoconf and automake
	o modern C++ compiler, egcs recomended
	o glibc (libc.so.6) recommended
	o sendmail installed (8.9.x recommended!)
	o root permissions, you need to configure sendmail!
	o and, of course, a running webserver. This is
	  not recommended - you can distribute the
	  created files yourself to a website!

	It would be a good idea to have some knowledge about
	HTML and about sendmail config.





INSTALLATION
------------

	To compile it, simply type
	"./configure"
	If you like to get some debug output, use the 
	option "--enable-debugging=YES". You can also 
	specify some additional options to configure, refer
	to INSTALL for more informations!

	Note: configure determines the location of sendmail,
	      which you should have installed. You will be 
	      prompted, if it is not the case.
	
	If configure was successfull, type
	"make"
	This will compile the source of htnews.
	
	And if make was successfull too, then type
	"make install"
	This will install the htnews binary to $(PREFIX)/sbin
	and the man-page to $(PREFIX)/man. A default config
	file will be installed to /etc/htnews.conf.
	Please note, that the HTML-documentation will not
	installed in any place!
	
	Now add an email-alias to your system:
	Edit the file /etc/aliases (or /etc/mail/aliases) and
	add the following line depending on, where the binary
	was installed:
	htnews: "|/usr/sbin/htnews -c /where/ever/htnews.conf"
	Then type (as root):
	"newaliases".
	You may want (or must) to add a line to your virtuser-
	table, if the domain of your localhost differs from
	the one, sendmail is responsible for (see /etc/sendmail.cw):
	"htnews@foo.bar		htnews"
	Type:
	"makemap hash virtusertable < virtusertable". 

	The last step: You must create a output directory, if it
	does not exist, create or edit the template-files and you
	must edit the configuration-file. You can use the config
	from my sample page as reference (see SAMPLE).
	The most important step is to define the ADMIN parameter
	in the config, because htnews will send any error messages
	via email to this address. If it is not specified it will use
	root@localhost!




NOTES
-----

	You may (better: will) get problems during the installation
	with permissioins. 
	htnews will run under the UID and GID of your mailserver.
	On most systems it runs as daemon:daemon. 
	But your webserver's UID could be adifferent UID and GID than 
	this one. But the webserver must be able to read the output
	files and sendmail must be able to wrtie them and to create
	new files in that directory!




DOCUMENTATION
-------------

	If you want to read the documentation, type
	"man htnews"

	You can also read the HTML-version of the manpage,
	that came with this package.

	Additionally there is a FAQ with some very usefull
	informations.



USAGE
-----
	
	What to say? Simply send an email to the new email-alias.
	Don't forget to provide a subject and a message text.
	If anything goes wrong you will get an error-message.

	If you have enabled authentication, then you must put the
	password in front of the real subject:
	Subject: "password Some really hot news!"
	Of course it will be removed later.

	You can use a special feature, if you have modified the
	config and if you want to update the HTML-output.
	Send a whole message to your htnews-alias with the following
	subject:
	Subject: "refresh".
	Note, that only the person specified in "ADMIN" is allowed
	to do this!

	If you have archiving enabled and if you want to archive old
	news items every month, you can run htnews from a cronjob.
	Add a line like this one to your crontab file:
	"01 00 1 * * /usr/sbin/htnews -a /where/ever/htnews.conf > /dev/null 2>&1"
	Note the -a instead of the -c! This causes htnews to run in
	a special mode, where it will not try to open a pipe to
	<STDIN>.
	Be carefull with this mode! Espessially look for the UID and GID
	htnews runs as if you install it as cronjob. It would be a 
	good idea to run the cronjob under the same UID as the 
	mailserver.




FILES
-----

	BUGS............Known bugs (which are features as you all know...)
	CHANGES.........What have been changed since the last version
	README..........this file
	VERSION.........Version number
	configure.......creates the Makefile from Makefile.in
	Makefile.in.....needed by configure
	configure.in....needed by configure
	fake.mail.......A complete mail (header and body)
	htnews-faq.html.F.A.Q.
	htnews.1........man page
	htnews.access...sample access list
	htnews.cc.......htnews source
	htnews.conf.....sample config-file
	htnews.h........htnews source (header)
	htnews.html.....man page in html-format
	util.cc.........htnews source




SAMPLE
------

	If you want to see, how it works, there is a test 
	installation available:
	http://mc200.cybernet-ag.net/htnews/




MAINTAINER
----------

	Currently htnews is maintained by Thomas Linden.
	Visit my website to get the newest version of
	htnews:
		http://www.htnews.org
	
	Feel free to tell me, what you think about htnews, 
	or if you have any questions or problems with it:
		tom@daemon.de

















--- have a nice day.


Thomas Linden, munich 02.08. 1999
