From: Teemu Murtola Date: Thu, 23 Apr 2015 10:31:22 +0000 (+0300) Subject: Update help output X-Git-Url: http://biod.pnpi.spb.ru/gitweb/?a=commitdiff_plain;h=867ea01d072d64bbee718fc23dcf47bccb8ef93f;p=alexxy%2Fgromacs.git Update help output Various changes to console help output (and some to man output) based on feedback in #1687: - People seem to prefer a centered startup header with some ASCII art, so made the first output line just like that (except if running with -quiet), and center the list of authors. - Always start the option description at a new line. - Give more space to various parts of the option list so that they are more likely to align up. - Split the file listing based on input/output type. This causes, e.g., some logically related options (e.g., -cpi and -cpo) to get separated in the output, but this seems to be the preferred approach. - Add formatting to the synopsis on man pages (similar to how the options appeared in the 4.6-era man pages, except that reasonable line wrapping is still there). Clean up the design for formatting the options list; now the actual formatting code is better encapsulated in HelpWriterContext. The user-visible scope of this change is limited to changing behavior that changed between 4.6 and 5.0. Thus, the changes here should be sufficient to close #1687. Change-Id: I349fd9021472f064f5797441090a3f3864868280 --- diff --git a/src/gromacs/commandline/cmdlinehelpwriter.cpp b/src/gromacs/commandline/cmdlinehelpwriter.cpp index 788991565a..addc8c8361 100644 --- a/src/gromacs/commandline/cmdlinehelpwriter.cpp +++ b/src/gromacs/commandline/cmdlinehelpwriter.cpp @@ -51,7 +51,6 @@ #include #include "gromacs/commandline/cmdlinehelpcontext.h" -#include "gromacs/onlinehelp/helpformat.h" #include "gromacs/onlinehelp/helpwritercontext.h" #include "gromacs/options/basicoptions.h" #include "gromacs/options/filenameoption.h" @@ -174,7 +173,9 @@ class OptionsFilter : public OptionsVisitor //! Specifies the type of output that formatSelected() produces. enum FilterType { - eSelectFileOptions, + eSelectInputFileOptions, + eSelectInputOutputFileOptions, + eSelectOutputFileOptions, eSelectOtherOptions }; @@ -233,9 +234,26 @@ void OptionsFilter::visitOption(const OptionInfo &option) { return; } - if (option.isType()) + const FileNameOptionInfo *const fileOption = option.toType(); + if (fileOption != NULL && fileOption->isInputFile()) + { + if (filterType_ == eSelectInputFileOptions) + { + formatter_->formatOption(option); + } + return; + } + if (fileOption != NULL && fileOption->isInputOutputFile()) + { + if (filterType_ == eSelectInputOutputFileOptions) + { + formatter_->formatOption(option); + } + return; + } + if (fileOption != NULL && fileOption->isOutputFile()) { - if (filterType_ == eSelectFileOptions) + if (filterType_ == eSelectOutputFileOptions) { formatter_->formatOption(option); } @@ -323,25 +341,17 @@ std::string fileOptionFlagsAsString(const FileNameOptionInfo &option, bool bAbbrev) { std::string type; - if (option.isInputOutputFile()) - { - type = bAbbrev ? "In/Out" : "Input/Output"; - } - else if (option.isInputFile()) - { - type = "Input"; - } - else if (option.isOutputFile()) - { - type = "Output"; - } if (!option.isRequired()) { - type += bAbbrev ? ", Opt." : ", Optional"; + type = bAbbrev ? "Opt." : "Optional"; } if (option.isLibraryFile()) { - type += bAbbrev ? ", Lib." : ", Library"; + if (!type.empty()) + { + type.append(", "); + } + type.append(bAbbrev ? "Lib." : "Library"); } return type; } @@ -377,7 +387,8 @@ class SynopsisFormatter : public OptionsFormatterInterface public: //! Creates a helper object for formatting the synopsis. explicit SynopsisFormatter(const HelpWriterContext &context) - : context_(context), lineLength_(0), indent_(0), currentLength_(0) + : context_(context), bFormatted_(false), lineLength_(0), indent_(0), + currentLength_(0) { } @@ -390,6 +401,7 @@ class SynopsisFormatter : public OptionsFormatterInterface private: const HelpWriterContext &context_; + bool bFormatted_; int lineLength_; int indent_; int currentLength_; @@ -409,9 +421,10 @@ void SynopsisFormatter::start(const char *name) file.writeString(name); break; case eHelpOutputFormat_Rst: + bFormatted_ = true; lineLength_ = 74; indent_ += 4; - file.writeLine("::"); + file.writeLine(".. parsed-literal::"); file.writeLine(); file.writeString(" "); file.writeString(name); @@ -432,14 +445,16 @@ void SynopsisFormatter::formatOption(const OptionInfo &option) { std::string name, value; formatOptionNameAndValue(option, &name, &value); - std::string fullOptionText(" [-" + name); + int totalLength = name.length() + 4; + std::string fullOptionText + = formatString(" [%s-%s", bFormatted_ ? ":strong:`" : "", name.c_str()); if (!value.empty()) { - fullOptionText.append(" "); + fullOptionText.append(bFormatted_ ? "` :emphasis:`" : " "); fullOptionText.append(value); + totalLength += value.length() + 1; } - fullOptionText.append("]"); - const int totalLength = fullOptionText.size(); + fullOptionText.append(bFormatted_ ? "`]" : "]"); File &file = context_.outputFile(); currentLength_ += totalLength; @@ -506,7 +521,6 @@ class OptionsListFormatter : public OptionsFormatterInterface const HelpWriterContext &context_; const CommonFormatterData &common_; - boost::scoped_ptr consoleFormatter_; const char *title_; const char *header_; bool bDidOutput_; @@ -521,63 +535,23 @@ OptionsListFormatter::OptionsListFormatter( : context_(context), common_(common), title_(title), header_(NULL), bDidOutput_(false) { - if (context.outputFormat() == eHelpOutputFormat_Console) - { - consoleFormatter_.reset(new TextTableFormatter()); - consoleFormatter_->setFirstColumnIndent(1); - consoleFormatter_->setFoldLastColumnToNextLine(4); - consoleFormatter_->addColumn(NULL, 6, false); - consoleFormatter_->addColumn(NULL, 8, false); - consoleFormatter_->addColumn(NULL, 10, false); - consoleFormatter_->addColumn(NULL, 50, true); - } } void OptionsListFormatter::formatOption(const OptionInfo &option) { writeSectionStartIfNecessary(); - std::string name, value; + std::string name, value; formatOptionNameAndValue(option, &name, &value); - std::string defaultValue(defaultOptionValue(option)); - std::string info; - if (!defaultValue.empty()) - { - info = "(" + defaultValue + ")"; - } + std::string defaultValue(defaultOptionValue(option)); + std::string info; const FileNameOptionInfo *fileOption = option.toType(); if (fileOption != NULL) { const bool bAbbrev = (context_.outputFormat() == eHelpOutputFormat_Console); - if (!info.empty()) - { - info.append(" "); - } - info.append("("); - info.append(fileOptionFlagsAsString(*fileOption, bAbbrev)); - info.append(")"); + info = fileOptionFlagsAsString(*fileOption, bAbbrev); } std::string description(descriptionWithOptionDetails(common_, option)); - if (context_.outputFormat() == eHelpOutputFormat_Console) - { - consoleFormatter_->clear(); - consoleFormatter_->addColumnLine(0, "-" + name); - consoleFormatter_->addColumnLine(1, value); - if (!info.empty()) - { - consoleFormatter_->addColumnLine(2, info); - } - consoleFormatter_->addColumnHelpTextBlock(3, context_, description); - context_.outputFile().writeString(consoleFormatter_->formatRow()); - } - else - { - if (!info.empty()) - { - value.append(" "); - value.append(info); - } - context_.writeOptionItem("-" + name, value, description); - } + context_.writeOptionItem("-" + name, value, defaultValue, info, description); } //! \} @@ -684,7 +658,11 @@ void CommandLineHelpWriter::writeHelp(const CommandLineHelpContext &context) writerContext.writeTitle("Synopsis"); SynopsisFormatter synopsisFormatter(writerContext); synopsisFormatter.start(context.moduleDisplayName()); - filter.formatSelected(OptionsFilter::eSelectFileOptions, + filter.formatSelected(OptionsFilter::eSelectInputFileOptions, + &synopsisFormatter, impl_->options_); + filter.formatSelected(OptionsFilter::eSelectInputOutputFileOptions, + &synopsisFormatter, impl_->options_); + filter.formatSelected(OptionsFilter::eSelectOutputFileOptions, &synopsisFormatter, impl_->options_); filter.formatSelected(OptionsFilter::eSelectOtherOptions, &synopsisFormatter, impl_->options_); @@ -698,11 +676,19 @@ void CommandLineHelpWriter::writeHelp(const CommandLineHelpContext &context) } CommonFormatterData common(impl_->timeUnit_.c_str()); OptionsListFormatter formatter(writerContext, common, "Options"); - formatter.startSection("Options to specify input and output files:[PAR]"); - filter.formatSelected(OptionsFilter::eSelectFileOptions, + formatter.startSection("Options to specify input files:"); + filter.formatSelected(OptionsFilter::eSelectInputFileOptions, + &formatter, impl_->options_); + formatter.finishSection(); + formatter.startSection("Options to specify input/output files:"); + filter.formatSelected(OptionsFilter::eSelectInputOutputFileOptions, + &formatter, impl_->options_); + formatter.finishSection(); + formatter.startSection("Options to specify output files:"); + filter.formatSelected(OptionsFilter::eSelectOutputFileOptions, &formatter, impl_->options_); formatter.finishSection(); - formatter.startSection("Other options:[PAR]"); + formatter.startSection("Other options:"); filter.formatSelected(OptionsFilter::eSelectOtherOptions, &formatter, impl_->options_); formatter.finishSection(); diff --git a/src/gromacs/commandline/tests/refdata/CommandLineHelpModuleTest_ExportsHelp.xml b/src/gromacs/commandline/tests/refdata/CommandLineHelpModuleTest_ExportsHelp.xml index b2612d7fb7..3bed43d174 100644 --- a/src/gromacs/commandline/tests/refdata/CommandLineHelpModuleTest_ExportsHelp.xml +++ b/src/gromacs/commandline/tests/refdata/CommandLineHelpModuleTest_ExportsHelp.xml @@ -37,9 +37,9 @@ test module =========== Synopsis -------- -:: +.. parsed-literal:: - test module [-int ] + test module [:strong:`-int` :emphasis:``] Description ----------- @@ -70,7 +70,7 @@ test other ========== Synopsis -------- -:: +.. parsed-literal:: test other diff --git a/src/gromacs/commandline/tests/refdata/CommandLineHelpModuleTest_PrintsGeneralHelp.xml b/src/gromacs/commandline/tests/refdata/CommandLineHelpModuleTest_PrintsGeneralHelp.xml index b8c655d7fa..6820ba327e 100644 --- a/src/gromacs/commandline/tests/refdata/CommandLineHelpModuleTest_PrintsGeneralHelp.xml +++ b/src/gromacs/commandline/tests/refdata/CommandLineHelpModuleTest_PrintsGeneralHelp.xml @@ -11,12 +11,18 @@ OPTIONS Other options: - -[no]h (no) Print help and quit - -[no]quiet (no) Do not print common startup info or quotes - -[no]version (no) Print extended version information and quit - -[no]copyright (yes) Print copyright information on startup - -nice (19) Set the nicelevel (default depends on command) - -[no]backup (yes) Write backups if output files exist + -[no]h (no) + Print help and quit + -[no]quiet (no) + Do not print common startup info or quotes + -[no]version (no) + Print extended version information and quit + -[no]copyright (yes) + Print copyright information on startup + -nice (19) + Set the nicelevel (default depends on command) + -[no]backup (yes) + Write backups if output files exist Additional help is available on the following topics: commands List of available commands diff --git a/src/gromacs/commandline/tests/refdata/CommandLineHelpWriterTest_HandlesLongFileOptions.xml b/src/gromacs/commandline/tests/refdata/CommandLineHelpWriterTest_HandlesLongFileOptions.xml index 8ac10f83fe..86a8aadf4d 100644 --- a/src/gromacs/commandline/tests/refdata/CommandLineHelpWriterTest_HandlesLongFileOptions.xml +++ b/src/gromacs/commandline/tests/refdata/CommandLineHelpWriterTest_HandlesLongFileOptions.xml @@ -9,18 +9,19 @@ gmx [-f [<.xtc/.trr/...>]] [-f2 [<.xtc/.trr/...>]] [-lib [<.xtc/.trr/...>]] OPTIONS -Options to specify input and output files: +Options to specify input files: - -f [<.xtc/.trr/...>] (path/to/long/trajectory/name.xtc) (Input) - File name option with a long value: xtc trr cpt gro g96 pdb tng - -f2 [<.xtc/.trr/...>] (path/to/long/trajectory.xtc) (Input) - File name option with a long value: xtc trr cpt gro g96 pdb tng - -lib [<.xtc/.trr/...>] (path/to/long/trajectory/name.xtc) (Input, Opt., Lib.) - File name option with a long value and type: xtc trr cpt gro g96 pdb tng - -longfileopt [<.dat>] (deffile.dat) (Input, Opt.) - File name option with a long name - -longfileopt2 [<.dat>] (path/to/long/file/name.dat) (Input, Opt., Lib.) - File name option with multiple long fields + -f [<.xtc/.trr/...>] (path/to/long/trajectory/name.xtc) + File name option with a long value: xtc trr cpt gro g96 pdb tng + -f2 [<.xtc/.trr/...>] (path/to/long/trajectory.xtc) + File name option with a long value: xtc trr cpt gro g96 pdb tng + -lib [<.xtc/.trr/...>] (path/to/long/trajectory/name.xtc) (Opt., Lib.) + File name option with a long value and type: xtc trr cpt gro g96 + pdb tng + -longfileopt [<.dat>] (deffile.dat) (Opt.) + File name option with a long name + -longfileopt2 [<.dat>] (path/to/long/file/name.dat) (Opt., Lib.) + File name option with multiple long fields ]]> diff --git a/src/gromacs/commandline/tests/refdata/CommandLineHelpWriterTest_HandlesLongOptions.xml b/src/gromacs/commandline/tests/refdata/CommandLineHelpWriterTest_HandlesLongOptions.xml index 92805bff8e..186f79e921 100644 --- a/src/gromacs/commandline/tests/refdata/CommandLineHelpWriterTest_HandlesLongOptions.xml +++ b/src/gromacs/commandline/tests/refdata/CommandLineHelpWriterTest_HandlesLongOptions.xml @@ -10,11 +10,13 @@ OPTIONS Other options: - -[no]longboolean (yes) Boolean option with a long name - -dvec (1.135 2.32 3.2132) Double vector option - -string (A very long string value that overflows even the description column Another very long string value that overflows even the description column) - String option with very long values (may be less relevant with selections - having their own option type) + -[no]longboolean (yes) + Boolean option with a long name + -dvec (1.135 2.32 3.2132) + Double vector option + -string (A very long string value that overflows even the description column Another very long string value that overflows even the description column) + String option with very long values (may be less relevant with + selections having their own option type) ]]> diff --git a/src/gromacs/commandline/tests/refdata/CommandLineHelpWriterTest_HandlesMultipleSections.xml b/src/gromacs/commandline/tests/refdata/CommandLineHelpWriterTest_HandlesMultipleSections.xml index 57f8bcf19d..baa4db0047 100644 --- a/src/gromacs/commandline/tests/refdata/CommandLineHelpWriterTest_HandlesMultipleSections.xml +++ b/src/gromacs/commandline/tests/refdata/CommandLineHelpWriterTest_HandlesMultipleSections.xml @@ -20,9 +20,12 @@ OPTIONS Other options: - -sub1 Option in subsection 1 - -sub2 Option in subsection 2 - -main Option in main section + -sub1 + Option in subsection 1 + -sub2 + Option in subsection 2 + -main + Option in main section ]]> diff --git a/src/gromacs/commandline/tests/refdata/CommandLineHelpWriterTest_HandlesOptionTypes.xml b/src/gromacs/commandline/tests/refdata/CommandLineHelpWriterTest_HandlesOptionTypes.xml index d60500d2bf..a3e570b815 100644 --- a/src/gromacs/commandline/tests/refdata/CommandLineHelpWriterTest_HandlesOptionTypes.xml +++ b/src/gromacs/commandline/tests/refdata/CommandLineHelpWriterTest_HandlesOptionTypes.xml @@ -11,27 +11,45 @@ gmx [-f [<.xtc/.trr/...>]] [-mult [<.xtc/.trr/...> [...]]] [-lib [<.dat>]] OPTIONS -Options to specify input and output files: +Options to specify input files: - -f [<.xtc/.trr/...>] (traj.xtc) (Input) - Input file description: xtc trr cpt gro g96 pdb tng - -mult [<.xtc/.trr/...> [...]] (traj.xtc) (Input, Opt.) - Multiple file description: xtc trr cpt gro g96 pdb tng - -lib [<.dat>] (libdata.dat) (Input, Opt., Lib.) Library file description - -io [<.dat>] (inout.dat) (In/Out, Opt.) Input/Output file description - -o <.xvg> (Output, Opt.) Output file description + -f [<.xtc/.trr/...>] (traj.xtc) + Input file description: xtc trr cpt gro g96 pdb tng + -mult [<.xtc/.trr/...> [...]] (traj.xtc) (Opt.) + Multiple file description: xtc trr cpt gro g96 pdb tng + -lib [<.dat>] (libdata.dat) (Opt., Lib.) + Library file description + +Options to specify input/output files: + + -io [<.dat>] (inout.dat) (Opt.) + Input/Output file description + +Options to specify output files: + + -o <.xvg> (Opt.) + Output file description Other options: - -[no]bool (yes) Boolean option - -[no]hidden (yes) Hidden option - -int (2) Integer option - -ivec (1 2 3) Integer vector option - -double (2.5) Double option - -dvec (1.1 2.3 3.2) Double vector option - -time