aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-10-25 05:37:00 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-10-25 05:37:00 +0000
commite99bd9d1357923e87db3979be3b9eff4b333c3c0 (patch)
tree3fab3cff6a6b62e1a75954e36d2831ae42a2d067
parent6fd3c01597f7cbd1a223e64f1a5c0c31f38c85ae (diff)
downloadpaludis-e99bd9d1357923e87db3979be3b9eff4b333c3c0.tar.gz
paludis-e99bd9d1357923e87db3979be3b9eff4b333c3c0.tar.xz
Allow clients to add an 'Examples' section to documentation
-rw-r--r--paludis/args/args_handler.cc19
-rw-r--r--paludis/args/args_handler.hh17
-rw-r--r--paludis/args/man.cc58
-rw-r--r--paludis/args/man.hh12
4 files changed, 106 insertions, 0 deletions
diff --git a/paludis/args/args_handler.cc b/paludis/args/args_handler.cc
index 34140e9..b3241ce 100644
--- a/paludis/args/args_handler.cc
+++ b/paludis/args/args_handler.cc
@@ -45,6 +45,7 @@ namespace paludis
std::list<std::string> parameters;
std::list<std::string> usage_lines;
std::list<std::pair<std::string, std::string> > environment_lines;
+ std::list<std::pair<std::string, std::string> > example_lines;
std::map<std::string, ArgsOption *> longopts;
std::map<char, ArgsOption *> shortopts;
@@ -73,6 +74,12 @@ ArgsHandler::add_environment_variable(const std::string & e, const std::string &
}
void
+ArgsHandler::add_example(const std::string & e, const std::string & desc)
+{
+ _imp->example_lines.push_back(std::make_pair(e, desc));
+}
+
+void
ArgsHandler::add(ArgsGroup * const g)
{
/// \bug Should check for name uniqueness.
@@ -240,6 +247,18 @@ ArgsHandler::end_environment_lines() const
return EnvironmentLineConstIterator(_imp->environment_lines.end());
}
+ArgsHandler::EnvironmentLineConstIterator
+ArgsHandler::begin_examples() const
+{
+ return EnvironmentLineConstIterator(_imp->example_lines.begin());
+}
+
+ArgsHandler::EnvironmentLineConstIterator
+ArgsHandler::end_examples() const
+{
+ return EnvironmentLineConstIterator(_imp->example_lines.end());
+}
+
ArgsHandler::ArgsGroupsConstIterator
ArgsHandler::begin_args_groups() const
{
diff --git a/paludis/args/args_handler.hh b/paludis/args/args_handler.hh
index 48af1da..168be76 100644
--- a/paludis/args/args_handler.hh
+++ b/paludis/args/args_handler.hh
@@ -68,6 +68,11 @@ namespace paludis
void add_environment_variable(const std::string & e, const std::string & desc);
/**
+ * Add a new example.
+ */
+ void add_example(const std::string & e, const std::string & desc);
+
+ /**
* Add an new ArgsGroup (called by the ArgsGroup constructor).
*/
void add(ArgsGroup * const);
@@ -179,6 +184,18 @@ namespace paludis
///\}
+ ///\name Iterate over our examples (for documentation)
+ ///\{
+
+ typedef libwrapiter::ForwardIterator<ArgsHandler,
+ const std::pair<std::string, std::string> > ExamplesConstIterator;
+
+ ExamplesConstIterator begin_examples() const;
+
+ ExamplesConstIterator end_examples() const;
+
+ ///\}
+
///\name Iterate over our groups
///\{
diff --git a/paludis/args/man.cc b/paludis/args/man.cc
index bf77454..68f7f74 100644
--- a/paludis/args/man.cc
+++ b/paludis/args/man.cc
@@ -137,6 +137,16 @@ paludis::args::generate_doc(DocWriter & dw, const ArgsHandler * const h)
dw.end_environment();
}
+
+ if (h->begin_examples() != h->end_examples())
+ {
+ dw.start_examples();
+
+ for (ArgsHandler::ExamplesConstIterator a(h->begin_examples()), a_end(h->end_examples()) ; a != a_end ; ++a)
+ dw.example(a->first, a->second);
+
+ dw.end_examples();
+ }
}
DocWriter::~DocWriter()
@@ -257,6 +267,24 @@ HtmlWriter::end_environment()
}
void
+HtmlWriter::start_examples()
+{
+ _os << "<h2>Examples</h2>" << endl;
+}
+
+void
+HtmlWriter::example(const std::string & first, const std::string & second)
+{
+ _os << "<pre>" << first << "</pre>" << endl;
+ _os << "<p>" << second << "</p>" << endl;
+}
+
+void
+HtmlWriter::end_examples()
+{
+}
+
+void
HtmlWriter::section(const std::string & title)
{
_os << "<h2>" << title << "</h2>" << endl;
@@ -390,6 +418,36 @@ ManWriter::end_environment()
}
void
+ManWriter::start_examples()
+{
+ _os << ".SH EXAMPLES" << endl;
+}
+
+namespace
+{
+ std::string ungroff(const std::string & s)
+ {
+ if ((! s.empty() && ('.' == s.at(0))))
+ return " " + s;
+ else
+ return s;
+ }
+}
+
+void
+ManWriter::example(const std::string & first, const std::string & second)
+{
+ _os << ".TP" << endl;
+ _os << first << endl;
+ _os << ungroff(second) << endl << endl;
+}
+
+void
+ManWriter::end_examples()
+{
+}
+
+void
ManWriter::section(const std::string & title)
{
_os << ".SH " << title << endl;
diff --git a/paludis/args/man.hh b/paludis/args/man.hh
index 261549b..b741bc7 100644
--- a/paludis/args/man.hh
+++ b/paludis/args/man.hh
@@ -75,6 +75,10 @@ namespace paludis
virtual void environment_line(const std::string & first, const std::string & second) = 0;
virtual void end_environment() = 0;
+ virtual void start_examples() = 0;
+ virtual void example(const std::string &, const std::string &) = 0;
+ virtual void end_examples() = 0;
+
virtual void section(const std::string & title) = 0;
virtual void subsection(const std::string & title) = 0;
virtual void paragraph(const std::string & text) = 0;
@@ -123,6 +127,10 @@ namespace paludis
void environment_line(const std::string & first, const std::string & second);
void end_environment();
+ void start_examples();
+ void example(const std::string &, const std::string &);
+ void end_examples();
+
void section(const std::string & title);
void subsection(const std::string & title);
void paragraph(const std::string & text);
@@ -169,6 +177,10 @@ namespace paludis
void environment_line(const std::string & first, const std::string & second);
void end_environment();
+ void start_examples();
+ void example(const std::string &, const std::string &);
+ void end_examples();
+
void section(const std::string & title);
void subsection(const std::string & title);
void paragraph(const std::string & text);