htnews 0.6.9 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 an 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!
	  (look at the FAQ to learn how to use htnews without
	   root permissions!)
	o and, of course, a running webserver. This is
	  not recommended - you can distribute the
	  created files yourself to any website!
	o it would be a good idea to know something about
	  html code and about email issues.

	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.
		  It is possible to run htnews without a sendmail
		  server (i.e. you could use qmail or exim), but
		  it needs sendmail for sending response messages!
		  It is _not_ possible to replace it with mail or 
		  the like, because of the different syntax.
	
	If configure was successfull, type
	"make"
	This will compile the source of htnews.
	If you encounter problems with make, try gmake.
	
	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. 

		Note: the pre-installed htnews.conf will be an
			  old config format file. If you want to try 
			  the new format, use the supplied file
			  "new_format.conf" with the parameter -C or -A.
			  Take a look to the manpage for details.

	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!

	If this comes true, you can try to use the provided script
	"sanity_check", which can check a htnews config for errors
	and permission problems. Please refer to the file
	README.sanity_check for more informations.




UPDATE FROM htnews 0.6.x => 0.6.9
---------------------------------

	htnews 0.6.9 comes with a new configuration file format. If you
	are updating your existing htnews installation, you have to
	be aware about these things:

		o there are a few new (optional) parameters:
			old					new

			Archiv_Months		List_Archiv_Months
			UseLastMonth		Bool_Use_Last_Month
			ArchivURL			Html_Archiv_URL
			Archiv_LinkType		Value_Archiv_Link_Type
			Archiv_LinkHead		Html_Archiv_Link_Left
			Archiv_LinkFoot		Html_Archiv_Link_Right

		o every new configuration option is available both within 
		  the new and the old format (but with different names...)

		o you can still use your existing configuration with 0.6.9.
		  If you want to do that, you have to call htnews with -C 
		  (or -A in cron-mode). You can add the new options to the
		  file (refer to htnews.conf.oldstyle file).

		o even if it is possible to use an old style configuration,
		  I recommend you to migrate to the new style as soon as
		  possible because version 0.7 will _not_ support the old
		  style configuration format!

		o htnews error messages will only point to new style options!
		  Please refer to the file style.changes if you want to know
		  which new option represents which old one.

		o the script sanity_check does _not_ support the old style
		  configuration format!




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 available.

	Another source for further informations is the website
	of htnews: htnews.org.



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.
	If you have turned on the option "UseLastMonth", then htnews will
	use the name of the last month instead of the current one.
	Therefore, if you run it as stated above, it will run on
	every 1st day of every month at 00:05 and archive the contents
	of the archive storage under the name of the current month.




FILES
-----

	AUTHORS...............who are the authors
	BUGS..................Known bugs (which are features as you all know...)
	COPYING...............GPL License
	Changelog.............What have been changed since the last version
	INSTALL...............Generic installation instructions
	Makefile.am...........used by configure
	Makefile.in...........needed by configure
	README................this file
	README.sanity_check...README for the script sanity_check
	TODO..................to do list for future version
	VERSION...............Version number
	aclocal.m4............needed by configure
	configure.............creates the Makefile from Makefile.in
	configure.in..........needed by configure
	doc/htnews.html.......man page in html-format
	doc/htnews-faq.html...F.A.Q.
	doc/rfc*..............various RFC's, if you are interested :-)
	fake.mail.............A complete mail (header and body)
	htnews.1..............man page
	htnews.access.........sample access list
	htnews.cc.............htnews source
	htnews.conf...........sample config-file
	htnews.conf.oldstyle..sample config-file (old format)
	htnews.h..............htnews source (header)
	install-sh............used by configure
	missing...............used by configure
	mkinstalldirs.........used by configure
	sample/...............sample configuration
	style.changes.........new/old style configuration options
	util.cc...............htnews source




SAMPLE
------

	If you want to see, how it works, there is a test 
	installation available:
	http://htnews.org




HELP
----

	There are two ways to get help:
	
		1. subscribe to the mailinglist, visit the 
		   htnews website (htnews.org) for more details.
		   you can post to the list if you are not a 
		   subscriber, but you will not get any answer,
		   instead you can use the mailinglist archiv
		   to look for your answer. It is beeing generated
		   every day.
		2. Send me an email: tom@daemon.de. It could take
		   some days until you receive an answer, because
		   I work on htnews in my spare time.




LICENSE
-------

	All scripts are distributed under the terms of the 
	GNU General Public License (GPL). Feel free to modify 
	or to redistribute the package or parts of it.
	
	It would be nice, if you inform me about any changes
	you made, because it could be of public interest.
	In that case it will be included in the main distribution.

	Look at the file COPYING for more details about the GPL.





MAINTAINER
----------

	Currently htnews is maintained by Thomas Linden.
	Visit my website to get the newest version of
	htnews:
		http://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 22.11. 1999
