newsportal/doc/readme-english.txt


                                News portal
                                      
   Version 0.24pre1
   
Introduction

   News portal is a PHP based newsreader. It is licensed under the GNU
   Public License (see enclosed LICENSE).
   
Overview

   This script collection enables the access to a newsserver (by NNTP)
   from a webpage. It allows you to combine web-forums and newsgroups.
   The script is also suitable for presentation of announce newsgroups on
   web pages, without having the user notice that he is in fact accessing
   a newsserver.
   
   The main functionality of the script is located in the file
   newsportal.php3, which contains the major part of the implemented
   php3-functions. In addition to that there are four more php3-files,
   which are directly accessed by the browser.
     * index.php3 shows the available newsgroups of the newsserver (if
       you have added the names to groups.txt)
     * thread.php3 displays the article-overview of a newsgroup. The
       articles are displayed in a thread.
     * article.php3 displays an individual article.
     * post.php3 posts a message into a newsgroup. WARNING: This script
       produces absolutely not RFC conformal messages. Thus 'umlauts' in
       the Subject are not mime encoded ! It still works fine though.
     * config.inc contains the configuration.
     * body.inc contains the header and the body-tag of the pages. This
       way the layout of the pages (i.e. the background) can easily be
       adjusted.
     * german.lang : The German language definitions
     * english.lang : The English language definitions
       
   Since fetching the article overview of the newsserver takes quite some
   time, newsportal caches this data in the directory spool/. Any file
   can be put in this directory, they will automatically be regenerated.
   
Installation:

    1. download the zip or tar.gz archive
    2. unzip it to a directory
    3. The fileconfig.inc must be edited with your settings (the most
       important variables are: $server, $port, $title and $readonly).
    4. Write the names of all groups newsportal should show into the file
       groups.txt. Behind the groupname, seperated by a blank, a
       description of the group can be added. If the description is
       missing, newsportal will try to request the description from the
       newsserver.
    5. The spool directory has to be created and configured to grant read
       an write access to the newsserver ("chmod 777 spool" ).
       
Configuration

   The following adjustments can be made in config.inc
   
   Directories and files:
     * $file_newsportal="newsportal.php3":Name of the file containing the
       newsportal-functions.
     * $file_groups="index.php3": The file which shows the list of
       available newsgroups.
     * $file_thread="thread.php3": The file which shows the
       article-thread of a selected newsgroup
     * $file_article="article.php3": Displays an article
     * $file_post="post.php3": The file which allows you to post an
       article to a newsgroup. This file can be removed, if the system is
       set on readonly (see below).
     * $file_language="english.lang": Reference to the language
       definition file.
     * $file_footer: Optionally, the name of a file can be indicated,
       which will be attached to every article posted to a newsgroup.
       
   Newsserver setip
     * $server : Hostname or IP of the newsserver
     * $port : Port of the newsserver, normally 119
     * $post_server: Optionally an extra newsserver can be indicated here
       which is used by post.php3 for writing articles. This is useful if
       two newsservers need to be accessed, a fast read-only server and a
       slow server to post articles. Be aware that it might take some
       time until the posted article will show up on your main newsserver
       ($server), which you use to read articles.
     * $post_port : Port of your post-newsserver
     * $server_auth_user: If the newsserver requires authentication by
       name and password put your username here. Otherwise just set the
       variable to "".
     * $server_auth_pass: Put your password here.
       
   Thread Layout
     * $treestyle :The appearance of the message tree:
          + 0: Simple listing of the articles
          + 1: Easy listing of the articles, with some more HTML tags
          + 2: Simple listing in a table
          + 3: Threaded with HTML-tags (UL, li)
          + 4: Threaded with text characters
          + 5: Threaded with graphical images
          + 6: Threaded with text characters and table
          + 7: Threaded with graphical images table
     * $thread_fontPre: The code given here is put in front of every text
       fragment in thread.php3, i.e. font face or size can be set.
     * $thread_fontPost: The same as $thread_fontPre, only code is
       appended at the end of the text.
     * $thread_showDate,
       $thread_showSubject,
       $thread_showAuthor:
          + true: the date / the subject / the author are displayed in
            the thread
          + false: output is suppressed.
     * $thread_maxSubject : Maximum number of characters of the subject
       displayed
     * $maxarticles: This number indicates the maximum amount of overview
       data of a newsgroup newsportal tries to get from the newsserver.
       "0" means no limitation. $maxarticles also indicates the amount of
       articles to be stored in the spoolfiles. A lower value means less
       work for newsportal
     * $maxarticles_extra: The problem with $maxarticles is that all
       article data must be completely requested again by the new server,
       if the indicated value is exceeded. $maxarticles_extra can be set
       to prevent this. The article-spool will only be restructured if
       $maxarticles + $maxarticles_extra articles are present, whereby
       $maxarticles many article data are requested. Only if an exact
       given number of articles should be displayed on the web page, the
       value of this variable schould be set "0".
     * $age_count : Number of different age levels for the coloured
       marking of articles
     * $$age_time[n] : maximal age of an article in seconds, so that the
       article gets marked with the colour $age_color[n]. n is a natural
       number > = 1 and all numbers from 1 to n must be assigned, gaps
       are not permitted.
     * $age_color[n]: The colour in which the article is marked
     * $thread_sorting : The sort sequence for the articles:
          + 0: No assortment, articles are displayed in the order in
            which they are polled from the server. This is nearly like
            ascending assortment.
          + 1: ascending assortment, the oldest articles to the top.
          + -1: descending assortment, the newest articles to the top.
     * $articles_per_page: If this value is not 0, the maximum amount of
       articles is given, which are to be displayed on one page at the
       same time. The thread will be split into individual pages.
     * $startpage: In connection with $$articles_per_page the variable
       indicates, which page is to be displayed first:
          + "first": The page with the newest articles
          + "last": the page with the oldest articles
       The specification should be co-ordinated with $thread_sorting.
       "first" for 0 and 1, and "last" for -1.
       
   Article layout
     * $article_show["Subject"],
       $article_show["From"],
       $article_show["Newsgroups"],
       $article_show["Organization"],
       $article_show["Date"],
       $article_show["Message-ID"],
       $article_show["User-Agent"],
       $article_show["References"]: "true" displays the respective header
       line in article.php3, by "false" it is suppressed.
       
   Frame support
   Example files for the frame support are located in extras/frames/. In
   this section the names of the frames can be defined. If you want to
   use frames you have to set the variable $frame_thread to
   "thread_frameset.php3".
     * $frame_articles: Name of the article frame. Must be the same as
       defined in thread_frameset.php3.
     * $frame_thread: Name of the thread frame.
     * $frame_groups: Name of the frame for the grouplist, normally set
       to "_top" to open a new frameset.
     * $frame_post : Name of the frame for post.php3
     * $frame_threadframeset : Name of the frame, in which the frameset
       is to appear, which takes up the article and thread Frames.
       Normally set to "_top".
     * $frame_externallink: Target frame for external links within
       articles.
       
   Safety settings
     * $send_poster_host: "true" means that a header-line named
       "X-HTTP-Posting-Host:" will be attached to every posted article,
       set to the hostname of the user who wrote the article.
     * $readonly : if set to "true", the newsportal is read-only. The
       file post.php3 can be safely removed.
     * $testgroup : if set to "true" newsportal checks if a group is
       listed in groups.txt when accessed through thread.php3. Otherwise
       a group could be seen simply entering the right URL, although the
       group is not displayed in the group list.
     * $validate_email : Sets how newsportal checks an email address in
       post.php3 for syntax:
          + 0: no examination. Not recommended, since the newsserver will
            give an error message, if the address is not syntactically
            correct.
          + 1: Checks the address on syntactic correctness.
          + 2: Additionally a MX or A record is checked for the
            domain-name of the e-mail address. Newsportal performs a
            hostname lookup.
       
   General setting
     * $title: The value of this variable is put in the title-header of
       the generated webpages.
     * $organization : Name of your organization. Put after the
       "Organization:"-header when posting articles.
     * $setcookies : Permits the user to save his name and his
       email-address as cookies in his browser.
     * $compress_spoolfiles: Sets whether the spool files should be
       compressed or not. This is recommended under normal conditions,
       since the size of the spoolfiles shrinks approximately to about
       15% of the original size. Be aware that some PHP-Versions do not
       support compressing
       
Safety notes

   A few things must be kept in mind to not allow newsportal to open
   safety-holes:
     * config.inc can be requested by every user that knows the filename,
       if you do not move it to a protected area of your webserver.
       
   This script was originally (and actually still) only meant for access
   to local newsgroups. If you use it with UseNet newsgroups, following
   problems could show up:
     * Articles could be posted anonymously (i.e. spamming), see
       $send_poster_host
     * Newsportal produces 8-bit header lines (i.e. the Subject), which
       is not permitted. However there do not seem to be any problems.
     * There are lists with so-called "open" newsservers in the internet.
       Mostly "open" doesn't mean for this server that everyone is
       allowed to use this server. Normally it means that the operator of
       the server forgot to protect his server adequatly. So before using
       an "open" newsserver, you should make sure that the operator
       permits the use of his server for newsportal.
     * Posting articles anonymously is not accepted in most UseNet
       groups. Before you give writing access to a newsgroup, you should
       ask the users in the newsgroup if they have no objections. Do not
       give public write access on UseNet newsgroups, if you do not know
       exactly, what you are doing!
       
   The author reserves the right not to be responsible for the
   topicality, correctness, completeness or quality of the program
   provided. Liability claims regarding damage caused by the program
   provided, will therefore be rejected.
   In other words: Use this program at your own risk !
   
Compatibility

   Newsportal should work with every phpserver with php3 support and
   every newsserver. Webserver and newsserver do not need to run on the
   same machine.
   
Contact

   Florian Amrhein
   email: florian.amrhein@gmx.de
   WWW: http://florian-amrhein.de
1	wakaba	1.1
2			News portal
3
4			Version 0.24pre1
5
6			Introduction
7
8			News portal is a PHP based newsreader. It is licensed under the GNU
9			Public License (see enclosed LICENSE).
10
11			Overview
12
13			This script collection enables the access to a newsserver (by NNTP)
14			from a webpage. It allows you to combine web-forums and newsgroups.
15			The script is also suitable for presentation of announce newsgroups on
16			web pages, without having the user notice that he is in fact accessing
17			a newsserver.
18
19			The main functionality of the script is located in the file
20			newsportal.php3, which contains the major part of the implemented
21			php3-functions. In addition to that there are four more php3-files,
22			which are directly accessed by the browser.
23			* index.php3 shows the available newsgroups of the newsserver (if
24			you have added the names to groups.txt)
25			* thread.php3 displays the article-overview of a newsgroup. The
26			articles are displayed in a thread.
27			* article.php3 displays an individual article.
28			* post.php3 posts a message into a newsgroup. WARNING: This script
29			produces absolutely not RFC conformal messages. Thus 'umlauts' in
30			the Subject are not mime encoded ! It still works fine though.
31			* config.inc contains the configuration.
32			* body.inc contains the header and the body-tag of the pages. This
33			way the layout of the pages (i.e. the background) can easily be
34			adjusted.
35			* german.lang : The German language definitions
36			* english.lang : The English language definitions
37
38			Since fetching the article overview of the newsserver takes quite some
39			time, newsportal caches this data in the directory spool/. Any file
40			can be put in this directory, they will automatically be regenerated.
41
42			Installation:
43
44			1. download the zip or tar.gz archive
45			2. unzip it to a directory
46			3. The fileconfig.inc must be edited with your settings (the most
47			important variables are: $server, $port, $title and $readonly).
48			4. Write the names of all groups newsportal should show into the file
49			groups.txt. Behind the groupname, seperated by a blank, a
50			description of the group can be added. If the description is
51			missing, newsportal will try to request the description from the
52			newsserver.
53			5. The spool directory has to be created and configured to grant read
54			an write access to the newsserver ("chmod 777 spool" ).
55
56			Configuration
57
58			The following adjustments can be made in config.inc
59
60			Directories and files:
61			* $file_newsportal="newsportal.php3":Name of the file containing the
62			newsportal-functions.
63			* $file_groups="index.php3": The file which shows the list of
64			available newsgroups.
65			* $file_thread="thread.php3": The file which shows the
66			article-thread of a selected newsgroup
67			* $file_article="article.php3": Displays an article
68			* $file_post="post.php3": The file which allows you to post an
69			article to a newsgroup. This file can be removed, if the system is
70			set on readonly (see below).
71			* $file_language="english.lang": Reference to the language
72			definition file.
73			* $file_footer: Optionally, the name of a file can be indicated,
74			which will be attached to every article posted to a newsgroup.
75
76			Newsserver setip
77			* $server : Hostname or IP of the newsserver
78			* $port : Port of the newsserver, normally 119
79			* $post_server: Optionally an extra newsserver can be indicated here
80			which is used by post.php3 for writing articles. This is useful if
81			two newsservers need to be accessed, a fast read-only server and a
82			slow server to post articles. Be aware that it might take some
83			time until the posted article will show up on your main newsserver
84			($server), which you use to read articles.
85			* $post_port : Port of your post-newsserver
86			* $server_auth_user: If the newsserver requires authentication by
87			name and password put your username here. Otherwise just set the
88			variable to "".
89			* $server_auth_pass: Put your password here.
90
91			Thread Layout
92			* $treestyle :The appearance of the message tree:
93			+ 0: Simple listing of the articles
94			+ 1: Easy listing of the articles, with some more HTML tags
95			+ 2: Simple listing in a table
96			+ 3: Threaded with HTML-tags (UL, li)
97			+ 4: Threaded with text characters
98			+ 5: Threaded with graphical images
99			+ 6: Threaded with text characters and table
100			+ 7: Threaded with graphical images table
101			* $thread_fontPre: The code given here is put in front of every text
102			fragment in thread.php3, i.e. font face or size can be set.
103			* $thread_fontPost: The same as $thread_fontPre, only code is
104			appended at the end of the text.
105			* $thread_showDate,
106			$thread_showSubject,
107			$thread_showAuthor:
108			+ true: the date / the subject / the author are displayed in
109			the thread
110			+ false: output is suppressed.
111			* $thread_maxSubject : Maximum number of characters of the subject
112			displayed
113			* $maxarticles: This number indicates the maximum amount of overview
114			data of a newsgroup newsportal tries to get from the newsserver.
115			"0" means no limitation. $maxarticles also indicates the amount of
116			articles to be stored in the spoolfiles. A lower value means less
117			work for newsportal
118			* $maxarticles_extra: The problem with $maxarticles is that all
119			article data must be completely requested again by the new server,
120			if the indicated value is exceeded. $maxarticles_extra can be set
121			to prevent this. The article-spool will only be restructured if
122			$maxarticles + $maxarticles_extra articles are present, whereby
123			$maxarticles many article data are requested. Only if an exact
124			given number of articles should be displayed on the web page, the
125			value of this variable schould be set "0".
126			* $age_count : Number of different age levels for the coloured
127			marking of articles
128			* $$age_time[n] : maximal age of an article in seconds, so that the
129			article gets marked with the colour $age_color[n]. n is a natural
130			number > = 1 and all numbers from 1 to n must be assigned, gaps
131			are not permitted.
132			* $age_color[n]: The colour in which the article is marked
133			* $thread_sorting : The sort sequence for the articles:
134			+ 0: No assortment, articles are displayed in the order in
135			which they are polled from the server. This is nearly like
136			ascending assortment.
137			+ 1: ascending assortment, the oldest articles to the top.
138			+ -1: descending assortment, the newest articles to the top.
139			* $articles_per_page: If this value is not 0, the maximum amount of
140			articles is given, which are to be displayed on one page at the
141			same time. The thread will be split into individual pages.
142			* $startpage: In connection with $$articles_per_page the variable
143			indicates, which page is to be displayed first:
144			+ "first": The page with the newest articles
145			+ "last": the page with the oldest articles
146			The specification should be co-ordinated with $thread_sorting.
147			"first" for 0 and 1, and "last" for -1.
148
149			Article layout
150			* $article_show["Subject"],
151			$article_show["From"],
152			$article_show["Newsgroups"],
153			$article_show["Organization"],
154			$article_show["Date"],
155			$article_show["Message-ID"],
156			$article_show["User-Agent"],
157			$article_show["References"]: "true" displays the respective header
158			line in article.php3, by "false" it is suppressed.
159
160			Frame support
161			Example files for the frame support are located in extras/frames/. In
162			this section the names of the frames can be defined. If you want to
163			use frames you have to set the variable $frame_thread to
164			"thread_frameset.php3".
165			* $frame_articles: Name of the article frame. Must be the same as
166			defined in thread_frameset.php3.
167			* $frame_thread: Name of the thread frame.
168			* $frame_groups: Name of the frame for the grouplist, normally set
169			to "_top" to open a new frameset.
170			* $frame_post : Name of the frame for post.php3
171			* $frame_threadframeset : Name of the frame, in which the frameset
172			is to appear, which takes up the article and thread Frames.
173			Normally set to "_top".
174			* $frame_externallink: Target frame for external links within
175			articles.
176
177			Safety settings
178			* $send_poster_host: "true" means that a header-line named
179			"X-HTTP-Posting-Host:" will be attached to every posted article,
180			set to the hostname of the user who wrote the article.
181			* $readonly : if set to "true", the newsportal is read-only. The
182			file post.php3 can be safely removed.
183			* $testgroup : if set to "true" newsportal checks if a group is
184			listed in groups.txt when accessed through thread.php3. Otherwise
185			a group could be seen simply entering the right URL, although the
186			group is not displayed in the group list.
187			* $validate_email : Sets how newsportal checks an email address in
188			post.php3 for syntax:
189			+ 0: no examination. Not recommended, since the newsserver will
190			give an error message, if the address is not syntactically
191			correct.
192			+ 1: Checks the address on syntactic correctness.
193			+ 2: Additionally a MX or A record is checked for the
194			domain-name of the e-mail address. Newsportal performs a
195			hostname lookup.
196
197			General setting
198			* $title: The value of this variable is put in the title-header of
199			the generated webpages.
200			* $organization : Name of your organization. Put after the
201			"Organization:"-header when posting articles.
202			* $setcookies : Permits the user to save his name and his
203			email-address as cookies in his browser.
204			* $compress_spoolfiles: Sets whether the spool files should be
205			compressed or not. This is recommended under normal conditions,
206			since the size of the spoolfiles shrinks approximately to about
207			15% of the original size. Be aware that some PHP-Versions do not
208			support compressing
209
210			Safety notes
211
212			A few things must be kept in mind to not allow newsportal to open
213			safety-holes:
214			* config.inc can be requested by every user that knows the filename,
215			if you do not move it to a protected area of your webserver.
216
217			This script was originally (and actually still) only meant for access
218			to local newsgroups. If you use it with UseNet newsgroups, following
219			problems could show up:
220			* Articles could be posted anonymously (i.e. spamming), see
221			$send_poster_host
222			* Newsportal produces 8-bit header lines (i.e. the Subject), which
223			is not permitted. However there do not seem to be any problems.
224			* There are lists with so-called "open" newsservers in the internet.
225			Mostly "open" doesn't mean for this server that everyone is
226			allowed to use this server. Normally it means that the operator of
227			the server forgot to protect his server adequatly. So before using
228			an "open" newsserver, you should make sure that the operator
229			permits the use of his server for newsportal.
230			* Posting articles anonymously is not accepted in most UseNet
231			groups. Before you give writing access to a newsgroup, you should
232			ask the users in the newsgroup if they have no objections. Do not
233			give public write access on UseNet newsgroups, if you do not know
234			exactly, what you are doing!
235
236			The author reserves the right not to be responsible for the
237			topicality, correctness, completeness or quality of the program
238			provided. Liability claims regarding damage caused by the program
239			provided, will therefore be rejected.
240			In other words: Use this program at your own risk !
241
242			Compatibility
243
244			Newsportal should work with every phpserver with php3 support and
245			every newsserver. Webserver and newsserver do not need to run on the
246			same machine.
247
248			Contact
249
250			Florian Amrhein
251			email: florian.amrhein@gmx.de
252			WWW: http://florian-amrhein.de