Add version/date API

[codesections]

I am including version and date in the same issue because I've checked several man(1) pages and noticed that the formatting of the two is related: specifically, the version will be displayed in the bottom center of the page if the man page doesn't have a date. If the man page has a date, the date is displayed in the bottom center of the page and the version is moved to the left.

I also note that we can use the env!("CARGO_PACKAGE_VERSION") macro to read the version from the Cargo.toml file and that version is a required field. Based on the above, I propose the following API:

Default (nothing specified; assume the Cargo.toml version is 0.2.0)

Manual::new("basic");

prints at the bottom:

                                       0.2.0                                    BASIC(1)

Date

Manual::new("basic")
  .date("August 2017");

0.2.0                                August 2017                              BASIC(1)

Date & Custom version

Manual::new("basic")
  .date("January 1, 2019")
  .version("0.1.0");

0.1.0                                January 1, 2017                          BASIC(1)

Custom date & no version

Manual::new("basic")
  .date("2015-05-23")
  .version("");

                                       2015-05-23                             BASIC(1)

Note: the API I suggest takes a str for the date and leaves the exact formatting to the user. It could, of course, take a date string or something (perhaps using Chrono) and format the date for the user. But, based on looking at a few man pages, there doesn't seem to be consensus on how to format dates and it seems better to leave that to the users.

Any thoughts on this API before I work on a PR?

[yoshuawuyts]

But, based on looking at a few man pages, there doesn't seem to be consensus on how to format dates and it seems better to leave that to the users.

I think it would be okay for us to be bold here and decide how to format it for people. I think this is something so minor that if people truly care about this they'll probably hand-roll their own pages.

It seems there's a good amount of options available, but if we look at kernel pages there seems to be a distinction between BSD and Linux:

• ls(1) on FreeeBSD
• ls(1) on Linux

We could go (slightly) overboard here, and use #[cfg] blocks to render the pages differently depending on which target it's compiled for. We should pick a default tho; either will probably work.

---

I also note that we can use the env!("CARGO_PACKAGE_VERSION") macro to read the version from the Cargo.toml file and that version is a required field.

Fun fact: if you call that macro from a dependency, the dependency's values are used instead of the main entry point's values. This means we'll have to make this an API.

---

I think the minimal API we could get away with would be:

build.rs

Manual::new("basic")
  .version(env!("CARGO_PACKAGE_VERSION"));

BSD

0.1.0                                August 1, 2017                           BASIC(1)

Linux

0.1.0                                August 2017                              BASIC(1)