ppl 4.0.2 → 4.0.3

data/gh-pages/documentation/commands/post/index.md

@@ -0,0 +1,61 @@
+---
+title: ppl post Manual Page
+layout: command
+section: documentation
+command: post
+---
+
+### Name
+
+ppl post - List, show or change postal addresses
+
+### Synopsis
+
+    ppl post
+    ppl post <contact>
+    ppl post <contact> <address>
+        -s, --street <street-address>
+        -z, --postal-code <postal-code>
+        -p, --po-box <po-box>
+        -l, --locality <locality>
+        -r, --region <region>
+        -c, --country <country>
+    ppl post <contact> <address> (-m | --move) <new-name>
+
+### Description
+
+With no arguments, the postal addresses of each contact in the address book are
+listed.
+
+If a just a `<contact>` is specified, the postal addresses of that contact are
+shown.
+
+If both a `<contact>` and an `<address>` are specified, an address will be
+created or updated using the options provided.
+
+Use the `-m` or `--move` flag to move an address to a new ID.
+
+### Examples
+
+    $ ppl post
+    alice:  home, work
+    jdoe:   home
+    $ ppl post alice
+    *  home  3701 Southwest 12th Street, Topeka, Kansas, USA
+       work  123 Business Road, Businesstown, USA
+    $ ppl post alice home
+    3701 Southwest 12th Street
+    Topeka
+    Kansas
+    USA
+    $ ppl post alice home --country Canada
+    $ ppl post alice home
+    3701 Southwest 12th Street
+    Topeka
+    Kansas
+    Canada
+
+### See Also
+
+* [color output](/documentation/configuration/color_post)
+

data/gh-pages/documentation/commands/pull/index.md

@@ -0,0 +1,39 @@
+---
+title: ppl pull Manual Page
+layout: command
+section: documentation
+command: pull
+---
+
+### Name
+
+ppl pull - Execute `git pull` in the address book directory
+
+### Synopsis
+
+    ppl pull <remote> <branch>
+
+### Description
+
+This command is an alias of `git pull`. It is intended to make it more
+convenient to use git to synchronise your address book. The rationale is that it
+is tiresome to have to type `cd ~/contacts` and then `git pull origin master`.
+Assuming you have configured ppl to [remember the location of your address
+book](/documentation/configuration/address_book), then `ppl pull origin master`
+is the equivalent of those two commands.
+
+Note that this command literally executes the git command `push` in the address
+book directory. If you don't have the git CLI tool installed, this command will
+not work.
+
+### Examples
+
+    $ ppl pull origin master
+    Already up-to-date.
+
+### See Also
+
+* [git pull](http://git-scm.com/docs/git-pull)
+* [ppl push](/documentation/commands/push)
+* [ppl remote](/documentation/commands/push)
+

data/gh-pages/documentation/commands/push/index.md

@@ -0,0 +1,36 @@
+---
+title: ppl push Manual Page
+layout: command
+section: documentation
+command: push
+---
+
+### Name
+
+ppl push - Execute `git push` in the address book directory
+
+### Synopsis
+
+    ppl push <remote> <branch>
+
+### Description
+
+This command is an alias of `git push`. It is intended to make it more
+convenient to use git to synchronise your address book. See the documentation
+for [git pull](/documentation/commands/pull) for more details.
+
+Note that this command literally executes the git command `push` in the address
+book directory. If you don't have the git CLI tool installed, this command will
+not work.
+
+### Examples
+
+    $ ppl push origin master
+    Everything up-to-date.
+
+### See Also
+
+* [git push](http://git-scm.com/docs/git-push)
+* [ppl pull](/documentation/commands/pull)
+* [ppl remote](/documentation/commands/push)
+

data/gh-pages/documentation/commands/remote/index.md

@@ -0,0 +1,40 @@
+---
+title: ppl remote Manual Page
+layout: command
+section: documentation
+command: remote
+---
+
+### Name
+
+ppl remote - Execute `git remote` in the address book directory
+
+### Synopsis
+
+    ppl remote [-v | --verbose]
+    ppl remote rename <old> <new>
+    ppl remote rm <name>
+
+### Description
+
+This command is an alias of `git remote`. It is intended to make it more
+convenient to use git to synchronise your address book. See the documentation
+for [git pull](/documentation/commands/pull) for more details.
+
+Note that this command literally executes the git command `remote` in the
+address book directory. If you don't have the git CLI tool installed, this
+command will not work.
+
+### Examples
+
+    $ ppl remote
+    origin
+    github
+    $ ppl remote rm github
+
+### See Also
+
+* [git remote](http://git-scm.com/docs/git-remote)
+* [ppl pull](/documentation/commands/pull)
+* [ppl push](/documentation/commands/push)
+

data/gh-pages/documentation/commands/rm/index.md

@@ -0,0 +1,23 @@
+---
+title: ppl rm Manual Page
+layout: command
+section: documentation
+command: rm
+---
+
+### Name
+
+ppl rm - Delete a contact
+
+### Synopsis
+
+    ppl rm <contact>
+
+### Description
+
+Delete the specified `<contact>` from the address book.
+
+### Examples
+
+    ppl rm jdoe
+

data/gh-pages/documentation/commands/scrape/index.md

@@ -0,0 +1,38 @@
+---
+title: ppl scrape Manual Page
+layout: command
+section: documentation
+command: scrape
+---
+
+### Name
+
+ppl scrape - Scrape contact details from an email in `stdin`
+
+### Synopsis
+
+    ppl scrape [<options>]
+        -q, --quiet        Add contacts to the address book without prompting
+        -s, --sender       Scrape the sender's contact details
+
+### Description
+
+Reads an email message from stdin and scrapes contact information from it into
+the address book. By default nothing will be scraped; the command must be told
+explicitly which information to scrape via its arguments.
+
+If the `--sender` option is used, then the details of the person in the email's
+`From:` header will be scraped into the address book.
+
+If the `--quiet` option is used, the command will not prompt the user to confirm
+whether they approve of each contact before saving them to the address book.
+
+This command is analogous to [abook](http://abook.sourceforge.net/)'s
+`--add-email` functionality. Both the confirmation prompt and the `--quiet` flag
+are provided with the intention of achieving feature parity with this part of
+abook.
+
+### Examples
+
+    ppl scrape --sender --quiet < ~/Mail/cur/1234.example.org
+

data/gh-pages/documentation/commands/shell/index.md

@@ -0,0 +1,39 @@
+---
+title: ppl shell Manual Page
+layout: command
+section: documentation
+command: shell
+---
+
+### Name
+
+ppl shell - Interactive mode
+
+### Synopsis
+
+    ppl shell
+
+### Description
+
+Opens ppl in interactive mode, allowing users to skip typing "ppl" at the start
+of every single command. This is intended to be useful in the case of longer
+sessions, when a user plans to interact with ppl many times and wants to avoid
+some of the repetition.
+
+In interactive mode, all the ppl commands work as normal. The only difference is
+that there is no need to prefix every command with `ppl`. So instead of typing
+`ppl ls`, in interactive mode you would just type `ls`.
+
+To exit interactive mode, type `exit`, or send a `sigint` or `eof` (Ctrl+C or
+Ctrl+D usually).
+
+### Examples
+
+    $ ppl shell
+    ppl 1.5.2 (type "exit" to leave)
+    ppl> ls
+    jdoe: John Doe <jdoe@example.org>
+    kdoe: Kent Doe <kdoe@example.org>
+    ppl> exit
+    $
+

data/gh-pages/documentation/commands/show/index.md

@@ -0,0 +1,33 @@
+---
+title: ppl show Manual Page
+layout: command
+section: documentation
+command: show
+---
+
+### Name
+
+ppl show - Display a contact's full details
+
+### Synopsis
+
+    ppl show <contact>
+
+### Description
+
+Display the full details of the specified `<contact>`. This command will output
+all the contact details that are currently stored, including email address, date
+of birth, organization, and so on.
+
+### Examples
+
+    $ ppl show jdoe
+    jdoe: John Doe <jdoe@example.org>
+
+        Birthday  1970-01-01
+
+    Phone Numbers:
+      0123456789
+      0543216790
+
+

data/gh-pages/documentation/commands/url/index.md

@@ -0,0 +1,44 @@
+---
+title: ppl url Manual Page
+layout: command
+section: documentation
+command: url
+---
+
+### Name
+
+ppl url - List, show or change URLs
+
+### Synopsis
+
+    ppl url
+    ppl url <contact>
+    ppl url <contact> <url>
+    ppl url <contact> (-d | --delete) <url>
+
+### Description
+
+With no arguments, the URLs of each contact in the address book are listed.
+
+If a `<contact>` is specified, the URLs of that contact are shown.
+
+If both a `<contact>` and a `<URL>` are given, then the URL is added to the
+contact.
+
+If the `--delete` or `-d` flag is set, then the given `<url>` is
+deleted from the specified `<contact>`.
+
+### Examples
+
+    $ ppl url jdoe http://facebook.com/jdoe
+    $ ppl url adam http://adamswebsite.com
+    $ ppl url jdoe
+    http://facebook.com/jdoe
+    $ ppl url
+    adam:  http://adamswebsite.com
+    jdoe:  http://facebook.com/jdoe
+
+### See Also
+
+* [color output](/documentation/configuration/color_url)
+

data/gh-pages/documentation/commands/version/index.md

@@ -0,0 +1,27 @@
+---
+title: ppl version Manual Page
+layout: command
+section: documentation
+command: version
+---
+
+### Name
+
+ppl version - Display ppl's version number
+
+### Synopsis
+
+    ppl version
+
+### Description
+
+This command simply displays the current version of ppl installed on the system.
+
+Pre-1.9.0 versions of ppl lack this command, but `gem list --local | grep ppl`
+ought to do the job just fine in its absence anyway.
+
+### Examples
+
+    $ ppl version
+    ppl version 1.9.0
+

data/gh-pages/documentation/configuration/address_book/index.md

@@ -0,0 +1,22 @@
+---
+title: ppl [address book] Configuration Guide
+layout: configuration
+section: documentation
+config_section: address book
+---
+
+### path
+
+    [address book]
+        path = ~/contacts
+
+By default, ppl determines the location of the address book based on the user's
+[working directory](http://en.wikipedia.org/wiki/Working_directory). This value
+overrides that behaviour and sets a particular directory as the location of the
+address book regardless of the working directory.
+
+This is intended for the typical use-case where a user of ppl only has one
+address book. The purpose is to increase the convenience of using ppl with that
+single address book by removing the requirement that the user first navigate to
+its directory before reading from or writing to it.
+

data/gh-pages/documentation/configuration/alias/index.md

@@ -0,0 +1,45 @@
+---
+title: ppl [alias] Configuration Guide
+layout: configuration
+section: documentation
+config_section: alias
+---
+
+Sometimes typing the same long commands repeatedly becomes tiresome. The
+`[alias]` section is intended to address this issue by providing a means of
+configuring shorter forms of commands.
+
+    [alias]
+        l = ls
+        s = show
+
+Adding the above lines to `~/.pplconfig` would allow the user to interact with
+ppl as follows:
+
+    $ ppl l
+    jdoe: John Doe    <jdoe@example.org>
+    fred: Fred Bloggs <fred@example.org>
+    $ ppl s jdoe
+    John Doe <jdoe@example.org>
+
+      Birthday      1970-01-01
+      Organization  Example Organization
+
+    Email Addresses
+      jdoe@example.org
+
+### Bang Aliases
+
+ppl's alias system is similar to git's in that it supports executing external
+commands via aliases prefixed with an exclamation mark, or "bang". In your
+`~/.pplconfig`, this would look something like the following:
+
+    [alias]
+        lsx = !ppl ls | grep -i x
+
+The above example creates an alias `lsx` that pipes the output of [ppl
+ls](/documentation/commands/ls) through `grep -i x`. This means that you
+effectively create a new command - `ppl lsx` - which is identical to `ppl ls`
+except that it only displays lines containing the letter x.
+
+