Link to macro syntax page from spec syntax page

[dmnks]

We speak about (built-in) macros and their expansion in various parts of the spec page but never care to actually mention to the reader that there's a dedicated page on macro syntax. Add a bunch of links where appropriate, and since one of those places mentions %dnl, also add %dnl to the macro page (this used to be there, just got missed in the reformatting commit 015c829).

Fixes: #3331

[dmnks]

Now that I look at the placement of the %dnl description again, I wonder if it really belongs to that particular table. Maybe "Spec specific macros" would be a better fit?

[pmatilai]

Uh, how on earth we didn't have %dnl documented in the macro docs? 😳 It certainly belongs in that table, it's not spec-specific although that's where the most typical usage may be.

Putting this into the "Comments" section seems strange. We should have (however brief) section about macros in the syntax, probably as the very first subsection as they're so fundamental to the spec. Maybe something like

### Macros

Each line in the spec is macro-expanded before further processing. The macro syntax and the built-in macros are 
described in <insert link>. Typically there are vast amounts of other macros available for helping with
common packaging tasks.

[dmnks]

Ack, I was too lazy and just added plain links but of course, it felt weird because then how do you decide which mentions of "macros" you turn into links... 😅 So yup, having a small, dedicated intro would be much better. I'll fix it up.

[dmnks]

Thanks, I've used your suggestion 😄 Should be fixed now.

[ffesti]

"discard to next line" sounds weird to me. How about "discard rest of the line"?

[dmnks]

The descriptions comes from the original commit that added %dnl where it says in the commit message:

... literally discards everything until the next newline (or end of string).

That said, unless there's a technical to reason to word it like that, I agree it'd sound more natural to just say "discard rest of the line".

[dmnks]

Oh yup, thanks! (re: fixup commits)

[dmnks]

OK, one theory as to whether it was worded like that: If you have a multiline macro with the line continuation mark at end of line, you technically have a single logical line, but two (text) lines:

%comment see\
%dnl comment\
this

rpm --eval "%comment" prints this:

see
this

[dmnks]

Maybe I'm reading too much into it, though, but it does seem like a somewhat important distinction 😄

[dmnks]

All that theorizing aside, typically when we mention "line" we mean the textual line, and I'm yet to see a language whose syntax interprets such line continuation markers in comments, so yep... I'm reading too much into it 😄

[pmatilai]

The "discard to next line" is a very deliberate wording, because that's what the acronym stands for, and how M4's dnl is described: https://www.gnu.org/software/m4/manual/html_node/Dnl.html, and M4 dnl is what we want people to associate this with 😄

[pmatilai]

I think it's fine as-is, just squash the two spelling fixes to the second commit.

[dmnks]

The "discard to next line" is a very deliberate wording, because that's what the acronym stands for, and how M4's dnl is described: https://www.gnu.org/software/m4/manual/html_node/Dnl.html, and M4 dnl is what we want people to associate this with 😄

Right, I had a feeling this must be deliberate 😄 Thanks for confirming.

[dmnks]

OK, we've had enough of bike shedding on this one, I think, merging now.