docs: add section anchors to config.ini in references.txt; change format

Added section anchors for each section of config.ini in the
reference.html file. This makes it easier to link to the right section
of the config file when discussing config.ini settings.

Getting this to work using the initial sed implementation was going to
be a nightmare, so rewrote it in awk.

The pre-section comments are now separated by a blank line from the
section marker. Also rst directives no longer have blank lines between
them.

Author: rouilj

doc/Makefile

@@ -6,44 +6,8 @@ tracker_config.txt: ../roundup/configuration.py
 	python3 ../roundup/scripts/roundup_admin.py \
                genconfig _temp_config.txt
 
-	## format and add directives to config file
-	# 1. delete first 8 lines of comments (1,8d)
-	# Some sections have a comment block before the section
-	#    [main] Put the comment block with the section marker
-	#    after the index/code directives. To do this:
-	# 2. Store all comment and blank lines in the hold space
-	#    (H).  Delete the current line and continue with the
-	#    next line (d).
-	# 3. When we see a section marker, append the section
-	#    marker to the hold space (H). substitute for the
-	#    section marker index and code directives
-	#    (s/.../.../) using the section name (\1) for the
-	#    index. Print the directives (p). Empty (zero) the
-	#    pattern space (z). Pull the hold space to the
-	#    pattern space (x) (which also empties the hold space
-	#    because of (z). Print the new pattern space
-	#    [comments and section marker] (p). Delete the patern
-	#    space and process next input line (d).
-	# 4. For any other line, append the line to the hold
-	#    space (H). Zero out the pattern buffer (z). Swap the
-	#    hold space and pattern space [comments and setting
-	#    line] (x).
-	#
-	#    Automatically print the pattern space after the last
-	#    command because we are not using 'sed -n'.
-	#
-	# The last sed command indents every line that is not
-	#   empty or does not start with '..' (a directive) with
-	#   two spaces.
-	# The cat -s squeezes adjacent blank lines to 1 blank
-	#   line.
-	@sed -e '1,8d' \
-	     -e '/^\#\|^$$/{H;d}' \
-	     -e '/^\[\([a-z]*\)\]/{H; s/^\[\([a-z]*\)\]/\n.. index:: config.ini; sections \1\n\n.. code:: ini/; p; z; x; p; d}' \
-	     -e '/./{H;z;x}' \
-	   _temp_config.txt | \
-	 sed -e '/^\.\.\|^$$/!s/^/  /' | \
-	 cat -s > tracker_config.txt
+	awk -f format_config.awk _temp_config.txt | \
+	    cat -s > tracker_config.txt
 	rm -f _temp_config.txt
 
 ## generate html versions of man pages for inclusion in documentation

doc/format_config.awk

@@ -0,0 +1,45 @@
+#! /bin/awk
+
+# delete first 8 lines
+NR < 9 {next}
+
+# When we see a section [label]:
+#  emit section index marker,
+#  emit section anchor
+#  set up for code formating
+#  emit any comments/blank line that are accumulated before the
+#     section marker
+#  print the indented section marker
+#
+# zero the accumulator and the variable that prevents large blocks
+#   of empty lines.
+/^\[([a-z]*)\]/ { match($0, /^\[([a-z]*)\].*/, section_match);
+                  section = section_match[1];
+                  print("\n\n.. index:: config.ini; sections " section);
+                  print(".. _`config-ini-section-" section "`:");
+                  print(".. code:: ini\n");
+		  if (accumulate) {
+		      print("  " accumulate "\n");
+		  }
+		  print("  " $0);
+		  accumulate = "";
+		  prev_line_is_blank = 0;
+	        }
+
+# if the line is a setting line (even if commented out)
+#  print the accumulated comments/blank lines and the setting line
+#  zero the accumulator and the variable that prevents blocks of blank lines
+# get the next input line
+/^#?[a-z0-9_-]* =/ { print accumulate "\n  " $0;
+                     accumulate = "";
+		     prev_line_is_blank = 0;
+		     next;
+                   }
+
+# accumulate comment lines and indent them
+/^#/ { accumulate = accumulate "\n  " $0; prev_line_is_blank =  0;}
+
+# accumulate a blank line only if the previous line was not blank.
+/^$/ { if (! prev_line_is_blank) {accumulate = accumulate $0};
+       prev_line_is_blank = 1;
+     }

doc/tracker_config.txt

@@ -1,6 +1,6 @@
 
 .. index:: config.ini; sections main
-
+.. _`config-ini-section-main`:
 .. code:: ini
 
   [main]
@@ -184,7 +184,7 @@
   password_pbkdf2_default_rounds = 2000000
 
 .. index:: config.ini; sections tracker
-
+.. _`config-ini-section-tracker`:
 .. code:: ini
 
   [tracker]
@@ -231,7 +231,7 @@
   language = 
 
 .. index:: config.ini; sections web
-
+.. _`config-ini-section-web`:
 .. code:: ini
 
   [web]
@@ -595,8 +595,8 @@
   # as is. It removes any whitespace at the end of the
   # line, so a newline can be put in the file.
   # 
-  # Default: 3CpCdT9GrdQv7SCn24DTIQTwAoBguqhAopZnXRZA38w=
-  secret_key = 3CpCdT9GrdQv7SCn24DTIQTwAoBguqhAopZnXRZA38w=
+  # Default: DWmbKgVUy6fF5D2Y5TD5Az+dnHhMYKCCpJzIY3H8nsU=
+  secret_key = DWmbKgVUy6fF5D2Y5TD5Az+dnHhMYKCCpJzIY3H8nsU=
 
   # This is used to sign/validate json web tokens
   # (JWT). Even if you don't use JWTs it must not be
@@ -624,11 +624,13 @@
   jwt_secret = disabled
 
 .. index:: config.ini; sections rdbms
-
+.. _`config-ini-section-rdbms`:
 .. code:: ini
 
+  
   # Settings in this section (except for backend) are used
   #  by RDBMS backends only.
+
   [rdbms]
 
   # Database backend.
@@ -767,10 +769,12 @@
   serverside_cursor = yes
 
 .. index:: config.ini; sections sessiondb
-
+.. _`config-ini-section-sessiondb`:
 .. code:: ini
 
+  
   # Choose configuration for session and one time key storage.
+
   [sessiondb]
 
   # Set backend for storing one time key (otk) and session data.
@@ -800,7 +804,7 @@
   redis_url = redis://localhost:6379/0?health_check_interval=2
 
 .. index:: config.ini; sections logging
-
+.. _`config-ini-section-logging`:
 .. code:: ini
 
   [logging]
@@ -836,12 +840,14 @@
   disable_loggers = no
 
 .. index:: config.ini; sections mail
-
+.. _`config-ini-section-mail`:
 .. code:: ini
 
+  
   # Outgoing email options.
   # Used for nosy messages, password reset and registration approval
   # requests.
+
   [mail]
 
   # The email domain that admin_email, issue_tracker and
@@ -942,10 +948,12 @@
   add_authoremail = yes
 
 .. index:: config.ini; sections mailgw
-
+.. _`config-ini-section-mailgw`:
 .. code:: ini
 
+  
   # Roundup Mail Gateway options
+
   [mailgw]
 
   # Keep email citations when accepting messages.
@@ -1087,10 +1095,12 @@
   keep_real_from = no
 
 .. index:: config.ini; sections pgp
-
+.. _`config-ini-section-pgp`:
 .. code:: ini
 
+  
   # OpenPGP mail processing options
+
   [pgp]
 
   # Enable PGP processing. Requires gpg. If you're planning
@@ -1137,10 +1147,12 @@
   require_incoming = signed
 
 .. index:: config.ini; sections nosy
-
+.. _`config-ini-section-nosy`:
 .. code:: ini
 
+  
   # Nosy messages sending
+
   [nosy]
 
   # Send nosy messages to the author of the message.
@@ -1190,10 +1202,12 @@
   max_attachment_size = 9223372036854775807
 
 .. index:: config.ini; sections markdown
-
+.. _`config-ini-section-markdown`:
 .. code:: ini
 
+  
   # Markdown rendering options.
+
   [markdown]
 
   # If yes/true, render single new line characters in markdown