9 ms·
Show HN: manpages-tldr – short manpages with examples
My small project similar to bropages and tldr, but (finally!) using manpages only. Manpages generated from Markdown files by Pandoc.
- deleted 13y ago[deleted]
- Jonovono 13y agoThis was on here not long ago: http://bropages.org/ http://bropages.org/
- hav 13y agoWow. It took me ten seconds to click the link and read the description where the difference is highlighted. Can't you spare ten seconds?
- croisillon 13y agoI can : "This was on here not long ago: http://bropages.org/ http://bropages.org/ but don't check it if you don't have ten seconds spare." Welcome.
- Jonovono 13y agohah damn :( My bad, apologies! I skimmed over the project and saw that it seemed similar so thought i'd throw that up there for people interested in it!
- pax 13y agoit would've been great if all these (3 so far?) tldr man attempts would've also had a web interface, so local install would be optional
- JIghtuse 13y agoWell, pandoc can easily generate html, which can be styled as you wish. I make a list of tldr-manpages on my homepage: http://begorov.me/man-tldr/ http://begorov.me/man-tldr/
- blueblob 13y agoIt would be nice to have an example that is viewable from the markdown/on github. I think it would make people more likely to build it.
- JIghtuse 13y agoDo you mean screenshot of opened manpage?
- blueblob 13y agoYeah, that's one way. Or a similar text formatting on html/md on the readme. If you look at the bropages one, it very concretely shows you what it is. Any way of doing this makes it easier for people to tell what exactly they're getting.
- andreasvc 13y agoWhy can't people just improve manpages so that they include a readable abstract and examples instead of coming up with projects with cute names?
- jasonlotito 13y agoSo you think they should be "written as part of real manpages?"
- DanBC 13y agoFrom the readme: > This project aims to make fast-updated, practical and precise manpages with examples for everyday usage. Its idea based on similar projects, like bropages and tldr, but written as part of real manpages (mostly converted from Markdown with pandoc). And if OP is reading this there's a couple of typos there. Normally I don't care, but this is a do umentation project so it's important. > Its idea based Should be > It's an idea based
- JIghtuse 13y agoIt is possible, but it takes a long way to approve and distribute manpages after changes. I like Michael Kerrisk for all his work. Manpages are great and I'm not trying to replace it, they have much more useful information.
- 13y ago
- deleted 13y ago[deleted]
- fredley 13y agoThis is the man I've been looking for my whole life.
- hf 13y agoElsewhere[0] I mentioned a shell alias called `eg` that jumps to the 'Examples' section in traditional man-pages. I made great use of it with the excellently structured yet rather verbose git man-pages. Anyways, here's the alias: alias eg='man --pager='\''less -p "^[A-Z]* ?EXAMPLES"'\''' Try it out: eg git pull (With older shells you might have to say `eg git-pull`). Now as concerns the fine project submitted here, I'd suggest to try getting as much of those tldr's into actual man-pages. This will at least make the long-term survival of OP's labour more probable. [0] https://news.ycombinator.com/item?id=7167815 https://news.ycombinator.com/item?id=7167815
- dredmorbius 13y agoNote that: • Manpages are short. The average length is around 4 pages printed, much of which is pro-forma. Some run longer. Shells in particular (bash(1) runs around 98 pages piped through 'pr'). • Manpages include an EXAMPLES section, though this isn't always filled. That should be considered a bug. • Manpages suffer from various projects attempting to deprecate them in favor of other forms of documentation. I particularly fault the GNU project's attempt to shoehorn info in place of man (the availability of man to Web utilities such as Debian's dwww largely wholly supplants this: info and the WWW were born within months of each other, Stallman and the FSF should have conceded the battle decades ago). Red Hat and the GNOME project have also been notably lax in providing manpages for utilities and programs. The Debian project considers omission of a manpage for an executable to be a bug, though not a release-critical one (I wish this severity would be increased). • Fixing the deficiencies of existing manpages (and beating upstreams over the head with these until they're accepted) would be preferable to creating numerous externally maintained nonstandard variants. http://xkcd.com/927/ http://xkcd.com/927/
- JIghtuse 13y agoThank you. I would do my best to improve real manpages. As I say in comments here, tldr pages aims to provide quick access to examples and must not replace real manpages. How do you think, would I need to change license of a project if I want to push some examples to manpages?
- dredmorbius 13y agoIf you're the author of the pages, you can set the licensing terms as you wish. Generally, an MIT/BSD style license tends to be compatible with most other licenses. If you're the sole author, licensing the manpages under the same terms as the specific upstream works would work. You might specify your own terms (say: a CC license), with a proviso "or, as an alternative, under the licensing terms of the original project for which this manual page applies". IANAL.
- blueblob 13y agoI think stating that manpages are short is a little inaccurate. The average may very well be 4 pages, but the standard deviation is probably high (bash, gcc, ssh among others have long man pages). A few commands nowadays also have multiple man pages because people don't want to search through all the crap that's in a normal manpage (ie git, gittutorial, gittutorial-2, Everyday Git, ...). People likely aren't going to use manpages-tldr for 4 page man pages. They may use it for gcc which is 17549 lines (without an examples section and examples are littered throughout the page, meaning you have to already know what you're looking for). According to Wikipedia, man pages have been around since 1971[1]. Man pages were designed before a paradigm shift from systems oriented to user oriented design and are usually written in a manner that makes them easy to write, not easy to read. If you think about the first time you looked at man pages, they were likely difficult to look through and you just got used to it; that's what happened to me. I would guess that most people would like examples of basic usage. The examples section of man pages is normally near the end but it's location isn't really standardized. I normally end up searching "/^[[:blank:]]*EXAMPLE" and if I don't find it I google it. This doesn't mean that man pages are not useful when you know what you're looking for. They can be particularly useful for c code to supplement the headers themselves. I think forcing man pages to be something that they are not isn't much better than having a bunch of nonstandard variants. I am not saying that the examples shouldn't be added, but man pages are very technical when most people probably want a layman example before the technical details. [1] http://en.wikipedia.org/wiki/Man_page#History http://en.wikipedia.org/wiki/Man_page#History
- CJefferson 13y agohf: if you see this, I think you are Hellbanned. All your posts come up as 'dead'.