updated and refactored to reflect new working system

Author: stephengaito

Readme.md

@@ -4,6 +4,27 @@ A collection of build and packaging tools for the pdf2htmlEX project
 
 We tag/release these files in sync with the pdf2htmlEX/pdf2htmlEX releases
 
+# Project layout:
+
+1. the **building** directory contains an [Ansible](https://ansible.com) 
+   project which knows how to commision an AWS EC2 instance (typically an 
+   Ubuntu AMI), for use to test-compile, package, and test-install a given 
+   pdf2htmlEX (potential) release on a *clean* *known* Linux release. 
+   (See the [Ansible documentation](https://docs.ansible.com))
+
+2. the **packaging** directory contains the **debian** based build_dists.py
+   packaging tool and associated files. These are automatically copied into 
+   the pdf2htmlEX project on the AWS EC2 build machine by the 
+   [ec2-install-pdf2html-master.yml](building/ec2-install-pdf2html-master.yml) 
+   ansible playbook.
+
+3. the **docs** directory contains more detailed information used to 
+   develop new versions of pdf2htmlEX. In particular:
+
+     * [TipsAndTricks](docs/TipsAndTricks.md) contains ideas which have 
+       been useful in the past for identifying how changes to poppler 
+       might impact pdf2htmlEX.
+
 ## To do
 
 At the moment the debian based build script *does not sign* the debian archive.

building/.gitignore

@@ -1 +1 @@
-hostsEnv
+hostEnvs

building/Readme.md

@@ -2,9 +2,9 @@
 
 This Ansible project contains the information required to commission and 
 setup a bare standard Ubuntu instance.  This allows me to create a new bare 
-standard instance in order to test compile packages on a know base system, 
-and will help to explicilty determine what dependencies are required for a 
-given project.
+standard instance in order to test compile the pdef2htmlEX package on a 
+know base system, and will help to explicilty determine what dependencies 
+are required for pdf2htmlEX.
 
 ## Setup
 
@@ -13,12 +13,12 @@ instance:
 
   https://cloud-images.ubuntu.com/locator/ec2/
 
-THEN edit the file `hostsEnv` to ensure the aws0, aws1, and/or aws2 are 
+THEN edit the file `hostEnvs` to ensure the aws0, aws1, and/or aws2 are 
 associated with the correct *public* ip address
 
-THEN each time you change the `hostsEnv` file you need to type:
+THEN each time you change the `hostEnvs` file you need to type:
 
-  source ./hostsEnv
+  source ./hostEnvs
 
 in each terminal you are using.