/*!
* @class ToolDoc
*
* @implements AssignableConcept
*
* @headerfile <seqan/arg_parse.>
*
* @brief Container for string documentation on a command line tool.
*
* @signature class ToolDoc;
*
* @section Remarks
*
* This class is generally not used directly by the user but through @link
* ArgumentParser @endlink. It allows to store and represent all information
* related to a command line tool that would normally go into a man page. It can
* be printed to STL streams in different formats, currently plain text, HTML
* and man pages are supported.
*
* You can also use basic formatting in text. This formatting is tailored to the
* usage on the command line. Use <tt>\fB</tt> to start bold font, <tt>\fI</tt>
* to start italic font and <tt>\fP</tt> to use the previous font (of course,
* use correct escaping of the backslash in C strings, so use <tt>"\\fB"</tt>,
* <tt>"\\fI"</tt>, and <tt>"\\fP"</tt> in your code.
*
* @section Examples
*
* The following shows a brief example of how to use @link ToolDoc @endlink.
*
* @code{.cpp}
* ToolDoc doc;
* setName(doc, "RazerS");
* setShortDescription(doc, "Read mapping with controllable sensitivity.");
* setDate(doc, "04 March 2012");
* setVersion(doc, "1.0");
* setCategory(doc, "Read Mapping");
* setManTitle(doc, "SeqAn Apps Reference Manual");
*
* addSection(doc, "Synopsis");
* addText(doc, "\\fBrazers\\fP [\\fIOPTIONS\\fP] \\fIREFERENCE\\fP \\fIREADS\\fP", false);
* addText(doc,
* "\\fBrazers\\fP [\\fIOPTIONS\\fP] \\fIREFERENCE\\fP \\fILEFT_READS\\fP "
* "\\fIRIGHT_READS\\fP", false);
*
* addSection(doc, "Description");
* addText(doc,
* "RazerS is a read mapper with controllable, sensitivity. This "
* "means that you can find all read matches in the reference sequence "
* "and optionally, you can trade lower sensitivity for better "
* "performance.");
* addText(doc,
* "What's special about RazerS is that you can control the sensitivity.");
*
* addSection(doc, "Options");
* addSubSection(doc, "Main Options");
* addListItem(doc, "\\fB-id\\fP, \\fB--indels\\fP",
* "Enable mapping with indels enabled.");
* addListItem(doc, "\\fB-i\\fP, \\fB--identity\\fP \\fIIDENTITY\\fP",
* "Set minimal identity of matches to find.");
*
* print(std::cout, doc, "text");
* @endcode
*
*
* @see ToolDoc#addText
* @see ToolDoc#addListItem
* @see ArgumentParser
*
* @fn ToolDoc::ToolDoc
*
* @brief Constructor
*
* @signature ToolDoc::ToolDoc()
*
* @fn ToolDoc#append
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Append two @link ToolDoc @endlink objects.
*
* @signature void append(a, b);
*
* @param[in,out] a This object is updated
* @param[in] b This object is appended to <tt>b</tt>.
*
* @fn ToolDoc#setName
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Set the tool name.
*
* @signature void setName(toolDoc, name);
*
* @param[in,out] toolDoc The ToolDoc object to the set the name for.
* @param[in] name The name of the tool (@link CharString @endlink).
*
* @fn ToolDoc#getName
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Get the tool name.
*
* @signature CharString getName(toolDoc);
*
* @param[in] toolDoc The ToolDoc object to the get the name for.
*
* @return CharString Resulting name (@link CharString @endlink).
*
* @fn ToolDoc#setCategory
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Set the tool name.
*
* @signature void setName(toolDoc, name);
*
* @param[in,out] toolDoc The ToolDoc object to the set the name for.
* @param[in] name The name of the tool (@link CharString @endlink).
*
* @fn ToolDoc#getCategory
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Get the tool category.
*
* @signature CharString getCategory(toolDoc);
*
* @param[in] toolDoc The ToolDoc object to the get the category for.
*
* @return CharString Resulting category (@link CharString @endlink).
*
* @fn ToolDoc#setShortDescription
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Set the tool short description.
*
* @signature void setShortDescription(toolDoc, text);
*
* @param[in,out] toolDoc The ToolDoc object to the set the short description
* for.
* @param[in] text The short description of the tool (@link CharString
* @endlink).
*
* @fn ToolDoc#getShortDescription
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Get the tool short description.
*
* @signature CharString getShortDescription(toolDoc);
*
* @param[in] toolDoc The ToolDoc object to the get the short description for.
*
* @return CharString Resulting short description (@link CharString @endlink).
*
* @fn ToolDoc#setDate
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Set the date string.
*
* @signature void setName(toolDoc, str);
*
* @param[in,out] toolDoc The ToolDoc object to the set the date string for.
* @param[in] str The date string of the tool (@link CharString @endlink).
*
* @fn ToolDoc#getDate
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Get the date.
*
* @signature CharString getDate(toolDoc);
*
* @param[in] toolDoc The ToolDoc object to the get the date from.
*
* @return CharString Resulting date string (@link CharString @endlink).
*
* @fn ToolDoc#setVersion
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Set the tool version string.
*
* @signature void setName(toolDoc, str);
*
* @param[in,out] toolDoc The ToolDoc object to the set the version string for.
* @param[in] str The version string of the tool (@link CharString @endlink).
*
* @fn ToolDoc#getVersion
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Get the tool version string.
*
* @signature CharString getVersion(toolDoc);
*
* @param[in] toolDoc The ToolDoc object to the get the version string.
*
* @return CharString Resulting version string (@link CharString @endlink).
*
* @fn ToolDoc#setManTitle
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Set the man title.
*
* @signature void setTitle(toolDoc, title);
*
* @param[in,out] toolDoc The ToolDoc object to the set the title for.
* @param[in] title The title of the tool (@link CharString @endlink).
*
* @fn ToolDoc#getManTitle
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Get the tool man page title of.
*
* @signature CharString getManTitle(toolDoc);
*
* @param[in] toolDoc The ToolDoc object to the get the man page title.
*
* @return CharString Resulting man page title (@link CharString @endlink).
*
* @fn ToolDoc#addSection
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Add a section with the given title.
*
* @signature void addSection(toolDoc, title);
*
* @param[in,out] toolDoc The ToolDoc object to add a section for.
* @param[in] title The section title (@link CharString @endlink).
*
* @fn ToolDoc#addSubSection
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Add a subsection with the given title.
*
* @signature void addSubSection(toolDoc, title);
*
* @param[in,out] toolDoc The ToolDoc object to add a subsection for.
* @param[in] title The subsection title (@link CharString @endlink).
*
* @fn ToolDoc#addText
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Add a text line/paragraph to ToolDoc.
*
* @signature void addText(toolDoc, text[, isParagraph]);
*
* @param[in,out] toolDoc The ToolDoc to add the text to.
* @param[in] text The text to add (@link CharString @endlink).
* @param[in] isParagraph Whether to insert as paragraph or just a line (only
* one line break if not a paragraph).
*
* @fn ToolDoc#addListItem
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Add a list item to a ToolDoc.
*
* @signature void addListItem(toolDoc, key, value);
*
* @param[in,out] toolDoc The ToolDoc object to add the list item to.
* @param[in] key The key for the list (@link CharString @endlink).
* @param[in] value The value for the list (@link CharString @endlink).
*
* @fn ToolDoc#print
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Print ToolDoc object in a given format.
*
* @signature void print(stream, toolDoc, format);
*
* @param[in,out] stream The <tt>std::ostream</tt> to write to.
* @param[in] toolDoc The ToolDoc to print.
* @param[in] format The format, one of {"html", "man", "txt"}.
*
* @fn ToolDoc#clearEntries
*
* @headerfile <seqan/arg_parse.h>
*
* @brief Clear entries from ToolDoc.
*
* @signature void clearEntries(toolDoc);
*
* @param[in,out] toolDoc The ToolDoc object to clear entries from.
*/