Bundle manpages with Yarn

[Daniel15]

Split from #1162

Do you want to request a feature or report a bug? Feature

What is the current behavior? You need to browse the Yarn website to get documentation on the CLI commands

What is the expected behavior? Some CLI documentation should be bundled with Yarn (particularly for the Linux packages, as this is a standard feature of Linux packages). This is useful for offline scenarios (eg. when using an internal npm server). Documentation should be viewable by running one of these commands:

man yarn-install
yarn help install

For example, see how Git does it: man git-add and git help add both open the manpage for the "add" command. Similarly, npm help install opens a manpage for npm's install command.

However, we do not want to duplicate content across the website and the Yarn repo. One approach that seems doable would be to grab all the Markdown files from the website CLI docs, convert them to manpages, and bundle them with Yarn.

[Daniel15]

npm have Markdown files formatted like manpages (eg. https://github.com/npm/npm/blob/d081cc6c8d73f2aa698aab36605377c95e916224/doc/cli/npm-install.md), and then use marked-man to convert them to manpages.

[Alhadis]

You're better off writing them by hand. Seriously.

marked-man generates horrid output, and the formatted results are sometimes less legible than simply reading the original markdown source. If you want man-pages written for Yarn, I'm happy to volunteer, but pleeeeease don't repeat NPM's mistake of forcing users to view subpar documentation.

[awwright]

@Alhadis I agree quality is important, but in my understanding, this issue is about getting any documentation at all:

$ man yarn
No manual entry for yarn

[Alhadis]

Bit of a sad irony, here; markdown is easier to generate from man-pages (Roff) than vice-versa:

mandoc -Tmarkdown manpage.1 > manpage.md

The reason is that you're using a more limited, less capable markup language to generate a lower-level, more powerful one. Of course, asking or expecting people to turn away from Markdown is idiotic, so we're left with these difficulties.

[Alhadis]

I'm happy to smash out some man-pages for people to use, regardless of whether they get accepted upstream or not.

[Daniel15]

cc @arcanis - Did you have any plans regarding manpages for Yarn v2?

[arcanis]

It's not technically a man page, but the --help option in the v2 generates full documentation for the given command.

For example, the code here generates the following output when running yarn add --help:

[arcanis]

Note that imo the main blocker for actual man pages is that they wouldn't work with the single-file build, so in some cases they would be available and in others they wouldn't.

Additionally, they wouldn't get synced with the specific Yarn version used by a project, which could generate some confusion when a modern option listed in the man page isn't supported on old projects.

[Alhadis]

@arcanis Will v2 have support for globally installed man pages? Because when I ran yarn global add guess-sig its manpage wasn't symlinked anywhere I could see.