redhat-documentation / modular-docs

Modular Documentation Project provides guidelines and examples for writing technical documentation using a modular framework.
Creative Commons Attribution Share Alike 4.0 International
80 stars 67 forks source link

Add [] to the snippet example file. #179

Closed emmurphy1 closed 2 years ago

emmurphy1 commented 2 years ago

@RichardHoch reported:

I think there's a slight but important omission in the Modular Documentation Reference Guide's discussion of snippets:

https://redhat-documentation.github.io/modular-docs/#using-text-snippets

The problem is: in the include statement shown, there are no square brackets after the snippet file name. That is, the example should be include::snippets/beta-note.adoc[] and not include::snippets/beta-note.adoc as the text currently reads.

Without those brackets, the document will build in bccutil as if everything is fine, [but the content of the snippet file is not included].

So you might think your document is OK since there is no error message in bccutil (that might be an issue, too) but it isn't.

Please check this out. From experimenting with include statements, I see they always must be followed by square brackets -- we're used to this since that's where we insert the level offset information. Nonetheless, it might be worth mentioning that when you include a snippet you have to include the square brackets, even though it's not a module, so there is no level offset.

mjahoda commented 2 years ago

@emmurphy1 This is a good catch. The square brackets are mandatory parts of the include syntax: https://docs.asciidoctor.org/asciidoc/latest/directives/include/

sterobin commented 2 years ago

@emmurphy1 @mjahoda Fixed in PR #180. Awaiting PR approval to merge fix.