Add API for version and date

README.md

@@ -15,6 +15,8 @@ use man::prelude::*;
 fn main() {
     let page = Manual::new("basic")
         .about("A basic example")
+        .date("January, 2019")
+        .version(env!("CARGO_PKG_VERSION"))
         .author(Author::new("Alice Person").email("alice@person.com"))
         .author(Author::new("Bob Human").email("bob@human.com"))
         .flag(
@@ -56,7 +58,7 @@ $ cargo run > /tmp/app.man; man /tmp/app.man
 ```
 Which outputs:
 ```txt
-BASIC(1)                                             General Commands Manual                                             BASIC(1)
+BASIC(1)                                             USER COMMANDS                                              BASIC(1)
 
 NAME
        basic - A basic example
@@ -93,6 +95,7 @@ EXAMPLES
 AUTHORS
          Alice Person <alice@person.com>
          Bob Human <bob@human.com>
+1.0.2                                                 January, 2019                                             BASIC(1)          
 ```
 
 ## Installation

examples/main.rs

@@ -5,6 +5,8 @@ use man::prelude::*;
 fn main() {
   let msg = Manual::new("auth-service")
     .about("authorize & authenticate members")
+    .version(env!("CARGO_PKG_VERSION"))
+    .date("February 2019")
     .arg(Arg::new("path"))
     .env(Env::new("PORT").help("The network port to listen to"))
     .flag(

src/man.rs

@@ -7,6 +7,8 @@ pub struct Manual {
   name: String,
   about: Option<String>,
   description: Option<String>,
+  date: Option<String>,
+  version: Option<String>,
   authors: Vec<Author>,
   flags: Vec<Flag>,
   options: Vec<Opt>,
@@ -23,6 +25,8 @@ impl Manual {
       name: name.into(),
       about: None,
       description: None,
+      date: None,
+      version: None,
       authors: vec![],
       flags: vec![],
       options: vec![],
@@ -45,6 +49,18 @@ impl Manual {
     self
   }
 
+  /// Add a last modified date
+  pub fn date<S: Into<String>>(mut self, date: S) -> Self {
+    self.date = Some(date.into());
+    self
+  }
+
+  /// Add a version
+  pub fn version<S: Into<String>>(mut self, version: S) -> Self {
+    self.version = Some(version.into());
+    self
+  }
+
   /// Add an author.
   pub fn author(mut self, author: Author) -> Self {
     self.authors.push(author);
@@ -91,8 +107,8 @@ impl Manual {
 
   /// Render to a string.
   pub fn render(self) -> String {
-    let man_num = 1;
-    let mut page = Roff::new(&self.name, man_num);
+    let title_line = title_line(self.name.clone(), self.version, self.date);
+    let mut page = Roff::new(&title_line, 5);
     page = about(page, &self.name, &self.about);
     page = synopsis(
       page,
@@ -383,6 +399,29 @@ fn custom(page: Roff, custom_section: Section) -> Roff {
   page.section(&custom_section.name, &paragraphs)
 }
 
+/// Add the date and version information to the header (if available)
+fn title_line(
+  name: String,
+  version: Option<String>,
+  date: Option<String>,
+) -> String {
+  // NOTE(ds): This is less elegant than it could be because Roff::new isn't set up
+  // to accept date or version information right now.  I'll submit a PR to that
+  // crate, but this (mostly) works in the meantime
+  let man_num: i8 = 1;
+  let mut title_line = format!("{} \"{}\"", name, man_num);
+  match date {
+    // This Roff::new capitalizes the date, incorrectly
+    Some(date) => title_line.push_str(format!(" \"{}\"", date).as_str()),
+    None => title_line.push_str(" \" \""),
+  }
+  match version {
+    Some(version) => title_line.push_str(format!(" \"{}\"", version).as_str()),
+    None => title_line.push_str(" \" \""),
+  }
+  title_line.push_str(" \"User Commands\"");
+  title_line
+}
 /// Create an examples section
 ///
 /// examples can have text (shown before the example command) and the command