Update of pages index and PDF generation

docs/index.md

@@ -4,16 +4,17 @@ nav_exclude: true
 # Audiveris Pages
 {: .d-block }
 
-## General documentation
+## For the end user
 
-- [HandBook](_pages/handbook)
+- [HandBook](_pages/handbook)  
+General user documentation  
+Available in web and PDF versions
 {: .d-inline-block }
-updated for 5.3
+new
 {: .label .label-yellow }
 
 ## For the developer
-- [Documentation of .omr file format](_pages/outputs/omr)
-{: .d-inline-block }
-new
-{: .label .label-yellow }
-- [Audiveris Wiki](https://github.com/Audiveris/audiveris/wiki)
+- [Format of ".omr" files](_pages/outputs/omr)  
+Description of the internals of any ".omr" Audiveris book file
+- [Audiveris Wiki](https://github.com/Audiveris/audiveris/wiki)  
+Articles about the development and potential evolutions of Audiveris project.

docs/pdf/pdf-build.sh

@@ -1,11 +1,30 @@
 #!/usr/bin/bash
 
-#---------------------------------------------------------------------------------
-#                            p d f - b u i l d . s h
-#---------------------------------------------------------------------------------
-# Generation of a PDF version of Audiveris handbook
-# This file must be run from docs/pdf folder
-#---------------------------------------------------------------------------------
+#---------------------------------------------------------------------------------------------------
+#                                     p d f - b u i l d . s h
+#---------------------------------------------------------------------------------------------------
+# Generation of a PDF version of Audiveris handbook.
+#
+# This is derived from the file hamoid / justTheDocsToPDF.bash
+# found at https://gist.github.com/hamoid
+#---------------------------------------------------------------------------------------------------
+#
+# This bash file has been tested on Windows/Cygwin. It should also run on Linux and MacOS.
+# It uses standard utilities: curl, grep, head, perl, sed, tail, echo, cat
+#
+# It also uses the "prince" software which is assumed to be found on PATH.
+# Prince can be downloaded from https://www.princexml.com/download/ for various OSes
+# and can be freely used for non-commercial use.
+#---------------------------------------------------------------------------------------------------
+#
+# This file is meant to be run from docs/pdf folder.
+#
+# If the optional "local" parameter is provided, HTML content is retrieved from
+# a local generator found at http://localhost:4000
+# Otherwise, it is retrieved from GitHub Audiveris at https://audiveris.github.io
+#
+# Path to the resulting file is docs/pdf/build/Audiveris_Handbook.pdf
+#---------------------------------------------------------------------------------------------------
 
 # Variables
 #----------
@@ -29,11 +48,11 @@ fi
 # Populate core.html
 #-------------------
 
-# curl retrieves HTML content from web site
-# grep retrieves all <nav> ... </nav> sections (there are 2 such sections)
-# head picks up just the first nav section
-# perl removes all <button> ... </button> sections
-# sed adjusts href values
+# 1/ curl retrieves HTML content from local or remote site
+# 2/ grep retrieves all <nav> ... </nav> sections (there are 2 such sections)
+# 3/ head picks up just the first <nav> ... </nav> section
+# 4/ perl removes all <button> ... </button> sections
+# 5/ sed adjusts href values
 curl -sk $PREFIX/audiveris/_pages/handbook/ |\
 grep -o -P '<nav .*?</nav>' |\
 head -1 |\
@@ -46,12 +65,12 @@ sed -E "s|/audiveris/_pages/|$PREFIX/audiveris/_pages/|g" > build/core.html
 echo "build/nav.html" > build/catalog.txt
 
 # Retrieve all urls:
-# sed(1) injects a line break in front of every URL PREFIX
-# sed(2) deletes from each line the " character and everything that follows, leaving the clean URL
-# tail deletes the first line, which contains a lonely <nav> tag
+# 1/ sed injects a line break in front of every URL PREFIX
+# 2/ sed deletes from each line the " character and everything that follows, leaving the clean URL
+# 3/ tail deletes the first line, which contains a lonely <nav> tag
 sed "s|$PREFIX|\n$PREFIX|g" build/core.html | sed "s/\".*//g" | tail +2 >> build/catalog.txt
 
-# Finalize nav.html
+# Populate nav.html
 #------------------
 
 echo "<!DOCTYPE html>" > build/nav.html
@@ -69,4 +88,4 @@ echo "</html>" >> build/nav.html
 # Use Prince to build the PDF
 #----------------------------
 
-"c:/Program Files (x86)/Prince/engine/bin/prince.exe" --input-list=build/catalog.txt -o build/handbook.pdf
+prince --input-list=build/catalog.txt -o build/Audiveris_Handbook.pdf