docs: improve handling of ResourceItem descriptions

[joergsteffens]

Thank you for contributing to the Bareos Project!

Document and make sure, that ResourceItem descriptions are plain text.

Please check

• Short description and the purpose of this PR is present above this paragraph
• Your name is present in the AUTHORS file (optional)

If you have any questions or problems, please give a comment in the PR.

Helpful documentation and best practices

• Git Workflow
• Automatic Sourcecode Formatting
• Check your commit messages
• Boy Scout Rule

Checklist for the reviewer of the PR (will be processed by the Bareos team)

Make sure you check/merge the PR using devtools/pr-tool to have some simple automated checks run and a proper changelog record added.

General

• Is the PR title usable as CHANGELOG entry?
• Purpose of the PR is understood
• Commit descriptions are understandable and well formatted
• Required backport PRs have been created

Source code quality

• Source code changes are understandable
• Variable and function names are meaningful
• Code comments are correct (logically and spelling)
• Required documentation changes are present and part of the PR

[bruno-at-bareos]

Nicely done, now to be able to build the PR,
@sebsura do you want to fix the extra openssl command we have in the C code

sphinx-build -M html ../b-at-bareos/docs/manuals/source docs/BareosMainReference -j16
Running Sphinx v5.3.0
/bareos/git/b-at-bareos/docs/manuals
INFO generate-resource-descriptions.createSphinx: Create RST/Sphinx files ...
INFO generate-resource-descriptions.__init__: format-version: 2
INFO generate-resource-descriptions.createSphinx: daemon: bareos-dir, resource: Catalog
INFO generate-resource-descriptions.createSphinx: daemon: bareos-dir, resource: Client
Traceback (most recent call last):
  File "scripts/generate-resource-descriptions.py", line 507, in <module>
    createSphinx(data)
  File "scripts/generate-resource-descriptions.py", line 455, in createSphinx
    sphinx.writeResourceDirectives(
  File "scripts/generate-resource-descriptions.py", line 193, in writeResourceDirectives
    self.out.write(self.getConvertedResourceDirectives(daemon, resourcename))
  File "scripts/generate-resource-descriptions.py", line 289, in getConvertedResourceDirectives
    "description": self.getDescription(data),
  File "scripts/generate-resource-descriptions.py", line 264, in getDescription
    raise RuntimeError(f"Description is not plain text: '{description}'")
RuntimeError: Description is not plain text: 'List of valid TLSv1.2 and lower Ciphers; see :command:`openssl ciphers`'

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/usr/local/lib/python3.8/site-packages/sphinx/config.py", line 350, in eval_config_file
    exec(code, namespace)
  File "/bareos/git/b-at-bareos/docs/manuals/source/conf.py", line 417, in <module>
    subprocess.check_call(
  File "/usr/lib64/python3.8/subprocess.py", line 364, in check_call
    raise CalledProcessError(retcode, cmd)
subprocess.CalledProcessError: Command '['scripts/generate-resource-descriptions.py', '--sphinx', 'source/include/autogenerated/bareos-dir-config-schema.json']' returned non-zero exit status 1.

[joergsteffens]

I did the description changes in a minimal way, by rewriting the description in the C code (core/src/lib/tls_resource_items.h). This has the advantage that it is centrally defined and reused in all programs, resulting in 2 changed lines, instead of modifying 30 files.

[bruno-at-bareos]

See comments

[joergsteffens]

@bruno-at-bareos When you finished your review, I'd like to squash some of the commits together.

[bruno-at-bareos]

Thanks everything looks good now.
I would recommend to backport to 23 (at least) so the rules and the sphinx generator are in place.

to do so, you may want to go for squashing commits first maybe.