Improve help printing in the command-line runner - Redmine #666
Archive from user: Teemu Murtola
These issues should be considered:
-
Formatting of the help output should be improved. The main issue is in line wrapping, but it should also be thought about how closely we want to follow the help format from the old tools. The new option handling mechanism allows a lot of things that the old one did not, so the format could perhaps also be improved.
-
src/gromacs/options/AsciiHelpWriter.* should be renamed to something like CommandLineHelpWriter, because writing a generic help that would apply to something else than a command-line tool is probably too difficult. Separate help writers can be implemented in other contexts if needed (and common functionality refactored back to src/gromacs/options/ if the need arises).
-
It should be thought about how much of the functionality from the old wman.c is really needed, and that should be ported to the new system. It should also be possible to refactor things such that both implementations use the same underlying routines for text handling.
-
In 4.5, some help is accessible with (using g_select as an example)
g_select -h
, some withg_select -select help
and friends. In 5.0, these becomeg_ana select -h
,g_ana select -select help
, and there can additionally beg_ana -h
(see #672). It would be good to consolidate these. Also, different tools may provide the selection option under a different name than-select
, or may provide multiple options, which may make it confusing to use them for printing hel Suggestions of how it would work best for the user would be welcome. Also, how extensive should the command-line help be? An alternative is to refer to the manual or to a wiki page. If the command-line help contains a lot of information, we may want to add a script that extracts it and inserts it into the manual automatically (see #679).
(from redmine: issue id 666, created on 2011-01-14 by gmxdefault, closed on 2012-07-12)
- Relations:
- relates #642 (closed)
- relates #665 (closed)
- relates #690 (closed)
- relates #672 (closed)
- relates #679 (closed)
- relates #685 (closed)
- relates #969 (closed)
- Changesets:
- Revision 8b8f4566 by Teemu Murtola on 2012-04-18T15:21:36Z:
Renamed AsciiHelpWriter to CommandLineHelpWriter.
Kept the changes to a minimum to avoid messing the git rename detect.
Will rename/reorganize the code a bit more in a separate commit.
Also install the files, since they are documented as being part of the
public API.
IssueID #666
Change-Id: I96cf743d9364f80624ae3424c99019ae824e1520
- Revision 282d5e36 by Teemu Murtola on 2012-04-18T15:39:56Z:
More reorganization of cmdlinehelpwriter.*.
- Moved classes used in the implementation from the -impl.h header to an
anonymous namespace in the source file.
- Removed "Ascii" from the names of the moved classes.
- Changed from prefix underscore to a postfix underscore for member
variables.
- Removed unnecessary bit flags.
- Slightly changed the order of the classes.
IssueID #666
Change-Id: Iaedc803ba752753abc8943f1e82427cdc276cd13
- Revision 9f9d331b by Teemu Murtola on 2012-04-21T08:36:42Z:
Split command line parsing to separate directory.
Part of IssueID #666.
Change-Id: Ia4969f636fbf6a3b00a9859d6705fc7375f0eb36
- Revision 273c2d6d by Teemu Murtola on 2012-04-26T08:30:50Z:
Misc. option fixes.
- Fix two bugs introduced by earlier refactoring (one-liners in
optionstoragetemplate.h and cmdlinehelpwriter.cpp).
Both noticed when starting to work on #666, subsequent commits will
add tests that failed because of these.
- Added isRequired() to OptionInfo and related classes.
Needed for IssueID #666, but doing this in a separate commit to reduce
the footprint of bigger subsequent commits.
Change-Id: Ifee906fe589fd93ff259a02166c41c9b1568439c
- Revision e898bbc3 by Teemu Murtola on 2012-04-26T09:17:07Z:
Add text formatting classes.
Added classes for wrapping lines and for formatting tables, and tests
for those.
Needed for IssueID #666.
Change-Id: I7d217a01ff43d2a79aa8bc0b9ae5db6a43b14868
- Revision 0a03fb48 by Teemu Murtola on 2012-04-26T09:17:32Z:
Move string array concatenation to format.h.
- Moved code from Options::setDescription() that concatenated strings
from an array into format.h to make it more generally usable.
- Changed the code such that instead of requiring the array to be
NULL-terminated, it can also deduce the length of the array passed as
an argument.
- Made Options::setDescription() to take a simple string to allow using
the alternative overload, and also to help in writing test code
(for #666).
Change-Id: I96f45577fc6a4258a1c993983cc1d1a1a0846bdc
- Revision b514fd27 by Teemu Murtola on 2012-05-03T04:32:49Z:
Rewrote command line help writer.
- Rewrote printing code for options using TextTableFormatter. Should now
produce at least as good output as the old code invoked by
parse_common_args() while keeping most of the layout, and in some
cases does significantly better (partly because of the item below).
- Split selection options into a separate table with its own formatting
to make more space for long values that they typically have.
- Added test code that exercises different parts of the formatting code
and allows one to easily see the output (with -stdout cmd-line
parameter to the test executable). Without the -stdout parameter,
each test is marked as failed if anything in the output changes,
allowing them to work as regression tests.
- Added line wrapping for descriptions.
- Markup substitution ([TT], [PAR] etc.) is not yet done. Will add that
separately, since it requires changes to the line wrapping code to
strip some whitespace...
There are some TODOs in the code, but they mostly concern better
handling of corner or more complex cases.
IssueID #666
Change-Id: I538fbaac27572a518d24dff7b0f30f8746a540af
- Revision 6aee5224 by Teemu Murtola on 2012-05-03T04:32:50Z:
Implement markup substitution in command-line help.
Use code from wman.h, and adjust the line wrapper to strip extra
whitespace from beginning and end of lines (these are easily produced
with the combination of concatenateLines() and, e.g., [PAR] markup).
IssueID #666
Change-Id: I5413578c5fc51239b9f4dfc74387e21ac1d1c5ca
- Revision 5ef19f95 by Teemu Murtola on 2012-05-03T15:57:58Z:
Add "replace all" functionality to format.h.
Use the new function in File::readToString() to make the Windows line
end handling more robust.
Related to #666.
Change-Id: I24fc8e0dfd8af7ac08c94f2e9392fd418fe463c8
- Revision c09ab7ec by Teemu Murtola on 2012-05-03T15:57:58Z:
Replace "%t" in option descriptions with time unit.
Not sure how useful this is, but there was such functionality in the old
option listing, and it was easy to implement.
IssueID #666
Change-Id: Ib9538211fefcde7a89dceb7e1b30a81ab03d9e76
- Revision 4db1c85a by Teemu Murtola on 2012-05-03T15:57:58Z:
Remove replace.* and use replaceAll() in wman.c.
Remove old O(N^2) implementation of replacing. Instead, use the C++
version also in wman.c (switched the file to C++ compilation).
Removed unused variables from wman.c, since they give warnings with our
C++ compiler flags.
This is the first commit that introduces a real dependency from the
pre-5.0 C code to new C++ code.
Related to #666.
Change-Id: I89db3badc51775cd5c683ac7e8b1040efac16447
- Revision 4cce7c9d by Teemu Murtola on 2012-05-07T03:56:55Z:
Print default file names for command-line help.
Print the value set with defaultValueIfSet() for a file name option in
the command-line help if no other value is provided for the option.
- The value is formatted by the AbstractOptionStorage::formatValue()
pure virtual method when a special index is provided.
- OptionStorageTemplate implements handling of this special index, and
provides a new pure virtual method formatSingleValue() to do the
actual formatting, which no longer needs to know where the value comes
from.
- Adjust the concrete option storage classes to the changes.
IssueID #666.
Change-Id: I8b51262042415f314bd5d4c8da51e6e31cfe3b21
- Revision ab300758 by Teemu Murtola on 2012-05-07T10:16:23Z:
Generic handling for multiple cmd-line modules.
Added generic methods for multiple independent modules within a single
command-line tool, and modified g_ana to use this.
By itself, does not change the external behavior significantly, but
makes it easier to implement parts of #666 and #672.
The wrapper binary in #685 should also be easy to implement using this
approach.
Change-Id: I3058bf5db2cbb7c7a1f9e4c87dd2db8f9727fe82
- Revision 2ea25c76 by Teemu Murtola on 2012-05-08T05:35:26Z:
Print list of modules with 'g_ana help'.
IssueIDs #666 and #672.
Change-Id: I001966ab3ba44c59b0186456a6467322b3b3d26d
- Revision 8aef6a7c by Teemu Murtola on 2012-05-29T13:56:41Z:
Separated string formatting used only for help.
Moved string formatting routines used only in help printing to
src/gromacs/onlinehelp/ from src/gromacs/utility/format.*.
Also moved one function from cmdlinehelpwriter.cpp to the new file.
Subsequent commits will add more content to the new directory and will
use the same string formatting routines.
Added NOMINMAX define for Windows to avoid min/max macros.
Related to #666.
Change-Id: I9b52012df2fc718bc3d68c697140661a241a1467
- Revision bfdfd536 by Teemu Murtola on 2012-05-29T13:56:52Z:
Additional features to TextTableFormatter.
Add possibility to print out a table without a header (if there are no
column titles) and possibility to indent the whole table.
Use the new features for formatting the list of commands in
CommandLineModuleManager.
IssueID #666
Change-Id: I2d5aaceaf1c5545ff3be215d27ec30df38fbacde
- Revision 1440526f by Teemu Murtola on 2012-05-29T13:56:53Z:
Generic handling of online help topics.
- Added a few simple classes for handling a tree of help topics
(src/gromacs/onlinehelp/).
- Rewrote the selection help to use the new classes. Required changing
the help parser slightly to pass all requested help topics in a single
call to _gmx_sel_handle_help_cmd(). Although this changes the usage of
the help slightly, did not yet update the help texts.
- Added a way to specify the bison and flex binaries to use for
regenerate_parser.sh (useful, e.g., if multiple versions are
installed).
Related to #666.
Change-Id: I318fc0fc42e4af39734a5aa65a503582302ecdd8
- Revision 7c771f0a by Teemu Murtola on 2012-05-29T13:56:54Z:
Improve 'g_ana help'.
- 'g_ana help' now internally uses the new online help classes.
Without any additional arguments, it still prints out the list of
commands, and now also list of additional help topics.
- 'g_ana help <command>' prints help for the given command (the same as
'g_ana <command> -h' for the trajectory analysis modules).
- 'g_ana help selections <subtopic>' can be used to access the general
help for selections.
IssueID #666.
Change-Id: Id34044842b297591923bef242a93b4ae1ae9e14e
- Revision 45d74f45 by Teemu Murtola on 2012-06-13T21:52:53Z:
Updates to selection online help.
Some of the help topics were outdated after changes introduced by the
linked Redmine issues (some of them even before that). Improved the
situation a bit and also did some misc. other documentation fixes.
Related to #656 and #666.
Change-Id: I7f18ca4ad8ce2aa5cd808281bab044253ca77f56