Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Link to macro syntax page from spec syntax page #3352

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

dmnks
Copy link
Contributor

@dmnks dmnks commented Oct 2, 2024

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

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: rpm-software-management#3331
@dmnks dmnks requested a review from a team as a code owner October 2, 2024 10:45
@dmnks dmnks requested review from pmatilai and removed request for a team October 2, 2024 10:45
@dmnks
Copy link
Contributor Author

dmnks commented Oct 2, 2024

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
Copy link
Member

pmatilai commented Oct 3, 2024

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
Copy link
Contributor Author

dmnks commented Oct 3, 2024

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Macro syntax and Spec syntax doc. pages should be interlinked
2 participants