redhat-documentation / tools Goto Github PK
View Code? Open in Web Editor NEWTools for making writers' lives easier.
License: GNU General Public License v3.0
Tools for making writers' lives easier.
License: GNU General Public License v3.0
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:
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}
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.