search

grigio / obs-cmd

obs-cmd is a OBS cli for obs-websocket v5 the current obs-studio implementation. It is useful on Wayland Linux or to control OBS via terminal
MIT License
126 stars 20 forks source link

[Request] Writing of manual #54

Open jackharro opened 3 months ago

jackharro commented 3 months ago

G'day,

I've noticed that this project doesn't have manpages. I'd like to introduce myself to write manpages for this project.

I know that it has --help flags for each command (built with clap?), but it can't hurt having a manpage.

It would be the first time that I write manpages, but I look forward to learning troff which seems, to me, like a very ergonomic tool to produce manpages. I would also enjoy reading through obs-cmd's codebase and learning all about the tool so that the manpages can be fairly comprehensive and accurate.

This would also be the first contribution I make to a FLOSS project, so I might need a little guidance around best practices e.g. should we have ./man or a separate manpage branch? How do we install manpages, maybe like # ./man/install? That sort of thing. I'm comfortable with learning/using tools on my own, so it's not babying, it's just a little guidance.

As for the timeframe, I'm a busy student at the business end of the school year. So this is something that I might be able to work on for a couple hours every second weekend. So it might be a while…

I'm happy to commit to keeping the manpages up-to-date with current versions by checking the logs and seeing if there's any changes to how commands work, if all goes well.

What do you guys think?

grigio commented 3 months ago

I don't know, maybe a --help is enough and I don't know if it will be maintaned

jackharro commented 3 months ago

Yea not many people like maintaining manpages. And there is always the possibility that I miss some crucial changes. However, I will have all notifs for this repo enabled so that I can review every major change.

--help isn't always enough because it can't go into details about how something is implemented, whereas the manpages can waffle about anything that users might misunderstand. I'll come up with a better example of this later.

Tell you what, I'll familiarise myself with this software and then evaluate if I want to write manpages for it.

Again the roadmap for this issue spans several months, but I will be less busy in November—December.

grigio commented 3 months ago

Ok, if you make a PR I'll review it for merge

jackharro commented 3 months ago

I gave it some more thought. I'm at a very early point of my career so I might have some precious projects later own and be forced to chop off some of my active contributions so I'm not spread too thin. However, if the manpages ever become sorely outdated or there are core features that are missing, please contact me via the public address on my profile so I can come back.

Expect the PR in December–January.

jackharro commented 1 month ago

[Update title because manpages is a torvalds/linux project]

jackharro commented 1 month ago

An update leading up to December–January:

• I've started using obs-cmd for global keybinds in a Wayland environment. It was OK but I'd rather run man obs-cmd than obs-cmd --help

• I'm starting to learn groff_mdoc

• The manuals will focus on examples and describing practical uses of obs-cmd while also explaining the theory behind its usage

• I'll get most of the information from the websocket documentation but I'll also read through main.rs to see what's available

I think the manual has a use as a kind of processed form of the websocket documentation in the context of system administration rather than software development.

So I'm excited to have a PR ready for this issue.