[HN Gopher] Man pages are great, man readers are the problem
___________________________________________________________________
Man pages are great, man readers are the problem
Author : WhyNotHugo
Score : 115 points
Date : 2025-04-09 13:11 UTC (9 hours ago)
(HTM) web link (whynothugo.nl)
(TXT) w3m dump (whynothugo.nl)
| amelius wrote:
| Can't we just convert all man pages to a modern format like HTML,
| and never look back?
| happosai wrote:
| Well I read man pages Via debians web server precisely because
| they are easier to read in html.
|
| https://manpages.debian.org/bookworm/manpages-dev/syslog.3.e...
|
| Bit I don't think html would be a good source format.
| oneshtein wrote:
| Try HTML version: man --html=firefox man
| Cthulhu_ wrote:
| Triggered by your "modern format" comment, if my sleuthing is
| correct, the mdoc format was first introduced with "4.4BSD"
| from 1995, with a major update in the early 2000s', whereas
| HTML was first conceptualized in the 80's with a first major
| release in the early 90's; mdoc IS the modern format.
|
| Granted, it may not be the ideal format for documentation, but
| I'd argue neither is HTML - too much cruft for reading in a
| terminal and not very ergonomic to type out. I'd argue markdown
| or something like that would be a better fit, it's got support
| for the formatting and linking needed, most developers are
| familiar enough with it, you don't actually need to parse or
| render it to be able to read it, etc.
| amelius wrote:
| From the mdoc manpage:
|
| > Many aspects of the basic syntax of the mdoc language are
| based on the roff(7) language
|
| So, I wouldn't say that mdoc is the modern format here ...
| pavon wrote:
| And the basic syntax of HTML is based on SGML which was
| standardized in 1986, and which in turn was based on GML
| and COCOA from the 1960's.
| amelius wrote:
| Yeah ok, but HTML won the heart of the modern user.
| t-3 wrote:
| HTML is easy to parse and generate. I've never seen
| anybody attempt to claim that it's enjoyable to read or
| write.
| mplanchard wrote:
| Emacs does a nice job of this, I think
| Zambyte wrote:
| Emacs also highlights how underrated info pages are. Truly a
| hidden gem.
| hirvi74 wrote:
| I truly appreciate when tools come with everything one needs
| to know about how to use them. I think it helps foster a real
| sense of sustainability.
| goku12 wrote:
| That is in line with the Free Software and GNU philosophy.
| It isn't just about making the source available to you.
| Rather, they expect that you - the user - will tinker
| around and modify it substantially to suit your needs. So
| they include practically everything needed to achieve that
| - including full documentation, developer tools, code
| introspection capabilities and sometimes even entire
| textbooks (The bundled elisp book is actually an
| introductory textbook on programming).
|
| The other GNU software all follow a similar strategy - be
| it Guix, Shepherd, Guile, Poke,... It's so pleasant to work
| with them. Too bad this approach didn't catch on.
| nemoniac wrote:
| See woman-mode in Emacs
|
| https://www.gnu.org/software/emacs/manual/html_mono/woman.ht...
| perlgeek wrote:
| Easiest solution: convert to HTML, view in browser.
|
| If that's not an option for you: the good old `info` document
| reader supports links and jumping. Somehow I never quite got the
| grasp of it though (probably because I didn't spent enough time
| with it to make it worth finding out how it works).
| tasn wrote:
| Hard disagree. Markdown is the way to go.
|
| I've been using Linux for a couple of decades at this point, and
| I've use man pages quite a bit over the years. Though even though
| man pages are not foreign to me, I think they are no longer the
| right solution to the problem.
|
| First of all, we are all used to reading documents on the web (or
| in a code editor) nowadays, so having a completely different
| interface is not great. At some point 10 years ago or so I mostly
| stopped using the `man` command and just googled for man pages so
| that I can have the interface I'm used to.
|
| Additionally, developers are very much used to markdown, and most
| other docs are written in markdown (maybe some RST, but probably
| mostly markdown) so this is not great for the person writing the
| docs either.
|
| So man pages are inferior for both the producers and the
| consumers of documentation.
| Spivak wrote:
| Is there some issue with writing your documentation in markdown
| and pandoc-ing it to the roff format? It's what I do for all my
| personal man pages and it works fine.
| __mharrison__ wrote:
| Is there some issue with pandoc-ing man files to the HTML
| format? (It's not what I do, I use man from the terminal, but
| I understand after teaching thousands that terminal mastery
| is not common.)
| bregma wrote:
| Yes. Markdown is semantics-free. The man macro set in roff is
| semantic in nature. There is no bijection.
|
| If you're writing semantic-free man pages you're already
| doing it wrong.
| lupusreal wrote:
| What most manuals on the web get wrong is not offering a
| single-page version, so you're forced to use clumsy search
| engines (on-site or third party) to search through the
| document. With manpages, the whole manual is _usually_ in one
| document. Some big programs split it, usually for the worse.
| RunningDroid wrote:
| > Some big programs split it, usually for the worse.
|
| For some reason ZSH provides split manpages and a
| concatenated manpage (zshall, iirc.) I personally just use
| the concatenated manpage
| BeetleB wrote:
| > What most manuals on the web get wrong is not offering a
| single-page version
|
| Obligatory: https://blog.nawaz.org/posts/2025/Apr/an-appeal-
| to-documenta...
| lupusreal wrote:
| > Printing out the documentation
|
| Big time. I don't do that very often anymore, but it used
| to be how I read all documentation. There is a lot to be
| said for being able to flip through physical pages with a
| highlighter in hand.
| milesrout wrote:
| You're used to reading documents on the web. I am used to
| reading them on paper, in the terminal using man (strictly,
| troff and less), in the web browser and in a split or tab in
| vim (also using troff). I wish people would stop this "we"
| business where they purport to speak for everyone.
|
| Man pages are superior because they don't give you the
| opportunity to add all the other stupid markup, animations, css
| etc people put in HTML documentation. The key thing is that
| they're consistent. Always in the same format.
|
| Man pages don't have to be in troff. And as you illustrated,
| nothing stops you from generating web pages from them.
| rglullis wrote:
| > I wish people would stop this "we" business where they
| purport to speak for everyone.
|
| That has become a strong signal regarding the (lack of)
| quality in any argument. Anyone using this cheap rhetoric
| trick gets an immediate penalty in my "how seriously should I
| take this person?" book.
| johnnyjeans wrote:
| personally i hate when i have to open a web browser to view
| documentation. it's an absolute waste with how heavy they are
| and the interface sucks. troff is a nicer markup language than
| markdown. definitely prefer man pages over anything else.
| dijit wrote:
| There was a time that web-browsers were content viewers, in
| that time they were more efficient by far than things like
| PDFs.
|
| Man pages are more efficient but difficult to print, they
| don't include hyperlinks to more context, or inline images to
| provide some kind of higher level understanding.
|
| Web browsers became application distribution platforms, and
| thus; I agree with you- they're _really_ heavy for just
| document viewing these days.
| graemep wrote:
| Someone needs to devise software and a standard for viewing
| documents over the internet.
| hulitu wrote:
| > Web browsers became application distribution platforms,
| and thus; I agree with you- they're really heavy for just
| document viewing these days.
|
| Too bad they are crap at printing. Apparently rendering on
| the screen and rendering an image are two completely
| different things.
| pornel wrote:
| Markdown is semantically less expressive than man's markup. man
| goes into details like explicitly marking up command's
| arguments.
|
| You can convert man to Markdown easily using full capabilities
| of Markdown, but Markdown lacks semantic information to be
| converted back to fully-features man document.
|
| If we had _good_ man viewers that have consistent level of
| support, then man would be a better data source format.
|
| Unfortunately, there's no way to know what features man viewers
| support, and AFAIK no good ways to provide graceful fallbacks.
| This is most broken with tables and links that have dedicated
| markup, but are not rendered in common setups.
| KerrAvon wrote:
| But the various man source formats aren't semantic markup of
| any particular use. Yeah, you can ensure that all of your
| arguments are typeset as italic or something, but it's not
| consistent because there are different source macro packages
| and they do different things.
|
| If there was useful semantic markup, it'd be great, because
| you could imagine, for example, tools allowing you to
| generate commands on the user's behalf. But the man source
| formats are mostly, at core, typesetting for 70's typesetting
| machines, not intended for modern reference documentation.
| bentley wrote:
| mdoc(7), which is the primary macro set used on BSD
| systems, is a 90s language (as opposed to a 70s language)
| with useful semantics that support both hyperlinking and
| featureful search, both on the web and in the terminal.
|
| For example, here's a search for "C functions beginning
| with 'str' and with return type size_t": https://man.openbs
| d.org/?query=Ft%3Dsize_t+-a+Fn~^str&apropo...
|
| On OpenBSD you can do the same from a terminal:
|
| $ apropos -s 3 Ft=size_t -a Nm~^str
|
| But the biggest value of manpages to me is somewhat
| independent of the underlying format: its quality as
| documentation. BSD systems have a strong tradition of
| cohesive usability, including good manpages. A lot of the
| manpage alternatives I see advertised in Linux circles
| (such as tldr pages or bro pages) are of little use to me,
| because OpenBSD manuals are thoughtfully written, clear,
| concise, complete, and have useful examples. The difference
| is very noticeable when I try reading manpages for programs
| I've installed from packages, which are often incredibly
| sparse or incredibly verbose, and lack examples in both
| cases.
|
| The nifty features that come from the modern language and
| tooling used by BSD manpages are really just symptomatic of
| the overall care that BSD communities put into their
| documentation generally. I wish it were more widespread in
| the free software world.
| juped wrote:
| "whatis -O In [some c library function]" is a very handy
| one
| bentley wrote:
| That's way better than my example!
| thangalin wrote:
| > Markdown lacks semantic information to be converted back to
| fully-features man document.
|
| Core Markdown, yes. Pandoc has a fenced div extension that
| can capture the semantic meaning. :::
| Warning ::: This is a warning. ::: Danger
| This is a warning within a warning. ::: :::
|
| Not suggesting that Markdown is the right tool, only that it
| has extensions to capture semantic meaning. Here are example
| documents produced using Markdown:
|
| * https://impacts.to/downloads/lowres/impacts.pdf
|
| * https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software
| _...
|
| * https://dave.autonoma.ca/blog/2020/04/28/typesetting-
| markdow...
|
| * https://gitlab.com/DaveJarvis/keenwrite-
| themes/-/blob/main/e...
| sgarland wrote:
| > Hard disagree. Markdown is the way to go.
|
| As other child comments have stated, this is entirely
| subjective, and many would disagree with you (myself included).
| I live primarily in the terminal, and the ability to seamlessly
| look up syntax, flags, features, etc. without ever leaving the
| keyboard is wonderful. Additionally, I agree with milesrout
| that I do not want emoji, animations, etc. in my manuals (nor
| my terminal). I want searchable text. I also agree with
| lupusreal that having a single large page, at least as an
| option, is ideal.
|
| A perfect example of the two approaches is HAProxy. Here [0] is
| their commercial site. It's very flashy, modern web, etc. I
| don't necessarily hate it, but it's definitely designed to get
| the attention who may not necessarily know what they want, and
| can be sold to. In comparison, here [1] is their community
| site. It is extremely Web 1.0, and I love it. Everything you
| need, nothing you don't. Similarly, their docs [2] are [3]
| logically [4] split, and manage to be readable, navigable, yet
| information-dense. I don't need a tutorial with code snippets
| every few paragraphs in my docs.
|
| > Additionally, developers are very much used to markdown, and
| most other docs are written in markdown (maybe some RST, but
| probably mostly markdown) so this is not great for the person
| writing the docs either.
|
| Web devs, perhaps, though I imagine there's more variety than
| you think. Kernel devs likely do not have the same opinion as
| you (though I do not wish to speak for them, as I am not a
| kernel dev). I've seen the same argument against the build and
| packaging process for Linux distros, like Debian. "Why is so
| much of this in Perl," "why are there so many bash scripts,"
| etc. Because that is what the original developers wrote it in,
| it works well, and at this point is largely bug-free.
| Drastically changing something to suit the tastes of some at
| the risk of introducing errors is not a reasonable strategy.
|
| [0]: https://www.haproxy.com
|
| [1]: https://www.haproxy.org
|
| [2]: https://docs.haproxy.org/3.1/intro.html
|
| [3]: https://docs.haproxy.org/3.1/configuration.html
|
| [4]: https://docs.haproxy.org/3.1/management.html
| 0x0203 wrote:
| I am a kernel dev and you've captured my thoughts on the
| matter quite well. I would very much rather stick with man,
| even with the deficiencies the article discusses, than use
| markdown and web.
| KerrAvon wrote:
| It doesn't have to be either/or. You can generate a rich
| format to mdoc. I'm not completely convinced markdown isn't
| sufficient, but it doesn't have to be markdown.
| znpy wrote:
| Having been using Linux for a couple of decades as well, i'd
| never give away manpages in the terminal.
|
| Any time i need a quick refresher ("was it -f or -F?") i can
| just pause the current editor (ctrl-z) look up the manpage (man
| <whatever>), exit (q) and then go back (fg) to whatever i was
| doing.
|
| Having a web browser is just useless annoyance in the workflow.
| spudlyo wrote:
| I find it weird that most of my younger colleagues totally do
| not understand job control, and generally use just a subset
| of shell features in their day to day development work. I
| would wager they also don't value man pages. I remember the
| blank stares I was met with when I suggested we create a man
| page for an extremely complex CLI tool we maintain.
|
| There was already an often out of date wiki page that people
| hated maintaining, nobody could understand why you wouldn't
| just use that.
| homebrewer wrote:
| This is not necessary, man-db can automatically convert your
| man pages into HTML and show them in your preferred browser:
| $ man --html man
| jandrese wrote:
| Basic Ubuntu 24.04 install: man --html man
| man: can't resolve man7/groff_man.7 man: command
| exited with status 3: (cd /tmp/hman6rTowJ &&
| /usr/libexec/man-db/zsoelim) | (cd /tmp/hman6rTowJ &&
| /usr/libexec/man-db/manconv -f UTF-8:ISO-8859-1 -t
| UTF-8//IGNORE) | (cd /tmp/hman6rTowJ && preconv -e UTF-8) |
| (cd /tmp/hman6rTowJ && tbl) | (cd /tmp/hman6rTowJ && groff
| -mandoc -Thtml)
|
| The error seems to be about the groff manpage that I didn't
| even ask for? Very confusing.
| kevin_thibedeau wrote:
| Which Markdown? That is the problem with Markdown.
| BeetleB wrote:
| Whatever. As long as I can view it easily in Emacs (ideally
| using their info tool), I'm good. :-)
| sjmulder wrote:
| It's a shame so many web versions of man pages are typeset with
| monospace fonts and barely any formatting. The mandoc-powered
| OpenBSD online man pages are great though:
| https://man.openbsd.org/acme-client
|
| Still I also really like being able to read man pages in the
| terminal. Getting a bit familiar with less helps to make it
| convenient. I mostly use the search features (/ and ?) and half
| page scrolling (d an u).
| cassepipe wrote:
| I should add that it supports j/k for scrolling line by line
| lupusreal wrote:
| Man pages are nice to read but a pain in the ass to write (unless
| you're using modern tools that convert markdown/etc to the
| manpage, which honestly, you should be doing.)
| shadowgovt wrote:
| ... at which point, one does wonder why we use man at all
| instead of markdown.
| lupusreal wrote:
| Conventions matter, manpages get indexed so you can access
| them easily with man readers. With raw markdown docs I have
| to go searching for the documentation myself.
| shadowgovt wrote:
| True, but I don't think the gap on indexing Markdown docs
| is very large.
|
| In fact... man already supports two parsable languages for
| the pages themselves. It could, hypothetically, support
| three.
| Jenk wrote:
| I page man (and many other things) through bat[0] which improves
| my experience.
|
| [0]: https://github.com/sharkdp/bat
| vages wrote:
| I use batman from bat-extras[0]. It may very well be the best
| named command line utility I know.
|
| [0]: https://github.com/eth-p/bat-extras
| kstrauser wrote:
| What do you prefer about that? I already use bat for syntax
| highlighting but haven't used it as a pager.
|
| Edit: Oh! That's pretty. Details are at
| https://github.com/sharkdp/bat?tab=readme-ov-file#man
| WhyNotHugo wrote:
| This approach discards all mark-up, which bat tries to re-build
| with some heuristics. It works for the basic case, but not
| beyond that.Subsections get mangled (see sway-ipc as an
| example). Links disappear completely of course, since they
| don't even reach bat.
| DadBase wrote:
| Exactly. The problem isn't the man pages, it's that folks stopped
| reading them with a highlighter and a cup of day-old coffee.
| That's how you retain flags.
| hirvi74 wrote:
| If one wants to retain flags, then why not redirect the output
| a man page to a text file and using an editor to make
| highlights?
| DadBase wrote:
| Tried that once, opened the file in vi, blinked, and somehow
| mailed it to my dentist. Highlighter never did that.
| fred69 wrote:
| Success! Coffee through nose achieved.
|
| Printouts, usually many of them, are the original
| "overlapping windows".
| DadBase wrote:
| Exactly. I used to stack printouts on the floor in
| layers. Top one was active, bottom one was swap. If you
| walked too fast past my cube, you'd trigger a context
| switch.
| cassepipe wrote:
| As a vimmer I was glad to discover that `less` supports j/k
| scrolling, search with / + n/N, gg and G.
|
| A neat trick is : export MANPAGER="less
| --incsearch"
|
| which mimicks the behaviour of `:set incsearch` in vim and allows
| you no quickly move around
|
| It really increased the usefulness of man pages by a lot for me.
|
| `info` has a vim mode but it's more obscure to me how to use it
| properly
|
| Any other useful tricks ?
|
| Edit: s/man/less
| blueflow wrote:
| What you are referring to is not done by `man`, but by `less`.
| The pager that `man` uses is configurable.
| cassepipe wrote:
| I stand corrected
| yoyohello13 wrote:
| Neovim supports use as a manpager: export
| MANPAGER="nvim +Man!"
|
| You get all the vim movement/search and highlighting.
| cassepipe wrote:
| Even better, thank you for the tip
| blueflow wrote:
| I disagree. I have been writing man pages for a while, and
| mastering the language is hard. The documentation for both mdoc
| and mandb format is not covering the whole language, and the only
| remaining reference for roff itself seems to be the book by Brian
| Kernigham. mdoc and mandb are like a macro set on top of roff.
|
| Just this week i considered proposing to $distro to convert all
| manpages to markdown as part of the build process, and then use a
| markdown renderer on the shipped system to display them. This
| would allow the distro to stop shipping *roff per default.
|
| Markdown profits from the much larger amount of tooling. There
| are a ton of WYSIWYG editors that would allow non-technical users
| to write such documentation. I imagine we would all profit if
| creating manual pages was that easy.
|
| On the other side, Markdown is even less formalized. Its like 15
| different dialects from different programs that differ in their
| feature sets and parsing rules. I do not believe things like "How
| do i quote an asterisk or underscore so it is rendered verbatim"
| can be portably achieved in Markdown.
| thechao wrote:
| Yeah. Without even looking at google, I bet there's a "mandown"
| project that formalizes markdown with man extensions.
|
| The irony of the poor state of affairs of the quality of
| documentation for mdoc & mandb are not lost on me.
|
| EDIT: couldn't resist. There's at least _two_ mandown projects.
| mattkrause wrote:
| It's such a good name that, once you thought of it, you'd
| almost be obligated to start writing the code.
| packetlost wrote:
| scdoc makes writing man pages a lot more pleasant:
| https://git.sr.ht/~sircmpwn/scdoc
| blueflow wrote:
| Until i use it "wrong" and Drew does the Drew thing with me,
| like he did with the hyprland guy. No thanks.
| packetlost wrote:
| I'm not a fan of Drew's political grandstanding (or views,
| in some cases) but scdoc is good and packaged in many
| distros. There's no foundation for him to abuse with it, so
| it's safe.
| pkal wrote:
| The IRC bouncer Soju uses scdoc and this has been
| personally annoying, as I refuse to install it just to
| build semantically less expressive documentation than
| when using the very well documented
| (https://mandoc.bsd.lv/man/mdoc.7.html) mdoc format. I
| asked the maintainer if they were interested in a
| contribution to translate it, and they just dismissed it
| out of the box.
| packetlost wrote:
| Who cares how expressive it is? It hits all the core
| pieces of formatting you can realistically do in a
| terminal using syntax that is familiar to a much wider
| range of developers. The output is completely usable and
| reasonable. I'd rather use something closer to markdown
| than roff macro gunk that is largely irrelevant anywhere
| else.
| homebrewer wrote:
| adoc is fine and is more widely supported. Linux (the kernel)
| documentation is written in adoc, along with man pages for
| many projects like git:
|
| https://github.com/git/git/blob/master/Documentation/git-
| rm....
| packetlost wrote:
| I wasn't aware AsciiDoc could be used to generate man docs.
| I'm not a huge fan of AsciiDoc's syntax, but I can see that
| being preferable to other options.
| WhyNotHugo wrote:
| Asciidoc doesn't support links in man pages. It can only
| link to URLs. If you check the repo which you linked,
| you'll see they use some perl code to actually inject
| links.
| WhyNotHugo wrote:
| I've used it quite a bit. It doesn't support links to other
| pages nor links to other sections. Which arguably is fine,
| since man page readers don't render them anyway, but HTML
| renders also suffer because of this.
| alabastervlog wrote:
| Even the most vanilla of markdown (the Daring Fireball kind)
| means committing to a good chunk of a Web rendering stack.
| You'd need some pared-down version.
| rollcat wrote:
| I don't think Markdown is the right language to solve these
| problems. As you've noted, it's not standardised at all, and
| you'd have to pick an interpreter that everyone could agree on
| (and that means C).
|
| Markdown also doesn't do semantic references. It does do plain
| links, you can give them a title; or you can use a default
| title, so perhaps you could infer the semantics from the
| context, maybe like: Use the flag [-R][] to
| recursively apply to all files and subdirectories.
| Please refer to [chmod(2)][] for the details.
|
| But that feels like overloading one kind of syntax with so many
| different meanings. Take HTML as a counterexample, it has <link
| rel="...">, which fits neatly into the rest of the language.
|
| Why do these semantics matter? Well, you can obviously render
| roff into HTML and browse the man pages online; also, someone
| _ought to_ write a simple _and_ smart pager that can follow
| these references (Emacs doesn 't count as simple).
|
| Anything that aims to replace roff should preserve its most
| important features, have a proper formal spec, and be easy to
| write a parser for - in super plain dumb C/flex/yacc.
| tgv wrote:
| Semantics also matter for the apropos/whatis database. Not
| sure how many people know about them.
| delusional wrote:
| I only knew `apropros` from gdb. It looks pretty neat as an
| alternative to googling that function i never remember the
| name of.
|
| Thanks :)
| MyOutfitIsVague wrote:
| RST/Sphinx solves that problem in that there is a single
| canonical dialect, and it's already effectively used in many
| very large projects, including the Linux kernel and (obviously)
| the Python programming language.
| arnsholt wrote:
| Another big plus in my book is that rST has a much more well
| defined model for extensions than Markdown.
| tgv wrote:
| If you want to know more about nroff (which is what man calls
| when you want text output, I believe), then you could e.g. read
| https://www.nesssoftware.com/home/mwc/doc/coherent/manual/pd...
| , or https://www.quut.com/berlin/ms/troff.html. It's terse,
| like nroff itself.
|
| I think people tried to convert man pages by redefining the
| macros and then let nroff produce the output.
| jandrese wrote:
| As noted there are already HTML versions of the manpages that
| work without apparent issue. It makes me think about having the
| documentation converted to html and then have a thin script
| that invokes w3m on the correct file.
|
| Then again GNU tried something similar with the info pages and
| it never really caught on. I think that was more due to the
| info program being kinda hard to use and the search facility
| being awkward.
| PhilipRoman wrote:
| man -H
| WhyNotHugo wrote:
| > It makes me think about having the documentation converted
| to html and then have a thin script that invokes w3m on the
| correct file.
|
| `mandoc -T html` will do this for you with functional links
| between man pages and links to sections inside man pages.
| taeric wrote:
| GNU trying with info pages was largely hampered by the
| fragmented UNIX world of the day? I seem to recall various
| UNIX controllers were far more active in standards and such
| than they seem to be today. Specifically, I don't think any
| one company had the dominance that would be needed to drive a
| large migration.
|
| Not that I'm certain that company exists today. There does
| seem to have been more consolidation than we had back then.
| cafard wrote:
| I didn't think info was at all bad. But the boss who had
| responded 'uh-hu' to a demo of documentation in Linux,
| responded 'Wow!' to the same document converted to HTML and
| displayed in Mosaic. These days, I suppose that I only see
| info in connection with Emacs.
| WhyNotHugo wrote:
| Sounds like your major gripe with mdoc(7) is that lack of
| better documentation for the format and a shortage of tools to
| generate it. I agree on this second item, most tools don't
| support adding cross-references / links.
|
| At this point, markdown is 12 different standards, some of
| which even diverge on the most basic things like their
| treatment of newlines and how to wrap text. But even so,
| markdown provides mark-up for styles, with no semantic meaning.
| mdoc has macros to mark-up flags, optional flags, arguments,
| environment variables, files, etc. How to format this depends
| on the reader, and we can have _much_ richer readers than we do
| right now. Simply converting man to markdown discards most of
| this information.
|
| A new format isn't going to help solve this; what we want is
| better guides and tools for produce high quality mdoc pages.
| kccqzy wrote:
| On macOS you can format the man pages into a PostScript which can
| be distilled into a PDF by Preview and then opened there. PDFs do
| support links for cross references. On Linux you can do the same
| except you will probably need to manually install ghostscript for
| the distillation and evince or something similar to view it.
|
| This should not surprise anyone because roff is originally
| designed to be a typesetting tool and the man pages are naturally
| printable as a nicely formatted document.
| frou_dh wrote:
| https://kapeli.com/dash for MacOS supports man pages just like
| any of its _many_ other documentation sources. Simply type
| `man:foo`. Absolute hall of fame app IMO.
| tengwar2 wrote:
| PostScript: this is how I solve the biggest problem I see. I
| don't care about linking to other pages. I don't care about
| reflowing. I care very much that if you use man in the
| terminal, the output is really hard to read other than for
| short man pages. man bash, for instance, is something you could
| reasonably want to read, but it's about 5000 lines long and in
| the terminal it's hard to see the organisational structure.
|
| Reformatting as Postscript shows the pages they were meant to
| be. I started as a Sun admin, and we used to have paper
| manuals, properly typeset - and that's what you get when you
| use Postscript as the output.
|
| For Unix/Linux users - investigate "man -t".
|
| However - MacOS doesn't support reading Postscript now. It used
| to, but the feature was removed from Preview. At the risk of
| teaching multiple grandmothers to suck eggs, I use this script:
| manps () { if [ -z "$1" ] then
| echo usage: $FUNCNAME topic echo This will open
| a PostScript formatted version of the man page for \'topic\'.
| else man -t $1 | ps2pdf - | open -f -a
| /System/Applications/Preview.app fi }
|
| where ps2pdf comes from Homebrew.
| wpm wrote:
| Preview can no longer directly open .ps files.
|
| For shorter man pages, I use the Terminal apps "Man Page"
| profile which you can get to by right clicking the command
| name, and selecting "View man page". Then, scroll to the bottom
| to render the entire thing, and Command+P > Save to PDF.
|
| For long shit, parts will get truncated (overfilling the
| scrollback? I have no clue), so I have to export the ps with
| man and convert to PDF with ps2pdf. This puts everything in a
| basic Times New Roman font and I hate it. Much preferred when I
| could directly open the output on the Mac.
| jordemort wrote:
| I like pinfo for this (although it is primarily intended for
| viewing GNU Info pages, it can also display man pages):
| https://github.com/baszoetekouw/pinfo
|
| Using it feels a lot like lynx. It recognizes cross-references
| between pages and allows you to navigate through them, as the
| author of this post requests.
| 77pt77 wrote:
| Has also been around for several decades
| kevin_thibedeau wrote:
| This is how I get a better _man_ : alias
| man='pinfo -m'
| krick wrote:
| Honestly, no. They are not great, and it's getting silly to
| pretend they are. If they were, we wouldn't have stuff like tldr,
| cheat, bropages, and a good half of StackOverflow wouldn't exist
| as well, let alone LLM tools to translate your verbal request to
| half-broken ffmpeg command.
|
| Man readers suck, man pages suck too, man markup language sucks,
| the contents of a typical manpage suck.
| shadowgovt wrote:
| Fundamentally, the problem is that manpages are a framework
| (and not actually a bad one, if everyone where to adhere to it
| and populate every section), but writing good documentation is
| an art and not a well-taught one.
| teddyh wrote:
| > _writing good documentation is an art and not a well-taught
| one._
|
| Some recommendations here:
| <https://www.gnu.org/prep/standards/html_node/GNU-
| Manuals.htm...>
| MaxGripe wrote:
| I prefer Markdown :(
| kazinator wrote:
| I have a man page reader which remembers the position you were in
| the last time you read the same man page. There is nice syntax
| highlighting.
|
| Also, you can jump to other man pages, because it's just using
| Vim.
|
| In Vim, you can use K to open a man page for the word under the
| cursor. You can prefix that command with a section number.
| Something could be hacked to scrape that from the parentheses
| after the word.
|
| https://www.kylheku.com/cgit/mnpgr/about/
| tomxor wrote:
| > In Vim, you can use K to open a man page for the word under
| the cursor
|
| Holy crap! TIL, and I've been using vim for a decade.
| saagarjha wrote:
| Man reader here. I largely agree, I'm not very good at reading
| documentation.
| neuroelectron wrote:
| Gnu and its associated tech is basically shit. Its arcane,
| awkward, and sometimes self-defeating aspects is only matched by
| its ugly naming. Stallman's obsession with purity over pragmatism
| has kept GNU projects stagnant. I don't think it's the terminal
| interface that is a problem. The entire smell is unapproachable
| and just plain weird for real-world users and devs.
|
| Look at thus coreutils guide:
| https://www.gnu.org/software/coreutils/#mailinglists
|
| This is for general help. Mailing lists. Can you think of a less
| productive way to manage this type of information? Sending an
| email to the void and siloing it in a specific reader? No HTML
| allowed?
|
| Yes, "man" pages are annoying to use and not helpful but that's
| been true for decades. Have you tried apropos? Does git really
| need to be so difficult?
|
| I understand creating a barrier to entry but does that even work?
| Has it been effective in increasing the quality of Linux tooling?
| Is Linux even a good ecosystem? When you see modern projects like
| systemd, what do you think?
| shadowgovt wrote:
| I think you're conflating a few pieces of the ecosystem.
|
| Linux (and GNU/Linux, and POSIX, and the tools that run on and
| through them) have the same great strength and great weakness:
| they aren't _owned_ by anyone. To a first approximation, the
| only thing that gives them consistency is some loci of
| discourse and consensus built up around some charismatic
| leaders (Torvalds, Stallman). But the end result is that nobody
| 's actually in charge of making all this stuff work together
| "all of the time or we don't ship," which means... It all kind
| of works, most of the time, with some weird corner cases that
| make a person dig _deep_ into some historical interactions to
| fix it (TIL that manpages aren 't even all in the same
| language, or that `man` does more that pop a file open and dump
| it raw to the terminal).
|
| ... but on the flip side, there's no artificial barrier to
| entry. If you want to get started, you can download a distro
| onto a machine willing to accept some media that will overwrite
| its boot rules and get started. And that's extremely powerful.
|
| The Linux ecosystem is awful and weird and gross and arbitrary
| and broken... And beautiful. And it's not going away anytime
| soon because it's free (beer and usually speech). The
| alternatives can't replace it because they generally lack the
| incentives to be as open and fast as the incumbent ecosystem;
| they either aren't free (beer or speech), so already constrain
| their domain to people willing to pay... Or they are too
| different (even if different in a better way), and therefore
| don't interoperate with the software that's already there and
| have a labor shortage (having an ecosystem that mostly works
| most of the time creates a positive feedback loop on improving
| it that is missing in the attempts to burn it down and replace
| it).
|
| (Side-note on git: while I concur that git out of the box
| doesn't make it obvious the right way to use it... In fact,
| there is no one right way, that's the thing about git... I've
| used four version control systems in my day, and git's the only
| one I've ever used where there _was_ a way to do what I wanted,
| _every time._ The flexibility of its abstraction makes it
| tricky to delve into but powerful).
| NoSalt wrote:
| I would also suggest that man pages need examples. Oftentimes,
| what is required, and how it is required, is not very clear, and
| examples would go a long way towards helping people more.
| Granted, some man pages do have examples, but not near enough do.
| seri4l wrote:
| I agree. In case you haven't heard of it already
| https://tldr.sh is pretty good for this.
| criddell wrote:
| Is there a local AI that could provide a more modern interface to
| the information buried in man pages?
|
| Sometimes I don't even know where to start and that's why I end
| up in Google or on StackOverflow.
|
| I'd like to be able to type "hey man, how do I show all the
| bootable partitions on my drive?"
| pjmlp wrote:
| There are tons of X Windows readers for man pages, none of them
| referred on the article, maybe that is already the first problem.
| gnuser wrote:
| Gnu info for anything gnu, then man pages, then tools like tldr
| teddyh wrote:
| * Info1
|
| * Gnome Devhelp2
|
| * Zeal3
|
| * Local RFC archive4 dumps (by Debian5)
|
| * Man pages
|
| 1. https://www.gnu.org/software/emacs/manual/html_node/info/
|
| 2. https://wiki.gnome.org/Apps/Devhelp
|
| 3. https://zealdocs.org/
|
| 4. https://www.rfc-editor.org/
|
| 5. https://tracker.debian.org/pkg/doc-rfc
| ksynwa wrote:
| My dream feature in man page readers is to somehow go to the
| description of a specific flag. Maybe it already exists and I
| don't know about it. But as of now I resort to regex hacks like
| searching for `^\s+-p` or `, -p` to find where the flag is
| described.
| shadowgovt wrote:
| As far as I can tell, this is _the_ missing feature: flags
| definitions are extremely semantically meaningful to humans and
| not even `mdoc` has expliict semantics for them (the closest
| you can get is that the pattern `.It Fl A` almost always means
| "the -A flag's definition", especially if it's in the
| DESCRIPTION section, but that's not a hard-and-fast rule).
|
| And of course, even if your pager isn't `less`, by the time the
| content has been fed through `man` itself it's been crunched
| into a terminal representation, not a semantic representation.
| You'd have to `man -w whatever` to get the raw file and parse
| it yourself (and handle whether it's mdoc or man format, etc.).
|
| The regex you have keyed that matches to "What these flag
| definitions usually look like on the terminal" is almost
| certainly the saddle-point solution between using the tooling
| as it is and burning it to the ground to build something
| better.
| ryandrake wrote:
| I'd love to be able to type: man ffmpeg
| "-ss"
|
| And have it jump right to the -ss option so I can see the
| expected format. For me the 99+% use case of man is to look
| up parameters of a command line or parameters of a
| programming function call. It's shocking that the UX for what
| I presume is the single most used use case is so broken.
| sudahtigabulan wrote:
| Does searching with /-ss not do this well enough?
|
| For options, the first hit often is the description. When
| it's not, filtering with & can give you an idea how much
| further it is, so you can repeat the search with n.
|
| It's not an exact, "semantic" jump, but I find it good
| enough.
| ryandrake wrote:
| Sometimes it works, sometimes it doesn't. Sometimes the
| application has options like -o and --original and
| --output, and they are littered throughout the man page,
| so if I only want -o, I'm getting dozens of false
| positives.
| AStonesThrow wrote:
| You know, I cut my teeth on AT&T SVR3. I loved reading up on
| the basic tools and learning their options and then putting
| them into everyday practice.
|
| In those systems there were far fewer tools, far fewer
| options, and much simpler workflows, so honestly I didn't
| _need_ to endlessly flip through manpages to sift out
| hundreds of options with arcane, incompatible, unintuitive
| syntaxes. The few options we needed to memorize were always
| paired with consistent syntax and impeccable mnemonics to
| remember (who can forget 'ls -l' or 'rm -f'?)
|
| Ironically, 'vi' was already quite evolved, complex, and
| arcane by this point, but that was completely different: it
| was required for us to acquire proficiency in order to code,
| and it was easy to build skills from basic to expert/power,
| and all 'vi'-editing commands still featured those
| standardized mnemonics and consistency that can only come
| from a proprietary single-entity codebase. Plus all possible
| legacy compat with 'ed' which nobody used directly anymore!
|
| So while we may today consider this a lacuna in the reader
| tool, it wasn't by design, and I blame the explosion of "GNU
| long options" and lack of standardization, more than
| anything. But also 'tar' and 'ps' and BSD vs. the world. Eff
| those guys.
|
| https://m.xkcd.com/1168/
| bentley wrote:
| It's fun to compare BSD alternatives to GNU software and
| BSD documentation to GNU documentation. For example,
| OpenBSD refused to integrate GnuPG for package signing due
| to its complexity, instead developing its own signify(1):
|
| https://man.openbsd.org/signify.1
|
| https://www.gnupg.org/documentation/manuals/gnupg24/gpg.1.h
| t...
|
| Oops, sorry, this is GNU software, so we need the real
| documentation from texinfo:
|
| https://www.gnupg.org/documentation/manuals/gnupg/
|
| GnuPG certainly has more features. Does that make it better
| software? For checking signatures (the only thing I've used
| GnuPG for in 15 years), I find the signify(1) documentation
| more readable and the signify(1) tool more usable.
|
| Or how about tar(1), everyone's favorite punching bag due
| to its weird options?
|
| https://man.openbsd.org/tar.1
|
| https://manpages.debian.org/bookworm/tar/tar.1.en.html
|
| https://www.gnu.org/software/tar/manual/tar.html
|
| Yikes!
| MrDresden wrote:
| I would recommend 'manly'[0] for that. It's a super convenient
| tool for looking up descriptions for specific flags.
|
| No affiliation, just an avid user.
|
| [0]: https://pypi.org/project/manly/
| WhyNotHugo wrote:
| The `.Fl` macro identifies flags in mdoc, so what you're asking
| for is perfectly doable.
| bentley wrote:
| This feature exists, on systems that use _mandoc_ as the
| default manpage formatter _and_ viewer (such as OpenBSD).
|
| In HTML output, definitions for flags, environment variables,
| and other such things are converted to hyperlinks, and
| hyperlinks can point directly to them.
| https://man.openbsd.org/ssh#D
|
| In terminal output, this same capability is used to create a
| ctags file, which is supported by less(1). On OpenBSD, I can
| type "man ssh", then :tD to jump to the tag named "D".
|
| This relies on the mdoc(7) language's semantics, so
| unfortunately it won't work for manpages using the older man(7)
| macros. But nearly all BSD manpages are written in mdoc(7), and
| a significant minority of manpages from packages.
| SoftTalker wrote:
| Yes, ctags is not full hyperlinking but is is quite helpful
| for navigating a single man page in the terminal.
| shadowgovt wrote:
| Interesting! I never thought about the issue being the reader
| treating it as just strings and making that an ill-fit for the
| problem domain.
|
| My bugbear with man is that the only way to find a particular
| flag is via string search, so if I want to find out what "-c"
| does I'm going to bounce off of every hyphenated word starting
| with "c" in the file. Turns out `mdoc` makes it extremely easy to
| find those flags (they're all `.It Fl <whatever>` macros), but by
| the time it gets all the way to `less` that detail has been
| squeezed right out of the file.
|
| Emacs manpage display is like 90% of the way there but lacks a
| function to "find flag in file;" I should look into how hard that
| would be to hack in.
| bentley wrote:
| On systems that use the _mandoc_ implementation of the man(1)
| command, these semantics are preserved and accessible from
| within less(1). See my other comment:
| https://news.ycombinator.com/item?id=43634894
| SuperNinKenDo wrote:
| I's be inclined to agree, but having tried to use Emacs man and
| woman modes for viewing manpages, I wonder. There's always
| something broken.
| tomxor wrote:
| Expanding on pjmlp's comment [0] buried in this thread:
| export MANPAGER="nvim +Man!"
|
| Using Vim's built in ft-man-plugin [1] as the default man pager
| seems to go pretty far towards resolving what the author is
| complaining about.
|
| Links work, and it respects the indentation when soft wrapping
| lines. It isn't doing full reflow or regenerating the page, but
| it maintains legibility while soft wrapping, and messing up
| indentation is my main annoyance with less... You can improve
| less by chopping lines -S by default, but then you have
| horizontal scrolling so neither is great.
|
| [0] In Vim, you can use K to open a man page for the word under
| the cursor
|
| [1] https://neovim.io/doc/user/filetype.html#ft-man-plugin
| impalallama wrote:
| the crawlers are working hard today because I got lead here
| just by searching for a better man page on kagi
|
| I liked the idea of using nvim but i rewrote it with bash
| function for easier argument handling nman () {
| if [ $# -ne 1 ]; then echo "Usage: nman <command>"
| return 1 fi command nvim "+hide Man $1" }
| dannyfritz07 wrote:
| Thank you for this. This is actually quite marvelous.
|
| Here is what I'm using for fish: if type -q
| neovim set -gx MANPAGER "nvim +Man!" #
| abbr --add man --set-cursor "nvim \"+hide Man %\"" end
|
| I can finally retire fisher and decors/fish-colored-man.
| jasonjmcghee wrote:
| I found reading man pages with syntax highlighting to help just
| enough to make them readable for me.
|
| You need bat installed- and then you can set the manpager in your
| rc.
|
| (But as an example it's doing) MANPAGER="sh -c
| 'col -b | bat -p -l man'" man tmux
| taeric wrote:
| Getting used to browsing info pages in Emacs is something that is
| rather nice. You can do similar with man pages, there. Often
| times, it will let you jump directly to the source code of
| includes and such, if you want to take a peak at the actual code.
|
| To that end, I fully agree with the idea. The richness of
| existing man pages is far nicer than many people seem to realize.
|
| I do find a bit of dismay at the folks that want to ditch some of
| that richness and move to markdown or similar. That lets you
| layout some things fine, I think. I am 100% convinced that as you
| try to get all of the linking and general semantics of the
| existing solution done, you will find that you have added a lot
| of "schema" expectations to markdown that isn't there by default.
| And then you will start to build "markdown schema" tools to check
| that what you have fits some standards. And then...
|
| Seriously, just look at a lot of the data that moved to JSON from
| XML. I saw they are trying to add namespaces to JSON in some
| projects. Truly terrifying to see people slowly and poorly add
| the features of the more complicated thing they avoided the first
| time around.
| HankB99 wrote:
| Will I be struck down or downvoted into oblivion if I mention
| man2html? Definitely not light weight since it also installs
| Apache, but I do like to view man pages in the browser. I think
| 'python3 -m http.server' could be substituted for the server and
| perform well enough for a single user system.
|
| It's unfortunate that Markdown isn't better standardized so it
| could be extended to better meet the needs for man pages. (Do we
| need a new standard to rule them all? Yes, I'm thinking of the
| XKCD comic.)
| foxyv wrote:
| Markdown, Markdown Extended, GLFM, Mediawiki Markup, Asciidoc,
| reStructuredText (RST), Pandoc, Mundimark, Djot, Creole,
| Textile, BBCode, Dendron, Pendown.
|
| I bet at this point if you came up with a new completely
| independent standard it would probably match one of the ones
| already created. We mostly just have to pick one.
| graemep wrote:
| I find KDE Help centre makes a good man page reader: pleasant to
| read, searchable, and references to other man pages are links (I
| do not think references within the page a links though).
| Pxtl wrote:
| Imho, fundamentally man pages fail because they're generally a
| bunch of descriptive front-matter and then an exhaustive list of
| parameters, when 99% of time users want to do some of the most
| common actions with this tool and so the first things shown
| should be explaining how to do common workflows with examples.
| jmclnx wrote:
| OpenBSD man pages are great. NetBSD and FreeBSD are a close
| second. Linux man pages stink.
|
| Many Linux man pages points to info(1). Nothing is worse than
| info. I would rather search facebook for help on Linux than use
| info :)
| teddyh wrote:
| If you have ever used the terminal-based standalone "info"
| program, please try to forget all about it. Use Emacs to read
| Info documentation, and preferably use a graphical Emacs
| instead of a terminal-based one; Info documentation
| occasionally has images.
|
| Also, the enforced structure of man pages does not encourage
| good documentation:
| <https://news.ycombinator.com/item?id=6655417>
| yyyk wrote:
| If you're thinking of man readers, do consider the mandoc
| (previously mdocml) project. By treating the page semantically
| (rather like a macro language), it can achieve better results
| (pretty HTML output, even markdown output!).
|
| https://mandoc.bsd.lv/man/mandoc.1.html
| mmphosis wrote:
| I've mostly abandoned man pages. The manual is contained within
| the program: program --help
| bentley wrote:
| I hate --help.
|
| First, I hate having to run the program. If I wanted to refresh
| myself on the shutdown command, running "shutdown --help" would
| make me extremely nervous!
|
| There have been times where I've only had source code and
| wanted to read the documentation before taking the time to
| compile it or install dependencies or whatever. With a manpage
| I can just pipe it through mandoc.
|
| Sometimes --help output is short, sometimes it's 150 lines long
| and scrolls off my screen. So I hit up, end, |less, and I get
| nothing, because in some programs it goes to stderr instead of
| stdout. So I hit up, end, ^W, 2>&1 |less. Ugh.
|
| And --help is not even close to a universal convention. In some
| programs --help will open HTML documentation in a browser
| (really!?). Often programs don't print help at all, instead
| printing a generic "bad flag" error. Some will create a file
| named --help without asking! Some programs don't use long
| options and relegate it to -h, or -?.
|
| Manpages are a much more universal convention, thanks to
| Debian's policy that all packaged programs have manuals. I
| don't even use Debian, but I encounter manuals attributed to
| them all the time. I do my part by writing manpages for my own
| software and sometimes contributing new manpages to programs I
| encounter that don't have one.
| mmphosis wrote:
| I agree. I just ran "shutdown -h" and it turned off my
| computer.
|
| I need to look into creating man pages again.
| Command 'mandoc' not found, but can be installed with:
| apt install mandoc
|
| A universal convention would be nice. That whole stdout vs
| stderr business. openbsd-cut -badoption |
| less
|
| I didn't even consider -?. And -h can mean --how-many-
| different-things: Host, --human-readable, --poweroff (as I
| just discovered), open HTML documentation in a browser (just
| wow), and maybe Help, maybe not enough help, maybe too much
| help, maybe...
___________________________________________________________________
(page generated 2025-04-09 23:01 UTC)