a different version of the same question: if you find man pages difficult or impossible to use, what makes them so hard? do you feel like it's something that could be fixed?

(other than "the lack of examples", which is possibly the #1 issue, also please don't tell me about tldr.sh)

@b0rk i have a hard time reading large amounts of text in the terminal, for some reason, and find it especially hard to seek efficiently through longer texts. That’s my issue number one.

My issue number two is they often use unfamiliar, ambiguous or unnecessarily terminology to describe things. Often programs have their own terminology local to themselves.

Issue number three is search isn’t very good. Together with issue number one this is Very Bad.

@b0rk also, paging, cross referencing and so on. Most man pages are best read as web documents, by far.

@amanda web man pages are so good

@b0rk I think my main issue is that I have a hard time remember the SYNOPSIS syntax (could be a me problem)

@defuneste it's tough, even though I think I know the syntax sometimes I find it hard to decode what it's trying to tell me

@b0rk i feel like the number one problem i run into with documentation of any sort is jargon. and that’s very likely a hard problem to solve because at some level of technical depth, jargon is pretty much necessary, or its lack would be disorienting for people who know more about the field.

but too much of it makes things opaque to people who just want the thing to do the thing. (added bonus: english as a seco— wait, no, third language)

@gekitsu yeah jargon is a huge problem and i think it's extremely possible to address

@b0rk man pages, like so much other technical documentation, is written by people who don't need the documentation any more, but are unable to "pretend" they do. Basically, https://xkcd.com/2501/

@tkissing yea one thing i've been thinking about is how a lot of these old C projects have kind of an arcane system for contributing to them and it can be really hard for a "regular" user of the tool who might want to contribute to the docs to navigate

i feel like at this point I can make my way through arcane systems if I want to make a contribution but I definitely could not have done it 15 years ago

@b0rk Man pages are pretty perfect. For example the pages for systemd and podman-systemd.unit.

I think the man interface can be a bit off-putting. You really have to take the time to read the reference that comes up when you hit "h".

I still prefer to read man pages in Emacs even though the man interface has all the functionality I need (for example searching with /). It just looks a bit nicer and links to other man pages are easy to open with Emacs.

@sysedit the post said "if you find man pages difficult or impossible to use", not "if you think man pages are almost perfect"

@b0rk They often seem to be geared towards people who already understand the command, rather than explaining to people who don't.

@b0rk Man pages for simple commands are totally fine for me, but I can't get a good overview on large ones. I think it really would be better if pages were split up more like you would see in online docs, and used hyperlinking to jump between pages. Man pages don't need to be linear or work on a teletype so I think it doesn't really embrace the interactive medium well.

@b0rk possible for sure! but i can see why it often isn’t being addressed when you put together highly-subject-matter-involved people writing it, and writing with a condensed length in mind.

this isn’t me poo-pooing manpage/--help writers, this is me sympathising.

@gekitsu oh yeah I was trying to agree with you :)

it's really hard especially for people who are not used to doing it and who are really immersed in the topic

@b0rk

Beyond lack of examples & pages written as though the reader already knows the options, my main issue is when the man page references some kind of 'standard options' that aren't described there.

Larger projects with a lot of tools can do this. Often, they're simply noted with no context. Sometimes they aren't directly referenced at all, you just need to work out that the man page doesn't have all of the info and you need to go elsewhere for it.

@joewells thanks, this is a great point. do you have an example in mind?

@b0rk Man pages for large "it grew like topsy" programs. These are long and confusing, especially about interactions between commands. I try not to need those programs.

About the biggest good one is man rclone, which I fetch, convert to text and open an editor on it in a personal man directory

#!/bin/sh
#
# manx -- man to vi with a long search path
#
if [ ! -s $HOME/man/$1.man ]; then
MANPATH=$MANPATH:$HOME/man man "$@" |\
col -b >$HOME/man/$1.man
fi
vi $HOME/man/$1.man

@davecb @b0rk why not just this?

MANPATH=$MANPATH:$HOME/man man "$@" |view -

(You can also add $HOME/man to MANPATH in your .bashrc or similar so it's just an exercise of piping man's output to view)

@b0rk Searching for things like -e usually yields tons of irrelevant hits (e.g. see also: --no-skip-existing), and it's unpleasant to have to look for the actual entry for -e.

@b0rk And/or they're geared towards someone who wants a complete and thorough understand of a command rather than someone who might use it for its 90% use-case once a year

@b0rk a) despite using Linux for 18 years, I don’t know how one is supposed to use the command-line man viewer other than scrolling up and down; it is Not Comfy and I find it a lot easier to look at html’ized versions online

b) man pages tend to be written in the spirit of “it is not, legally speaking, undocumented” with just an alphabetized wall of options that can stretch into the hundreds

@b0rk I miss a hotkey to search for "identifiers", e.g. if I want to search for `-x` I don't want to see `-X --xenomorph`. The situation is even worse for one character identifiers/symbols (think tmux, bash, etc.).

I also find it impossible to remember section/page arguments (argument order + what number means what in `man N printf`).

@b0rk Compared to programming, exposition in natural language can be considered a distinct skill altogether, needing to be honed seperately. Pedagogical materials about composing effective documentation might help those willing to learn and improve their skills.

Notwithstanding our fondness to manual pages as a representative of *nix culture and philosophy, we still have to consider the its relevance to those finding the underlying philosophy unappealing; given the volunteer-driven nature of FOSS projects, man pages are thus driven to obscurity, outside of its dedicated userbase.

In my imagined overhaul of manual page ecosystem, I would like to see (off the top of my head): a better authoring language than man(7) or mdoc(7) (while doubling down on mdoc’s take on semantic requests, unlike scdoc; see reStructuredText, AsciiDoc, Org mode or Typst for inspiration), with readable request names (even if we choose to stick to roff(7) style requests), a graphviz/mermaid like DSL to save us from manually drawing ASCII art diagrams (as much as we are fond of them), support for hyperlinks and hierarchically organized documentation (we need to do better than the friendly info, at least, all the while not turning as bloated), and so on. If there’s any interest in this direction, I’ll be quite happy to participate.

@smlckz yeah i’ve used tools to convert AsciiDoc or RST to man pages and it was a good experience, the git and dig projects use them for example if you’re interested

@amanda @b0rk Cross references, yes! How do I use those? Also, I just looked at `man man` and noticed that there is no ToC ("Is there even something about hotkeys in this thing?").