search

rust-cli / roff-rs

ROFF (man page format) generation library
docs.rs/roff
Apache License 2.0
59 stars 11 forks source link

Add ManSection enum, own title line struct and other minor updates #14

Closed sondr3 closed 2 years ago

sondr3 commented 2 years ago

The title line, manpage section and compatibility settings come from clap-rs/clap#3174, where we decided on extracting out Roff-specific functionality to this crate. I also did a few minor changes, like removing the derive for PartialEq and Eq from the structs. The title line struct will make #7 obsolete, and is in my opinion a better solution as the order of the elements is important and is not just a list of strings.

cc @epage

sondr3 commented 2 years ago

Your two comments about whether things should go here or in a more manpage specific crate was one of the reasons I ended up trying to do everything in clap_man, the inclusion of a title line means we're already targeting manpages and not "pure" roff. It is a massive type-setting system (here is short reference of GNU variant of the format, you can see we're only really touching a tiny, tiny part of it), and has historically been used for lots of different things from books, articles and more.

Nowadays however I thing nobody uses it outside of manpages anymore, and while the man crate contains useful tools to build manpages for CLI tools this crate already targets a subset of roff specific to manpages, at least in my opinion. :sweat_smile: roffman that you mentioned in the PR in clap has sections in it, though the name implies that it is specific for manpages, but not a huge fan of its API.

Sorry, this is a lot of words for saying that in my head roff-rs is already a manpage specific crate :slightly_smiling_face: It's again one of the reasons I've attempted a few different approaches to this, I haven't found a good solution for it yet besides creating my own crate for this.

larswirzenius commented 2 years ago

I had a closer look at the manual page generation and the roff crate. I've pushed two branches that I think would be an improvement.

https://github.com/larswirzenius/roff-rs/tree/liw/roff-only changes roff to have an abstraction level of ROFF only, dropping manual page stuff. The commit message has some more detailed explanations. The branch isn't ready to be merged, and needs some cleanup first.

I then ported @sondr3's maual page generation to my roff version (https://github.com/larswirzenius/clap/tree/liw/generate-man). This, too, probably needs cleanup.

What do you think? Is my approach of any interest?

epage commented 2 years ago

What do you think? Is my approach of any interest?

I really like this! By focusing on the roff structure, I feel like it makes clearer the intent of what is going on while giving the benefit of escaping and typing (compared to doing everything with raw strings).

sondr3 commented 2 years ago

I too like your approach and from the comment over on the PR to clap you have far more experience working with manpages and the roff-format, so you can be the judge for this crate. Do you want to create a PR against my fork of clap so we can integrate your changes once you feel it's ready? :smile:

larswirzenius commented 2 years ago

I will do that later today or tomorrow, as soon as I've dug myself out from this horde of elves I'm buried under.

sondr3 commented 2 years ago

Superseded by #15.