From 62306b648487ec9e7345507a17d9927eada0b9e9 Mon Sep 17 00:00:00 2001 From: Teemu Murtola Date: Sat, 30 May 2015 09:24:31 +0300 Subject: [PATCH] Replace gromacs.7 man page with gmx.1 The description is the same, and the command list is there, but other content is omitted. Useful parts can be added back later, when it is clearer what we want to include here. Also, the man page now contains a synopsis and common options for the gmx binary, as is suitable for gmx.1. Part of #1437. Change-Id: I4dbdf542dd2b8a0a7a2e734eebdf13d68483842e --- docs/CMakeLists.txt | 2 +- docs/man/.gitignore | 2 - docs/man/gromacs.7.rst | 68 --------- src/gromacs/commandline/cmdlinehelpmodule.cpp | 136 ++++++++++++------ .../CommandLineHelpModuleTest_ExportsHelp.xml | 62 ++++++-- 5 files changed, 146 insertions(+), 124 deletions(-) delete mode 100644 docs/man/.gitignore delete mode 100644 docs/man/gromacs.7.rst diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 9f48109107..f2a3809d31 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -120,7 +120,6 @@ if (SPHINX_FOUND) dev-manual/tools.rst dev-manual/uncrustify.rst install-guide/index.rst - man/gromacs.7.rst user-guide/index.rst user-guide/getting-started.rst user-guide/flow.rst @@ -175,6 +174,7 @@ if (SPHINX_FOUND) # TODO: Make this remove obsolete .rst files. gmx_add_custom_output_target(sphinx-programs OUTPUT STAMP COMMAND ${CMAKE_COMMAND} -E make_directory programs + COMMAND ${CMAKE_COMMAND} -E make_directory man COMMAND gmx -quiet help -export rst DEPENDS gmx WORKING_DIRECTORY ${SPHINX_INPUT_DIR} diff --git a/docs/man/.gitignore b/docs/man/.gitignore deleted file mode 100644 index a0e7b5c1cb..0000000000 --- a/docs/man/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -man1 -man7/gromacs.7 diff --git a/docs/man/gromacs.7.rst b/docs/man/gromacs.7.rst deleted file mode 100644 index 5dd753ba0e..0000000000 --- a/docs/man/gromacs.7.rst +++ /dev/null @@ -1,68 +0,0 @@ -:orphan: - -GROMACS -======= - -Description ------------ - -**GROMACS** is a full-featured suite of programs to perform molecular dynamics -simulations - in other words, to simulate the behavior of systems with hundreds -to millions of particles, using Newtonian equations of motion. -It is primarily used for research on proteins, lipids, and polymers, but can be -applied to a wide variety of chemical and biological research questions. - -Synopsis --------- - -The following commands make up the GROMACS suite. Please refer to their -individual man pages for further details. - -.. include:: bytopic.rst - -Additional documentation ------------------------- - -Consult the manual at for an introduction to molecular -dynamics in general and GROMACS in particular, as well as an overview of the -individual programs. - -References ----------- - -The development of GROMACS is mainly funded by academic research grants. -To help us fund development, the authors humbly ask that you cite the GROMACS papers: - -H.J.C. Berendsen, D. van der Spoel and R. van Drunen. **GROMACS: A message-passing -parallel molecular dynamics implementation**. Comp. Phys. Comm. *91*, 43-56 (1995) - -Erik Lindahl, Berk Hess and David van der Spoel. **GROMACS 3.0: A package for -molecular simulation and trajectory analysis**. J. Mol. Mod. *7*, 306-317 (2001) - -B. Hess, C. Kutzner, D. van der Spoel, and E. Lindahl. **GROMACS 4: Algorithms for -Highly Efficient, Load-Balanced, and Scalable Molecular Simulation**. -J. Chem. Theory Comput. *4*, 3, 435-447 (2008), - - -Authors -------- - -Current developers: - -David van der Spoel -Berk Hess -Erik Lindahl - -A full list of present and former contributors -is available at - -This manual page is largely based on the GROMACS online reference, and the text -was prepared originally by Nicholas Breen . - -Bugs ----- - -GROMACS has no major known bugs, but be warned that it stresses your CPU more -than most software. Systems with slightly flaky hardware may prove unreliable -while running heavy-duty simulations. If at all possible, please try to -reproduce bugs on another machine before reporting them. diff --git a/src/gromacs/commandline/cmdlinehelpmodule.cpp b/src/gromacs/commandline/cmdlinehelpmodule.cpp index e32e337cb2..db58fec104 100644 --- a/src/gromacs/commandline/cmdlinehelpmodule.cpp +++ b/src/gromacs/commandline/cmdlinehelpmodule.cpp @@ -57,6 +57,7 @@ #include "gromacs/onlinehelp/helpwritercontext.h" #include "gromacs/options/basicoptions.h" #include "gromacs/options/options.h" +#include "gromacs/utility/arrayref.h" #include "gromacs/utility/baseversion.h" #include "gromacs/utility/exceptions.h" #include "gromacs/utility/file.h" @@ -88,7 +89,7 @@ class CommandLineHelpModuleImpl const CommandLineModuleMap &modules, const CommandLineModuleGroupList &groups); - void exportHelp(HelpExportInterface *exporter) const; + void exportHelp(HelpExportInterface *exporter); boost::scoped_ptr rootTopic_; const ProgramContextInterface &programContext_; @@ -188,22 +189,29 @@ class HelpExportInterface struct RootHelpText { - static const char name[]; static const char title[]; static const char *const text[]; }; -// The first two are not used. -const char RootHelpText::name[] = ""; -const char RootHelpText::title[] = ""; -const char *const RootHelpText::text[] = { "" }; +// These are used for the gmx.1 man page. +// TODO: Do not hardcode them here, but pass them from the outside to make this +// code more generic. +const char RootHelpText::title[] = "molecular dynamics simulation suite"; +const char *const RootHelpText::text[] = { + "|Gromacs| is a full-featured suite of programs to perform molecular", + "dynamics simulations, i.e., to simulate the behavior of systems with", + "hundreds to millions of particles using Newtonian equations of motion.", + "It is primarily used for research on proteins, lipids, and polymers, but", + "can be applied to a wide variety of chemical and biological research", + "questions.", +}; /*! \brief * Help topic that forms the root of the help tree for the help subcommand. * * \ingroup module_commandline */ -class RootHelpTopic : public CompositeHelpTopic +class RootHelpTopic : public AbstractCompositeHelpTopic { public: /*! \brief @@ -216,6 +224,9 @@ class RootHelpTopic : public CompositeHelpTopic { } + virtual const char *name() const { return helpModule_.binaryName_.c_str(); } + virtual const char *title() const { return title_.c_str(); } + //! Adds a top-level topic and optionally marks it as exported. void addTopic(HelpTopicPointer topic, bool bExported) { @@ -226,18 +237,22 @@ class RootHelpTopic : public CompositeHelpTopic addSubTopic(move(topic)); } //! Exports all the top-level topics with the given exporter. - void exportHelp(HelpExportInterface *exporter) const; + void exportHelp(HelpExportInterface *exporter); virtual void writeHelp(const HelpWriterContext &context) const; private: + // unused because of the writeHelp() override + virtual std::string helpText() const { return ""; } + const CommandLineHelpModuleImpl &helpModule_; + std::string title_; std::vector exportedTopics_; GMX_DISALLOW_COPY_AND_ASSIGN(RootHelpTopic); }; -void RootHelpTopic::exportHelp(HelpExportInterface *exporter) const +void RootHelpTopic::exportHelp(HelpExportInterface *exporter) { std::vector::const_iterator topicName; for (topicName = exportedTopics_.begin(); @@ -248,33 +263,55 @@ void RootHelpTopic::exportHelp(HelpExportInterface *exporter) const GMX_RELEASE_ASSERT(topic != NULL, "Exported help topic no longer found"); exporter->exportTopic(*topic); } + // For now, the title is only set for the export to make it not appear in + // console output, which makes things consistent for 'gmx help' and + // 'gmx help '. + title_ = RootHelpText::title; + exporter->exportTopic(*this); } void RootHelpTopic::writeHelp(const HelpWriterContext &context) const { - if (context.outputFormat() != eHelpOutputFormat_Console) - { - // TODO: Implement once the situation with Redmine issue #969 is more - // clear. - GMX_THROW(NotImplementedError( - "Root help is not implemented for this output format")); - } { - CommandLineCommonOptionsHolder optionsHolder; - CommandLineHelpContext cmdlineContext(*helpModule_.context_); - cmdlineContext.setModuleDisplayName(helpModule_.binaryName_); + CommandLineCommonOptionsHolder optionsHolder; + boost::scoped_ptr cmdlineContext; + if (helpModule_.context_ != NULL) + { + cmdlineContext.reset(new CommandLineHelpContext(*helpModule_.context_)); + } + else + { + cmdlineContext.reset(new CommandLineHelpContext(context)); + } + cmdlineContext->setModuleDisplayName(helpModule_.binaryName_); optionsHolder.initOptions(); + Options &options = *optionsHolder.options(); + options.setDescription(RootHelpText::text); // TODO: Add [] into the synopsis. - CommandLineHelpWriter(*optionsHolder.options()) - .writeHelp(cmdlineContext); + CommandLineHelpWriter(options) + .setShowDescriptions(context.outputFormat() != eHelpOutputFormat_Console) + .writeHelp(*cmdlineContext); + } + if (context.outputFormat() == eHelpOutputFormat_Console) + { + // TODO: Consider printing a list of "core" commands. Would require someone + // to determine such a set... + writeSubTopicList(context, + "Additional help is available on the following topics:"); + // TODO: Make these respect the binary name passed in, to make tests work better. + context.writeTextBlock("To access the help, use '[PROGRAM] help '."); + context.writeTextBlock("For help on a command, use '[PROGRAM] help '."); + } + else + { + context.writeTitle(formatString("%s commands", helpModule_.binaryName_.c_str())); + context.writeTextBlock( + "The following commands are available. Please refer to their " + "individual man pages or [TT][PROGRAM] help [tt] " + "for further details."); + context.writeTextBlock(""); + context.writeTextBlock(".. include:: /man/bytopic.rst"); } - // TODO: Consider printing a list of "core" commands. Would require someone - // to determine such a set... - writeSubTopicList(context, - "Additional help is available on the following topics:"); - // TODO: Make these respect the binary name passed in, to make tests work better. - context.writeTextBlock("To access the help, use '[PROGRAM] help '."); - context.writeTextBlock("For help on a command, use '[PROGRAM] help '."); } /******************************************************************** @@ -472,6 +509,7 @@ class HelpExportReStructuredText : public HelpExportInterface private: FileOutputRedirectorInterface *outputRedirector_; + const std::string &binaryName_; HelpLinks links_; boost::scoped_ptr indexFile_; boost::scoped_ptr manPagesFile_; @@ -480,6 +518,7 @@ class HelpExportReStructuredText : public HelpExportInterface HelpExportReStructuredText::HelpExportReStructuredText( const CommandLineHelpModuleImpl &helpModule) : outputRedirector_(helpModule.outputRedirector_), + binaryName_(helpModule.binaryName_), links_(eHelpOutputFormat_Rst) { File linksFile("links.dat", "r"); @@ -515,7 +554,7 @@ void HelpExportReStructuredText::exportModuleHelp( // This would make Sphinx reruns much faster. File file(outputRedirector_->openFileForWriting("programs/" + tag + ".rst")); file.writeLine(formatString(".. _%s:", displayName.c_str())); - if (0 == displayName.compare("gmx mdrun")) + if (0 == displayName.compare(binaryName_ + " mdrun")) { // Make an extra link target for the convenience of // MPI-specific documentation @@ -534,7 +573,7 @@ void HelpExportReStructuredText::exportModuleHelp( file.writeLine(" See also"); file.writeLine(" --------"); file.writeLine(); - file.writeLine(" :manpage:`gromacs(7)`"); + file.writeLine(formatString(" :manpage:`%s(1)`", binaryName_.c_str())); file.writeLine(); file.writeLine(" More information about |Gromacs| is available at ."); file.close(); @@ -551,7 +590,11 @@ void HelpExportReStructuredText::finishModuleExport() { indexFile_->close(); indexFile_.reset(); - manPagesFile_->writeLine(" ('man/gromacs.7', 'gromacs', 'molecular dynamics simulation suite', '', 7)"); + // TODO: Generalize. + manPagesFile_->writeLine( + formatString(" ('programs/%s', '%s', '%s', '', 1)", + binaryName_.c_str(), binaryName_.c_str(), + RootHelpText::title)); manPagesFile_->writeLine("]"); manPagesFile_->close(); manPagesFile_.reset(); @@ -574,7 +617,7 @@ void HelpExportReStructuredText::exportModuleGroup( indexFile_->writeLine(title); indexFile_->writeLine(std::string(std::strlen(title), '-')); manPagesFile_->writeLine(title); - manPagesFile_->writeLine(std::string(std::strlen(title), '+')); + manPagesFile_->writeLine(std::string(std::strlen(title), '^')); ModuleGroupContents::const_iterator module; for (module = modules.begin(); module != modules.end(); ++module) @@ -590,8 +633,8 @@ void HelpExportReStructuredText::exportModuleGroup( indexFile_->writeLine(formatString("| :doc:`%s <%s>` - %s", displayName.c_str(), tag.c_str(), module->second)); - manPagesFile_->writeLine(formatString("| ``%s`` - %s", - displayName.c_str(), + manPagesFile_->writeLine(formatString(":manpage:`%s(1)`\n %s", + tag.c_str(), module->second)); } indexFile_->writeLine(); @@ -611,6 +654,11 @@ void HelpExportReStructuredText::exportTopic(const HelpTopicInterface &topic) const std::string path("programs/" + std::string(topic.name()) + ".rst"); File file(outputRedirector_->openFileForWriting(path)); HelpWriterContext context(&file, eHelpOutputFormat_Rst, &links_); + if (topic.name() == binaryName_) + { + context.writeTextBlock(":orphan:"); + context.writeTextBlock(""); + } HelpManager manager(topic, context); manager.writeCurrentTopic(); } @@ -701,7 +749,7 @@ CommandLineHelpModuleImpl::CommandLineHelpModuleImpl( { } -void CommandLineHelpModuleImpl::exportHelp(HelpExportInterface *exporter) const +void CommandLineHelpModuleImpl::exportHelp(HelpExportInterface *exporter) { // TODO: Would be nicer to have the file names supplied by the build system // and/or export a list of files from here. @@ -807,22 +855,20 @@ int CommandLineHelpModule::run(int argc, char *argv[]) return 0; } - File &outputFile = impl_->outputRedirector_->standardOutput(); - HelpLinks links(eHelpOutputFormat_Console); + File &outputFile = impl_->outputRedirector_->standardOutput(); + HelpLinks links(eHelpOutputFormat_Console); initProgramLinks(&links, *impl_); - boost::scoped_ptr context( - new CommandLineHelpContext(&outputFile, - eHelpOutputFormat_Console, &links)); - context->setShowHidden(impl_->bHidden_); + CommandLineHelpContext context(&outputFile, eHelpOutputFormat_Console, &links); + context.setShowHidden(impl_->bHidden_); if (impl_->moduleOverride_ != NULL) { - context->setModuleDisplayName(impl_->programContext_.displayName()); - impl_->moduleOverride_->writeHelp(*context); + context.setModuleDisplayName(impl_->programContext_.displayName()); + impl_->moduleOverride_->writeHelp(context); return 0; } - impl_->context_ = context.get(); + impl_->context_ = &context; - HelpManager helpManager(*impl_->rootTopic_, context->writerContext()); + HelpManager helpManager(*impl_->rootTopic_, context.writerContext()); try { for (int i = 1; i < argc; ++i) diff --git a/src/gromacs/commandline/tests/refdata/CommandLineHelpModuleTest_ExportsHelp.xml b/src/gromacs/commandline/tests/refdata/CommandLineHelpModuleTest_ExportsHelp.xml index 7ad92f536e..dbb0ffa7ca 100644 --- a/src/gromacs/commandline/tests/refdata/CommandLineHelpModuleTest_ExportsHelp.xml +++ b/src/gromacs/commandline/tests/refdata/CommandLineHelpModuleTest_ExportsHelp.xml @@ -13,7 +13,7 @@ man_pages = [ ('programs/test-help', 'test-help', "Print help information", '', 1), ('programs/test-module', 'test-module', "First module", '', 1), ('programs/test-other', 'test-other', "Second module", '', 1), - ('man/gromacs.7', 'gromacs', 'molecular dynamics simulation suite', '', 7) + ('programs/test', 'test', 'molecular dynamics simulation suite', '', 1) ] ]]> . ]]> @@ -60,7 +60,7 @@ Other options: See also -------- - :manpage:`gromacs(7)` + :manpage:`test(1)` More information about |Gromacs| is available at . ]]> @@ -81,7 +81,7 @@ Synopsis See also -------- - :manpage:`gromacs(7)` + :manpage:`test(1)` More information about |Gromacs| is available at . ]]> @@ -99,12 +99,14 @@ Group 2 ]]> + ] + [-[no]backup] + +Description +----------- +|Gromacs| is a full-featured suite of programs to perform molecular +dynamics simulations, i.e., to simulate the behavior of systems with +hundreds to millions of particles using Newtonian equations of motion. +It is primarily used for research on proteins, lipids, and polymers, but +can be applied to a wide variety of chemical and biological research +questions. + +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 + +test commands +------------- +The following commands are available. Please refer to their individual man pages or ``commandline-test help `` for further details. + +.. include:: /man/bytopic.rst ]]> -- 2.22.0