README.md in pinpress-1.0.2 vs README.md in pinpress-1.1.0

- old
+ new

@@ -7,11 +7,11 @@ # Why? Every two weeks, I create a "link mash" for my website; this link mash consists of URLs that I find interesting and want to share with my readers. Previously, I would save those interesting URLs to an Evernote note and, every two weeks, manually create my link mash for use in Wordpress. <barf/> -When I began using [Pinboard](http://pinboard.in "Pinboard") to save interesting links, I knew I needed a better method. This tool is the result: **Pin**board + Word**press**. +When I began using [Pinboard](http://pinboard.in "Pinboard") to save interesting links, I knew I needed a better method. This tool is the result: **Pin** board + Word **press**. # Prerequisites In addition to Git (which, given you being on this site, I'll assume you have), Ruby (v. 1.9.3 or greater) is needed. @@ -32,11 +32,11 @@ SYNOPSIS pinpress [global options] command [command options] [arguments...] VERSION - 1.0.2 + 1.1.0 GLOBAL OPTIONS --help - Show this message --version - Display the program version @@ -71,101 +71,17 @@ $ pinpress init ``` Initialization will prompt you to enter your Pinboard API token. Once, entered, this (and other pertinent data) will be stored in `~/.pinpress`. -# Getting Pins - -``` -$ pinpress pins -# => <ul><li><b><a title="Using Drafts for Remote CLI" href="https://gist.github.com/hiilppp/10993803" target="_blank">Using Drafts for Remote CLI</a>.</b> As a text file is added to a directory to which this AppleScript is associated as Folder Action, the content of the received file is executed as shell script and the generated output sent to an iOS device.</li></ul> -``` - -This simple command will return all pins from the user's account and output them based on the [Pin Template](https://github.com/bachya/PinPress#pin-templates "Pin Templates") provided. - -Pinpress also provides some flags that allow a user to define specific pins to grab: - -* `-s`: the start date to use (uses [Chronic](https://github.com/mojombo/chronic "Chronic"), which allows dates like "last Tuesday") -* `-e`: the end date to use (also uses [Chronic](https://github.com/mojombo/chronic "Chronic")) -* `-n`: the number of pins to return (e.g., 20) -* `-t`: a CSV list of tags to grab (e.g., "tag1,tag2") - -## Getting Pins From a Date Forward - -``` -$ pinpress pins -s 2014-01-01 -``` - -...returns all pins from January 1, 2014 to the current day. - -## Getting Pins Until a Date - -``` -$ pinpress pins -e 2014-01-01 -``` - -...returns all pins up to January 1, 2014. - -## Getting Pins Between a Date Range - -``` -$ pinpress pins -s 2014-01-01 -e 2014-01-31 -``` - -## Getting Tagged Pins - -``` -$ pinpress pins -t "ruby,cli" -``` - -...returns all pins tagged "ruby" *and* "cli". - -# Getting Tags - -Pinpress can also work with tags in a Pinboard account: - -``` -$ pinpress tags -# => cli (1),github (1),applescript (1),osx (1),link-mash (1) -``` - -This simple command will return all tags from the user's account and output them based on the [Tag Template](https://github.com/bachya/PinPress#tag-templates "Tag Templates") provided. - -Pinpress also provides some flags that allow a user to define specific tags to grab: - -* `-s`: the start date to use (uses [Chronic](https://github.com/mojombo/chronic "Chronic"), which allows dates like "last Tuesday") -* `-e`: the end date to use (also uses [Chronic](https://github.com/mojombo/chronic "Chronic")) - -## Getting Tags From a Date Forward - -``` -$ pinpress tags -s 2014-01-01 -``` - -...returns all tags used from January 1, 2014 to the current day. Note that for each tag returned, the data includes both the tag name and the number of times it was used. - -## Getting Tags Until a Date - -``` -$ pinpress tags -e 2014-01-01 -``` - -...returns all tags used up to January 1, 2014. - -## Getting Tags Between a Date Range - -``` -$ pinpress tags -s 2014-01-01 -e 2014-01-31 -``` - # Templates -The first stop on the PinPress journey is templates. Templates are used to define how data should be output and are defined in `~/.pinpress` and come in two forms: **Pin Templates** and **Tag Templates**. +The first stop on the PinPress journey is templates. Templates are used to define how data should be output and are defined in `~/.pinpress`. They come in two forms: **Pin Templates** and **Tag Templates**. ## Pin Templates -Pin Templates define how a pin should be output. +Pin Templates define how a pin from Pinboard should be output. ### Schema Pin Templates are placed under the `pin_templates` section of the `~/.pinpress` config file -- as an example: @@ -174,20 +90,19 @@ - name: pinpress_default opener: "<ul>" closer: "</ul>" item: "<li><b><a title=\"<%= description %>\" href=\"<%= href %>\" target=\"_blank\"><%= description %></a>.</b> <%= extended %></li>" - item_separator: "\n" + /Users/abach/.pinpress: "\n" ``` A Pin Template can have several different sub-keys: * `name` (**required**): the name of the template * `opener` (*optional*): the text that should exist above the pins * `closer` (*optional*): the text that should exist above the pins * `item` (**required**): the formatted text that should be output for every pin -* `item_separator` (**required**): the text that should exist between each pin ("item") ### Available Tokens Additionally, a Pin Template can make use of several different tokens that are filled by a pin's values: @@ -216,24 +131,16 @@ config_location: "/Users/abach/.pinpress" default_pin_template: pinpress_default # ... other keys ... pin_templates: - name: pinpress_default - opener: "<ul>" + opener: "<ul>\n" closer: "</ul>" item: "<li><b><a title=\"<%= description %>\" href=\"<%= href %>\" target=\"_blank\"><%= - description %></a>.</b> <%= extended %></li>" - item_separator: "\n" + description %></a>.</b> <%= extended %></li>\N" ``` -Using this example, here's what's output: - -``` -$ pinpress pins -s 'yesterday' -# => <ul><li><b><a title="Using Drafts for Remote CLI" href="https://gist.github.com/hiilppp/10993803" target="_blank">Using Drafts for Remote CLI</a>.</b> As a text file is added to a directory to which this AppleScript is associated as Folder Action, the content of the received file is executed as shell script and the generated output sent to an iOS device.</li></ul> -``` - ## Tag Templates Tag Templates are exactly like Pin Templates, but are used for tags. ### Schema @@ -242,20 +149,19 @@ ```YAML tag_templates: - name: pinpress_default item: "<%= tag %> (<%= count %>)" - item_separator: "," + /Users/abach/.pinpress: "," ``` A Pin Template can have several different sub-keys: * `name` (**required**): the name of the template * `opener` (*optional*): the text that should exist above the pins * `closer` (*optional*): the text that should exist above the pins * `item` (**required**): the formatted text that should be output for every pin -* `item_separator` (**required**): the text that should exist between each pin ("item") ### Available Tokens Additionally, a Pin Template can make use of several different tokens that are filled by a pin's values: @@ -280,19 +186,102 @@ # ... other keys ... pin_templates: # ... other keys ... tag_templates: - name: pinpress_default - item: "<%= tag %> (<%= count %>)" - item_separator: "," + item: "<%= tag %> (<%= count %>)," ``` -Using this example, here's what's output: +# Getting Pins ``` -$ pinpress tags -s 'yesterday' +$ pinpress pins +# => <ul><li><b><a title="Using Drafts for Remote CLI" href="https://gist.github.com/hiilppp/10993803" target="_blank">Using Drafts for Remote CLI</a>.</b> As a text file is added to a directory to which this AppleScript is associated as Folder Action, the content of the received file is executed as shell script and the generated output sent to an iOS device.</li></ul> +``` + +This simple command will return all pins from the user's account and output them based on the [Pin Template](https://github.com/bachya/PinPress#pin-templates "Pin Templates") provided. + +Pinpress also provides some flags that allow a user to define specific pins to grab: + +* `-s`: the start date to use (uses [Chronic](https://github.com/mojombo/chronic "Chronic"), which allows dates like "last Tuesday") +* `-e`: the end date to use (also uses [Chronic](https://github.com/mojombo/chronic "Chronic")) +* `-n`: the number of pins to return (e.g., 20) +* `-t`: a CSV list of tags to grab (e.g., "tag1,tag2") + +## Getting Pins From a Date Forward + +``` +$ pinpress pins -s 2014-01-01 +``` + +...returns all pins from January 1, 2014 to the current day. + +## Getting Pins Until a Date + +``` +$ pinpress pins -e 2014-01-01 +``` + +...returns all pins up to January 1, 2014. + +## Getting Pins Between a Date Range + +``` +$ pinpress pins -s 2014-01-01 -e 2014-01-31 +``` + +## Getting Tagged Pins + +``` +$ pinpress pins -t "ruby,cli" +``` + +...returns all pins tagged "ruby" *and* "cli". + +# Getting Tags + +Pinpress can also work with tags in a Pinboard account: + +``` +$ pinpress tags # => cli (1),github (1),applescript (1),osx (1),link-mash (1) ``` + +This simple command will return all tags from the user's account and output them based on the [Tag Template](https://github.com/bachya/PinPress#tag-templates "Tag Templates") provided. + +Pinpress also provides some flags that allow a user to define specific tags to grab: + +* `-s`: the start date to use (uses [Chronic](https://github.com/mojombo/chronic "Chronic"), which allows dates like "last Tuesday") +* `-e`: the end date to use (also uses [Chronic](https://github.com/mojombo/chronic "Chronic")) + +## Getting Tags From a Date Forward + +``` +$ pinpress tags -s 2014-01-01 +``` + +...returns all tags used from January 1, 2014 to the current day. Note that for each tag returned, the data includes both the tag name and the number of times it was used. + +## Getting Tags Until a Date + +``` +$ pinpress tags -e 2014-01-01 +``` + +...returns all tags used up to January 1, 2014. + +## Getting Tags Between a Date Range + +``` +$ pinpress tags -s 2014-01-01 -e 2014-01-31 +``` + +# Other Configuration Options + +In addition to `default_pin_template` and `default_tag_template`, you can place some other special keys in the `pinpress` section of `~/.pinpress`: + +* `default_tags`: the default tags to be used when getting pins (e.g., `'ruby,pinboard'`). This can be overridden by using the `-t` flag. +* `default_num_results`: the default number of results to return (e.g., '5'). This can be overridden by using the `-n` flag. # Known Issues & Future Releases Check out the Pinpress roadmap via the [Trello Board](https://trello.com/b/lmuC8TT0/pinpress "Pinpress Trello Board"). \ No newline at end of file