commit 93444b4d839df511da00a33657d5ad3e57dc7179 Author: Romain Prieto Date: Sun Dec 8 19:56:16 2013 +1100 initial commit diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000000..3c3629e647 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +node_modules diff --git a/README.md b/README.md new file mode 100644 index 0000000000..7b385bf174 --- /dev/null +++ b/README.md @@ -0,0 +1,36 @@ +# What is this? + +New to the command-line world? Or just a little rusty? +Or like me you can't always remember the arguments to `lsof` or `tar`? + +Maybe it doesn't help that the first option explained in `man tar` is: + +``` +-b blocksize + Specify the block size, in 512-byte records, for tape drive I/O. + As a rule, this argument is only needed when reading from or writing to tape drives, + and usually not even then as the default block size of 20 records (10240 bytes) is very common. +``` + +I'm sure people could benefit from simplified "teach me the basics" man pages. +What about: + +[tldr screenshot](http://raw.github.com/rprieto/tldr/master/screenshot.png)! + +# Installing + +```bash +$ npm install -g tldr +``` + +# Contributing + +Your favourite command isn't covered? You can think of more examples? + +Just [open an issue](http://github.com/rprieto/tldr/issues) or [send a pull request](http://github.com/rprieto/tldr/pullrequest), it's all **Markdown** stored right here on Github. + +The rough guidelines are: + +- the main description is 2 or 3 bullet points (80 columns) +- give around 5 examples of the most common usages +- when in doubt, keep new command-line users in mind diff --git a/bin/tldr b/bin/tldr new file mode 100644 index 0000000000..eceb314914 --- /dev/null +++ b/bin/tldr @@ -0,0 +1,11 @@ +#!/usr/bin/env node + +var util = require('util'); +var tldr = require('../lib/tldr'); + +if (process.argv.length != 3) { + util.log('Usage: tldr '); + process.exit(1); +} else { + tldr.get(process.argv[2]); +} diff --git a/lib/output.js b/lib/output.js new file mode 100644 index 0000000000..78de4b15a6 --- /dev/null +++ b/lib/output.js @@ -0,0 +1,37 @@ +var markit = require('markit'); +var colors = require('ansicolors'); +var styles = require('ansistyles'); + +exports.fromMarkdown = function(markdown) { + var r = new markit.Renderer(); + + // automatically created by new lines + r.paragraph = function(text) { + return text; + }; + + // high-level command description + r.list = function(body, ordered) { + return body + '\n'; + } + + r.listitem = function(text) { + return ' ' + styles.italic(styles.bright(text)) + '\n'; + }; + + // description for each example + r.header = function(text, level) { + if (level == 2) { + return colors.green(' - ' + text) + '\n'; + } else { + return ''; + } + }; + + // example code + r.codespan = function(code, lang) { + return ' ' + colors.white(' ' + colors.bgBlack(code)) + '\n\n'; + }; + + return markit(markdown, {renderer: r}); +}; diff --git a/lib/repo.js b/lib/repo.js new file mode 100644 index 0000000000..6a88a1c8ee --- /dev/null +++ b/lib/repo.js @@ -0,0 +1,18 @@ +var os = require('os'); +var util = require('util'); + +exports.url = function(command) { + if (process.env.NODE_ENV == 'development') { + return 'http://localhost:3000/pages/' + osGroup() + '/' + command + '.md'; + } else { + return 'http://raw.github.com/rprieto/tldr/master/pages/' + osGroup() + '/' + command + '.md'; + } +} + +function osGroup() { + if (os.platform() == 'darwin') { + return 'osx'; + } else { + return 'unsupported'; + } +} diff --git a/lib/request.js b/lib/request.js new file mode 100644 index 0000000000..0782b51430 --- /dev/null +++ b/lib/request.js @@ -0,0 +1,14 @@ +var request = require('request'); +var repo = require('./repo'); + +exports.get = function(command, done) { + // TODO: add local disk cache that respects HTTP headers + // for example https://github.com/matteoagosti/node-request-caching + request.get(repo.url(command), function(err, res, body) { + if (err || res.statusCode != 200) { + done(command + ' command not available'); + } else { + done(null, body); + } + }) +}; diff --git a/lib/tldr.js b/lib/tldr.js new file mode 100644 index 0000000000..4f38a1b547 --- /dev/null +++ b/lib/tldr.js @@ -0,0 +1,14 @@ +var util = require('util'); +var request = require('./request'); +var output = require('./output'); + +exports.get = function(command) { + request.get(command, function(err, body) { + if (err) { + util.error(err); + process.exit(1); + } else { + util.puts(output.fromMarkdown(body)); + } + }); +}; diff --git a/package.json b/package.json new file mode 100644 index 0000000000..a91c52e648 --- /dev/null +++ b/package.json @@ -0,0 +1,40 @@ +{ + "name": "tldr", + "version": "0.0.1", + "description": "Simplified and community-driven man pages", + "author": "Romain Prieto", + "license": "BSD", + "repository": { + "type": "git", + "url": "https://github.com/rprieto/tldr.git" + }, + "keywords": [ + "tldr", + "man", + "unix", + "commands" + ], + "main": "./bin/tldr", + "bin": { + "tldr": "./bin/tldr" + }, + "directories": { + "test": "test" + }, + "scripts": { + "start": "NODE_ENV=development node server.js", + "example": "NODE_ENV=development node ./bin/tldr tar", + "test": "./node_modules/.bin/mocha" + }, + "dependencies": { + "request": "~2.29.0", + "markit": "~0.1.0", + "ansicolors": "~0.3.2", + "ansistyles": "~0.1.3" + }, + "devDependencies": { + "mocha": "~1.15.1", + "connect": "~2.11.2", + "should": "~2.1.1" + } +} diff --git a/pages/osx/curl.md b/pages/osx/curl.md new file mode 100755 index 0000000000..6a6bcb5bb7 --- /dev/null +++ b/pages/osx/curl.md @@ -0,0 +1,20 @@ +# curl + +- Transfers data from or to a server +- Supports most protocols including HTTP, FTP, POP + +## Head request + +`curl --head http://localhost` + +## Send form-encoded data + +`curl --data name=bob http://localhost/form` + +## Send JSON data + +`curl -X POST -H "Content-Type: application/json" -d '{"name":"bob"}' http://localhost/login` + +## Specify an HTTP method + +`curl -X DELETE http://localhost/item/123` diff --git a/pages/osx/grep.md b/pages/osx/grep.md new file mode 100755 index 0000000000..73962ec6f2 --- /dev/null +++ b/pages/osx/grep.md @@ -0,0 +1,23 @@ +# grep + +- Matches patterns in input text +- Supports simple patterns and regular expressions + +## Search for an exact string +`grep something FILE` + +## Use a regex instead of a word + +`grep -e ^regex$ FILE` + +## See 3 lines of context + +`grep -C 3 something FILE` + +## Print the count of matches + +`grep -c something FILE` + +## Use the standard input instead + +`cat FILE | grep something` diff --git a/pages/osx/less.md b/pages/osx/less.md new file mode 100755 index 0000000000..cf5dc8eb07 --- /dev/null +++ b/pages/osx/less.md @@ -0,0 +1,25 @@ +# less + +- Opens a file for reading +- Allows movement and search +- Doesn't read the entire file (suitable for logs) + +## Open a file + +`less source_file` + +## Page up / down + +`d (next), D (previous)` + +## Start / end of file + +`g (start), G (end)` + +## Search for a string + +`/something then n (next), N (previous)` + +## Exit + +`q` diff --git a/pages/osx/ps.md b/pages/osx/ps.md new file mode 100755 index 0000000000..425d0709df --- /dev/null +++ b/pages/osx/ps.md @@ -0,0 +1,7 @@ +# ps + +- Information about running processes + +## List all running processes + +`ps aux` diff --git a/pages/osx/scp.md b/pages/osx/scp.md new file mode 100755 index 0000000000..4968c70af9 --- /dev/null +++ b/pages/osx/scp.md @@ -0,0 +1,20 @@ +# scp + +- Copies files between hosts on a network +- Works over a secure connection (SSH) + +## Uploading a file + +`scp local_file 10.0.0.1:/remote/path/filename` + +## Uploading a directory + +`scp -r local_folder 10.0.0.1:/remote/path/` + +## Downloading a file + +`scp 10.0.0.1:/remote/path/filename local_file` + +## Specifying credentials + +`scp local_file my_user@10.0.0.1:/remote/path` diff --git a/pages/osx/tar.md b/pages/osx/tar.md new file mode 100644 index 0000000000..e26c6a2cd7 --- /dev/null +++ b/pages/osx/tar.md @@ -0,0 +1,16 @@ +# tar + +- Archiving utility +- Supports tar / gzip / bzip + +## create an archive from files + +`tar cf target.tar file1 file2 file3` + +## create a gzipped archive + +`tar cfz target.tar.gz file1 file2 file3` + +## extract an archive in a target folder + +`tar xf source.tar -C folder` diff --git a/screenshot.png b/screenshot.png new file mode 100644 index 0000000000..d20e57ab53 Binary files /dev/null and b/screenshot.png differ diff --git a/server.js b/server.js new file mode 100644 index 0000000000..1a587dbc1f --- /dev/null +++ b/server.js @@ -0,0 +1,12 @@ +var util = require('util'); +var http = require('http'); +var connect = require('connect'); + +if (process.env.NODE_ENV != 'development') { + util.log('For local development only.'); + process.exit(1); +} + +var port = process.env.PORT || 3000; +connect().use(connect.static(__dirname)).listen(port); +console.log('Local server listening on port ' + port);