Libelektra: Manpage issues

[Namoshek]

The manpages spread across the documentation have some issues, of which most are only cosmetic. But we should fix them to keep consistency and because it looks better to have a common style for all documents.

I noticed that some manpage files contain additional top-level headlines besides the manpage-name. When generating the manpages with ronn, these additional headlines are skippped, because there can be only one top-level headline a manpage. The bodies of the preceding and the succeeding section are then just glued together, even without a space. (Examples: src/plugins/README.md, doc/help/elektra-introduction.md)

• [ ] fix headlines of all manpages to start at level 2

Further I noticed that we also use different styles in the manpages, e.g. when it comes to case-sensitive spelling. (Examples: doc/help/elektra-architecture.md, doc/help/elektra-backends.md)

• [ ] change all level-2 manpage headlines to upper case (looking at some other manpages, this seems common practice, for level-3 headlines we can use normal casing)
• [x] close headline tags (closed ATX style, e.g. ## headline ## instead of ## headline) [purely cosmetic, low priority]
• [x] remove unnecessary newlines, i.e. one newline between elements (headlines, body, etc.), except tight lists (enumerations) [purely cosmetic, low priority]

When looking at other manpages, it seems very uncommon to have the description or content of the manpage as part of the "NAME" section (which is auto-generated from the manpage name). Therefore I think we should invent either an "introduction" section or a "description" (seems common practice when looking at other manpages).

• [ ] introduce ## DESCRIPTION ## section for manpage content without extra headline

Links look weird in manpages, because both text and link are displayed, but often the link is only a repetition of the link text. We could use bold text markup around the link, then the link text is bold and the link not, which makes the text more readable and emphasizes links further. (Example: **[elektra](elektra/)** will generated something like: elektra _elektra/_)

• [ ] emphasize links with ** markup

[Namoshek]

I added an example in b2d0af0ee9ff175356e441fc74897be11cf074ee. To see how it looks, copy the file content into a new file and run ronn -r <filename>.

[markus2330]

I like the ideas! @iandonnelly do you have some time to update (some of) the man pages?

[markus2330]

@sanssecours Does #2422 fix this issue?

[sanssecours]

Does #2422 fix this issue?

I do not think so. I added a checkmark in the issue description for the only ToDo that pull request #2422 fixes.

[markus2330]

The "close headline tags" is basically also fixed as we decided not to do that?

[markus2330]

This is now fixed due to automatic formatting.