Style (including asciidoctor markups) reminders

There should be a short guideline to keep debmake-doc consistent.

Here is a short memo to address this issue. Please ask here to keep this open on-going documentation.

Backtick-quoted parts are in asciidoctor syntax while the text below is using markdown, here for salsa.

Rationale

Some mark-up choices taken may look excessive but are for making the resulting HTML/PDF results consistent. Few points are considered.

• The old ADCIIDOC(python) result
• GENERATED XML files to be as similar for PO file consistency
• Look and feel of debian-reference style

Text Style

• Chapter name: 20 characters or less
  • Command name etc. should not be capitalized even for the first character but should be in bold as == *debmake* options
  • Don't start with "A" or "The" if possible.
• Section name: 40 characters or less
  • Command name etc. should not be capitalized even for the first character but should be in bold as === *debconf*
  • Don't start with "A" or "The" if possible.
• Main text
  • Command name etc. should avoid to be at the start of sentence to avoid capitalization.
  • Use of "A" or "The" at the start of the sentence should be acceptable.

Markup

• The command name and the package name are marked up as bold using **bold**.
• Some commands are mentioned with its manpage section as **command**(1)
• Variable substituted words are marked up as packagename using __packagename__.
• When space(s) are found in a quoted in-line script, they are quoted between curly double quotes as "`**gtk -a**`"
• Slightly aggressive use of ** to ensure nice highlighting by the treesitter/nvim. So use **command**(1) instead of *command*(1) which seems to be sufficient for the asciidoctor parser.