WTFM

calendar Dec 4, 2024 · 4 min read · Prattle

The absolute fucking state of Linux documentation shows undeniably that nobody ever reads it.

Open a terminal, and just try, in earnest, to learn about what is happening:

 1$ ?
 2$ help
 3
 4
 5GNU bash, version 5.2.37(1)-release (x86_64-pc-linux-gnu)
 6These shell commands are defined internally.  Type `help' to see this list.
 7Type `help name' to find out more about the function `name'.
 8Use `info bash' to find out more about the shell in general.
 9Use `man -k' or `info' to find out more about commands not in this list.
10
11A star (*) next to a name means that the command is disabled.
12
13 job_spec [&]                            history [-c] [-d offset] [n] or hist>
14 (( expression ))                        if COMMANDS; then COMMANDS; [ elif C>
15 . filename [arguments]                  jobs [-lnprs] [jobspec ...] or jobs >
16 :                                       kill [-s sigspec | -n signum | -sigs>
17 [ arg... ]                              let arg [arg ...]
18 [[ expression ]]                        local [option] name[=value] ...
19 alias [-p] [name[=value] ... ]          logout [n]
20 bg [job_spec ...]                       mapfile [-d delim] [-n count] [-O or>
21 bind [-lpsvPSVX] [-m keymap] [-f file>  popd [-n] [+N | -N]
22
23   [...]

Nothing is remotely clear to anyone who doesn't already know everything they need to. This 'help' cannot help anyone.

And what are these 'functions'? Probably the things written below the top paragraph.

1$ help job_spec
2
3/bin/bash: line 1: help: no help topics match `job_spec'.  Try `help help' or `man -k job_spec' or `info job_spec'.
4
5$ info job_spec
6
7info: No menu item 'job_spec' in node '(dir)Top'

The document's gone from 'pointless' to 'actively misleading'. Perhaps we can try the next suggested command?

 1$ info bash
 2
 3
 4File: bash.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
 5
 6Bash Features
 7*************
 8
 9This text is a brief description of the features that are present in the
10Bash shell (version 5.2, 19 September 2022).  The Bash home page is
11<http://www.gnu.org/software/bash/>.
12
13   This is Edition 5.2, last updated 19 September 2022, of 'The GNU Bash
14Reference Manual', for 'Bash', Version 5.2.
15
16   Bash contains features that appear in other popular shells, and some
17features that only appear in Bash.  Some of the shells that Bash has
18borrowed concepts from are the Bourne Shell ('sh'), the Korn Shell
19('ksh'), and the C-shell ('csh' and its successor, 'tcsh').  The
20following menu breaks the features up into categories, noting which
21features were inspired by other shells and which are specific to Bash.
22
23   This manual is meant as a brief introduction to features found in
24
25   [...]

This nonsense continues for 11,623 lines, and 74,749 words.

I'm not going to read them, but would stake everything I own on the claim that the document contains nothing useful, or helpful, for someone who might need to type 'help' into a shell-prompt to understand what's going on.

And how on earth does this info work?

1$ info info?

14,961 words, covering topics such as:

  • "Texinfo itself (*note (texinfo)Top::) is a documentation system",
  • setting up info with MS-DOS/Windows keybindings,
  • how to move the cursor with C-n (no explanation of what that means), and finally
  • what is a delete key? And how to use it.

Better Alternatives

Option 1: Just Don't!

Remove all false-promises, and false hope of actual help.

Option 2: Vim-Style Tutorial

Place the basic commands to move about. Imagine the following:

 1$ help
 2
 3           *** Welcome to the shell! ***
 4
 5   Help has the following topics:
 6
 7    - help basics (start here)
 8    - help shortcuts
 9    - help links
10    - help print command ('>')
11    - help permissions
12    - help networking
13
14$ help basics
15
16    ## List Directory Contents: ls
17
18    Type `ls` then 'Enter' to see a list of the files here.
19    Some of these files are actually directories ('folders') which
20    contain other files.
21
22    The directories usually show up in different colours, but you
23    can also see which files are directories by typing 'ls -F':
24
25    file    : just a normal file.
26    dir/    : the slash ('/') at the end shows this is a directory.
27    file*   : this file can be executed, like a program (but that does not
28              mean you should just that you can!).
29    
30
31$ ls
32
33    [...]