It would be great if Arcanist had man-style help pages. For example, git help $command brings up a man page for git-$command. It would be great if Arcanist behaved in a similar way as man pages are a lot easier to read than help text echoed to the console.
Description
Description
| Status | Assigned | Task | ||
|---|---|---|---|---|
| Open | None | T4200 Building OS packages and install scripts | ||
| Wontfix | epriestley | T5173 Provide man pages for Arcanist |
Event Timeline
Comment Actions
Is there a chance to have a man page for arcanist anytime soon?
Creating a manpage only requires running "help2man /path/to/arc -N -n "command-line interface to Phabricator" > arc.1". It can of course be run automatically when a new arc version changes its usage.
Comment Actions
Is there a chance to have a man page for arcanist anytime soon?
No. See Planning, Paid Prioritization, Roadmap, etc.
Comment Actions
Generally, there's possibility of having multiple arc binaries (for example Internal/external/public phab in your company are all different instances) and causing arc to have different plugins and/or different conduit version requirements. So this solution is not "drop in, fit-for-all" :)
However... You could add this info to phriction (eg community resources) and for example create diff for arcanist that would enable manpage creation via command or have it directly in docs!
Comment Actions
If the arcanist manpage is shipped with the arcanist binary, i don't see where is the problem. Are you telling me the arcanist manpage content depends on the installed plugins ?
Considering one can create a manpage with help2man, when a new version of arcanist is released, wouldn't it be enough to just create the manpage and ship both altogether in git? As far as i understand, if people have different arcanist versions, they would also have the corresponding manpages.
Comment Actions
Are you telling me the arcanist manpage content depends on the installed plugins ?
Yes, and on the current working directory when you run arc, and on your user and system configuration files.
Comment Actions
@rsellam - Either I misunderstood You or You misunderstood me...
Currently there's no manpage distributed with arcanist. Your best bet is to generate it the way you described. Since it's possible that people have multiple diferent acranist binaries, doing man arc wouldn't help them. However it would be quite alright for You to add documentation that if one desires it, it's possible to generate manpage for oneself using Your suggested command.
Well, I'd actually suggest this command for fuller manpage:
help2man /path/to/arc -N -n "command-line interface to Phabricator" -h "help --full" -o arc.1
That way IF one needs manpage, one would get it. Hell, even put it in cron or have it as partof arc upgrade ( you'd need to write extension for it).
Comment Actions
I don't plan to pursue this.
I don't understand the original claim, "man pages are a lot easier to read than help text echoed to the console". If that's "...because they pipe through a pager", we could add a couple lines of if (is_tty()) { echo help | less; }. You can do this yourself by running arc help diff | less. Technically, arc help diff --ansi | less -r, perhaps. I'm open to "when stdout is a TTY, pipe arc help X through a pager".
If that's "because the way man pages are written is better than the way arc help is written" -- that this is an issue with the content, not the UI -- I'd like more context on why you believe that to be true.
In other cases, it's not clear why man arc-diff is better than arc help diff. It's worse in several ways: it's more complex for us to maintain and test, it's less compatible across platforms, it can fall out of date, and it won't reflect runtime extensions which change behavior.
Although git help diff invokes man git-diff, hg help diff and svn help diff do not invoke man. SVN installs a stub manpage pointing at svn help, and hg has not installed a manpage at all on my local system. On secure001, man hg produces an 8,000 line manpage documenting every command. I believe this is generally less useful than <binary> help <thing I'm trying to do>.