skvadrik/re2c

Add rst2c tool instead of gen_help.sh.

Closed this issue · 7 comments

skvadrik commented

Currently the way we generate help message is from the .rst sources (shared between the manpage, help message and online documentation) to an intermediate manpage, and from the intermediate manpage to a C++ literal string: doc/help.rst.in -> (configure) help.rst -> (rst2man) help.rst.1 -> (gen_help.sh) help.cc.

It is possible to simplify the process, bypass the intermediate manpage and generate C++ source code from the .rst sources directly, if we write a tool rst2c that will convert help.rst to help.cc. Then we could get rid of the man invocation and make it work on Windows without Cygwin.

sergeyklay commented

I'd like to declare some points that we may want to test during some test suite:

  • The manpage was created
  • The output of --help is not empty
  • The line width of --help output is 80
  • The --help output starts from USAGE word w/o extra lines before
  • The "footer" of the --help output does not contain extra lines
  • The content of the --help output is the same as the relevant manpage part
  • 👍1
sergeyklay commented

Just to share one of the possible solutions for testing the command output: for blackbox testing (run a command and verify the output/result) I used https://github.com/chriscool/sharness

skvadrik commented

This looks neat!

Comparing command output against the reference output will not work if the .rst sources have changed (because the output will change accordingly). This comparison will only succeed when the help is regenerated from the same sources.

Ideally we should also run spell-checker on all .rst files (with a custom dictionary), such as aspell -c. I find errors way too often when I run it manually after updating the docs. But that is a different issue and quite a bit of work on top of writing the script.

  • 👍1
idigdoug commented

I think this can be closed now, unless we want to wait for the autotools build to match.

skvadrik commented

I think this can be closed now, unless we want to wait for the autotools build to match.

We do: the two build systems should be on par, as they are both used. Now that you've done the difficult part and wrote the scripts, it's should be easy to fix autotools and get rid of the old gen_help.sh (I can take a look after merging you PRs #421 and #422).

idigdoug commented

Sounds good. I can look into it as well. Agree that it shouldn't be hard.

  • 👍1
skvadrik commented

@idigdoug fixed this in #419 and #426. Closing.