What about adding man page of built-in command to the docs

Chat / Discussions
, ,
1

Or add corresponding explanatory links on the Guide page to make the documentation more complete and consistent?

Recently, I realized that I didn’t know where to look for the OPTIONS details for the iex command when the shell was unavailable. This may not be a problem for people already familiar with the basics, but when I tried to give a reference link for beginners, I found that neither the elixir-lang.org website nor the path /elixir and /iex of hexdocs.pm had the complete command-line usage. As a result, I had to refer to other third party sites like man.archlinux.org & manpages.ubuntu.com.

This is actually a minor annoyance if only for iex and mix two commands, but it is a little sad whenever I see “Documentation: https://elixir-lang.org/docs.html” at the bottom of the man page text.
Because you can’t find and jump to the docs of full CLI instructions for iex from the link, even using the DuckDuckGo search on the page’s right side with (site:elixir-lang.org|site:hexdocs.pm/elixir|site:hexdocs.pm/mix|site:hexdocs.pm/eex|site:hexdocs.pm/logger|site:hexdocs.pm/iex|site:hexdocs.pm/ex_unit) doesn’t help, and the best you can find is a few related info in Elixir Changelog :melting_face:.

Though I’ve considered the same kind of improvements could also be added to ex_doc (by giving it the option to include man pages at compile time), user-level scripts can be extended by using Mix.Tasks, which feel unnecessary when help information of the tasks already included.

8 years have passed since the man page content of iex was first committed, and the longer the subtle inconsistencies persist, the more unreasonable it becomes.

Personally, I don’t think the official documentation must contain a full copy with all existing man pages. However, when considering search engine indexing and website archiving (e.g. archive.org), it is really necessary to provide external links to the relevant missing information.

Since I don’t have permission to create a topic in the Suggestions & Proposals, I’m leaving this thread here for now. Besides, it’s almost 2024, there should be a more appropriate solution, :thinking:?

1 Like