Merge branch 'dev'

Changes

@@ -1,3 +1,12 @@
+5.985 2021-09-28
+
+    - !ChordPro functionality
+    - Change config preset lookup algorithm and document it.
+    - (docs) First 'hints and tips' contributed by xeruf.
+    - !BugFixes
+    - Remove obsolete code from Makefile.PL and GNUmakefile.
+    - Fix issue #175.
+
 5.983 2021-09-24
 
     - !ChordPro Syntax
@@ -9,16 +18,16 @@
     - Add --no-songconfig to ignore song specific configs.
     - Add --reference to defeat configs and other fun.
     - !BugFixes
-    - Fix issue #165.
     - Prevent wrapping loop with long comment with chords.
     - Fix Can't locate object method "reset_parsers" (Songbook).
-    - Fix issue #163.
     - Fix colour default with {xxxcolor}.
     - Prevent havoc when pdf.chorus.recall.type has illegal values.
-    - Fix issue #178 (non-ascii filenames on Windows).
     - (ChordPro/MSPro) Fix missing meta in substitutions. 
-    - Fix incomplete chord warning for {chord x}.c
+    - Fix incomplete chord warning for {chord x}.
     - Fix issue #132.
+    - Fix issue #163.
+    - Fix issue #165.
+    - Fix issue #178 (non-ascii filenames on Windows).
 
 5.982 2021-08-31
 

GNUmakefile

@@ -27,7 +27,7 @@ dist : Makefile resources
 install : Makefile
 	$(MAKE) -f Makefile install
 
-Makefile : Makefile.PL lib/App/Music/ChordPro/Version.pm
+Makefile : Makefile.PL lib/App/Music/ChordPro/Version.pm resources
 	perl Makefile.PL
 
 ################ Extensions ################
@@ -89,12 +89,3 @@ checkjson :
 	${JSONVALIDATOR} ${JSONOPTS} \
 	  ${CFGLIB}/config.schema .json/*.json
 	rm -fr .json
-
-xxcheckjson :
-	for i in ${CFGLIB}/*.json ; \
-	do \
-	  echo "Verifying $$i..."; \
-	  json_pp -json_opt relaxed < $$i | \
-	  jsonschema -i /dev/stdin ${CFGLIB}/config.schema; \
-	done
-

Makefile.PL

@@ -86,41 +86,3 @@ WriteMakefile
 # Note about the no_index: CPAN and MetaCPAN have differing opinions
 # on how no_index must be interpreted, in particular in combination
 # with provides.
-
-sub MY::postamble {
-    my $ret = <<'EOD';
-
-# Actualize resources.
-
-LIB = lib/App/Music/ChordPro
-RES = ${LIB}/res
-PODSELECT = podselect
-
-resources : ${RES}/config/chordpro.json ${RES}/pod/ChordPro.pod ${RES}/pod/Config.pod ${RES}/notes/common.json
-
-${RES}/config/chordpro.json : ${LIB}/Config.pm
-	$(PERL) -Ilib $< > $@
-
-${RES}/notes/common.json : ${RES}/notes/dutch.json
-	$(CP) $< $@
-
-${RES}/pod/ChordPro.pod : ${LIB}.pm
-	${PODSELECT} $< > $@
-
-${RES}/pod/Config.pod : ${LIB}/Config.pm ${RES}/config/chordpro.json
-	${PODSELECT} $< > $@
-	${PERL} -pe 's/^/  /' ${RES}/config/chordpro.json >> $@
-
-# Verify JSON data
-
-CFGLIB = ${LIB}/res/config
-
-checkjson :
-	for i in ${CFGLIB}/*.json ; \
-	do \
-	  echo "Verifying $$i..."; \
-	  json_pp -json_opt relaxed < $$i | \
-	  jsonschema -i /dev/stdin ${CFGLIB}/config.schema; \
-	done
-EOD
-}

docs/assets/pub/config60.schema

@@ -1333,30 +1333,7 @@
 
 	"debug": {
 	    "description": "Miscellaneous debug settings.",
-	    "additionalProperties": false,
-	    "properties": {
-
-		"abc": {
-		    "description": "Debug setting for ABC.",
-		    "type": "integer",
-		    "default": 0
-		},
-		"ly": {
-		    "description": "Debug setting for LilyPond.",
-		    "type": "integer",
-		    "default": 0
-		},
-		"song": {
-		    "description": "Debug setting for songs.",
-		    "type": "integer",
-		    "default": 0
-		},
-		"spacing": {
-		    "description": "Debug setting for output spacing.",
-		    "type": "integer",
-		    "default": 0
-		}
-	    }
+	    "additionalProperties": true
 	}
     }
 }

docs/content/ChordPro-Configuration-Overview.md

@@ -7,6 +7,8 @@ description: "Configuration: Overview"
 
 The way the output is formatted and some behavioural aspects of the reference implementation are configurable via configuration files. These are [JSON](http://www.json.org/) files that can be created and modified using any convenient text editor. There are also several JSON editors available, often in the form of web services. For schema-based editors, the schema can be downloaded [here]({{< asset "pub/config60.schema" >}}).
 
+## Standard configuration files
+
 ChordPro tries to read several configuration files and combines their contents to form the actual configuration. ChordPro always starts with the built-in default configuration. Then all configuration files are processed in order, and their contents are merged into the existing configuration. So all settings accumulate. Configuration files do not need to be complete (i.e., contain all settings), it is often sufficient to only include the settings that must be changed. See for example the preset configurations [modern1]({{< asset "pub/modern1.json" >}}) and [nashville]({{< asset "pub/nashville.json" >}}), that only contains a few changes.
 
 In the examples below the symbol `~` denotes the user's home directory. Windows users may need to change the forward slashes to backward slashes.
@@ -15,6 +17,10 @@ In the examples below the symbol `~` denotes the user's home directory. Windows
 
 2. A user specific configuration file is read from either:
 
+    `$XDG_CONFIG_HOME/chordpro/chordpro.json`
+
+	or:
+
     `~/.config/chordpro/chordpro.json`  
     `~/.chordpro/chordpro.json`  
   Note that if you have a `~/.config` directory ChordPro expects the configs to be there and the latter alternative will be ignored.
@@ -41,6 +47,31 @@ In the examples below the symbol `~` denotes the user's home directory. Windows
    steps 1 through 3, and then its song specific configuration file if
    it exists.
 
+## Configuration resources (presets)
+
+Preset configurations can be specified by their names, without path
+and extension. For example, `--config=modern1` refers to the preset
+`modern1`.
+
+When a preset config is used, ChordPro will try to find the
+corresponding config file in the following locations (using `modern1`
+as example):
+
+* File `config/modern1.json` or `config/modern1.prp` in one of the
+  paths from the `CHORDPRO_LIB` search path, provided this
+  environment variable has been set.
+
+* File `config/modern1.json` in a built-in location that comes with
+  the ChordPro install.
+
+If environment variable `CHORDPRO_LIB` is not explicitly set, 
+ChordPro will use the first valid directory of:
+
+`$XDG_CONFIG_HOME/chordpro` (provided variable `XDG_CONFIG_HOME` is set)  
+`$HOME/.config/chordpro`  
+`$HOME/.chordpro`  
+`$HOME/chordpro`
+
 ## How config files are combined
 
 The config files are processed in order, and their contents are merged. In general, a config setting from a later file replaces the value from previous files. There are a few exceptions: instrument definitions, hashes and arrays.
@@ -51,9 +82,9 @@ Instrument definitions, in particular the settings `"tuning"`, `"notes"` and `"c
 
 For example, assume `"chords_italian.json"` defines a number of chords using italian (latin) note names and `"chords_german.json"` defines some chords using german note names. Then the following sequence of configuration files will work as expected:
 
-    notes_latin           (built-in, enable latin note names)
+    notes::latin          (built-in, enable latin note names)
     chords_italian.json   (defines chords with latin note names)
-    notes_german          (built-in, enable german note names)
+    notes::german         (built-in, enable german note names)
     chords_german.json    (defines chords with german note names)
 
 ### Merging hash valued items

docs/content/ChordPro-Reference-RelNotes.md

@@ -1,5 +1,26 @@
 # Release info
 
+## 5.985
+
+Released: 2021-09-28
+
+
+### ChordPro functionality
+
+* Change config preset lookup algorithm and document it.
+* (docs) First 'hints and tips' contributed by xeruf.
+
+### BugFixes
+
+* Remove obsolete code from Makefile.PL and GNUmakefile.
+* Fix issue #175.
+
+### Social and support
+
+[User community](https://groups.io/g/ChordPro) for feedback and help.
+
+[Follow us on Twitter](https://twitter.com/ChordPro_Org) to stay informed about new releases and updates.
+
 ## 5.983
 
 Released: 2021-09-24
@@ -19,22 +40,16 @@ Released: 2021-09-24
 
 ### BugFixes
 
-* Fix issue #165.
 * Prevent wrapping loop with long comment with chords.
 * Fix Can't locate object method "reset_parsers" (Songbook).
-* Fix issue #163.
 * Fix colour default with {xxxcolor}.
 * Prevent havoc when pdf.chorus.recall.type has illegal values.
-* Fix issue #178 (non-ascii filenames on Windows).
 * (ChordPro/MSPro) Fix missing meta in substitutions. 
-* Fix incomplete chord warning for {chord x}.c
+* Fix incomplete chord warning for {chord x}.
 * Fix issue #132.
-
-### Social and support
-
-[User community](https://groups.io/g/ChordPro) for feedback and help.
-
-[Follow us on Twitter](https://twitter.com/ChordPro_Org) to stay informed about new releases and updates.
+* Fix issue #163.
+* Fix issue #165.
+* Fix issue #178 (non-ascii filenames on Windows).
 
 ## 5.982
 

docs/content/Support-Hints-And-Tips.md

@@ -5,4 +5,60 @@ description: "Hints and Tips"
 
 # Hints and Tips
 
-Currently a placeholder page, but we hope to provide useful hints and tips soon.
+## Bold chorus
+
+A common style nowadays puts the chorus in bold.
+You need two modifications to achieve this.
+
+First off, set some config keys:
+
+````
+pdf.chorus.indent=0
+pdf.chorus.bar.width=0
+pdf.chorus.recall.quote=1
+pdf.chorus.recall.choruslike=1
+````
+
+Secondly, wrap the chorus in `textfont` directives:
+
+````
+{soc}
+{textfont Times-Bold}
+[E]Dreaming, [A]Dreaming, [B]Just go on
+[E]Dreaming, [A]Dreaming, [B]Just go on
+{textfont}
+{eoc}
+````
+
+This might become easier in the future,
+see https://github.com/ChordPro/chordpro/issues/174.
+
+## [Conditional chords](https://github.com/ChordPro/chordpro/issues/176)
+
+You can use the following preprocessor directive
+to suffix chords with an instrument name
+and thus generate versions of different difficulty or specificity.
+````
+{
+  // Settings for the parser/preprocessor.
+  // Replaces all instrument-specific chords with conditional directives
+  "parser" : {
+    "preprocess" : {
+      "songline" : [
+        { "pattern" : "\\[([^-\\]]+)-(\\w+)\\]",
+          "replace" : "%{instrument=$2|[$1]}"
+        }
+      ],
+    },
+  },
+}
+````
+
+An example of how to use it:
+````
+{comment This is the %{instrument} variant}
+{begin_of_verse}
+[A]He[A7-piano]llo, [Bm]World![C-keyboard]
+[A]Swe[A7-piano]et [Bm]Home![C-keyboard]
+{end_of_verse}
+````