Open FranciscoPombal opened 4 years ago
Chocobo1
commented
4 years ago It is not very nice to ship bundled man pages with very incomplete information (and some of it could now be inaccurate even).
Agreed. We would need someone to work on it though. Also I think manually editing raw man pages is inhumane, we could use some tool (ronn, pandoc) let us write in markdown format (or other human readable format) and convert it to roff (man page format).
FranciscoPombal
commented
4 years ago @Chocobo1
Agreed. We would need someone to work on it though. Also I think manually editing raw man pages is inhumane, we could use some tool (ronn, pandoc) let us write in markdown format (or other human readable format) and convert it to roff (man page format).
I looked into it and writing groff_man does not seem that bad...
Obviously it would be better to write in markdown, but then we are totally dependent on pandoc's flexibility in the markdown <-> roff conversion - which is not necessarily a disadvantage, it may well be good enough for our purposes. I would also prefer pandoc to ronn.
The biggest disadvantage is having to add the man page generation as a build step/target and having to add pandoc as an (optional) build dependency. The dependency can be optional if man page generation can be controlled by a flag (e.g. --disable-docs and -DDISABLE_DOCS, for autotools and cmake, respectively).
~I think I can look further into this at the end of the week or the weekend, and I'll let you know what I find.~ ok I see there is already an existing PR.
Chocobo1
commented
4 years ago I looked into it and writing groff_man does not seem that bad...
Probably... however I would have no interest to spend time learning its syntax/directives, needless to say updating the man pages.
The biggest disadvantage is having to add the man page generation as a build step/target and having to add pandoc as an (optional) build dependency. The dependency can be optional if man page generation can be controlled by a flag (e.g. --disable-docs and -DDISABLE_DOCS, for autotools and cmake, respectively).
I would propose the pandoc is left out of the build chain. The one who edits the markdown man page needs to commit also the newly generated roff man pages (with pandoc). Given man pages are only relevant to linux users and pandoc should be widely available on every distro, IMO this wouldn't be a high requirement for the editor/contributor to follow.
FranciscoPombal
commented
4 years ago Probably... however I would have no interest to spend time learning its syntax/directives, needless to say updating the man pages.
I would propose the pandoc is left out of the build chain. The one who edits the markdown man page needs to commit also the newly generated roff man pages (with pandoc). Given man pages are only relevant to linux users and pandoc should be widely available on every distro, IMO this wouldn't be a high requirement for the editor/contributor to follow.
Seems reasonable.
fice-t
commented
4 months ago I'm here because I was just about to create an issue about the outdated man page for qbittorrent-nox, specifically about the missing --torrenting-port option (which I almost missed and was about to create a redundant feature request for).
The man page should at least match the --help output, which lists about a dozen additional options.
Related comment: https://github.com/qbittorrent/qBittorrent/pull/12083#issuecomment-592010800
Man pages and general documentation about qBittorrent's flags is severely out of date. It would be helpful to document all the new flags that qBittorrent now supports. The description should be clear and concise, but not miss out on any important detail of how exactly they change qBittorrent's behaviour.
It is not very nice to ship bundled man pages with very incomplete information (and some of it could now be inaccurate even).
@Chocobo1 @glassez I assigned you because you have a lot of understanding of qBittorrent's internals and recently participated in a related PR. Feel free to un-assign though.