> Say you've just reminded yourself how grep works for the third time this month.
Hahaha, exactly. There are some commands that I just don't use enough for them to properly stick in my mind. Awk is another one. This utility would be helpful for me. Thanks!
The most confusing thing about it for me now (after I eventually decided to learn it and figured out what you mentioned) is the missing dash. Somehow it works both with and without, which makes no sense considering how *nix tools work. Why is it made to be like that?
The history of tar is quite long, but the short version is that it was first released as part of 7th edition Unix. It was a successor to tp[1] which was introduced in 4th edition Unix, which was a successor to tap[2] which was released in 1st edition Unix. In 1st edition Unix (as far as I could tell from looking through the man pages), no command had '-abc'-style flag support at all (so tap's semantics made sense). I imagine that quite a few users did something like 'alias tap=tp' and 'alias tp=tar' when upgrading, and so CLI backwards compatibility was required. As a result, everyone learned to use tar that way and it stuck.
Though from what I've seen, most people I talk to use the POSIX forms (such as 'ps -ef') and aren't aware that there is a BSD form (such as 'ps aux'). I've always used the BSD form, even though I came to Linux much much later, but I guess which form you use comes from where you learned basic *nix commands.
I guess the lack of '-' with tar is more apparent because POSIX didn't create a different syntax, and so most people omit the '-' for terseness -- while with ps it would require learning a different syntax.
> I've always used the BSD form, even though I came to Linux much much later, but I guess which form you use comes from where you learned basic *nix commands.
I too use the BSD form but came from the Linux world. Probably it is just a matter of taste (a common answer to everything!).
> I guess the lack of '-' with tar is more apparent because POSIX didn't create a different syntax, and so most people omit the '-' for terseness -- while with ps it would require learning a different syntax.
I argue the ps situation is worse than tar exactly because of that reason. There are three different classes of options in ps, often with slightly different meanings and sometimes with two different long-form options only distinguished by their cases...
And the (funny?) thing is that now the whole world has to suffer, probably millions of developers, because at one point tar had an installed user base of about 500 people. Yay for backwards compatibility :)
Make is another famous victim of this:
> Why the tab in column 1? Yacc was new, Lex was brand new. I hadn't tried either, so I figured this would be a good excuse to learn. After getting myself snarled up with my first stab at Lex, I just did something simple with the pattern newline-tab. It worked, it stayed. And then a few weeks later I had a user population of about a dozen, most of them friends, and I didn't want to screw up my embedded base. The rest, sadly, is history.
Yeah, tar is actually pretty simple these days. (At least GNU tar, don't know about other tars.) In 99.9% of cases you only need to know the following:
tar caf $archive $file... to create
tar xf $archive to extract
"x" will automatically recognize the compression format, and "ca" will automatically infer the desired compression format from the extension in $archive, e.g.
I still prefer to pipe through a compression program on principle. tar has no good reason to messing around with compression, per the Unix single-function philosophy.
to people who grew up with archive programs, "making all of this into a single file" and "compressing all of this" is the same thing; requiring two commands is counterintuitive
For some reason, I think it would be more funny if the fourth frame was an exact copy of the third (with no text). I think it would be a simpler and less obvious route to the same "punchline".
Tar is one example of a command with dubious usage syntax. But how about cp?
cp a.txt b/c/d
Will this create a new file "b/c/d/a.txt", or will it create a new file "b/c/d"? It's not clear, and depends on the circumstances (if a directory b/c/d exists). There's a flag to control the behavior, but nobody uses it often, so nobody remembers that flag. The best way to assert that "d" is a directory is by adding a trailing slash, but there's no similar way to assert that "d" should be a file. I suspect that there are many bash scripts that are essentially broken because of this problem.
I love the idea of this utility (I use TLDR myself) and wonder if there is a way that tldr could be integrated with your tooling https://github.com/tldr-pages/tldr.
I can see that there may be instances where you/your company would like to have internal docs that should not be public and this utility would would work for it
Does anybody know why this can't run on linux now? I haven't touched Ruby in a very long time and I didn't fully read over all the code but from my brief look it seems like it is only because of the convenience of being able to use Homebrew to ensure that pandoc is already installed when installing Um. Am I missing something?
Interesting project. I believe these two shell functions in the shell's initialization file (~/.profile, ~/.bashrc, etc.) can serve as a poor man's um:
umedit() { mkdir -p ~/notes; vim ~/notes/"$1.txt"; }
um() { less ~/notes/"$1.txt"; }
Make pandoc convert the txt/md/whatever to roff and pipe it to man, and you're pretty much there. It would also work on more than OSX, unlike um itself.
Great, thank you! I rewrote them for fish shell syntax and added the '-c' flag for `less` so it starts writing from the top of the window instead that from the bottom, I'm more confortable with it (still I don't know why it doesn't fit the terminal width like man does, but it wraps text every 80 characters - I guess it's not a problem anyway).
function mdless
pandoc -s -f markdown -t man $argv[1] | groff -T utf8 -man | less -c
end
function umedit
mkdir -p ~/.notes; nvim ~/.notes/$argv[1];
end
function um
mdless ~/.notes/"$argv[1]"
end
function umls
ls ~/.notes/
end
(reminder, to make them permanent just: `funcsave mdless umedit um umls`)
> Is there something like wiki, but for man pages?
yes. it's the source repo for whatever app you want improved man pages on. Everyone can submit changes to it. All the good ones get merged in. It's effectively a wiki curated by the most knowledgeable people on the subject.
um solves a different problem though. It's not trying to make a _common_ man page. It's trying to make a man page that works _for you_. What _you_ need to be highlighted is likely different from what _I_ need to be highlighted.
Personally I don't _want_ a generic wiki man page for stuff. I like the man pages written by the creators of the code (because i know they're correct), combined with my notes highlighting what's important to me.
I love how immediately customizable this makes everything. Thank you. I'm imagining somebody tweaking this just a bit so that a robotic arm throws "Linux in a Nutshell" at them from across the room.
:D I never thought about it, but now that you say it:
Why are there no scriptreplay/asciinema 'videos' available within normal man pages? I mean yes, just a few more basic examples would certainly help more, but for some more complicated commands a video might help too.
One thing I hate about man pages is that there are not enough examples. Sometimes feature is explained on five pages while simple one line example would explained it instantly. And at the end there should be 2-3 pages of examples at least, maybe even more.
I know this is late but you are right. For some reason I thought info was only fore coreutils, but it seems I was wrong. I only ever used it for coreutils, but hey, thats good news to me!
Better search and better organization of the document (TOC, index search, etc.). And reading/searching Info manuals is a lot more convenient in Emacs Info-mode.
If you’re using a GNU system now you might be surprised by the quality of the BSD man pages, and documentation in general. Concise but still comprehensive, and plenty of examples. The tools (like man) aren’t really the problem here, the documentation itself is. (But it helps that the BSD folks show a bit more restraint wrt adding command line options.)
I find the cut man page (looking at the OpenBSD one) very clear. It's just 62 lines (fits on a screen), has only 5 flags and the 2 examples clearly show how the tool is used.
The xargs man page is ought to have some examples, I agree.
The find manual is lengthy (as it has a bunch of options) but not excessively so and it also has a good bunch of examples.
Edit: it also helps to be familiar with the pager, like using the search feature (hit / , n, n, Shift+n, ...) and the jump keys (G and g).
Not enough examples is only in GNU/Linux; the BSD’s and illumos-based operating systems have plenty of examples. Especially illumos, since they enforce a rule that no component may be integrated without a comprehensive manual page and since they come from Solaris, most of the documentation was written by a dedicated department of professional technical writers working with the engineers to document their work in a systematic fashion.
This is a pet peeve of mine. Teachers are not somehow inferior to those who do. It's a completely different skill set that actually helps you "do" better.
Sure we respect coaches, but we also still in every sport pay them significantly less than the pros they ostensibly lead. I personally value both coaches and teachers but it's very clear that we as a people have decided that ability to do is more valuable than the ability to teach others.
While this is laudable, how many GNU projects, especially, don't use an archaic development/contribution process? I don't want to have to register on a mailing list and prepare patches.
This is an honest question. Friction and barriers to entry reduce contributions.
I second this, there's so much wasted work, and because that old contribution process there's no guarantee that even an absolutely fantastic patch, like a better man page for example. Will ever see the light of day.
I've tried in the past, it doesn't work out (not man pages, but I was fixing a bug and yeah, three, four submissions was enough for me to quit trying)
It's not hard, just suck it up and register for the ML, and prepare the patches. People are irrationally scared of this process. There are plentiful guides.
It's not always that it's hard, rather it can be demoralizing to have the same experience that @S-E-P did [a sibling comment to yours] where you _do_ expend the energy and then patches sit unactioned for months or years
Your patches are your responsibility. Bump them, reach out to maintainers directly, etc. Manual improvements are easy to review once you can get someone to.
Or I could just do what 99% of devs do, not give a crap and try StackOverflow/blogs to find an answer... That was my whole point, higher friction => much fewer contributions.
But also fewer contributions, I reckon. If someone wants to contribute something big, they'll jump through all the hoops. But if all one wants is to contribute another example to a man page, I'd wager they're more easily discouraged by an arcane setup process. GitHub solves a lot of this friction by having:
1. One account for manifesting your chosen identity, which you likely already have.
2. One common way of getting the source code and sending diffs/patches (read: PRs).
The workflow is quite similar, in the abstract. But GitHub and friends solve important pain points.
It looks like you think that older approaches to open-source collaboration (like many of the GNU projects are using) are more or less as user-friendly as GitHub. I don't have the data to prove that they aren't, just an intuition.
Perhaps the last argument I have is that I've heard a number of times about moving a project to GitHub (for example: the Go language or Vim the editor), but decidedly less often one hears of projects moving away from GitHub towards older forms (such as the wonderfully documented https://gcc.gnu.org/contribute.html). Despite the great documentation, I'm somehow not drawn to hacking on it to fix a small glitch, due to the overhead that entails. Mind, some of that overhead would be incurred just once, as it is general to the mailing list approach to collaboration. That, I believe, is another advantage of a project being on GitHub: for almost all projects there's a standard way of sending your patch: make a pull request.
About your counterpoints:
1. True. I was thinking of the bug trackers many mailing-list oriented projects have, which often require creating accounts just to file a bug.
2. I was more referring to things like (1) where to find the clone URL and (2) how to send a patch (the make a PR button is always the same).
Removing friction (even small frictions) will enable fishing for the long tail of small fixes. On the other side, I do not believe large contributions are greatly affected by the differences between these systems.
I don’t think being afraid of the process is the problem. It’s more about how unnecessarily manual the process is paired with the possibility of your patch’s email thread getting buried never to be seen again or worse, its reviewer abandoning it halfway through the review process with no easy way for someone else to pick it up.
That’s not to say that Github pull requests and the like are perfect (far from it) but it’s undeniable that they smooth the process quite considerably and make contribution far more accessible.
People are busy. If you want your patch considered, you should be bumping it and reaching out to people who can merge it. Man page improvements are generally a shoe-in, just get someone to pay attention to it for a few minutes and it'll get in.
I don't think the use case is the same. um is for saving and viewing personal notes about usage, bropages is a common set of examples submitted by the wider community.
Attempting to read nix man pages, always felt like I was alone in learning best from examples. Documentation in any form without examples is always difficult for me to sort through.
Just an aside, the repo complains about the length of curl's manpage, but that's what I love about it. Fond memories of sitting on the train home from uni, and browsing big long manpages looking for interesting new options to try out.
Interesting project but I do wonder if you're going to go through this amount of effort if that idea of Literate-Devops with Org.Mode might not be a better path.
“Writing man pages using roff today is not very fun or intuitive.”
Depends on who you ask: for me the best part of delivering software which I wrote is writing the manual pages in straight nroff in vi, with lots of examples. Seeing the engine typeset my documentation exactly the way I want is always an awesome feeling.
It looks like to me that “um” is a reactionary effort because of the notoriously poor quality of GNU/Linux manual pages which often lack examples; if so, then the solution is to switch to a higher quality operating system like FreeBSD or SmartOS / illumos.
While this is interesting, I will probably find this too much of work to type in all the stuff again with examples. Throwing a not-so-random extension idea - may be a tool to go through the weird commands in my bash history and suggest me to explain the commands which I just used?
Right now, I usually grep the man pages to search for things relevant to specific context. Something like,
man find | grep -i --color=always -C10 "file name"
Worked well in most cases. So, for figuring out how to send a POST request, I would try
man curl | grep -C10 --color=always POST
If that bombs, I would then immediately try
curl --help | grep --color=always POST
If I end up using certain set of flags frequently, I will set up a bash command like most others. Or, make a weird joke out of the flags, for example,
A good joke consists of an introduction, which establishes the story to be told and gracefully segues into the punchline. Your post here demostrate that very well sir.
How could it check that the command from bash history successfully ran? I often iterate about 10 times to get the right command, so that's 9 errors in the history.
1. You need Pandoc. On Debian, Ubuntu, etc. this is: `sudo apt-get install pandoc`. I'm sure there's a similar incantation for Arch and so forth, but I can't be arsed. If you don't already have Ruby installed in your system, you'll need that too.
3. Add a symlink to um in /usr/local/bin: `sudo ln -s /your/path/to/um/bin/um /usr/local/bin/um`. Make sure you're symlinking to the um script, not the um directory.
I'd like this function except it would add a section to the existing man page. That way my knowledge and the canonical information would be in the same place.
169 comments
[ 4.4 ms ] story [ 237 ms ] threadHahaha, exactly. There are some commands that I just don't use enough for them to properly stick in my mind. Awk is another one. This utility would be helpful for me. Thanks!
The history of tar is quite long, but the short version is that it was first released as part of 7th edition Unix. It was a successor to tp[1] which was introduced in 4th edition Unix, which was a successor to tap[2] which was released in 1st edition Unix. In 1st edition Unix (as far as I could tell from looking through the man pages), no command had '-abc'-style flag support at all (so tap's semantics made sense). I imagine that quite a few users did something like 'alias tap=tp' and 'alias tp=tar' when upgrading, and so CLI backwards compatibility was required. As a result, everyone learned to use tar that way and it stuck.
[1]: http://man.cat-v.org/unix-6th/1/tp [2]: http://man.cat-v.org/unix-1st/1/tap
[1] http://man.cat-v.org/unix-6th/1/ps
I guess the lack of '-' with tar is more apparent because POSIX didn't create a different syntax, and so most people omit the '-' for terseness -- while with ps it would require learning a different syntax.
I too use the BSD form but came from the Linux world. Probably it is just a matter of taste (a common answer to everything!).
> I guess the lack of '-' with tar is more apparent because POSIX didn't create a different syntax, and so most people omit the '-' for terseness -- while with ps it would require learning a different syntax.
I argue the ps situation is worse than tar exactly because of that reason. There are three different classes of options in ps, often with slightly different meanings and sometimes with two different long-form options only distinguished by their cases...
Make is another famous victim of this:
> Why the tab in column 1? Yacc was new, Lex was brand new. I hadn't tried either, so I figured this would be a good excuse to learn. After getting myself snarled up with my first stab at Lex, I just did something simple with the pattern newline-tab. It worked, it stayed. And then a few weeks later I had a user population of about a dozen, most of them friends, and I didn't want to screw up my embedded base. The rest, sadly, is history.
Bad example, since tar still works with a dash:
> Make is another famous victim of this:Now that is a much better example.
- all unix commands support both short and long options
- option letters/names are, at least to a much greater extent than currently, common across different commands
Rsync has a similar problem.
bomb disarmed
“Um, how do I use this tool again?”
I can see that there may be instances where you/your company would like to have internal docs that should not be public and this utility would would work for it
function mdless pandoc -s -f markdown -t man $argv[1] | groff -T utf8 -man | less -c end function umedit mkdir -p ~/.notes; nvim ~/.notes/$argv[1]; end function um mdless ~/.notes/"$argv[1]" end function umls ls ~/.notes/ end
(reminder, to make them permanent just: `funcsave mdless umedit um umls`)
I can share my man pages with git/github, but nobody will notice them, nobody will fix my spelling errors or contribute additional information.
Is there something like wiki, but for man pages?
yes. it's the source repo for whatever app you want improved man pages on. Everyone can submit changes to it. All the good ones get merged in. It's effectively a wiki curated by the most knowledgeable people on the subject.
um solves a different problem though. It's not trying to make a _common_ man page. It's trying to make a man page that works _for you_. What _you_ need to be highlighted is likely different from what _I_ need to be highlighted.
Personally I don't _want_ a generic wiki man page for stuff. I like the man pages written by the creators of the code (because i know they're correct), combined with my notes highlighting what's important to me.
sphinx.builders.manpage: http://www.sphinx-doc.org/en/master/_modules/sphinx/builders...
I can see myself running `um git` literally before every invocation.
This needs integration with voice assistants.
You are always free to install manpages, however only one manpage per name IIRC.
In this case, I'd just namespace it so you avoid any conflicts.
i.e.
And So both are preserved.Why are there no scriptreplay/asciinema 'videos' available within normal man pages? I mean yes, just a few more basic examples would certainly help more, but for some more complicated commands a video might help too.
http://heirloom.sourceforge.net/doctools/troff.pdf
https://www.oreilly.com/openbook/utp/
CLI tool to show simple examples instead of a full man page http://tldr.sh
View programming language and library documentation offline and in a single place http://devdocs.io
Cheat sheets for command line tools, programming languages, and libraries https://devhints.io
What happened to ‘info’ pages. I hated it, but wasn’t that supposed to address these kinds of issues with examples?
The info for gcc is a printed book, which is also accessible in the shell as hypertext (which predates html).
Example provided on the FreeBSD man page of cut.
Examples provided on the Linux man page of xargs.
More examples provided on the Linux man page of find.
The xargs man page is ought to have some examples, I agree.
The find manual is lengthy (as it has a bunch of options) but not excessively so and it also has a good bunch of examples.
Edit: it also helps to be familiar with the pager, like using the search feature (hit / , n, n, Shift+n, ...) and the jump keys (G and g).
lrf, guvf vf n cha
See e.g. https://metacpan.org/pod/release/PHRED/Archive-Zip-1.62/lib/...
Those who can't, teach
Those who can't teach, write
Those who can't write, write man pages
Rather a disappointment.
This is an honest question. Friction and barriers to entry reduce contributions.
I've tried in the past, it doesn't work out (not man pages, but I was fixing a bug and yeah, three, four submissions was enough for me to quit trying)
https://www.gnu.org/prep/standards/html_node/Man-Pages.html
> The time you spend on the man page is time taken away from more useful work.
Making sure your users know how your program works, how to use it and what it's capable of seems incredibly important and useful to me.
If it weren't for Arch Linux's fantastic focus on documenting everything to do with Linux, I wouldn't be using Linux at all.
See https://www.gnu.org/prep/standards/html_node/GNU-Manuals.htm...
https://www.gnu.org/prep/standards/html_node/Documentation.h...
You also have an email address, so. You need an email address to get a GitHub account, so technically it's harder to set up GitHub.
2. One common way of getting the source code and sending diffs/patches (read: PRs).
This is built into git. Don't need GitHub for either.
Perhaps the last argument I have is that I've heard a number of times about moving a project to GitHub (for example: the Go language or Vim the editor), but decidedly less often one hears of projects moving away from GitHub towards older forms (such as the wonderfully documented https://gcc.gnu.org/contribute.html). Despite the great documentation, I'm somehow not drawn to hacking on it to fix a small glitch, due to the overhead that entails. Mind, some of that overhead would be incurred just once, as it is general to the mailing list approach to collaboration. That, I believe, is another advantage of a project being on GitHub: for almost all projects there's a standard way of sending your patch: make a pull request.
About your counterpoints:
1. True. I was thinking of the bug trackers many mailing-list oriented projects have, which often require creating accounts just to file a bug. 2. I was more referring to things like (1) where to find the clone URL and (2) how to send a patch (the make a PR button is always the same).
Removing friction (even small frictions) will enable fishing for the long tail of small fixes. On the other side, I do not believe large contributions are greatly affected by the differences between these systems.
That’s not to say that Github pull requests and the like are perfect (far from it) but it’s undeniable that they smooth the process quite considerably and make contribution far more accessible.
http://bropages.org/
This other response says it better: https://news.ycombinator.com/item?id=17801788
I’ve never found actual help at the command line, delving any deeper beyond the --help switch.
Depends on who you ask: for me the best part of delivering software which I wrote is writing the manual pages in straight nroff in vi, with lots of examples. Seeing the engine typeset my documentation exactly the way I want is always an awesome feeling.
It looks like to me that “um” is a reactionary effort because of the notoriously poor quality of GNU/Linux manual pages which often lack examples; if so, then the solution is to switch to a higher quality operating system like FreeBSD or SmartOS / illumos.
Right now, I usually grep the man pages to search for things relevant to specific context. Something like,
Worked well in most cases. So, for figuring out how to send a POST request, I would try If that bombs, I would then immediately try If I end up using certain set of flags frequently, I will set up a bash command like most others. Or, make a weird joke out of the flags, for example,- open a real manpage `um grep`.
- add a custom field to it, like "personal notes", at the beginning or at the end, whatever.
- save the new manpage in my home directory, so each time I do `man grep` that custom manpage is used and I see my own notes.
1. You need Pandoc. On Debian, Ubuntu, etc. this is: `sudo apt-get install pandoc`. I'm sure there's a similar incantation for Arch and so forth, but I can't be arsed. If you don't already have Ruby installed in your system, you'll need that too.
2. cd into your favorite personal toolbox directory and `git clone https://github.com/sinclairtarget/um.git`
3. Add a symlink to um in /usr/local/bin: `sudo ln -s /your/path/to/um/bin/um /usr/local/bin/um`. Make sure you're symlinking to the um script, not the um directory.
That's it. Enjoy.
Nice little widget. I like it.