API design

[yoshuawuyts]

The current API is more of a sketch of what this could look like. On chat there seems to be a sentiment that the current API might not suffice for more complex man pages.

I'm opening this issue to gather examples of complex man pages, and to help shape the design of the crate. This should hopefully allow us to get a deeper understanding of which API we can, and should expose.

[epage]

Not sure but my guess is more a matter of single sourcing

• header information pulled from Cargo.toml
• flags pulled from clap
• body pulled from markdown that can also be used as web documentation

Granted, if this is a lower level API, then it might make sense to not have all of that built in

[yoshuawuyts]

I think clap actually has a really neat API. Taking some notes on the structure would probably be a good idea. https://github.com/kbknapp/clap-rs#quick-example

extern crate clap;
extern crate clap_md;

use clap::{App, AppSettings, Arg, SubCommand};
use clap_md::app_to_md;

fn main() {
  let a = App::new("testapp")
    .about("Pointless application")
    .setting(AppSettings::SubcommandRequiredElseHelp)
    .author("Katharina Fey <kookie@spacekookie.de>")
    // .author("Yosh Wuyts <y@w.s")
    .long_about("Lorem Ipsum bla bla bla")
    .arg(Arg::with_name("debug").short("d").help("Make program output debug messages"))
    .arg(Arg::with_name("output").short("o").takes_value(true).help("Output File"))
    .subcommand(SubCommand::with_name("foo").arg(Arg::with_name("bar").short("b").long("barr")));

  let markdown = app_to_md(&a, 1).unwrap();
  println!("{}", markdown);
}