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.
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.
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.
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.
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.
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.
I think it was more hampered by the default viewer program operating like EMACS, which if you're a regular EMACS user is great if you're not it is not terribly ergonomic. What was the command to find the next search item? Ctrl-X N?
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.
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.
I disagree as well, but on a bit different grounds.
Man pages often lack examples of the syntactical structure, and the syntax is not appropriately documented either.
You can have commands where the flag is followed by an argument, but that flag also is positional, and the position is not documented. You can't just read the man page and get a working command, there's a lot of trial and error which is naturally solved by having a section of commands in an extended form with examples. Powershell does this, and they took it, from somewhere though I'm having trouble recalling the exact name at the moment I know it wasn't an innovation on their part they just glued a bunch of things together that were used in isolation.
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.
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.
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.
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.
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.
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.
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.
I think the larger problem with markdown is that it is not semantic at all? Yes, the "break glass to drop into html" is a problem. I'm assuming folks would try to disallow inline html, though?
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
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).
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.
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.
I remapped K to :grep for the word under the cursor instead. The way I did it, though, is such that if I give it the numeric prefix, it will do the man lookup in that section.
I hear you, have an hard to overcome ctrl-d muscle memory from back in my sublime-text days. Which unfortunately conflicts a little with vim's default ctrl-d in some modes.
But for the most part I was surprised how much muscle memory I could re-wire when I forced myself. I think so long as you pick one at a time, and are using it for a solid chunk of time, i.e while you are working, then it doesn't take long, ~1 week maybe until it's 90% instinct.
I think I probably need to finally shake ctrl-d, maybe today is the day.
In Vim, I use Ctrl-T to indent, and Ctrl-D to deindent (in cases where automation doesn't handle it). Ctrl-T works with the correct indentation amount which is defined by the value of "shiftwidth"; whereas the Tab key inserts a tab, or spaces to get to the next tabstop if "expandtab" is in effect.
I trained myself on Ctrl-T more than 20 years ago; some people remap the Tab key to indent.
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.
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.
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.
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.
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.
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.
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.
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.
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):
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?
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!).
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.
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.
> 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.
> I wish people would stop this "we" business where they purport to speak for everyone.
Saying that we are all used to consuming content in a web browser is hardly a controversial comment, especially when posting on HN which is accessed using a web browser. You most likely read my comment on a web browser and wrote it on a web browser.
Additionally, you said yourself the sentence before the one I quoted that you are used to reading documents on the web, so it seems like this "we" also applies to you. So I'm just baffled by both this and the sibling comment.
In full context, it was implicitly "as opposed to anywhere else".
I look at many documents every day. 90% of them are PDFs and most were Word docs before that. Pages on the web are incredibly unreliable. In the programming world random websites are more commonly used but I don't think they are actually much more reliable. A lot of online resources are just some guy's blog post. Sometimes they're great. Sometimes not.
No, I wasn't implying "as opposed to anywhere else". I spend much more time a day in the terminal than the browser (todos are in vim, knowledge in vimwiki, code in vim etc), but I realize not everyone is this way and the web is the much more common medium.
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.
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.
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.
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.
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.
> 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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.)
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).
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.
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
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.
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.
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.
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
}
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.
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.
The font is Times, not Times New Roman. The original PostScript standard only mandated three font sets: Times, Helvetica, Courier.
Personally when reading long man pages (or any long documents), I greatly prefer a proportional type face over a monospace one like in the terminal. These days, people's hand-written markdown also overuses the backtick syntax to make too many things monospace. Using a proportional font just feels right to me.
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.
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.
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).
Fun fact - you already have them. The gnu project made ‘info’ pages decades ago to solve exactly this problem. It never caught on outside of the gnu project though, sadly.
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.
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.
For small programs with limited flags, I like (and write them this way) having `--help` simply list the expected syntax, and a brief description of the short and long flags. If I need a pager to read it, it's too long for `--help`.
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...
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.)
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.
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.
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.
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.)
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.
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.
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.
We have those because people do not know other options exist, or know, and lack the patience to read. By and large, people don't read docs, full stop. This is why you get entire stack traces being dumped into Slack, or error messages that clearly state the problem.
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.
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?
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).
> 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?
Wait until you find out how Linux PRs are developed and accepted.
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.
reply