This updates config-help to have more control over how the output is written for the user. We dump config-help output for per-generator documentation, and this cleans up some cross-platform compatibility issues that might arise from tweaking the output for clarity in the target file.
Previously, we'd pipe config-help output to sed, then insert the generator name, which we then redirected to an output file. The sed syntax had to include a trailing newline so our tabbed configs would automatically become code tags in markdown. Inserting newlines into sed replacement strings doesn't work the same across platforms, mostly because of Apple's customizations to GNU programs.
This commit moves the generator name and newline insertion into the command itself. It also includes a new --output option, allowing the user to specify the output location of the config-help.
Currently, we only dump in plain-text, and it is only coincidental that
our plaintext output results in a desirable Markdown output. If
tabbed lines did not automatically convert to a code style block, some
generators like C# would end up with broken text (List<T> would become
just List, for example).
I had previously discussed extending config-help to output to other formats like asciidoc. This commit does not introduce any steps toward that end.
PR checklist
-
Read the contribution guidelines. -
Ran the shell script under ./bin/to update Petstore sample so that CIs can verify the change. (For instance, only need to run./bin/{LANG}-petstore.shand./bin/security/{LANG}-petstore.shif updating the {LANG} (e.g. php, ruby, python, etc) code generator or {LANG} client's mustache templates). Windows batch files can be found in.\bin\windows\. -
Filed the PR against the correct branch: master,3.4.x,4.0.x. Default:master. -
Copied the technical committee to review the pull request if your PR is targeting a particular programming language.
Description of the PR
(details of the change, additional tests that have been done, reference to the issue for tracking, etc)