Allow clients to add an 'Examples' section to documentation

1 files changed, 58 insertions, 0 deletions

diff --git a/paludis/args/man.cc b/paludis/args/man.cc
index bf7745467..68f7f7457 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;