htnews  - E-mail robot for adding news items to a webpage.




SYNOPSIS

       htnews [-c | -C | -a | -A configfile]




DESCRIPTION

       With htnews you can very easily add  news  items  to  your
       webpage.  Simply  send an e-mail to it, and htnews will do
       the rest!

       Since it is an e-mail robot, you have to create a  special
       e-mail address and an entry in /etc/aliases. If you do not
       use  sendmail,  refer  to  the   documentation   of   your
       mailserver  about  sending  mail to a program. htnews will
       open a pipe, read the incoming message, and start to  pro-
       cess it.

       For example, if your system uses a virtual user table, add
       a line like this to /etc/virtusertable :
        htnews@foo.bar          robot

       And add a line like this to /etc/aliases (you will have to
       run newaliases afterward) :
        robot:        "|/usr/sbin/htnews"

       Now  you can send an e-mail to htnews@foo.bar, and it will
       be passed through htnews.  The program is  highly  config-
       urable.  See below for a detailed description of available
       configuration flags.







OPTIONS

       -c | -C configfile
              Opens the file configfile, instead of  the  default
              /etc/htnews.conf.   If you are using -c htnews will
              look for old-style configuration parameters. If you
              are using -C, it will use the new style.  Since you
              can have as many e-mail addresses as you want,  you
              can  have  multiple  htnews  robots running on your
              system. This is especially usefull if you are  run-
              ning  several virtual webservers or want to provide
              htnews for your customers as a special service.

       -a | -A configfile
              will use the new style.  Run htnews  in  cron-mode.
              It  will  not  open  a  pipe  for reading an email.
              htnews can be used to archive the news items of the
              last month with this option. Note, that ARCHIV must
              be enabled (ARCHIV YES). You have to run  it  every
              first day of every month:
               05 00 1 * * /usr/bin/htnews -a
               You  have also to enable the option UseLastMonth !
              (see below).

       -h --help
              Print a usage message to standard output then  exit
              successfully.

       -v --version
              Print  version  information to standard output then
              exit successfully.




Configuration

       You can specify some variables  in  the  configfile,
              which  will parsed everytime htnews runs.

              Please be aware of the config format  you  want  to
              use! Currently there are two formats available, the
              new and the old style format. This is  because  the
              format  will  completely change within version 0.7.
              To make  the  migration  process  easier  for  you,
              htnews  0.6.9 supports both formats. In the parame-
              ter description below you will find the new parame-
              ters  first and the second parameters in () are the
              old ones.

       The format of a flag is as follows: PARAMETER <value>.   A
       parameter  and  its  value must be separated with at least
       one blank. The value must be defined without the <  and  >
       characters used here in this man-page! You can use tabs or
       blanks as you choose. If you do not want to use a  parame-
       ter,  simply leave it blank, or you can delete the parame-
       ter itself. This is only possible if the parameter is  not
       required!  If  a  parameter is required, it is marked with
       comment. A line beginning with # is  a  comment.  Comments
       and blank lines will be ignored.
        There are a few different types of parameters. To make it
       easier for you to know, what a certain parameter  expects,
       the  type  is  now  included  in the name of the parameter
       itself. The following types  are  available:  Bool,  File,
       Html, Value, Mail


   Configuration Flags
              Required!   This  is  the  e-mail address of htnews
              itself. If the program has to send an  e-mail  mes-
              sage  (an  error  or a delivery notification), then
              this adress will be used in the From: field of  the
              mail.

       Mail_Admin (ADMIN) <e-mail_address>
              The  server  administrator,  who will get any error
              messages. If not specified, a default value will be
              used.   This  default  is  defined  in  the  source
              htnews.cc.  It is not required but  recommended  to
              have  this  address and one person who really reads
              mail from this box.

       Mail_Rcpt (TOsmtp) <e-mail_address>
              The person who will get delivery notifications.  If
              not specified, the originator will get the message.
              If you set it to /dev/null ,  no  response  message
              will be sent.

       Mail_Cc (CC) <e-mail_address>
              You may send a carbon copy to someone.

       File_Allow_From (Allow_From) <filename>
              You  may  specify  a  filename, where you have some
              e-mail addresses (one per line) of  users  who  are
              allowed  to  use (send mail to) the htnews program.
              If not specified, everybody can use it.

       Value_Auth_Code (Auth_Code) <cipher>
              htnews has a basic authentication  mechanism  built
              in.  If you specify a password here, the user would
              have to add the password to the subject line  of  a
              new   mail.   If,  for  example,  the  password  is
              "hucka13", and the subject you want to use is  "New
              update of program bla bla...", then the line in the
              subject field must be "hucka13 New update  of  pro-
              gram bla bla...".
               Of  course the password will be parsed before html
              generation. It is  important  that  you  leave  one
              space  after  the password. This is required if you
              want to use special characters in the subject (like
              german "Umlauts"). Most e-mail clients format these
              characters, and any blanks will  be  replaced  with
              "_".  Currently,  you cannot use special characters
              in the subject field if  authentication  is  turned
              on. But I am working on this.
               If not specified, authentication is disabled.

       File_Index_Template (TEMPLATE) <filename>
              Required!   You  must  specify  a file that will be
              used as a template  for  generating  the  resulting
              item(s),  you  must  have an html comment like this
              (on one line): <!--htnews--> at this position items
              will  be  inserted.  Note  that  the output will be
              written to a separate file, specified within OUTPUT
              .

       File_Index_Output (OUTPUT) <filename>
              Required!   htnews  will  write  its output to this
              file. Note that it will be overwritten everytime it
              runs,  so  do not edit this file; edit the template
              instead.

       File_Index_Storage (STORE) <filename>
              Required!  htnews will store all old news items  in
              this  file.  A new item will be added to the top of
              the file.  The format of this file is a little spe-
              cific, so take a look to your store file to see how
              it appears. Note that the "%<htnews"  string  is  a
              marker for the end of an item.

       Bool_Use_Html (UseHTML) YES | NO
              It  is  possible  to  send  mime formatted mails to
              htnews, which are  in  the  "multipart-alternative"
              format, that means such a mail contains the message
              in text format and in html format.
               With the parameter UseHTML you can  choose,  which
              of the two parts will be used. If set to "NO" or if
              blank, the text part will be used.

       Bool_Htmlize_Crlf (CRLF) YES|NO
              htnews can, if you want,
               "\n"......"<br>"
               "\t"......8 x "&nbsp;"
               more than one " " with n x "&nbsp;"
               This is useful, if the  postings  should  be  dis-
              played like the autor wrote them.
               Note,  that  it will be turned off, if the message
              is already in HTML-format and UseHTML is turned on!

       Html_Item_Head (ITEM_HEAD) <html-code>
              You  can  specify some html code. htnews has to add
              this before inserting the item into the page  (e.g.
              "<tr><td>").

       Html_Item_Foot (ITEM_FOOT) <html-code>
              You  can  specify some html code. htnews has to add
              this after inserting the item into the  page  (e.g.
              "</td></tr>").

       Value_Field1 ... Value_Field4 (Field1 ... Field4) <field-
              name>
              Required!  You can  specify  the  order  that  some
              example,  if you want to have Date displayed first,
              then From, and then the Text, you could specify:

               Value_Field1 date
               Value_Field2 From
               Value_Field3 Text

               You must specify at least ONE  field,  and  it  is
              required to have the "Text" field.

       Bool_Create_Mailto (Mailto) YES | NO
              You  can,  if  you  have coosen to display the From
              field, specify how it is to be  displayed.  If  you
              set  Mailto  to  "YES",  then  htnews will create a
              "mailto:" link like this:
               "<A HREF="mailto:user@foo.bar">Real Name</A>".
               If there is no real name found in the from line of
              your  e-mail,  then the e-mail address will be used
              instead. If you set this parameter  to  NO  ,  then
              only the name will be displayed.
               Since  spammers  get  e-mail  addresses especially
              from websites (searched by the "mailto:" tag),  you
              may  find  it  better  not  to  display  an  e-mail
              address. Simply edit the  "Field1  ...  Field4"  to
              remove  From.   That's all. See also Bool_Spam_Pro-
              tect(SPAMPROTECT) .

       Html_Date_Head and Html_Date_Foot (Date_HEAD, Date_FOOT)

       Html_Subject_Head  and  Html_Subject_Foot   (Subject_HEAD,
              Sub- ject_FOOT)

       Html_From_Head and Html_From_Foot (From_HEAD, From_FOOT)

       Html_Text_Head and Html_Text_Foot (Text_HEAD, Text_FOOT)
              You may like to specify what kind of html  will  be
              inserted  BEFORE  and  AFTER a specific field.  For
              example, if you want to make  the  Date  bold,  you
              have  to specify "<b>" for Date_HEAD and "</b>" for
              Date_FOOT.

       Bool_Spam_Protect (SPAMPROTECT) YES | NO
              It is possible to protect your page  against  spam-
              mers.  htnews  can insert blanks into the displayed
              address (i.e. "user @ foo.bar").
               A spammer cannot use such an  address.  Note  that
              someone  who  wants to send an e-mail to an address
              prepared this way must edit the address first.


       Bool_Make_Archiv (ARCHIV) YES | NO
              If set to YES  ,  all  the  following  options  are
              recent  messages  on  the  front  page.  The  other
              (older) ones will be displayed on another page.  Of
              course you have to create a link to this page.



       File_Archiv_Output (Archiv_Output) <filename>
              The  html  page  where htnews will put the old news
              items.
               If you want to store older  items  in  a  separate
              file  every  month, you can run htnews from a cron-
              job! If you di this, you must  have  the  following
              HTML-comment in your archiv-template: <!--cron--> .
               htnews will insert at this position several  links
              to the monthly pages.



       File_Archiv_Template (Archiv_Template) <filename>
              The template to use for generating the output file.
               Again, the template must contain a comment,  where
              htnews will insert the news items: <!--archiv-->

              Note:  htnews will use all flags in htnews.conf for
              formatting every item field in  the  archive  page.
              So,  please  take care about which template you use
              and which flags you use.


       File_Archiv_Storage (Archiv_Store) <filename>
              Where old news items are  stored.  This  file  will
              have the same format as your main storage file.


       Value_Archiv_Maxitems (Archiv_MAXITEMS) <number>
              The  max  N  Number of items to be displayed on the
              front page. Only the most recent items will be dis-
              played.  Any  older  ones  will  be  stored  in the
              archive.


       List_Archiv_Months  (Archiv_Months)  <comma-separated
              list   of months>
              The names of months htnews should use for  display-
              ing  at the archiv output. It will assign the names
              to a list starting at 1 and ending at 12. Therefore
              the  first  name  has  to  be the name of the first
              month in a year, in english 'january'.


       Bool_Use_Last_Month (UseLastMonth) YES | NO
              Usefull in for arching from a cronjob. You can  run
               If set to NO or if it is not specified htnews will
              use the name of the current month for  archiv  nam-
              ing.


       Html_Archiv_Title_Head         and
              Html_Archiv_Title_Foot          (Archiv_Title_Head,
              Archiv_Title_Foot) <html-code>
              The monthly generated page can have  a  title  with
              the  name  of  the month and the year. The title of
              the archiv  page  can  be  customized:  <h1>October
              1999</h1>.  The  title  will  be inserted if htnews
              finds   the   following   comment   in   the   file
              File_Cron_Template (Cron_TEMPL): <!--title-->.


       Html_Archiv_URL (ArchivURL) <html-code>
              This  is  usefull, if your archiv-directory differs
              from your main html directory.  You  can  leave  it
              blank  if  the  archives  are in the same directory
              like the main page. This has to be a valid HTTP URL
              (without filename!), i.e.:
               "../news/archived/" The leading / is required!


       Value_Archiv_Link_Type (Archiv_LinkType) <value>
              Controls  how  the  link to a certain archiv should
              looks. Possible values are:
               "TEXT" - creates <a  href="Nov_1999.html">November
              1999</a> using the the name of the month you speci-
              fied in "List_Archiv_Months (Archiv_Months)".
               "DIGIT"           -           creates           <a
              href="Nov_1999.html">11.1999</a>
               "C_TEXT" - (Custom Text), creates the same as TEXT
              using          "Html_Archiv_Link_Left           and
              Html_Archiv_Link_Foot             (Archiv_LinkHead,
              Archiv_LinkFoot)" - see below for details!
               "C_DIGIT" -  the  same  as  C_TEXT  using  11.1999
              instead of "November 1999".
               The Default value is TEXT.


       Html_Archiv_Link_Left and Html_Archiv_Link_Foot
              (Archiv_LinkHead, Archiv_LinkFoot) <html-code>
              You  can  manipulate  the  look  of the link to the
              monthly pages. You need to specify either C_TEXT or
              C_DIGIT  if you want to use it! For example you can
              define a custom font for the link or the like.



       File_Cron_Template (Cron_TEMPL) <filename>
               This   template   can   contain   a   HTML-comment
              <!--title-->.  If this comment exists, htnews  will
              insert at this position the title of this page. The
              title will look like this: "May 1999". You can for-
              mat    this   title   with   the   two   parameters
              Archiv_Title_Head   and   Archiv_Title_Foot    (see
              below).



       File_Cron_Output_Path (Cron_OUTPATH) <path>
              The  complete  unix-PATH  to  the  directory, where
              htnews can store  the  various  monthly  web-pages.
              htnews  must  have write permissions to this direc-
              tory. Note, that the links to these files  will  be
              without any PATH!
               So,  it  would be a very good idea, if this output
              directory is the same as the root directory of  the
              other HTML-pages.



       File_Cron_History (Cron_Hist) <filename>
              Where  should  the  archiv  history be saved to. (a
              list of filenames).



       Html_Archiv_Link_Head   and   Html_Archiv_Link_Foot
              (Cron_HEAD, Cron_FOOT) <html-code>
              htnews will add a link to the archiv  page  to  the
              monthly page. With these parameters you can specify
              some HTML-formatting, if you wish.





       Bool_Look_Detail (LookDetail) YES | NO
              Enable the "detail"-feature. htnews  can  create  a
              separate  web-page for every news item with details
              (like "read more...").
               If enabled, all Detail_* parameters must  be  con-
              figured!
               The program will look for the first occurence of a
              HTML-comment    within    the    incoming     mail:
              <!--detail--> , every stuff after this line will be
              passed to a separate new file.



       File_Detail_Template (Detail_TEMPL) <filename>
              <!--title-->, if it occurs, htnews will insert  the
              subject at this position!



       File_Detail_Output_Path (Detail_PATH) <PATH>
              The  path  to  the  output directory containing the
              detailpages, it should be the same where the  other
              files are located.
               htnews will generate for every news item (when the
              mail contained the detail-comment) a new  file.  It
              uses the MessageID to create a unique filename! Any
              occurence of "@", "$", "%" or "*" will be  replaced
              with "O".



       Html_Detail_Link (Detail_LINK) <link name>
              How  the  link  on the news item to the detail-page
              should be named, i.e. "read more...".
               If you specify Subject here, then the  subject  of
              the   item   itself   will   be  the  link  to  the
              detail-page.



       Html_Detail_URL (DetailURL) <valid URL>
              If you specify an URL here it will be used for  the
              detail-link. If you use nothing here, simply a link
              the detail-file will be created. Note, that Detail-
              PATH and DetailURL must match.
               This URL has to start with http:// or https://. It
              is not required to append a / to the URL,  it  will
              be done automatically, if it is not there.


       Html_Detail_Head  and Html_Detail_Foot (Detail_HEAD,
              Detail_FOOT) <html-code>
              You  can format the link to the detail-page, if you
              wish.



   Hints
       You can use the supplied sample installation  as  a  basis
       for your own installation, also take a look to the running
       samplepage at http://htnews.org.
        htnews will send you back an email, if one or more param-
       eters  are  incorrect  or something else is wrong. You can
       use the script sanity.check (see below) to check  if  your
       configuration is correct.
        Again, use -C or -A if you want to use the new format and

       htnews will not be able to read it! Therefore migrate now!






Usage

   Insert a new news-item
       You  can  insert  a  new  item  by sending an eamil to the
       robot. The subject-line will be the title of the item  and
       the  body  of  the message will be the item itself. If the
       message becomes too long, you can  use  the  "Detail"-Fea-
       ture:  Write  a short description and on a line itself the
       following "tag": and then the complete  message.  If  this
       feature  is  turned on, htnews will create a separate page
       with the text after the tag. You  can  configure,  how  it
       will look, see above.


   Updating the webpages
       If  you  already  have  some  items  created, and you have
       changed the configuration, then there is a way to force  a
       refresh  of  the output, without putting a new item on the
       page. Simply send an e-mail to  htnews  (the  address  you
       have  configured) with the keyword refresh in the subject.
       htnews will re-read the config-file and recreate the  out-
       put.  Note that ONLY the adminstrator can do this. You can
       specify who that is with the "ADMIN" flag in the  configu-
       ration. See above for details.


   Removing item(s)
       Currently  there  is no comfortable way to remove an item.
       You have to edit the storage file. Read  below  about  the
       format of this file. You have to delete all lines begining
       from "%From:" until "%htnews_end" per item. After that you
       have to refresh the output.





Trouble Shooting

       Testing
              It  is  possible  to  test htnews from the command-
              line. The  source  archiv  contains  a  file  named
              fake.mail. This is a complete mail (header and mes-
              sagebody), the body is in MIME  format  and  it  is
              quoted-printable formatted.
               Issue the following command:

               cat fake.mail | htnews -c /where/ever/htnews.conf

              You can view debugging output, if you invoke htnews
              from the commandline. You have to compile  it  with
              --enable-debugging.
               Additional  you  can  use the provided script san-
              ity_check to force a check on you actual configura-
              tion.  Refer  to  the  file README.sanity_check for
              more informations!





       Error messages
              htnews sends small error messages back to the orig-
              inator  (or  to  the person you have specified with
              "TO"). There are two kinds of messages.  The  first
              kind  is a "delivery" message, sent when everything
              works well. If something goes wrong, you  will  get
              an  error message. htnews will in most cases detect
              and "know" what was wrong, so  the  error  messages
              will help you find the mistake (or what ever).

       SMTP   You  may  also  have  problems with your mailserver
              configuration. Note  that  the  given  installation
              procedure  is  only  good for use with sendmail. If
              you run another smtp server (like qmail, etc.)  you
              must  refer to the documentation for that server on
              how to configure it. If someone has experience with
              some other mailservers, please drop me a line, so I
              can add some tips for those users.




Attachments

       Currently, htnews can NOT handle attachments!  If  someone
       sends  an attachment to htnews, it will read its data con-
       tent as ascii data and display it as ascii. If you require
       this feature, please be patient; I am working on this.




Supported Message Formats

       htnews can currently process plain text mail and a sort of
       MIME  messages  (multipart/alternative),  also  known   as
       html-mail. htnews "understands" two MIME-types: text/plain
        and text/html.  You can choose, which one  of  these  you
       want  to use. If you use the html-part, any occurence of a
       <body> -or <html>-tag will  be  removed,  because  it  may
       "destroy"  the  ouptut,  which  is HTML and which contains
       already these tags.
        htnews  is  also  capable  of  parsing   quoted-printable
       e-mails.  If a message is quoted-printable formatted, then
       follows it will be removed, and a "=" foolowed by  a  new-
       line  will  be replaced by a "" (nothing) without the new-
       line.
        Example:
        <font size=3D2=20
        face=3Darial>
        will be changed to:
        <font size=2 face=arial>

        htnews cannot handle  pure  html-mails!  Pure  HTML-Mails
       will be handeled like plain textmails!
        I  have  tested it with Netscape Messenger (both text and
       text/html), Outlook Express, Outlook '97, pine  and  kmail
       :-)





Storage file format

       Every  message  will  be  stored in a plain textfile in an
       certain format. Perhaps sometimes I will move to the  mbox
       format...

       How it looks:
        %From:  Thomas Linden <tom@daemon.de>
        %Subject:  NEW!
        %Date: Sat Nov  6 21:31:51 1999
        %Message-ID: 99911062031.VAA24254
        %Message: this is a testmessage!
        %htnews_end

       Newer items will be stored on top of the file. This method
       enables you to change the looking of the output every time
       you  like. Once you changed the look (via templates and/or
       via the configuration) send a refresh message to the robot
       - that's all.





Security

       htnews  will replace any occurence of a "`" character with
       a "'". So it will not be possible to  let  htnews  execute
       any  command  while  it  calls  sendmail  for  sending the
       response  message  back  to  the  originator.  In  earlier
       releases  of htnews, it was possible, if one had something
       like `cat /etc/passwd` into the message body.
        If you need this "dangerous"  character,  then  you  must
       edit  the source of htnews. But I recommend you, NOT to do
       it! It is dangerous and you cannot trust everybody!


       I plan to provide a Web interface to htnews. With such  an
       interface,  one  could  configure  the  program  from  his
       browser. And I  want  to  implement  a  system  to  handle
       attachments (i.e. converting images to gif, etc.).




Author and download location

       Author Author  of htnews is Thomas Linden, tom@daemon.de ,
              Munich Germany. Drop me a line if you have any com-
              ments or questions.

       Download location
              http://uss.cybernet-ag.net/~tlinden/
               or ftp.daemon.de/pub/utils/htnews.tar.gz




Credits

       Very  special thanks to Jeff W. Bizzaro, who has corrected
       many mistakes in the man-page. With his help, it is "nice"
       english. Thanks a lot, Jeff!
        ZeimoT made the logo of htnews. Thank you very much!
        Also thanks to all the people, who have reported bugs and
       who have requested some additional features.






Copyright

       htnews is published under the terms  of  the  GNU  General
       Public  License.  If  you  are running an operating system
       like Linux or BSD, you should already have a local copy of
       the    document.    If   not,   you   can   read   it   at
       http://www.gnu.org/

















Man(1) output converted with man2html