README.md in pinpress-1.5.2 vs README.md in pinpress-1.6.0

- old
+ new

@@ -40,11 +40,11 @@ SYNOPSIS pinpress [global options] command [command options] [arguments...] VERSION - 1.5.2 + 1.6.0 GLOBAL OPTIONS --help - Show this message --version - Display the program version @@ -66,15 +66,22 @@ SYNOPSIS pinpress [global options] pins [command options] COMMAND OPTIONS + -a - Auto-links any URLs found in a pin description + -c - Copy final output to the system clipboard -e arg - The end date to pull pins to (default: none) + l - Allows the user to create <a> links around detected URLs -m arg - The pin template to use (default: none) -n arg - The number of results to return (default: none) -s arg - The start date to pull pins from (default: none) -t arg - The tags to use (e.g., "ruby,pinboard") (default: none) + +COMMANDS + <default> - + last - Gets all pins from the last run date + 1 ``` # Initialization ```bash @@ -100,10 +107,13 @@ * `-e`: the end date to use (also uses [Chronic](https://github.com/mojombo/chronic "Chronic")) * `-m`: the PinPress template to use * `-n`: the number of pins to return (e.g., 20) * `-t`: a CSV list of tags (e.g., "tag1,tag2") that must exist for the returned pins +By default, pin template text will be output to the terminal; you can use the +`-c` switch to output it to the system clipboard instead. + ## Getting Pins From a Date Forward ```bash $ pinpress pins -s 2014-01-01 ``` @@ -160,10 +170,13 @@ * `-m`: the PinPress template to use * `-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")) +By default, pin template text will be output to the terminal; you can use the +`-c` switch to output it to the system clipboard instead. + ## Getting Tags From a Date Forward ```bash $ pinpress tags -s 2014-01-01 ``` @@ -374,10 +387,109 @@ ```bash link-mash (15),app (2),ios (3),productivity (1),launch-center-pro (1),drafts (2), ``` +# URL Linking + +I often run into the situation where I want to take a URL from a pin's description +and add an `<a>` tag around it (since Pinboard doesn't allow you to embed the HTML +within the pin description itself). PinPress provides two mechanisms to accomplish +this: automatic linking and manual linking. + +## Automatic URL Linking + +### Using It + +To use automatic linking, simply use the `-a` switch when running PinPress. + +Alternatively, to always use automatic linking, include a `auto_link` key/value +in `~/.pinpress`: + +```yaml +pinpress: + auto_link: true +``` + +Note that the `auto_link` configuration key can be overridden by using a different +URL linking switch (such as `-l`). + +### How It Works + +Using this method, PinPress will scan each pin that is being requested for URLs. +Upon finding a URL, PinPress will automatically wrap it in an `<a>` tag. + +For example, given a description that looks like this: + +```html +...this is some text with a URL: http://www.google.com. +``` + +...PinPress will modify the description such that the following is output +instead: + +```html +...this is some text with a URL: <a href="http://www.google.com" target="_blank">http://www.google.com</a>. +``` + +Finally, this link gets stored in `~/.pinpress`: + +```yaml +links: + # This ID is a combination of the URL + # and the pin in which it is found. + 853d65b7e76a57955040e97902fc2b3c: + title: Pin with Google + url: http://www.google.com + link_text: http://www.google.com +``` + +This happens for two reasons: + +1. Going forward, any request that returns this pin will use the data found +in `~/.pinpress` (so that it doesn't have to be recalculated). +2. If you want to modify the text that gets used for this link in this pin, +you can do it here. + +## Manual URL Linking + +### Using It + +To use automatic linking, simply use the `-l` switch when running PinPress. + +Alternatively, to always use automatic linking, include a `manual_link` key/value +in `~/.pinpress`: + +```yaml +pinpress: + manual_link: true +``` + +Note that the `manual_link` configuration key can be overridden by using a different +URL linking switch (such as `-a`). + +### How It Works + +This method is similar to automatic linking in that it will search each pin in the +output for URLs in its description. When found, the user is prompted to enter the +text that will create the link. + +For example, given a description that looks like this: + +```html +Check out https://gifyoutube.com/! +``` + +...imagine that the user types in `GIF Youtube`; the result will look like this: + +```html +Check out <a href="https://gifyoutube.com/" target="_blank">GIF Youtube</a>! +``` + +Like automatic linking, the results of this URL/pin combo are stored in +`~/.pinpress` for easy lookup and future editing. + # Other Configuration Options ## Global Keys You can place special keys in the `pinpress` section of `~/.pinpress` to @@ -386,15 +498,25 @@ ```yaml pinpress: # ...other keys... # The default pins template to use - default_pin_template + default_pin_template: template_name # The default tags template to use - default_tag_template + default_tag_template: template_name + # Automatic URL linking; note that this + # cannot exist eat the same time as manual + # URL linking + auto_link: true + + # Manual URL linking; note that this + # cannot exist eat the same time as auto + # URL linking + manual_link: true + # ...other keys... ``` ## Template Keys @@ -432,11 +554,12 @@ pinpress: config_location: "/Users/abach/.pinpress" default_pin_template: pinpress_default default_tag_template: pinpress_default log_level: WARN - version: 1.5.0 + version: 1.6.0 api_token: bachya:1234567890987654321 + manual_link: true pin_templates: - pinpress_default: opener: | <em>The weekly Link Mash is a curated selection of tools, stories, and other links that I found during my travels on the web. All of my links can be found on <a title="Bachya's Pinboard: Link Mash" href="https://pinboard.in/u:bachya/t:link-mash/" target="_blank">my Pinboard</a>; you can also find the Link Mash archives <a href="http://www.bachyaproductions.com/tag/link-mash/">here</a>.</em><ul> item: |