I've no problem merging this, but it seems to have conflicts. Not sure how that happened as the repository hasn't changed recently, but in any case, did you want to fix them up?

@tibbs Huh! Strange. Perhaps I based the branch off my fork, instead of the upstream. I'll sort it out.

Edit: Heh. Yup, the commit prior to mine in the branch history is from 2019. Whoops!

@tibbs Should be sorted out now.

Package Maintainer Docs also have something like that already:
Packaging Tutorial line 370

it was copied over from Quick Docs when the packaging tutorial was moved.
Seems to use slightly different syntax, however.
I do not know if it has ever worked.

@oturpe Thanks for pointing that out! That would serve as an effective test; the highlighting wouldn't have worked in production, up to this point, because highlight.js requires a plugin to support .spec file highlighting.

I did check that page on the staging server, and highlighting of the tagged block is still not succeeding — the console reports:

Falling back to no-highlight mode for this block.
Could not find the language 'RPMSpec', did you forget to load/include a language module?

That's either because the language tags @darknao set up for spec files don't include RPMSpec — they're apparently configurable, and I forgot to ask which tag name(s) the staging instance has enabled — or because the plugin isn't being loaded at all. (I'm actually sort of leaning towards the latter, as I don't see any signs of it in the page source on the staging server.)

Regardless, that existing doc means I don't have to wait for this to be merged, to start the process of figuring out with @darknao why highlighting isn't showing up on staging. So I'll update fedora-docs-ui #53 using that page as our first test, and we can start chasing down whatever needs to be corrected to get specfile syntax highlighting switched on.

(That page also shows that unknown source-language tags are indeed simply ignored, demonstrating that this PR is safe to merge prior to support being enabled in production. I mean... I know I said that it was, but even I'd be hesitant to just take my word on that! :wink: )

I'm going to merge this but for those like me who aren't experts at asciidoc, it would be nice to know why all of the instances of four dots were changed to four dashes. Basically if you have any syntax hints for us to get this right in the future, please let us know.

@tibbs AsciiDoc's block syntax is expansive and complex — there are actually 27 different block contexts built in, and several of them have unique shorthand delimiters. But just to be confusing, a block with any delimiters can "masquerade" as another type by making an explicit declaration of its type.

The basic block syntax is an "open block", uses two-dash fencing, and will apply no special formatting to the contents unless it's annotated with a context.

--
Nothing special about this block.
--

Four-dots fencing:

• is shorthand for a literal block
• is equivalent to

[literal]
--
Block contents
--

• wraps the contents in <pre>...</pre>
• doesn't perform syntax-highlighting

Four dashes:

• is shorthand for a "listing" block
• is equivalent to

[listing]
--
Block contents
--

• can be promoted to a source block by using [source] as the annotation instead of [listing]
• (with [source])
  • wraps the contents in <pre><code>...</code></pre>
  • accepts an optional language attribute
  • will enable syntax highlighting by setting the lang= attribute of the code tag, if either:
    • a language is directly specified for the block
    • the document has a source-language attribute, which sets a document-wide default

There are also shorthand fencings for comment blocks (////), example blocks (====), sidebar blocks (****), passthrough blocks (++++), and quote blocks (____).

Most of those just apply a particular styling to the contents, but the passthrough and comment blocks are special. Comment blocks are omitted from the rendered output entirely, their contents are only present in the source file. Passthrough blocks, OTOH, go directly into the output document with no processing, so they can be used to embed raw HTML.

Thanks for the explanation. It occurs to me that we could use a short style guide for packaging guidelines pages, but I wouldn't really know where to start, and this PR definitely isn't the right place to talk about it.

It occurs to me that we could use a short style guide for packaging guidelines pages, but I wouldn't really know where to start, and this PR definitely isn't the right place to talk about it.

Agreed on both counts. (He says, and then proceeds to talk about it anyway.)

Just as one general change/adjustment, it strikes me that the current docs are probably overreliant on .... fencing — all of those blocks could be ---- instead, even the ones that aren't necessarily source code.

(Without a [source] context annotation, ---- will end up being styled the same as ...., so it hardly seems like it would matter, but semantically it's a bit more accurate. Even program output and etc. is still a "listing" more than it is a "literal". And then those blocks are then more readily converted to possibly-highlighted source blocks by simply adding a [source] context ahead of them. Or, to put it another way around, since they're styled the same there doesn't seem to be any reason to use .... for some blocks, when ---- will work for all of them.)