redhat-documentation / tools Goto Github PK

Since redhat-documentation/modular-docs#61 was merged, the guideline is NOT to use proc, con, ref and assembly as part of the filenames. I understand some teams want to still use that, and that is perfectly ok. However, since most teams would be following the official guidelines, which do not recommend the use of these prefixes, it would be good if we can provide this as a command line option to include/exclude (whichever is easier).

It would be great if newdoc could generate assemblies populated with include:: statements based on either a series of command-line options (specifying the assembly and its modules), or an input file.

CLI options:

newdoc --populate -a assembly.adoc -c concept.adoc -p procedure.adoc -r reference.adoc

Or an input file:

$ cat input.txt
a assembly.adoc
c concept.adoc
p procedure.adoc
r reference.adoc

newdoc --populate --inputfile input.txt

Both of these examples would generate assembly.adoc with the following:

$ cat assembly.adoc
[...snip...]
include::concept.adoc[leveloffset=+1]
include::procedure.adoc[leveloffset=+1]
include::reference.adoc[leveloffset=+1]
[...snip...]

It should be possible to define multiple assemblies.

(I ended up scripting my own solution to this in Bash, so I could share if deemed useful.)

Running atree on the RHEL8 docs repo, branch 8.0-GA, specifically on enterprise/titles/installing/performing-a-standard-rhel-installation/master.adoc, shows one of the included files as being nonexistent:

assemblies/assembly_installing-red-hat-enterprise-linux-on-ibm-power-system-l-server.adoc
     ...
     N! /modules/installer/con_powering-on-your-l-server-with-ipmi.adoc

The file exists, though:

$ file modules/installer/con_powering-on-your-l-server-with-ipmi.adoc
modules/installer/con_powering-on-your-l-server-with-ipmi.adoc: ASCII text

The problem is the include has a leading slash (include::/modules/installer/con_powering-on-your-l-server-with-ipmi.adoc[leveloffset=+1] in file enterprise/assemblies/assembly_installing-red-hat-enterprise-linux-on-ibm-power-system-l-server.adoc). None of the other includes in the title have a leading slash, this is likely to be the problem.

ASCIIDoctor/ccutil build the title fine.

The output of atree can contain warnings in front of filenames that aren't documented in the README:

• R! = (infinitely) recursive include
• X! = invalid for some reason
• N! = file does not exist

The newdoc script currently uses built-in templates. These were originally based on those in the modular-docs repository, but are now outdated. Please update the templates produced by newdoc to match the official ones.

It might be nice to have an option to choose the filename splitter since it can be a hyphen or an underscore.

redhat-documentation/modular-docs#121

Most of runtimes are using all hyphens.

On line https://github.com/redhat-documentation/tools/blame/master/newdoc/newdoc/templates/assembly_title.adoc#L34 of the template, the context variable is defined. However, it is already used before that on line 28: https://github.com/redhat-documentation/tools/blame/master/newdoc/newdoc/templates/assembly_title.adoc#L28.

This causes the build to fail as aura tries to decipher moduleid_{context} instead of the actual context value that should be substituted.

Solution would be to line 34 before line 28. That is, define the context value before using it.

The other larger issue, of course, is that the templates are out of sync with the actual templates defined in the mod docs repo. Is there a way to keep these in sync?

When running newdoc in a directory that contains a file with a name same as what newdoc is attempting to create, the script crashes. It would be nice if it instead offered to overwrite or keep the existing file. E.g.:

File called 'proc_module.adoc' already exists.
(o)verwrite, (k)eep, (O)verwrite all, (K)eep all

Or something similar.

But for starters, it could just fail gracefully, listing the offending file.

@mrksu, could you please update the newdoc version to what's in https://github.com/mrksu/newdoc?

This is a request for an enhancement.

Please add the path of the directory to the file instead of include::<path>/assembly_test.adoc[leveloffset=+1]. Same regarding the script response in the terminal window.

I believe that most people run the script from the directory in which they want the file to be created. Therefore, the directory should be available to the script.

A README file needs to be added to describe the purpose and structure of the repo.

suggested changes for the procedure template:
To align with IBM style guide, instead of (Optional) use Optional: 

It would be useful to have an option for newdoc to omit the inclusion of the content governed by the internal attribute. For some upstream uses, this metadata is redundant.

The following block occurs twice in the assembly template file created when using this script. Is this necessary? There is one block near the start of the generated file and and another at the end of the generated file.

// The following line is necessary to allow assemblies be included in other
// assemblies. It restores the `context` variable to its previous state.
:parent-context-of-<my-assembly-name>: {context}