Improved and updated README

diff --git a/README.md b/README.md
index 5e54454c6800ba706d1020fe4b531597723cfa4f..edbc9b1bc3eda129c865223895b0a7d49651d25a 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,25 +1,53 @@
+# Installation
 
-# Installation (using virtualenv)
+Dependencies include:
 
-For Trisquel users: Note that although virtualenv and pip are free software, they are not in the Trisquel repositories because these don't include third-party package repositories. You can install python3-pip and python3-virtualenv from packages.ubuntu.com using the matching upstream version of Ubuntu for the Trisquel release you use (For Trisquel 10 nabia use "Focal" packages, For Trisquel 11 aramo use "Jammy" packages.
+ * python3
+ * python3-pip and python3-virtualenv
+ * fonts-roboto
+ * make
 
+## Installing virtualenv on trisquel 10 and 11 using deb files
+
+Note that although virtualenv and pip are free software, they are not in the Trisquel repositories because these don't include third-party package repositories. You can install python3-pip and python3-virtualenv from packages.ubuntu.com using the matching upstream version of Ubuntu for the Trisquel release you use (For Trisquel 10 nabia use "Focal" packages, For Trisquel 11 aramo use "Jammy" packages.
+
+## Installation using virtualenv
+
+    # Clone sources and initiate the virtual env
     git clone git@vcs.fsf.org:financial-reports.git
     virtualenv financial-reports
+    cd financial-reports
     . bin/activate
-
+    
+    # Install pelican and its dependencies
     pip install pelican[markdown]
     pip install pelican-liquid-tags
     pip install pelican-image-process
     pip install matplotlib
-    python -m pip install font-roboto
-
+    
+    # Copy the custom liquid_tags plugins made for the site
     cp plugins/* ./lib/python*/site-packages/pelican/plugins/liquid_tags
+    
+    # Optionally, install font roboto. This can also be done with "sudo apt install fonts-roboto"
+    pip install font-roboto
+    mkdir ~/.fonts ; cp ./lib/python*/site-packages/font_roboto/files/*ttf.ttf ~/.fonts
 
 # Usage notes
 
+To use pelican first you have to activate the virtualenv. In a terminal, run:
+
+    cd financial-reports
+    . bin/activate
+
+From this point on, and until you close this terminal, the versions of python and python libraries available would be those installed (usually via pip) inside of the virtualenv directory. You must run the activation commands every time you start a new work session with a new terminal.
+
+With the virtualenv activated, the "make" command would show the basic pelican usage options. The most common ones are "make html" to generate the output html site once, "make clean" to remove that output, and "make devserver" which would start a local http server that you can connect to from a web browser to test the site. While that command is running, any changes to the site content or theme would automatically trigger a full rebuild of the site, which will show in the browser when you next reload the page there.
+
+# Syntax notes
+
 * Table headers have two '||' if the right-side column is empty (the default in our theme). You can have text on both columns of the header by using "foo | bar" as in "Expenses | Dollars"
-* Images don't need to be scaled down, pelican does it automatically. Include the large resolution versionJPG of the image.
-* Logos should be svg if possible. If they are png, the background should be transparent.
+* Images don't need to be scaled down, pelican does it automatically. Include the original large resolution version of the image, in JPG format.
+* Project logos should be svg if possible. If they are png, the background should be transparent.
 
 # License information