/*
* 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.
impl_->bHidden_ = bHidden;
}
+void CommandLineHelpContext::enterSubSection(const std::string &title)
+{
+ impl_->writerContext_.enterSubSection(title);
+}
+
const HelpWriterContext &CommandLineHelpContext::writerContext() const
{
return impl_->writerContext_;
/*
* 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.
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;
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);
/*
* 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.
#include <vector>
#include "gromacs/onlinehelp/helptopicinterface.h"
+#include "gromacs/onlinehelp/helpwritercontext.h"
#include "gromacs/utility/exceptions.h"
#include "gromacs/utility/stringutil.h"
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
/*
* 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.
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
*/
void AbstractSimpleHelpTopic::writeHelp(const HelpWriterContext &context) const
{
- writeBasicHelpTopic(context, *this, helpText());
+ context.writeTextBlock(helpText());
}
/********************************************************************
void AbstractCompositeHelpTopic::writeHelp(const HelpWriterContext &context) const
{
- writeBasicHelpTopic(context, *this, helpText());
+ context.writeTextBlock(helpText());
writeSubTopicList(context, "\nAvailable subtopics:");
}
*/
/*! \libinternal \file
* \brief
- * Declares helper classes and functions for implementing
- * gmx::HelpTopicInterface.
+ * Declares helper classes for implementing gmx::HelpTopicInterface.
*
* \author Teemu Murtola <teemu.murtola@gmail.com>
* \inlibraryapi
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
*
* 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
*
//! \internal \addtogroup module_onlinehelp
//! \{
+//! Characters used for reStructuredText title underlining.
+const char g_titleChars[] = "=-^*~+#'_.";
+
struct t_sandr
{
const char *search;
//! Shorthand for a list of markup/other replacements.
typedef std::vector<ReplaceItem> 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();
}
StatePointer state_;
//! List of markup/other replacements.
ReplaceList replacements_;
+ //! Number of subsections above this context.
+ int sectionDepth_;
private:
GMX_DISALLOW_ASSIGN(Impl);
*/
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)
{
return impl_->state_->file_;
}
+void HelpWriterContext::enterSubSection(const std::string &title)
+{
+ GMX_RELEASE_ASSERT(impl_->sectionDepth_ - 1 < static_cast<int>(std::strlen(g_titleChars)),
+ "Too deeply nested subsections");
+ writeTitle(title);
+ ++impl_->sectionDepth_;
+}
+
std::string
HelpWriterContext::substituteMarkupAndWrapToString(
const TextLineWrapperSettings &settings, const std::string &text) const
void HelpWriterContext::writeTitle(const std::string &title) const
{
+ if (title.empty())
+ {
+ return;
+ }
File &file = outputFile();
switch (outputFormat())
{
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(
*
* 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
*/
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.
*
// 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
biod.pnpi.spb.ru / alexxy / gromacs.git / commitdiff