Update README.md #197
Update README.md #197
Conversation
Added updated download options for IE CLI and fixed out of date instructions
| @@ -169,19 +170,6 @@ jobs: | |||
| python3 main.py test README.md | |||
| ``` | |||
|
|
|||
|
|
|||
| ## Use Executable Documentation for Interactive Documentation | |||
There was a problem hiding this comment.
Is interactive mode something that we're not suggesting for users to use anymore?
There was a problem hiding this comment.
It is something we're still suggesting but these details are already in the 'Modes of Operation' section
README.md
Outdated
| @@ -114,16 +106,25 @@ markdown. For example: | |||
| <!!-- | |||
| ```variables | |||
There was a problem hiding this comment.
I think we should do away with this method of declaring variables as variables declared in the codeblocks provide the best experience for both the authors of the documents and users executing the documents. This way of declaring variables is very hacky from an authoring perspective and introduces hidden state into the documents from the users perspective
There was a problem hiding this comment.
Agreed. I think we can keep the functionality but don't have to call it out here.
README.md
Outdated
| ``` | ||
|
|
||
| CLI argument variables override environment variables declared within the markdown document, | ||
| which override variables set in a .ini file, which override preexisting environment variables. |
There was a problem hiding this comment.
Same as variable comment blocks, I think we should also deprecate ini files for variable declarations. I've not seen any doc authors use these and don't think they add much value to the authoring experience, but these aren't nearly as bad as variables declared inside HTML comments.
There was a problem hiding this comment.
Another thing to note is that the INI files MUST have the same name as the scenario itself. So, if we are to keep them, we should make that abundantly clear if not already.
There was a problem hiding this comment.
I'm impartial either way, removed for now to keep things more concise. Let's keep the functionality though assuming no effort is needed to maintain it. But there is a request to expand on the ini doc to install dependencies in #152 . Although this request would also be solved by pre-reqs.
There was a problem hiding this comment.
IMO the INI file wouldn't be able to effectively solve #152 because there's no good way to resolve package names across various Linux distributions. Each distribution uses a different package management tool and each the name of the packages can be different across distributions although containing the same content as each other. Pre-requisites is definitely the preferred solution for this problem.
Updated IE installation and environment variables details. General doc formatting improvements.