search

rndusr / stig

TUI and CLI for the BitTorrent client Transmission
GNU General Public License v3.0
554 stars 24 forks source link

Add man page #156

Closed wzykubek closed 4 years ago

wzykubek commented 4 years ago

I created a man page for this app but you need to implement installation of it. Man pages are more useful and more comfortable to use compared to help command.

rndusr commented 4 years ago

Thank you!

Although I'm not sure this is a good idea. I've built all the documentation into the code because stig changes a lot and I'm not mindful enough to always remember all the places that need updating. This has been a problem even though most docs are built on demand.

Ideally, stig would have a command that generates its man pages. Or maybe the repo should contain an extra command for that.

In any case, this is a very nice contribution for the next release as stig is not going to change much for now.

rndusr commented 4 years ago

It looks like you used the help from the current release? Your man page says "hit ':'" and I've changed that to "press ':'" on 2018-09-17. I've changed a lot of other stuff since then.

I've also found some rendering issues, e.g. newline between "--" and "notui" on line 58, badly rendered indentation on line 71 and what looks like a missing \fB on line 115. Please do more quality checking.

I'd really prefer a script that generates the man page from stig help ... output or even just a stub that has some very basic information that doesn't change.

I'm sorry, but I won't ship the man page as it is.

wzykubek commented 4 years ago

Uh, I looked at version from AUR which is Out of Date... I do deletion request, so if this PKGBUILD will be removed I can maintain it. Anyway in this situation man is to rewrite. I can do that in free time but I don't know you like that, because you want to create script which automate it.

rndusr commented 4 years ago

The version on AUR isn't out of date, it's the current release. But if you submit a man page now, it must be for the next release. You'd need to install the current master branch from GitHub.

Generating a man page from the regular stig output is probably pretty hard, if not impossible because there probably isn't enough formatting information in it, or at least it would be really hard to parse consistently.

We'd have to use some kind of (custom?) markup language to generate man pages and output for the TUI and CLI. That's not trivial and I don't want to delay the next release for that.

But that's the only way to keep the docs synchronized reliably and easily. I think it's best if we don't include a man page for now.

wzykubek commented 4 years ago

Yes, I was confused. Package in AUR is good, simply release is old, I should check it out. Sorry.

If you have nothing to add you can close this PR. I wanted to help but today I should go outside from home. :)

rndusr commented 4 years ago

A wise choice. Have fun outside. :)

I'm sorry you wasted your time. I wanted to pull, but I think it's not worth it.

Please open an issue next time you would like to contribute so I can tell if you're going to waste your time.