fix(doc): backintime-config man page

Man page backintime-config corrections around SSH proxy entries.

The script create-manpage-backintime-config.py does not parse config.py probably when methods have line breaks in it.

common/config.py

@@ -669,25 +669,22 @@ def setSshProxyHost(self, value, profile_id=None):
 
     def sshProxyPort(self, profile_id=None):
         #?Proxy host port used to connect to remote host.;0-65535
-        return self.profileIntValue(
-            'snapshots.ssh.proxy_host_port', '22', profile_id)
+        return self.profileIntValue('snapshots.ssh.proxy_host_port', '22', profile_id)
 
     def setSshProxyPort(self, value, profile_id = None):
-        self.setProfileIntValue(
-            'snapshots.ssh.proxy_host_port', value, profile_id)
+        self.setProfileIntValue('snapshots.ssh.proxy_host_port', value, profile_id)
 
     def sshProxyUser(self, profile_id=None):
-        #?Remote SSH user;;local users name
-        return self.profileStrValue(
-            'snapshots.ssh.proxy_user', getpass.getuser(), profile_id)
+        #?Remote SSH user;;the local users name
+        return self.profileStrValue('snapshots.ssh.proxy_user', getpass.getuser(), profile_id)
 
     def setSshProxyUser(self, value, profile_id=None):
         self.setProfileStrValue('snapshots.ssh.proxy_user', value, profile_id)
 
     def sshMaxArgLength(self, profile_id = None):
         #?Maximum command length of commands run on remote host. This can be tested
         #?for all ssh profiles in the configuration
-        #?with 'python3 /usr/share/backintime/common/sshMaxArg.py [initial_ssh_cmd_length]'.\n
+        #?with 'python3 /usr/share/backintime/common/sshMaxArg.py LENGTH'.\n
         #?0 = unlimited;0, >700
         value = self.profileIntValue('snapshots.ssh.max_arg_length', 0, profile_id)
         if value and value < 700:

common/doc-dev/BiT_release_process.md

@@ -44,6 +44,12 @@ using a "feature" branch and sending a pull request asking for a review.
 - Execute the script `./updateversion.sh` to update the version numbers (based on `VERSION` file) in several files.
 - Update the "as at" date in the man page files `backintime.1` and `backintime-askpass.1`.
 - Autogenerate and update the man page file `backintime-config.1` by executing the script `common/create-manapge-backintime-config.py`.
+  - Validate the content of the created man page. For example compared it to a
+    previous version of the man page.
+  - Create a plain text file from the man pages: `man <man-file> | col -b >
+    man.plain.txt`
+  - Use `git diff` (or another diff tool) to compare them and see if the
+    content is as expected.
 - Update `README.md` file.
 - Run `codespell` to check for common spelling errors.
 - Commit the changes.

common/man/C/backintime-config.1

@@ -1,4 +1,4 @@
-.TH backintime-config 1 "August 2024" "version 1.5.3-dev.3e80feee" "USER COMMANDS"
+.TH backintime-config 1 "Aug 2024" "version 1.5.3-dev" "USER COMMANDS"
 .SH NAME
 config \- BackInTime configuration files.
 .SH SYNOPSIS
@@ -73,6 +73,15 @@ Which day of month the cronjob should run? Only valid for \fIprofile<N>.schedule
 Default: 1
 .RE
 
+.IP "\fIprofile<N>.schedule.debug\fR" 6
+.RS
+Type: bool      Allowed Values: true|false
+.br
+Enable debug output to system log for schedule mode.
+.PP
+Default: false
+.RE
+
 .IP "\fIprofile<N>.schedule.mode\fR" 6
 .RS
 Type: int       Allowed Values: 0|1|2|4|7|10|12|14|16|18|19|20|25|27|30|40|80
@@ -682,7 +691,7 @@ Default: false
 .RS
 Type: int       Allowed Values: 0, >700
 .br
-Maximum command length of commands run on remote host. This can be tested for all ssh profiles in the configuration with 'python3 /usr/share/backintime/common/sshMaxArg.py [initial_ssh_cmd_length]'.
+Maximum command length of commands run on remote host. This can be tested for all ssh profiles in the configuration with 'python3 /usr/share/backintime/common/sshMaxArg.py LENGTH'.
 .br
 0 = unlimited
 .PP
@@ -752,6 +761,33 @@ Private key file used for password-less authentication on remote host.
 Default: ~/.ssh/id_dsa
 .RE
 
+.IP "\fIprofile<N>.snapshots.ssh.proxy_host\fR" 6
+.RS
+Type: str       Allowed Values: text
+.br
+Proxy host used to connect to remote host.
+.PP
+Default: IP or domain address
+.RE
+
+.IP "\fIprofile<N>.snapshots.ssh.proxy_host_port\fR" 6
+.RS
+Type: int       Allowed Values: 0-65535
+.br
+Proxy host port used to connect to remote host.
+.PP
+Default: 22
+.RE
+
+.IP "\fIprofile<N>.snapshots.ssh.proxy_user\fR" 6
+.RS
+Type: str       Allowed Values: text
+.br
+Remote SSH user
+.PP
+Default: the local users name
+.RE
+
 .IP "\fIprofile<N>.snapshots.ssh.user\fR" 6
 .RS
 Type: str       Allowed Values: text
@@ -815,12 +851,8 @@ Internal version of profiles config.
 Default: 1
 .RE
 .SH SEE ALSO
-.BR backintime (1),
-.BR backintime-qt (1),
-.BR backintime-askpass (1)
-.PP
-\fBBack In Time\fP project website: https://github.com/bit-team/backintime
+backintime, backintime-qt.
 .PP
-\fBBack In Time\fP mailing list: https://mail.python.org/mailman3/lists/bit-dev.python.org
+Back In Time also has a website: https://github.com/bit-team/backintime
 .SH AUTHOR
-\fBBack In Time\fP Team
+This manual page was written by BIT Team(<bit-dev@python.org>).

create-manpage-backintime-config.py

@@ -89,7 +89,7 @@
 ''' % (strftime('%b %Y', gmtime()), VERSION)
 
 FOOTER = r'''.SH SEE ALSO
-backintime, backintime-qt.
+backintime, backintime-qt, backintime-askpass.
 .PP
 Back In Time also has a website: https://github.com/bit-team/backintime
 .SH AUTHOR
@@ -104,27 +104,48 @@
 REFERENCE = 'reference'
 LINE = 'line'
 
+def groff_indented_paragraph(label: str, indent: int=6) -> str:
+    """.IP - Indented Paragraph"""
+    return f'.IP "{label}" {indent}'
 
-def output(instance='', name='', values='', default='',
-           comment='', reference='', line=0):
+def groff_italic(text: str) -> str:
+    """\\fi - Italic"""
+    return f'\\fI{text}\\fR'
+
+def groff_indented_block(text: str) -> str:
     """
+    .RS - Start indented block
+    .RE - End indented block
     """
+    return f'\n.RS\n{text}\n.RE\n'
+
+def groff_linebreak() -> str:
+    """.br - Line break"""
+    return '.br\n'
+
+def groff_paragraph_break() -> str:
+    """.PP - Paragraph break"""
+    return '.PP\n'
+
+
+def output(instance='', name='', values='', default='',
+           comment='', reference='', line=0):
+    """Generate GNU Troff (groff) markup code for the given config entry."""
     if not default:
         default = "''"
 
-    ret = '.IP "\\fI%s\\fR" 6\n' % name
-    ret += '.RS\n'
-    ret += 'Type: %-10sAllowed Values: %s\n' % (instance.lower(), values)
-    ret += '.br\n'
-    ret += '%s\n' % comment
-    ret += '.PP\n'
+    ret = f'Type: {instance.lower():<10}Allowed Values: {values}\n'
+    ret += groff_linebreak()
+    ret += f'{comment}\n'
+    ret += groff_paragraph_break()
 
     if SORT:
-        ret += 'Default: %s\n' % default
+        ret += f'Default: {default}'
     else:
-        ret += 'Default: %-18s %s line: %d\n' % (default, reference, line)
+        ret += f'Default: {default:<18} {reference} line: {line}'
 
-    ret += '.RE\n'
+    ret = groff_indented_block(ret)
+    ret = groff_indented_paragraph(groff_italic(name)) + ret
 
     return ret
 
@@ -149,6 +170,7 @@ def select_values(instance, values):
 
 def process_line(d, key, profile, instance, name, var, default, commentline,
                  values, force_var, force_default, replace_default, counter):
+    """Parsing the config.py Python code"""
     # Ignore commentlines with #?! and 'config.version'
     comment = None
 
@@ -225,7 +247,7 @@ def main():
     regex_default = re.compile(r'(^DEFAULT[\w]*|CONFIG_VERSION)[\s]*= (.*)')
 
     with open(CONFIG, 'r') as f:
-        print(f'Read "{CONFIG}".')
+        print(f'Read and parse "{CONFIG}".')
         commentline = ''
         values = force_var = force_default = instance \
             = name = var = default = None
@@ -348,13 +370,37 @@ def main():
 
                 commentline = ''
 
+    """
+    Example for content of 'd':
+        {
+            "profiles": {
+            "instance": "str",
+            "name": "profiles",
+            "values": "int separated by colon (e.g. 1:3:4)",
+            "default": "1",
+            "comment": "All active Profiles (<N> in profile<N>.snapshots...).",
+            "reference": "configfile.py",
+            "line": 472
+        },
+            "profile<N>.name": {
+            "instance": "str",
+            "name": "profile<N>.name",
+            "values": "text",
+            "default": "Main profile",
+            "comment": "Name of this profile.",
+            "reference": "configfile.py",
+            "line": 704
+        }
+    """
     with open(MAN, 'w') as f:
-        print(f'Write into "{MAN}".')
+        print(f'Write GNU Troff (groff) markup to "{MAN}". {SORT=}')
         f.write(HEADER)
 
         if SORT:
+            # Sort by alphabet
             s = lambda x: x
         else:
+            # Sort by line numbering (in the source file)
             s = lambda x: d[x][LINE]
 
         f.write('\n'.join(output(**d[key]) for key in sorted(d, key=s)))