ppl 3.0.0 → 4.0.3

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

@@ -0,0 +1,43 @@
+---
+title: ppl add Manual Page
+layout: command
+section: documentation
+command: add
+---
+
+### Name
+
+ppl add - Add a new contact
+
+### Synopsis
+
+    ppl add <contact> <name>
+
+### Description
+
+This command adds a new contact to the address book. The first parameter,
+`<contact>`, is an alphanumeric string used to uniquely identify the contact
+within the address book. The second parameter, `<name>`, is the contact's actual
+name.
+
+The `<contact>` parameter must not already be in use as the identifier of
+another contact in the address book. Ideally you'll want to pick something short
+and easy to type, so if you're adding a contact named "John Doe", then "john" or
+"jdoe" might be good choices if they aren't already in use.
+
+The `<name>` parameter should be the full name of the contact, and is identical
+to its namesake expected by the [ppl name](../name) command.  Usually, this
+means it needs to be enclosed in quotation marks to indicate that all the words
+in the name are part of the same parameter. 
+
+The first word in the `<name>` will also be stored as the contact's given name,
+with the remainder of the string being treated as their family name.
+
+### Examples
+
+    ppl add jdoe "John Doe"
+
+### See Also
+
+[ppl name](../name)
+

data/gh-pages/documentation/commands/age/add/index.md

@@ -0,0 +1,40 @@
+---
+title: ppl add Manual Page
+layout: command
+section: documentation
+command: add
+---
+
+### Name
+
+ppl add - Add a new contact
+
+### Synopsis
+
+    ppl add <contact> <name>
+
+### Description
+
+This command adds a new contact to the address book. The first parameter,
+`<contact>`, is an alphanumeric string used to uniquely identify the contact
+within the address book. The second parameter, `<name>`, is the contact's actual
+name.
+
+The `<contact>` parameter must not already be in use as the identifier of
+another contact in the address book. Ideally you'll want to pick something short
+and easy to type, so if you're adding a contact named "John Doe", then "john" or
+"jdoe" might be good choices if they aren't already in use.
+
+The `<name>` parameter should be the full name of the contact, and is identical
+to its namesake expected by the [ppl name](../name) command.  Usually, this
+means it needs to be enclosed in quotation marks to indicate that all the words
+in the name are part of the same parameter. 
+
+### Examples
+
+    ppl add jdoe "John Doe"
+
+### See Also
+
+[ppl name](../name)
+

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

@@ -0,0 +1,38 @@
+---
+title: ppl age Manual Page
+layout: command
+section: documentation
+command: age
+---
+
+### Name
+
+ppl age - List or show contacts' ages
+
+### Synopsis
+
+    ppl age [<contact>]
+
+### Description
+
+This command calculates contacts' current ages in years based on their date of
+birth. The purpose of this command is to provide easy access to an often-needed
+piece of information which is indirectly available from the data in the address
+book.
+
+Invoked without any arguments, all contacts are listed with their respective
+ages. If a `<contact>` is specified, only the age of that contact will be shown.
+
+### Examples
+
+    $ ppl bday jdoe 1980-01-01
+    $ ppl age jdoe
+    33
+    $ ppl age
+    fred: 25
+    jdoe: 33
+
+### See Also
+
+* [ppl bday](../bday)
+* [color output](/documentation/configuration/color_age)

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

@@ -0,0 +1,44 @@
+---
+title: ppl bday Manual Page
+layout: command
+section: documentation
+command: bday
+---
+
+### Name
+
+ppl bday - List, show or change birthdays
+
+### Synopsis
+
+    ppl bday
+    ppl bday <contact>
+    ppl bday <contact> <date>
+
+### Description
+
+With no arguments, the dates of birth of each contact in the address book are
+listed.
+
+If a `<contact>` is specified, the date of birth of that contact is shown.
+
+If both a `<contact>` and a `<date>` are given, then the date is stored as the
+date of birth of that contact. The `<date>` parameter must be a valid date
+string parseable by Ruby's
+[Date.parse](http://ruby-doc.org/stdlib-1.9.3/libdoc/date/rdoc/Date.html\#method-c-parse)
+function.
+
+### Examples
+
+    $ ppl bday jdoe 1970-01-01
+    $ ppl bday adam 1975-06-01
+    $ ppl bday jdoe
+    1970-01-01
+    $ ppl bday
+    adam:  1975-06-01
+    jdoe:  1970-01-01
+
+### See Also
+
+* [Date.parse](http://ruby-doc.org/stdlib-1.9.3/libdoc/date/rdoc/Date.html\#method-c-parse)
+* [color output](/documentation/configuration/color_bday)

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

@@ -0,0 +1,38 @@
+---
+title: ppl completion Manual Page
+layout: command
+section: documentation
+command: completion
+---
+
+### Name
+
+ppl completion - Output a completion function for shell integration
+
+### Synopsis
+
+    ppl completion <shell>
+
+### Description
+
+Output a shell autocomplete function to enable automatic completion of commands
+
+The following shells are supported:
+
+* `bash`
+* `zsh`
+
+### Examples
+
+    $ ppl completion bash
+    _ppl()
+    {
+      ....
+    }
+    complete -F _ppl ppl
+
+### See Also
+
+* [Bash Integration Guide](/documentation/integration/bash)
+* [ZSH Integration Guide](/documentation/integration/zsh)
+

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

@@ -0,0 +1,64 @@
+---
+title: ppl email Manual Page
+layout: command
+section: documentation
+command: email
+---
+
+### Name
+
+ppl email - List, show or change email addresses
+
+### Synopsis
+
+    ppl email
+    ppl email <contact>
+    ppl email <contact> <email-address>
+        -d, --delete           delete email address
+        -p, --preferred        mark as preferred
+        -P, --not-preferred    mark as not preferred
+            --format <format>  specify a custom output format
+
+### Description
+
+With no arguments, the email addresses of each contact in the address book are
+listed.
+
+If a `<contact>` is specified, the email addresses of that contact are shown.
+
+If both a `<contact>` and an `<email-address>` are given, then the address is
+added to the email addresses of the contact.
+
+It the `--delete` or `-d` flag is set, then the given `<email-address>` is
+deleted from the specified `<contact>`.
+
+The `--preferred` and `--not-preferred` flags are for marking a given email
+address as "preferred" or not. Internally, this status is represented with
+vCard's `TYPE=pref` parameter in the `EMAIL` field. Preferred email addresses
+are shown with a `*` next to them in the output of `ppl email <contact>`.
+
+### Formatting Options
+
+Using the `--format` option, it is possible to customize the output of `ppl
+email` in several ways. This customizability is similar in usage to a typical
+`printf` function or [`git log`](http://git-scm.com/docs/git-log)'s own
+`--format` option. Here are the placeholders and their values.
+
+    %n   Newline
+    %a   Email address
+    %f   Preferred status ("*" if preferred)
+
+### Examples
+
+    $ ppl email jdoe jdoe@example.org --preferred
+    $ ppl email adam adam@example.com
+    $ ppl email jdoe
+    *  jdoe@example.org
+    $ ppl email
+    adam:  adam@example.com
+    jdoe:  jdoe@example.org
+
+### See Also
+
+* [color output](/documentation/configuration/color_email)
+

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

@@ -0,0 +1,32 @@
+---
+title: ppl grep Manual Page
+layout: command
+section: documentation
+command: grep
+---
+
+### Name
+
+ppl grep - Search the address book
+
+### Synopsis
+
+    ppl grep <options> <search>
+
+### Description
+
+This command is an alias of `git grep`. The `<options>` and the `<search>`
+string given are passed straight on through to `git grep`.
+
+The format and color of the output of this command is subject to your system's
+git configuration, not the contents of your `~/.pplconfig`.
+
+### Examples
+
+    $ ppl grep smith
+    john.vcf:EMAIL:john.smith@example.org
+
+### See Also
+
+* [git grep](http://git-scm.com/docs/git-grep)
+

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

@@ -0,0 +1,28 @@
+---
+title: ppl init Manual Page
+layout: command
+section: documentation
+command: init
+---
+
+### Name
+
+ppl init - Create an empty address book
+
+### Synopsis
+
+    ppl init [<directory>]
+
+### Description
+
+This command creates an empty ppl repository. It creates the specified directory
+if it doesn't already exist, and initializes a git repository there.
+
+If no `<directory>` parameter is explicitly specified, then the operation is
+applied to the current working directory.
+
+### Examples
+
+    ppl init ~/contacts
+
+

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

@@ -0,0 +1,55 @@
+---
+title: ppl ls Manual Page
+layout: command
+section: documentation
+command: ls
+---
+
+### Name
+
+ppl ls - List all contacts
+
+### Synopsis
+
+    ppl ls [<options>]
+        --format <format>  specify a custom output format
+        --pretty <preset>  specify a preset output format
+
+### Description
+
+List all the contacts in the address book.
+
+### Formatting Options
+
+Using the `--format` option, `ppl ls` can be customized to produce output in a
+user-specified format. This is similar functionality to `printf` or the
+customizability of other software such as [git
+log](http://git-scm.com/docs/git-log). Here are the placeholders.
+
+    %n   Newline
+    %i   Contact ID
+    %N   Name
+    %a   Age
+    %b   Birthday
+    %k   Nickname      (first)
+    %e   Email address (preferred/first)
+    %p   Phone number  (preferred/first)
+    %o   Organization  (first)
+
+Commonly used output formats can be stored in `~/.pplconfig` and invoked by name
+using the `--pretty` option. For example, the following configuration would
+allow the format to be used by running `ppl ls --pretty age_info`.
+
+    [pretty]
+        age_info = "%i: %a (%b)"
+
+### Examples
+
+    $ ppl ls
+    jdoe: John Doe <jdoe@example.org>
+    kdoe: Kent Doe <kdoe@example.org>
+
+### See Also
+
+* [color output](/documentation/configuration/color_ls)
+

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

@@ -0,0 +1,36 @@
+---
+title: ppl mutt Manual Page
+layout: command
+section: documentation
+command: mutt
+---
+
+### Name
+
+ppl mutt - Integration with mutt's query_command
+
+### Synopsis
+
+    ppl mutt [<options>] <query>
+        -i, --ignore-case     Turn off case sensitivity
+
+### Description
+
+Searches the names and email addresses in the address book for the given
+`<query>` string and returns a list of results formatted for compatibility with
+[mutt's query_command
+option](http://www.mutt.org/doc/manual/manual-4.html#ss4.5).
+
+This is intended to enable mutt users to integrate ppl as the search backend for
+recipient autocompletion.
+
+If the `-i` flag is given, the search will be case-insensitive, ignoring case
+differences between the query given and the contacts' names and email addresses.
+
+### Examples
+
+Put the following in your `~/.muttrc`:
+
+    set query_command = "ppl mutt '%s'"
+
+

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

@@ -0,0 +1,26 @@
+---
+title: ppl mv Manual Page
+layout: command
+section: documentation
+command: mv
+---
+
+### Name
+
+ppl mv - Move a contact to a different ID
+
+### Synopsis
+
+    ppl mv <source> <destination>
+
+### Description
+
+This changes the ID of a contact. The `<source>` parameter must correspond to
+the ID of an existing contact in the address book. The `<destination>` parameter
+must not already be in use as the ID of an existing contact.
+
+### Examples
+
+    ppl mv john jdoe
+
+