Looks great! I think there are still a few issues with this, mainly to do with the positional arguments to the translator script.
I've started writing it up, but it went longer and longer, so perhaps it's easier to discuss it in person, and I'll reduce this text here to a summary.
There are two ways a page like this can be designed:
A) to document how to call the translator stand-alone
B) to document how to set translator options from within the driver script
The page is currently called "translator usage", which suggests A, but the way it's described follows B more. I will assume that the intention was B. Different comments would apply from A. We could also do A and explain how to do B based on the documentation of A.
A and B are similar, but also different (for example regarding argument order, how to use --help, whether the domain file name is optional).
For the stand-alone translator package that we also discussed, we also want something like A, so perhaps we should also think in the discussion how we want to support that in the future.
The docs currently contain a bunch of things that lean into A rather than B, plus some other small things that perhaps would be good to change:
- The page title ("translator usage", parallel to "planner usage") suggests A, not B, also in the navigation bar.
- The page contains a usage string for using fast-downward.py to call the translator. In this context usage strings are meant to be comprehensive, but it isn't because one would often want driver options as well (time/memory limits). One way to address this, which would also address the points below regarding positional variables, is to do more of B rather than A and not include a comprehensive usage, only document the options. We could still include example invocations afterwards, as in the fast-downward.py docs.
- The positional arguments are described, but they are driver arguments, not translator options, and already described on the planner usage page and the help text of fast-downward.py.
- There is confusion between options and positional arguments; the positional arguments are described under "options". In the usual lingo in the argument parsing world, something like "domain" here is not an option, although it is an argument.
- The usage string uses the wrong positional argument names:
./fast-downward.py --translate [domain] problem [--translate-options OPTIONS]
But then the help text doesn't define "problem" and instead defines "task".
- preexisting issue: looks like the translator doesn't follow the same conventions as fast-downward.py for the positional arguments (lower-case vs. upper-case for the metavariable). I think the usual solution would be uppercase.
- The "--help" option behaves in an unusual way. The expectation should probably be that you don't need to specify PDDL files with "--translate-options --help", but you do when calling the translator through the driver script. I think this can trip people up and would be worth adding to examples or something.
- The documentation of "--help" ("print this help message and exit") isn't quite right because the translator prints a quite different usage string.
- I think it's a bit strange for us to document the translator options on the web page in this way, but not document fast-downward.py itself where we instead say "run ./fast-downward.py --help". Perhaps we should open a follow-up issue on this.
|