19 ms·
Um – Create your own man pages so you can remember how to do stuff
- amelius 8y agoIs it possible to host the manpages somewhere, so I can access them on all machines I use? (Perhaps using a git repository, and GitLab?)
- rus64 8y agoYou could put your pages on cloud storage?
- nodofox 8y agoStarted using it already! I love it :)
- susam 8y agoInteresting 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"; }
- gunnihinn 8y agoMake 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.
- danieldk 8y agoSomething like: umedit() { mkdir -p ~/notes; vim ~/notes/"$1.md" } um() { pandoc -s -t man ~/notes/"$1.md" | tbl | groff -Wall -mtty-char -man -Tascii -c | less -R } Not sure if pandoc creates tbl tables ;).
- zhann_dc 8y agoI went for: function mdless() { pandoc -s -f markdown -t man $1 | groff -T utf8 -man | less } umedit() { mkdir -p ~/.notes; vim ~/.notes/$1; } um() { mdless ~/.notes/"$1"; } umls() { ls ~/.notes } This way I can write the notes in markdown and view them as such in `less`.
- zaphodias 8y agoGreat, 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`)
- v_lisivka 8y agoBut how to share these man pages and how to search for man pages written by others? 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?
- masukomi 8y ago> 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.
- themodelplumber 8y agoI 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.
- westurner 8y agoIf you write these in .rst, you can generate actual manpages with Sphinx: http://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-manual-page-output http://www.sphinx-doc.org/en/master/usage/configuration.html... sphinx.builders.manpage: http://www.sphinx-doc.org/en/master/_modules/sphinx/builders/manpage.html http://www.sphinx-doc.org/en/master/_modules/sphinx/builders...
- v01d4lph4 8y agoNice!
- statictype 8y agoCurrently using dnote for this but this looks interesting as well. I can see myself running `um git` literally before every invocation.
- majewsky 8y ago> `um git` This needs integration with voice assistants.
- hx2a 8y ago> 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!
- mehrdadn 8y agoIt would come in handy in this situation: https://xkcd.com/1168/ https://xkcd.com/1168/
- fengb 8y agotar actually makes sense with a little mnemonic: tar xzf $file - xtract - ze (actually gzip but fake-accent "the" is more memorable) - file
- mehrdadn 8y agoThe 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?
- jldugger 8y agoBecause it comes from an era before POSIX, when tapes were prevalent and bytes were costly.
- cyphar 8y ago> 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. [1]: http://man.cat-v.org/unix-6th/1/tp http://man.cat-v.org/unix-6th/1/tp [2]: http://man.cat-v.org/unix-1st/1/tap http://man.cat-v.org/unix-1st/1/tap
- jamesrom 8y agoum is a great name for this tool
- rodorgas 8y agoWhat’s the meaning of such name?
- DoreenMichele 8y agoIt's a thing you say when you don't know what you are doing or can't remember a thing.
- jerkstate 8y agojust a guess, but "unofficial manpage"
- max-m 8y ago“um” is an expression of confusion or a space filler in conversation like “uh”. “Um, how do I use this tool again?”
- guilhermesteves 8y agoone in portuguese
- dbnoch 8y agoI 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 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
- lowleveldesign 8y agoThanks, this tool looks great. I am eagerly awaiting a version for Linux.
- jetti 8y agoDoes 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?
- jefurii 8y agoSee thaumaturgy's comment.
- shakna 8y agoIf you are actually generating manpages, by using pandoc to generate roff layouts... Why the extra view command? Why not register them with mandb?
- ByThyGrace 8y agoIs it possible to register alternative manpages in such a way that they serve as bullet-point cheatsheets?
- shakna 8y agoDepends what you mean by 'alternative'. 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. man git And man um.git So both are preserved.
- nathell 8y agoThe manpage namespaces are called sections. I think it would make a lot of sense to put these pages in section 1u ('u' for 'um').
- _red 8y agoFurther, why not just use vim templates as the way to create the base man boilerplate and just customize. So issue 'vi mygrep.man' and quickly edit.
- kichuku 8y agoI have used asciinema for this purpose. Do you think it will be useful to link asciinema recordings with this?
- arendtio 8y ago: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.
- tptacek 8y agoDoes it show the man page after the user hints? It should show the actual man page too, so I can replace “man” with it.
- jwilk 8y agoIt doesn't.
- NVRM 8y agoFor anyone looking to do it «by hand», it's fairly doable: https://stackoverflow.com/a/50436684/2494754 https://stackoverflow.com/a/50436684/2494754
- Annatar 8y agoBravo! And this should help as well: http://heirloom.sourceforge.net/doctools/troff.pdf http://heirloom.sourceforge.net/doctools/troff.pdf https://www.oreilly.com/openbook/utp/ https://www.oreilly.com/openbook/utp/
- deleted 8y ago[deleted]
- jiggunjer 8y agoI print 'cheat sheets' (e.g. regex, emmet & alt codes) and pin them next to my monitor.
- guu 8y agoSome similarly helpful projects: CLI tool to show simple examples instead of a full man page http://tldr.sh http://tldr.sh View programming language and library documentation offline and in a single place http://devdocs.io http://devdocs.io Cheat sheets for command line tools, programming languages, and libraries https://devhints.io https://devhints.io
- dvh 8y agoOne 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.
- dijit 8y agoI find that this is something openBSD gets /really/ right. In general the man pages in BSD are phenomenal. What happened to ‘info’ pages. I hated it, but wasn’t that supposed to address these kinds of issues with examples?
- JoshMnem 8y agoInfo pages are still there. $ info grep
- arminiusreturns 8y agoInfo is much better than man, but keep in mind it's only covering gnu coreutils (which isn't a bad thing!)
- jwilk 8y agoHuh? grep is not part of coreutils.
- arminiusreturns 8y agoI 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!
- dijit 8y agoWhy is info better than man?
- x0 8y agoJust 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.
- sissyFuss 8y agoTo be quite honest, I resist ever reading man pages simply out of purest spite for that one well-known acronym. I’ve never found actual help at the command line, delving any deeper beyond the --help switch.
- Quequau 8y agoInteresting 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.
- Annatar 8y ago“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.
- sharken 8y agoOn Windows i find that using OneNote covers everything i need, mostly due to excellent search via Ctrl+E. Being able to add pictures also helps.
- Sreyanth 8y agoWhile 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, ls -lionshit
- nazri1 8y agoA 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.
- seealso 8y agoSee also https://github.com/alphapapa/mangle https://github.com/alphapapa/mangle
- banku_brougham 8y agoHow 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.
- Sreyanth 8y agoMay be extend a bit further to check if the return value is 0? Can be accessed via `$?` in most non-Windows systems.
- tigrezno 8y agoFor me, it would be better if the tool actually did something like this: - 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.
- girishso 8y agoWhile not exactly same. But I find https://github.com/chubin/cheat.sh https://github.com/chubin/cheat.sh very useful for finding usage.
- thaumaturgy 8y agoInstalling this on Linux is straightforward. 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` 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.
- enedil 8y agoWell, better modify $PATH than changing some system directories.
- thaumaturgy 8y ago/usr/local/bin is a good place for things like that. See also http://man.openbsd.org/OpenBSD-current/man7/hier.7 http://man.openbsd.org/OpenBSD-current/man7/hier.7 or just `ls` your own system's /usr/local/bin directory.
- scandox 8y agoI'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.
- reacweb 8y agoChapter 2 concern system calls. IMHO, this should be maintained by kernel developpers and updated each time I update the kernel so that it is always in sync. I would like to understand what is the contract the developper has implemented. The limitations of a system call are the developpers regrets and their plans for future evolutiond. I do not care if the style is not good. What I care is how it should be used.
- deleted 8y ago[deleted]
- movedx 8y ago"Ha! What a great idea. That might be useful. Ah and it's a command line utility too. Well this shou-oh it's written in Ruby never mind." - Me. (Because I can't be bothered installing Ruby or dealing with it at all. I've never had a good experience. Sorry if that upsets you.)
- exabrial 8y agoI use a Gollum wiki to do this exact thing. The nice part is it's backed by git so it's easy to sync and backup to a gitlab private repo.
- javajosh 8y agoI use nvalt for this.
- neLrivVK 8y agoI just use my bash history with a very large HISTSIZE. Not as nice, but doesn't require any effort. Effort I never want to put in at the time I'm using the complicated command, I have other issues at that time :)
- zach43 8y agoHow do you deal with input from multiple concurrent bash sessions? Usually I’ll have two or three konsole windows open at the same time, and I’ve noticed that only one of them appears in the bash history...is there an easy way to have it store all the history from all the windows?
- phs2501 8y agoUse zsh. https://askubuntu.com/questions/23630/how-do-you-share-history-between-terminals-in-zsh https://askubuntu.com/questions/23630/how-do-you-share-histo... It is possible to get similar effects by kludging around with bash, but it's a built-in feature in zsh.
- aepiepaey 8y agoshopt -s histappend In your .bashrc. Note that history is only saved when the shell exits, so new shells will only see history from other shells that have already exited.
- MrEfficiency 8y agoLet me say thanks for vocalizing the problems you were running into. Googling axios for the third time this week...
- nautilus12 8y agoI hate how man pages are typically organized so I feel like if I built this tool I would try to rethink how man pages are used at the same time.
- throw7 8y agoOne helpful option to add is an "apropos" as I do grep through my personal stuff occasionally.
- ams6110 8y agoNot taking anything away from this effort, but I just keep a "howto" section in an org-mode file, where I keep all kinds of reminders and notes about stuff I do.
- deleted 8y ago[deleted]
- zombieprocess 8y agoI wish this was for life with a checklist like functionality. Like um edit morningRoutine
- nichochar 8y agoI love tldr for similar-ish problem. https://tldr.sh/ https://tldr.sh/
- bap 8y agoAs someone who runs terminal obsessed engineering organizations I can see a wider implication for team docs. Would love a distributed version of this. I suppose we could do something with git, etc but the sync cycle would inevitably kill forward momentum of usage. Bonus points for a web server for those who aren't terminal obsessed.
- lyngford 8y agoI started blogging to keep records on how to do certain things and it eventually turned into teaching others how to do it.
- pjungwir 8y agoum is a brilliant name. If you don't want to install anything new, you can also write your own man pages with a personal "man section". Just do something like this in your shell: export MANPATH="$MANPATH:$HOME/man" export MANSECT="1:n:l:8:3:2:3posix:3pm:3perl:5:4:9:6:7:pj" Here I've added the "pj" section (my initials). Then I have files like ~/man/manpj/postgres.pj or ~/man/manpj/ssl.pj. I can say `man pj postgres` to see my own notes. My own collection goes back to 2001 or so. I feel lucky that early on I started putting notes into something so portable. It's one of the few things that has always moved with me to new machines. It is here: https://github.com/pjungwir/manpj/ https://github.com/pjungwir/manpj/ You don't even need to use proper man formatting if you don't want to. I find that a plain text file comes out pretty well. And when you want to start adding sections/etc, there are only a handful of formatting codes to learn (or copy/paste). I got started from a tiny chapter in O'Reilly's Unix in a Nutshell. You're welcome to steal from my own repo above. (I'm sure the formatting is nowhere close to best practice, but it's good enough for personal use.)
- teddyh 8y agoIn fact, man pages were made to be extensible in this way. It was assumed that every site installation should have their local manual pages, and every individual user too. It pains me to see so many useless projects like “um” created just because people are assuming that the usual tool for something is restricted to exactly what they are using it for.
- toyg 8y ago> just because people are assuming that the usual tool for something is restricted To be fair, sometimes it's just because the usual tool is unfriendly. I've just spent 30 mins to extend my manpath as parent suggested (on osx), and it's not working. I have my variables, I have my directories, I have my text files, and still man can't find them. For a tool as old as man, there is precious little debugging information available. It shouldn't be this hard.
- pjungwir 8y ago
- alanbernstein 8y agoMy personal solution to this problem: https://github.com/alanbernstein/quickref https://github.com/alanbernstein/quickref
- a-b 8y agoThere are couple alternatives like http://bropages.org/ http://bropages.org/ and https://tldr.sh/ https://tldr.sh/ How UM is different?
- moelf 8y agoprettyy sure https://tldr.sh/ https://tldr.sh/ is enough.
- wruza 8y agoPure man(3) solution proposed here is very nice, but I usually just: vim ~/doc/nginx-snippets.txt # edit vim ~/doc/nginx-snippets.txt # consult I actually have more files, config samples and source code templates, so it’s not just ~/doc/.txt, but having them all in man registry would require yet another better apropos(3) replacement. I also have my own vim colors format that is much better looking to me than md^. I know that my argument may turn similar to ‘dropbox is easy via ftp mount’, but I can’t see any need for a tool even for my relatively big snippet-base. Moreover, with vim I can gf, grep -r, edit :w, etc. And with just files it is subject to svn/sh/make, unleashing the full power of unix. -- ^ just two levels of section headers, and :tags, all readable without color. Based on dead-simple regexps, so in theory I could |sed them into terminal escapes in five minutes.