[Rpm-maint] [rpm-software-management/rpm] More formatting fixes for macros doc (PR #3218)

[Frank Dana]

This PR, in separate commits, updates the macros documentation to fix one formatting issue I'd noticed on the docs site, reformats two code blocks into markdown tables, and updates the formatting of all other tables in the doc.

1. **Unindent fenced code blocks** — I noticed on the docs page that they looked _terrible_  with the leading indents, which are very visible inside the fenced blocks. (Blocks are already indented, so it's not needed.) I don't know why I didn't fix this in #2251.
2. **Convert expansion explanation to table** — The explanation for how a macro is expanded was formatted as a code block with two columns. That screamed for a table, so I made it one. Note the choice to use "→" to replace the indent on a couple of the lines, since Markdown doesn't support column spans or nested table formatting.
3. **Fence the left-hand column of macro tables** — In #2251 I'd resisted fencing inline code _too_ heavily (just to avoid having the entire text surrounded with \`\`), but I finally admitted that even by my own rules, the left-hand column of each table of macros should be inline-fenced. As part of this change, I also:
    * fixed some bare text strings that looked like HTML tags (most Markdown implementations will insert these into the HTML output verbatim, meaning they become invisible)
    * removed all tab characters from the document everywhere except inside the fenced code blocks, and aligned everything with space indents. Markdown isn't code (except where it contains code), and tabs really don't work well with its column-aligned formatting (as you can see if you look at the diff of the last table, in particular).
    * added trailing `|` characters to table rows with less than the number of columns. My editor likes to squiggly the end of row lines with too few columns.
    * removed a "Notes" column from a table with no notes.
You can view, comment on, or merge this pull request online at:

  https://github.com/rpm-software-management/rpm/pull/3218

-- Commit Summary --

  * Macros doc: Unindent fenced code blocks
  * Macros doc: Convert expansion explanation to table
  * Macros doc: Fence left-hand column of macro tables

-- File Changes --

    M docs/manual/macros.md (218)

-- Patch Links --

https://github.com/rpm-software-management/rpm/pull/3218.patch
https://github.com/rpm-software-management/rpm/pull/3218.diff

-- 
Reply to this email directly or view it on GitHub:
https://github.com/rpm-software-management/rpm/pull/3218
You are receiving this because you are subscribed to this thread.

Message ID: <rpm-software-management/rpm/pull/3218 at github.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rpm.org/pipermail/rpm-maint/attachments/20240729/665e4cbf/attachment-0001.html>