From: Teemu Murtola Date: Sun, 17 May 2015 18:27:17 +0000 (+0300) Subject: Add subsection depth to HelpWriterContext X-Git-Url: http://biod.pnpi.spb.ru/gitweb/?a=commitdiff_plain;h=57ecfc60bdfc15acc46081a3372c1d1dd9cca037;p=alexxy%2Fgromacs.git Add subsection depth to HelpWriterContext Necessary for exporting, e.g., the selection help as rst (#679), and cleans up the code by making more output go through HelpWriterContext instead of directly writing to the output file. Also, reorganize the way help topic titles are written: HelpManager is now responsible for writing out the title for a topic. This makes things behave the same as with HelpWriterContext::createSubSection(). Change-Id: If7e0ee6d4c9dd313e1523fa457f64cf3c4f891f9 --- diff --git a/src/gromacs/commandline/cmdlinehelpcontext.cpp b/src/gromacs/commandline/cmdlinehelpcontext.cpp index e98997e5bf..d18951146a 100644 --- a/src/gromacs/commandline/cmdlinehelpcontext.cpp +++ b/src/gromacs/commandline/cmdlinehelpcontext.cpp @@ -1,7 +1,7 @@ /* * This file is part of the GROMACS molecular simulation package. * - * Copyright (c) 2013,2014, by the GROMACS development team, led by + * Copyright (c) 2013,2014,2015, by the GROMACS development team, led by * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl, * and including many others, as listed in the AUTHORS file in the * top-level source directory and at http://www.gromacs.org. @@ -136,6 +136,11 @@ void CommandLineHelpContext::setShowHidden(bool bHidden) impl_->bHidden_ = bHidden; } +void CommandLineHelpContext::enterSubSection(const std::string &title) +{ + impl_->writerContext_.enterSubSection(title); +} + const HelpWriterContext &CommandLineHelpContext::writerContext() const { return impl_->writerContext_; diff --git a/src/gromacs/commandline/cmdlinehelpcontext.h b/src/gromacs/commandline/cmdlinehelpcontext.h index f682e22060..e5e48e003c 100644 --- a/src/gromacs/commandline/cmdlinehelpcontext.h +++ b/src/gromacs/commandline/cmdlinehelpcontext.h @@ -1,7 +1,7 @@ /* * This file is part of the GROMACS molecular simulation package. * - * Copyright (c) 2013,2014, by the GROMACS development team, led by + * Copyright (c) 2013,2014,2015, by the GROMACS development team, led by * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl, * and including many others, as listed in the AUTHORS file in the * top-level source directory and at http://www.gromacs.org. @@ -94,6 +94,8 @@ class CommandLineHelpContext void setModuleDisplayName(const std::string &name); //! Sets whether hidden options should be shown in help output. void setShowHidden(bool bHidden); + //! \copydoc HelpWriterContext::enterSubSection() + void enterSubSection(const std::string &title); //! Returns the lower-level context for writing the help. const HelpWriterContext &writerContext() const; diff --git a/src/gromacs/commandline/cmdlinehelpmodule.cpp b/src/gromacs/commandline/cmdlinehelpmodule.cpp index 17233eba54..cbd5115d7e 100644 --- a/src/gromacs/commandline/cmdlinehelpmodule.cpp +++ b/src/gromacs/commandline/cmdlinehelpmodule.cpp @@ -487,9 +487,9 @@ void HelpExportReStructuredText::exportModuleHelp( file.writeLine(".. _mdrun_mpi:"); } file.writeLine(); - file.writeLine(displayName); - file.writeLine(std::string(displayName.length(), '=')); + CommandLineHelpContext context(&file, eHelpOutputFormat_Rst, &links_); + context.enterSubSection(displayName); context.setModuleDisplayName(displayName); module.writeHelp(context); diff --git a/src/gromacs/onlinehelp/helpmanager.cpp b/src/gromacs/onlinehelp/helpmanager.cpp index 45193dcd51..89cb7cc811 100644 --- a/src/gromacs/onlinehelp/helpmanager.cpp +++ b/src/gromacs/onlinehelp/helpmanager.cpp @@ -1,7 +1,7 @@ /* * This file is part of the GROMACS molecular simulation package. * - * Copyright (c) 2012,2014, by the GROMACS development team, led by + * Copyright (c) 2012,2014,2015, by the GROMACS development team, led by * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl, * and including many others, as listed in the AUTHORS file in the * top-level source directory and at http://www.gromacs.org. @@ -47,6 +47,7 @@ #include #include "gromacs/onlinehelp/helptopicinterface.h" +#include "gromacs/onlinehelp/helpwritercontext.h" #include "gromacs/utility/exceptions.h" #include "gromacs/utility/stringutil.h" @@ -160,7 +161,10 @@ void HelpManager::enterTopic(const std::string &name) void HelpManager::writeCurrentTopic() const { const HelpTopicInterface &topic = impl_->currentTopic(); - topic.writeHelp(impl_->rootContext_); + const char *title = topic.title(); + HelpWriterContext context(impl_->rootContext_); + context.enterSubSection(title != NULL ? title : ""); + topic.writeHelp(context); } } // namespace gmx diff --git a/src/gromacs/onlinehelp/helptopic.cpp b/src/gromacs/onlinehelp/helptopic.cpp index 8bcaa6ac94..1cf1585187 100644 --- a/src/gromacs/onlinehelp/helptopic.cpp +++ b/src/gromacs/onlinehelp/helptopic.cpp @@ -1,7 +1,7 @@ /* * This file is part of the GROMACS molecular simulation package. * - * Copyright (c) 2012,2013,2014, by the GROMACS development team, led by + * Copyright (c) 2012,2013,2014,2015, by the GROMACS development team, led by * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl, * and including many others, as listed in the AUTHORS file in the * top-level source directory and at http://www.gromacs.org. @@ -56,20 +56,6 @@ namespace gmx { -/*! \cond libapi */ -void writeBasicHelpTopic(const HelpWriterContext &context, - const HelpTopicInterface &topic, - const std::string &text) -{ - const char *title = topic.title(); - if (title != NULL && title[0] != '\0') - { - context.writeTitle(title); - } - context.writeTextBlock(text); -} -//! \endcond - /******************************************************************** * AbstractSimpleHelpTopic */ @@ -87,7 +73,7 @@ AbstractSimpleHelpTopic::findSubTopic(const char * /* name */) const void AbstractSimpleHelpTopic::writeHelp(const HelpWriterContext &context) const { - writeBasicHelpTopic(context, *this, helpText()); + context.writeTextBlock(helpText()); } /******************************************************************** @@ -144,7 +130,7 @@ AbstractCompositeHelpTopic::findSubTopic(const char *name) const void AbstractCompositeHelpTopic::writeHelp(const HelpWriterContext &context) const { - writeBasicHelpTopic(context, *this, helpText()); + context.writeTextBlock(helpText()); writeSubTopicList(context, "\nAvailable subtopics:"); } diff --git a/src/gromacs/onlinehelp/helptopic.h b/src/gromacs/onlinehelp/helptopic.h index d6e8293f88..3a49e39bd0 100644 --- a/src/gromacs/onlinehelp/helptopic.h +++ b/src/gromacs/onlinehelp/helptopic.h @@ -34,8 +34,7 @@ */ /*! \libinternal \file * \brief - * Declares helper classes and functions for implementing - * gmx::HelpTopicInterface. + * Declares helper classes for implementing gmx::HelpTopicInterface. * * \author Teemu Murtola * \inlibraryapi @@ -52,33 +51,13 @@ namespace gmx { -/*! \cond libapi */ -/*! \libinternal \brief - * Helper for writing simple help text. - * - * \param[in] context Context for writing the help. - * \param[in] topic Topic to write the help for (used for title). - * \param[in] text Text to write for the topic. - * \throws std::bad_alloc if out of memory. - * \throws FileIOError on any I/O error. - * - * Formats basic help by writing a title (obtained from \p topic), followed by - * \p text with markup substituted and lines properly wrapped. - * - * \inlibraryapi - */ -void writeBasicHelpTopic(const HelpWriterContext &context, - const HelpTopicInterface &topic, - const std::string &text); -//! \endcond - /*! \libinternal \brief * Abstract base class for help topics that have simple text and no subtopics. * * This class implements subtopic-related methods from HelpTopicInterface such * that there are no subtopics. writeHelp() is also implemented such that it - * uses writeBasicHelpTopic() to write out the text returned by a new virtual - * method helpText(). + * uses HelpTopicContext::writeTextBlock() to write out the text returned by a + * new virtual method helpText(). * * \see SimpleHelpTopic * @@ -114,8 +93,9 @@ class AbstractSimpleHelpTopic : public HelpTopicInterface * public methods for adding subtopics (as HelpTopicInterface objects). * Subtopic-related methods from HelpTopicInterface are implemented to access * the internal container. writeHelp() is also implemented such that it - * uses writeBasicHelpTopic() to write out the text returned by a new virtual - * method helpText(), and a list of subtopics is written after the actual text. + * uses HelpTopicContext::writeTextBlock() to write out the text returned by a + * new virtual method helpText(), and a list of subtopics is written after the + * actual text. * * \see CompositeHelpTopic * diff --git a/src/gromacs/onlinehelp/helpwritercontext.cpp b/src/gromacs/onlinehelp/helpwritercontext.cpp index b7bc9c2308..4c928e02ab 100644 --- a/src/gromacs/onlinehelp/helpwritercontext.cpp +++ b/src/gromacs/onlinehelp/helpwritercontext.cpp @@ -66,6 +66,9 @@ namespace //! \internal \addtogroup module_onlinehelp //! \{ +//! Characters used for reStructuredText title underlining. +const char g_titleChars[] = "=-^*~+#'_."; + struct t_sandr { const char *search; @@ -465,9 +468,9 @@ class HelpWriterContext::Impl //! Shorthand for a list of markup/other replacements. typedef std::vector ReplaceList; - //! Initializes the context with the given state. - explicit Impl(const StatePointer &state) - : state_(state) + //! Initializes the context with the given state and section depth. + Impl(const StatePointer &state, int sectionDepth) + : state_(state), sectionDepth_(sectionDepth) { initDefaultReplacements(); } @@ -500,6 +503,8 @@ class HelpWriterContext::Impl StatePointer state_; //! List of markup/other replacements. ReplaceList replacements_; + //! Number of subsections above this context. + int sectionDepth_; private: GMX_DISALLOW_ASSIGN(Impl); @@ -672,13 +677,13 @@ void HelpWriterContext::Impl::processMarkup(const std::string &text, */ HelpWriterContext::HelpWriterContext(File *file, HelpOutputFormat format) - : impl_(new Impl(Impl::StatePointer(new Impl::SharedState(file, format, NULL)))) + : impl_(new Impl(Impl::StatePointer(new Impl::SharedState(file, format, NULL)), 0)) { } HelpWriterContext::HelpWriterContext(File *file, HelpOutputFormat format, const HelpLinks *links) - : impl_(new Impl(Impl::StatePointer(new Impl::SharedState(file, format, links)))) + : impl_(new Impl(Impl::StatePointer(new Impl::SharedState(file, format, links)), 0)) { if (links != NULL) { @@ -717,6 +722,14 @@ File &HelpWriterContext::outputFile() const return impl_->state_->file_; } +void HelpWriterContext::enterSubSection(const std::string &title) +{ + GMX_RELEASE_ASSERT(impl_->sectionDepth_ - 1 < static_cast(std::strlen(g_titleChars)), + "Too deeply nested subsections"); + writeTitle(title); + ++impl_->sectionDepth_; +} + std::string HelpWriterContext::substituteMarkupAndWrapToString( const TextLineWrapperSettings &settings, const std::string &text) const @@ -737,6 +750,10 @@ HelpWriterContext::substituteMarkupAndWrapToVector( void HelpWriterContext::writeTitle(const std::string &title) const { + if (title.empty()) + { + return; + } File &file = outputFile(); switch (outputFormat()) { @@ -746,7 +763,8 @@ void HelpWriterContext::writeTitle(const std::string &title) const break; case eHelpOutputFormat_Rst: file.writeLine(title); - file.writeLine(std::string(title.length(), '-')); + file.writeLine(std::string(title.length(), + g_titleChars[impl_->sectionDepth_])); break; default: GMX_THROW(NotImplementedError( diff --git a/src/gromacs/onlinehelp/helpwritercontext.h b/src/gromacs/onlinehelp/helpwritercontext.h index 167aa5c649..ed480bb818 100644 --- a/src/gromacs/onlinehelp/helpwritercontext.h +++ b/src/gromacs/onlinehelp/helpwritercontext.h @@ -123,9 +123,7 @@ class HelpLinks * * The state of a context object (excluding the fact that the output file is * written to) does not change after initial construction of the object. - * Copying creates a context object that shares state with the source. - * - * TODO: This class will need additional work as part of Redmine issue #969. + * Copying creates a context objects that share state with the source. * * \inlibraryapi * \ingroup module_onlinehelp @@ -186,6 +184,28 @@ class HelpWriterContext */ File &outputFile() const; + /*! \brief + * Creates a subsection in the output help. + * + * \param[in] title Title for the subsection. + * \throws std::bad_alloc if out of memory. + * \throws FileIOError on any I/O error. + * + * Writes \p title using writeTitle() and makes any further + * writeTitle() calls write headings one level deeper. + * + * Typical use for writing a subsection is to create a copy of the + * context for the parent section, and then call enterSubSection() on + * the copy. + * The whole subsection should be written out using the returned + * context before calling any further methods in the parent context. + * + * This method is only necessary if the subsection will contain further + * subsections. If there is only one level of subsections, it is + * possible to use writeTitle() directly. + */ + void enterSubSection(const std::string &title); + /*! \brief * Substitutes markup used in help text and wraps lines. * diff --git a/src/gromacs/selection/selhelp.cpp b/src/gromacs/selection/selhelp.cpp index 2bcb6de49d..8487fafe69 100644 --- a/src/gromacs/selection/selhelp.cpp +++ b/src/gromacs/selection/selhelp.cpp @@ -587,7 +587,7 @@ void KeywordsHelpTopic::writeHelp(const HelpWriterContext &context) const // TODO: The markup here is not really appropriate, and printKeywordList() // still prints raw text, but these are waiting for discussion of the // markup format in #969. - writeBasicHelpTopic(context, *this, helpText()); + context.writeTextBlock(helpText()); context.writeTextBlock(""); // Print the list of keywords