search

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
82 stars 68 forks source link

Comment on assembly template unclear #59

Closed ncbaratta closed 6 years ago

ncbaratta commented 6 years ago

At the top of the Assembly template there is a comment that reads:

// Save the context of the assembly that is including this one. // This is necessary for including assemblies in assemblies. // See also the complementary step on the last line of this file.

It's very confusing. What does 'Save' mean here? I recommend rewording this but I don't have a recommendation because I'm not sure what it means right now.

VladimirSlavik commented 6 years ago

This is a kind of fix for nested assemblies. If there is a module, then assembly, then another module, the last module gets context of the nested assembly, even if it is not in it. So an assembly should "save" the previous context found in the {context} attribute, set {context} to its own value, include things, and at the end restore the previous {context} value.

Disclaimer: I'm not the author.

pwright commented 6 years ago

Is there any point in trying to explain this as comments in asciidoc? would it be better to provide an example of a nested assembly? suggestion: remove these lines create a follow up issue to provide nested assembly example with accompanying documentation

tylerkelly13 commented 6 years ago

@ncbaratta, let me know if the pull request #74 resolves this issue

ncbaratta commented 6 years ago

Sure does!

ritz303 commented 6 years ago

PR #74 resolves this issue, so I'm closing this issue.