update README for PHP7,8

3 files changed, 133 insertions, 117 deletions

diff --git a/README.org b/README.org
deleted file mode 100644
index d3b2821..0000000
--- a/README.org
+++ /dev/null
@@ -1,18 +0,0 @@
-* Php module dependencies
-
-It is not clear what are the exact php modules required for the site to run.  On a Trisquel 9 VM typically it is sufficient to have the following extra modules installed on top of a standard php 7 installation:
-
-- php-gd
-- php-mbstring
-- php-mysql
-- php-xml
-
-Help with formalizing the module dependencies is appreciated.
-
-* Staging deployment patch
-
-When deploying to staging, run
-
-#+begin_src sh
-  patch -p2 <mark-staging.patch
-#+end_src
diff --git a/README.txt b/README.txt
index 5f7241f..3cbf454 100644
--- a/README.txt
+++ b/README.txt
@@ -1,179 +1,206 @@
-
 == Introduction ==
 
-h-source is web software that can be used to build a community of people that want to share their hardware information. It is based on the EasyGiant PHP framework (www.easygiant.org) and can be considered an EasyGiant application (note that EasyGiant is no longer active).
+h-source is web software that can be used to build a community of people that want to share their hardware information. It is based on the EasyGiant PHP framework (www.easygiant.org) and can be considered an EasyGiant application.
 
 
 == Requirements ==
 
-* Web server with URL rewrite (such as Apache with mod-rewrite)
-* PHP 5.2 or newer (does not work with PHP 7)
-* Any version of MariaDB, or MySQL 5 or newer (note that strict mode must be off, so this default must be changed in MariaDB 10.2+ or MySQL 5.7+)
-* php5-gd
-* php5-cli
+TODO: It is not clear what are the exact php modules required for the site to run.
+      Help with formalizing the module dependencies would be appreciated.
+      On a debian-like distro, typically it is sufficient to have the following
+      extra modules installed on top of a standard php 7 installation:
+
+* Web server with PHP and URL rewrite (such as Apache with mod-rewrite)
+* Any version of MariaDB, or MySQL 5 or newer
+* php (currently v7)
+* php-cli
+* php-gd
+* php-mbstring
+* php-mysql
+* php-xml
+
+On a Debian-like system, the following command should be sufficient:
+
+  # apt install apache2 mysql-server php libapache2-mod-php php-mysql php-xml
+  # a2enmod rewite
+
+The DB server must have strict mode set to 'off'. The default must be changed in MariaDB 10.2+ or MySQL 5.7+.
+* FIXME: i did not need to do that
+
 
 == Installation and configuration ==
 
-Extract the tarball inside a folder of your filesystem.
+Extract the tarball or clone the VCS to your filesystem.
 
-You have to create the MySQL database used by h-source. The tables of the database that have to be created are written inside the file tables.sql. A way to carry out this operation is the following:
+You have to create the MySQL database used by h-source. The tables of the database that have to be created are written inside the file tables.sql and distros.sql. A way to carry out this operation is the following:
 
 Open a terminal and type:
 
-	mysql -u <username> -p
-	
-where <username> is the database user. Write the password and type the following command:
+  # cp Config/Config.php{.sample,}
+  # cp admin/Config/Config.php{.sample,}
 
-	create database <db>;
-	
-where <db> is the database name you want to use. Close Mysql by typing the following command:
+And if necessary:
 
-	exit
-	
-Now you have to move inside the folder that contains the tables.sql file and type the following command:
+  # cp .htaccess{.sample,}
 
-	mysql -u username -ppassword <db> < tables.sql
-	
-where username and password have to be changed with the real username and password. <db> is the name of the database just created.
+Now edit those configuration files, at least, defining the DB password 'PWD' under "/*db parameters*/" section in Config/Config.php.
 
-Now you have created the database named <db>
+The following constants are mandatory:
 
-This will also create the default user having the following credentials:
+* DB          // name of the database (the database we will create now)
+* USER        // database user
+* PWD         // database password
+* HOST        // hostname of the mysql server (usually localhost)
+* DOMAIN_NAME // domain name of the website (use 'localhost'
+                 or create a virtual host in your web server)
 
-username: admin
-password: admin
+Note that the <USERNAME>, <PASSWORD>, and <DB> in the commands below, must correspond to the "/*db parameters*/" in Config/Config.php and admin/Config/Config.php.
 
-You will be able to login using the admin user and change the website preferences and the admin password.
+Back at the terminal, type:
 
-Open the Config/Config.php file
+  # mysql -u <USERNAME> -p
 
-You have to set the following constants:
+where <USERNAME> is the database user. Write the password and type the following command:
 
-	DB: name of the database (the database just created)
-	USER: database user
-	PWD: database password
-	HOST: name of the mysql server (usually localhost)
+  > create database <DB>;
 
-	DOMAIN_NAME: the domain name of the website (use localhost or create a virtual host in your web server)
+where <DB> is the database name you want to use. Close Mysql by typing the following command:
 
-Now you have to copy the extracted h-source files inside the DocumentRoot of your server. You can choose to leave all the files inside the DocumentRoot or not, see the explanations in this page (http://www.easygiant.org/learn/index/6).
+  > exit
+
+Now you have to move inside the folder that contains the tables.sql file and type the following commands:
 
-You have now to assure that the allowOverride directive is active in the configuration file of your Apache server. You have to activate the allowOverride directive for the folder inside which you have saved the h-source files (and the index.php file). If you have not activated the allowOverride directive, then your URL won't be interpreted by the mod_rewrite module (you won't be able to use h-source). In a GNU/Linux system the apache configuration file is usually saved at /etc/apache2/apache2.conf.
+  # mysql -u <USERNAME> -p<PASSWORD> <DB> < tables.sql
+  # mysql -u <USERNAME> -p<PASSWORD> <DB> < distros.sql
+  # mysql -u <USERNAME> -p<PASSWORD> <DB> < admin/tables.sql
 
-If necessary, make sure the .htaccess file is in place.
+Now you have created the database named <DB> and populated it with the default accepted/recognized distros. This will also create the default web user having the following credentials:
+
+  username: admin
+  password: admin
+  
+* FIXME: IIRC, no user was created by the preceding commands, i had to create the 'admin' user manually
+
+  > CREATE USER '<USERNAME>'@'localhost' IDENTIFIED BY '<PASSWORD>';
+  > GRANT ALL ON <DB>.* TO '<USERNAME>'@'localhost' IDENTIFIED BY '<PASSWORD>' WITH GRANT OPTION;
+  > FLUSH PRIVILEGES;
+
+Now you have to copy the extracted h-source files inside the DocumentRoot of your server. You can choose to leave all the files inside the DocumentRoot or not, see the explanations in this page (http://www.easygiant.org/learn/index/6).
+
+You have now to ensure that the 'allowOverride' directive is active in the configuration file of your Apache server. You have to activate the 'allowOverride' directive for the folder inside which you have saved the h-source files (and the index.php file). If you have not, then your URL won't be interpreted by the 'mod_rewrite' module (you won't be able to use h-source). In a GNU/Linux system the Apache configuration file is usually saved at /etc/apache2/apache2.conf.
 
 Direct your browser to the following URL:
 
-	http://DOMAIN_NAME/
-	
-where DOMAIN_NAME is the domain name you have previously set (perhaps localhost). You should see the home page of the h-source software.
+  http://<DOMAIN_NAME>/
+
+where DOMAIN_NAME is the domain name you have previously set (eg: localhost). You should see the home page of the h-source software.
 
+You will be able to login to the website using the 'admin' user and change the website preferences and the admin password.
 
 
 == Account issues ==
 
 If you want that the system can send e-mails you have to specify the name of the SMTP server that has to be used. Open the file Application/Include/params.php and set the following static attributes of the Website class:
 
-	$mailServer = "";  //set the mail server (only useful if $useSMTP = true)
-	
-	$generalMail = "";  //set the username of your mail account (always needed)
-	
-	$mailPassword = "";  //set the password of your mail account (only useful if $useSMTP = true)
-
-	$fromEmail = "noreply@h-node.org"; //this is the "from address e-mail" used inside the mails sent by h-source (example: confirmation requesta e-mail, change password e-mail, ...)
+  $mailServer = "";   // set the mail server (if $useSMTP = true)
+  $generalMail = "";  // set the username of your mail account (always needed)
+  $mailPassword = ""; // set the password of your mail account (if $useSMTP = true)
+  $fromEmail = "";    // this is the "from address e-mail" used inside the mails
+                         sent by h-source (example: confirmation requesta e-mail,
+                         change password e-mail, ...)
+  $useSMTP = true;    // if you want to use a SMTP account. It can be true or false.
+                         Set $useSMTP to false if you want that the software rely on
+                         the mail() PHP function.
 
-	$useSMTP = true;  //if you want to use a SMTP account. It can be true or false. Set $useSMTP to false if you want that the software rely on the mail() PHP function
-		
 You can also set these constants:
 
-	$generalName = "";  //the string that you want to use inside the <title> tag of your website
-	
-	$projectName = "";  //the name of your project 
+  $generalName = "";  // the string that you want to use inside the <title> tag of your website
+  $projectName = "";  // the name of your project
 
 
-== Change the configuration of some parts of the template (right column, top notices, top menu, ...) ==
+== Configure the HTML template (right column, top notices, top menu, etc.) ==
 
 Modify the file config.xml inside the ROOT folder of your h-source installation.
 
-If you want to change the position of the config.xml file change the following static attribute of the Website class inside the 
-Application/Include/params.php file:
-	
-	static public $xmlConfigFileFolder = ROOT; //the constant ROOT contains the path to the root folder of your installaton of h-source
+If you want to change the position of the config.xml file change the following static attribute of the Website class inside the Application/Include/params.php file:
+
+  static public $xmlConfigFileFolder = ROOT; // the constant ROOT contains the
+                                                path to the root folder of your
+                                                h-source installaton
 
-== Change the homepage ==
 
+== Change the homepage ==
 
 Modify the PHP files inside the folder Application/Views/Home
 
 
 == Change the hardware ==
 
-
 Modify the PHP file Application/Include/hardware.php
 
 
 == Change the allowed distributions ==
 
-
 Modify the PHP file Application/Include/distributions.php
 
 
 == Change the allowed languages ==
 
-
 Modify the PHP file Application/Include/languages.php
 
 
 == How to fill the vendors entry ==
 
-After the installation you have to fill the MySQL table containing the vendors. To carry out this task you need to download the proper scripts using the following command:
-	
-	svn co svn://svn.savannah.nongnu.org/h-source/trunk/scripts/vendorid
-	
-Move into the just downloaded vendorid folder. Open the file connect.php and modify the following variables:
+After the installation, you have to fill the MySQL table containing the vendors. To carry out this task, you need to download the proper scripts using the following command:
+* FIXME: why are these scripts not in the source tree?
+
+  svn co svn://svn.savannah.nongnu.org/h-source/trunk/scripts/vendorid
+
+Change into the vendorid/ directory. Open the file 'connect.php' and set the following variables with the same values as your h-node instance:
 
-	$host		=	'name of the mysql server (the same used for h-source)';
-	$user		=	'database user (the same used for h-source)';
-	$password	=	'database pasword (the same used for h-source)';
-	$dbName		=	'database name (the same used for h-source)';
+  $host     = '<DOMAIN_NAME>';
+  $user     = '<USERNAME>';
+  $password = '<PASSWORD>';
+  $dbName   = '<DB>';
 
-You will find two file containing the list of vendors: pci.ids and usb.ids. If you want more up-to-date versions of those files then delete them and write the following commands (or download those files from the URLs indicated below):
-	
-	command to get pci.ids (remember to delete the old pci.ids file): 
-		
-		wget pciids.sourceforge.net/v2.2/pci.ids
-	
-	command  to get usb.ids (remember to delete the old pci.ids file):
-		
-		wget http://www.linux-usb.org/usb.ids
+You will find two files containing the list of vendors: pci.ids and usb.ids. If you want more up-to-date versions of those files then delete them and write the following commands (or download those files from the URLs indicated below):
 
-Be sure you have installed php5-cli, then write the following command:
-	
-	php5 insert_vendors.php
+  wget pciids.sourceforge.net/v2.2/pci.ids
+  wget http://www.linux-usb.org/usb.ids
 
-It will fill the vendors MySql table. It will take a bit.
+Be sure you have installed php-cli, then write the following command:
+
+  php insert_vendors.php
+
+It will fill the 'vendors' MySql table. It will take a bit.
 
 
 == Learn the EasyGiant PHP framework ==
 
 Since h-source is an application of the EasyGiant PHP framework you can use the EasyGiant features in order to modify the h-source source code. Visit www.easygiant.org
+* FIXME: www.easygiant.org is offline
+
+
+<!-- NOTE: this file is legal mediawiki syntax -->
+
+<!-- LICENSE
+  h-source, a web software to build a community of people that want to share their hardware information.
+
+  Copyright (C) 2010  Antonio Gallo (h-source-copyright.txt)
+  Copyright (C) 2022 bill-auger <h-source-users@nongnu.org>
+
+  This file is part of h-source
 
+  h-source is free software: you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation, either version 3 of the License, or
+  (at your option) any later version.
 
-// h-source, a web software to build a community of people that want to share their hardware information.
-// Copyright (C) 2010  Antonio Gallo (h-source-copyright.txt)
-//
-// This file is part of h-source
-//
-// h-source is free software: you can redistribute it and/or modify
-// it under the terms of the GNU General Public License as published by
-// the Free Software Foundation, either version 3 of the License, or
-// (at your option) any later version.
-// 
-// h-source is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-// GNU General Public License for more details.
-// 
-// You should have received a copy of the GNU General Public License
-// along with h-source.  If not, see <http://www.gnu.org/licenses/>.
+  h-source is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
 
+  You should have received a copy of the GNU General Public License
+  along with h-source.  If not, see <http://www.gnu.org/licenses/>.
+-->
diff --git a/README_HNODE.ORG_WEBMASTERS.org b/README_HNODE.ORG_WEBMASTERS.org
new file mode 100644
index 0000000..36a78f9
--- /dev/null
+++ b/README_HNODE.ORG_WEBMASTERS.org
@@ -0,0 +1,7 @@
+* Staging deployment patch
+
+When deploying to staging, run
+
+#+begin_src sh
+  patch -p2 <mark-staging.patch
+#+end_src