Remove prefixes from the IDs in the module templates #201
Conversation
|
@mjahoda please update the comments in the template files and check the reference guide as well. For example, in the templates:
I |
|
@emmurphy1 @thatdocslady Thank you for your hints. I attempted to discover all affected parts but there is still a chance that I have overlooked something. I also noticed two broken xrefs (and two incorrect examples on the same lines), so I fixed them within this PR as well. Please review once again. |
There was a problem hiding this comment.
I started commenting on each potential point but then I realized that I might be missing something in general, since the edits didn't seem to remove the module/assembly prefix at all, and in fact some of them added prefixes where there were none before. Maybe I'm mistaken, but it's worth another look though the changes..
@thatdocslady I double-checked the diff [1] and also the individual commits, and I see only removals of prefixes from IDs. Could you please provide an example (a link or a screenshot from the web UI) of the described problem? Because I'm so used to do everything in Gitlab, there is still a chance that I'm messing something up here on Github. [1] https://github.com/redhat-documentation/modular-docs/pull/201/files |
There was a problem hiding this comment.
Sorry @mjahoda if this wasn't clear, here is a screenshot of what I'm seeing in the diff viewer:
You can see a side-by-side view of the various files, and the green boxes are meant to represent the proposed changes. I went ahead and proposed suggestions inline in the places where I noticed the issues, for example a prefix was actually added rather than removed, or simply changed from dash to underscore, etc.
Hopefully I'm not misreading the whole thing, but IIRC the decision was to remove prefixes from IDs and file names for all module types and assemblies. Please correct me if I'm wrong or missing anything, GH and GL have similar web UIs but some things are indeed different so they might not be skimmable in the same way (no worries, it's just practice!)
|
@thatdocslady Now, I see what probably confused you. Within this PR, I also fixed some other things such as broken xrefs. However, I did it in the most straightforward way (fixed an ID according to the existing xrefs, not the other way around). In the internal structure of the mod-docs ref. guide, we have really many things that no longer reflects what we recommend in the guide itself. Fixing all of it will be time-consuming and I believe it's not necessary. The important parts are the published content, the examples, and the template files. Then, we are still preserving the prefixes in the file names. Given that, I believe that the goal of this PR - remove prefixes from IDs - is met. |
| @@ -1,7 +1,7 @@ | |||
| //// | |||
| Base the file name and the ID on the module title. For example: | |||
| * file name: con-my-concept-module-a.adoc | |||
| * ID: [id="con-my-concept-module-a_{context}"] | |||
| * file name: con_my-concept-module-a.adoc | |||
There was a problem hiding this comment.
Why con_ instead of con-?
There was a problem hiding this comment.
@emmurphy1 I think that it makes sense to distinguish the prefix part and the title part of a file name this way. Moreover, it's a default in the newdoc tool, all RHEL modules and assemblies follow this pattern, and if you check the source files [1] of our mod-docs guide... :-)
#198