Comments (10)
This would be a question primarily for @mrksu , but as his accomplice in doing this, I am sure this is indeed broken and your analysis is correct. In fact it confirms a doubt I had a few weeks earlier. (Curious that nobody ran into this, including me...)
The actual reason for doing this "parent-context" dance is that the "context" variable is global, too, and including a sub-assembly within an assembly messes context up: If the sub-assembly is followed by a module, the module gets wrong context.
An alternative approach is that in every file where there is an include::assembly followed by include::module, one must insert in between them a line setting context to the right value. It is not as neat and automatic, but works.
Sorry for brevity-hopefully it is understandable.
Asciidoc being what it is, it lacks variable scopes or stack-like structures, which leads me to believe an automated solution is not possible. We (Marek and I) agreed on proposing this solution, believing the stacking would happen automatically. Apparently it does not.
(PS: Do we need context to agree with the assembly? It is the sole reason to have this whole context and parent-context complication.)
from modular-docs.
Setting the context again after each assembly include seems quite strange. But as I said - my workaround was removing all parent-context
's and using different variables where the context actually changes.
Of course having local variables in Asciidoc would be great, but I assume that is not a realistic option.
BTW: This is an actual problem we run into in our docs. The two examples are just for demonstration. Maybe nobody else run into this yet because of using more flat document structures.
from modular-docs.
An alternative approach is that in every file where there is an include::assembly followed by include::module, one must insert in between them a line setting context to the right value. It is not as neat and automatic, but works.
This was how I was doing it on the project @scholzj mentioned originally but I thought it seemed strange to repeat it over and over so I stopped doing that.
from modular-docs.
Hi, sorry for replying so late.
As the person who invented the parent-context
usage, I'm aware of this problem, and I think a semi-automated solution is possible.
The problem is that the parent-context
attribute gets overwritten when another assembly (also using the same attribute) is included in it. As suggested, the attribute must have a unique name in each assembly to prevent it from being overwritten.
The newdoc
script[1], which I've written for generating assembly and modules files from templates based on a title, solves the problem by naming the attribute parent-context-of-${assembly-ID}
, where ${assembly-ID}
is substituted with the actual ID of the assembly.
For example, if there's an assembly called "Creating a backup", its ID would be creating-a-backup
and its parent context would be stored in the parent-context-of-creating-a-backup
attribute. This would be really tedious if written by hand, which is why newdoc
generates all this code for you.
I'm actively using this solution and I haven't found any problems with it.
I'm planning on merging the templates used internally by newdoc
with the upstream templates in this project. When I get to it, I'd be happy to include this fix.
[1] https://github.com/redhat-documentation/tools/tree/master/newdoc
from modular-docs.
@mrksu Thanks. I will try the newDoc
utility. I guess we can close this issue, or?
from modular-docs.
@scholzj Personally, I'd say it's useful to keep this issue open until I actually "merge" the two projects (enabling newdoc
to use the templates from this repo directly), but closing it is fine by me, too.
from modular-docs.
No, its fine to keep it open. Thanks.
from modular-docs.
@mrksu - Conducting a review of outstanding issues in this repo, and checking in to see if this issue can now be closed.
from modular-docs.
I'll open by saying that whatever the solution, please update the Mod Docs reference guide.
Now...I'm running into a problem with parent-context...not sure if it's the same one noted here. But I noticed that the solution in the Mod Docs reference guide defines parent-context, but never undefines it. So I restructured the code a bit like this:
ifdef::context[:parent-context: {context}]
:context: customizing_engine_vm_deploy
My content.
ifndef::parent-context[:!context:]
ifdef::parent-context[]
:context: {parent-context}
:!parent-context:
endif::[]
Notice that I put the ifndef
first.
from modular-docs.
FYI, we ran into a similar problem in RHOSP and it turned out that we needed to set the :context: variable in the book/guide main assembly. This wasn't documented in the Mod Docs Reference Guide, and there is no template for master.adoc files so we had to scramble our own template for the team.
I'll be happy to add this information to the reference guide and work with someone who's more experienced with templates to create a book-level template, if this is indeed the best practice we want to implement across the teams.
from modular-docs.
Related Issues (20)
- Procedure module template link? HOT 1
- Structure the "Procedure modules" section to align with its counterparts
- Link to the "Procedure Module Guidelines" is broken
- Remove module prefixes from IDs in the templates HOT 4
- [On hold] Review and update guidance on using gerund verb form as the first word in a title of a procedure HOT 13
- Creating modules|Procedure modules contains unclear parts HOT 4
- Fix metadata in templates from content_type to module_type HOT 23
- Users no longer have a link to the procedure template HOT 4
- Do we have a Modular Documentation checklist? HOT 12
- Create a Vale style to check for Mod Docs rules HOT 5
- Error 404 for a reference module example
- Establish and document a process for maintaining the "What's new" release notes section
- Updates regarding ID's for headings HOT 4
- Addressing possible design flaws in maintaining and referencing assembly-specific context IDs HOT 13
- Re-remove [role="_abstract"]
- Add a one-line comment to the Procedure template to avoid rendering issues
- Update to the contributor instructions to fork the repo and clone the fork
- Incorporate the newdoc tool into our guidance for using the templates
- Define and document our team review process
- Demonstrating the use of snippets for both boilerplate content and module reuse HOT 6
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from modular-docs.