BLOGPOST(1)

NAME

blogpost – WordPress blog client

SYNOPSIS

blogpost [OPTIONS] COMMAND [BLOG_FILE]

DESCRIPTION

A WordPress command-line blog client. It creates and updates blog entries directly from AsciiDoc, Rimu Markup or HTML source documents. You can also delete and list blog entries from the command-line.

• Manages WordPress Posts and Pages.
• Automatically uploads media files (images, video, audio).
• Only posts new or modified content and media files.
• Manages WordPress blog categories.

COMMANDS

cat, categories

Specify the –categories option and either a BLOG_FILE or a –post-id to set the post’s categories. If the –categories option is not specified then all blog categories for all posts are listed.

d, delete

Delete blog post. Deletes the BLOG_FILE blogpost cache file but not the BLOG_FILE.

dump

Convert the BLOG_FILE to HTML and print on stdout.

i, info

Print blog post information. Information is sourced from the client-side BLOG_FILE blogpost cache file.

l, list

List recent blog Posts. Information is sourced directly from WordPress server. Use the –pages option to list published Pages.

p, post

Post the BLOG_FILE to the blog. If this is the first time the BLOG_FILE has been posted a new post is created, otherwise the existing post is updated.

OPTIONS

-a, –attribute=ATTRIBUTE

Set asciidoc(1) attribute value. Identical to asciidoc(1) –attribute option. This option may be specified more than once. Applicable to post command.

–asciidoc-opt=ASCIIDOC_OPT

A single asciidoc(1) option. This option may be specified more than once.

-c, –categories=CATEGORIES

A comma separated list of categories that will be assigned to the blog post. Prefixing CATEGORIES with a plus or minus character adds or removes the categories from an existing post. Category names are case insensitive. If an assigned category does not already exist it will be created. Applicable to categories and post commands.

-d, –doctype=DOCTYPE

Specifies the type of AsciiDoc BLOG_FILE. Allowed values are AsciiDoc document types: article, book or manpage. The default document type is article.

-f, –conf-file=CONF_FILE

Use blogpost configuration file CONF_FILE. This file is read after the (optional) implicit $HOME/.blogpost configuration file.

–force

Force blog file to upload even if it has not been modified since the last update command.

–force-media

Force media files to upload even if they have not been modified since the last update command.

-h, –help

Show this help message and exit.

–mandatory-parameters=PARAMETERS

Specifies a comma separated list of one or more blog parameters that must be defined in the BLOG_FILE. If this option is not present then BLOG_FILE attribute parameter definitions are optional. See the ATTRIBUTE PARAMETERS section. Applicable to post command.

–media-dir=MEDIA_DIR

The name of the directory containing those media files that have URLs with relative path names. Defaults to the same directory as the BLOG_FILE. The media file path is generated by joining MEDIA_DIR with the relative path name.

-M, –no-media

Do not upload media files. Applicable to post command.

-n, –dry-run

Simulate command execution without doing anything, instead report what would have been done.

-p, –pages

Apply COMMAND to blog Pages rather than normal blog Posts. Applicable to delete, list and post commands.

–post-id=POST_ID

Explicitly specify the blog post ID number. This option will only be necessary when there is no client-side BLOG_FILE cache file. Applies to delete and update commands.

–proxy=URL

Send WordPress XML-RPC via proxy server URL.

-t, –title=TITLE

Set the blog post title. Applicable to post command.

-u, –unpublish

Set blog post status to unpublished. Applicable to post command.

-U, –publish

Set blog post status to published. Applicable to post command.

-v, –verbose

Print more information about the actions being performed to stdout. Specifing this option twice to view asciidoc(1) verbose output.

–version

Show program’s version number and exit.

blogpost saves the values set by the following options in the BLOG_FILE blogpost cache file: –doctype, –doctype, –pages, –post-id, –publish, –unpublish and –title. This means that once a blog post has been created you won’t need to use them in subsequent commands unless you decide to change them.

BLOG FILE

The BLOG_FILE is either an AsciiDoc formatted text file; a Rimu Markup text file or an HTML file. blogpost(1) uses asciidoc(1) and rimuc(1) commands to convert AsciiDoc and Rimu Markup blog files to WordPress compatible HTML.

Rimu Markup files must have a .rmu file name extension; HTML files must have a .html or .htm extension; all other files are assumed to be AsciiDoc formatted.

You can insert a WordPress more tag in an AsciiDoc blog file using the AsciiDoc block passthrugh macro:

pass::[<!--more-->]

You can put the more tag in a Rimu Markup blog file verbatim:

<!--more-->

Be aware that WordPress does not handle all HTML tags, this is not an issue with the AsciiDoc or Rimu Markup blog files because the generated HTML is WordPress friendly.

ATTRIBUTE PARAMETERS

Blogpost allows the following blog parameters to be defined inside an AsciiDoc or Rimu Markup BLOG_FILE: categories, status, title, doctype, posttype. The parameters are defined using AsciiDoc attribute entries or Rimu Markup macro definitions — the parameter name is prefixed with blogpost-.

AsciiDoc examples:

:blogpost-status: published
:blogpost-categories: blogpost,AsciiDoc,Blog client,WordPress

Note	Blogpost attribute entry values are not subject to the usual AsciiDoc attribute substitution.

Equivalent Rimu Markup macro definitions:

{blogpost-status} = 'published '
{blogpost-categories} = 'blogpost,AsciiDoc,Blog client,WordPress'

The –mandatory-parameters option is used to make selected BLOG_FILE attribute entries mandatory. Example:

--mandatory-parameters=status,categories

Parameter precedence is (from highest to lowest):

1. Command-line options.
2. BLOG_FILE entries.
3. Blogpost cache.

Blog parameter name	Attribute name	Allowed values
categories	blogpost-categories	Comma separated list of blog category names (see –categories option).
doctype	blogpost-doctype	article, book or manpage (see –doctype option).
posttype	blogpost-posttype	post or page (see –pages option).
status	blogpost-status	published or unpublished (see published and –unpublished options).
title	blogpost-title	Blog title (see –title option).

blogpost(1) automatically creates the blogpost AsciiDoc attribute which is useful for conditionally processing AsciiDoc document content.

blogpost(1) automatically uses the AsciiDoc title if neither the –title option or the blogpost-title attribute is defined and the title is not in the cache file.

METADATA CACHING

You can upload media files to the WordPress server using XML-RPC but there is currently no way to programmatically list or delete media files held on the server. Blindly uploading new copies to the server every time the document is updated is an unacceptable.

To overcome this problem blogpost retains information about previously uploaded media (source paths, server URLs and media file MD5 checksums) in client-side per-document cache files. Cache files are stored in the same directory as the source BLOG_FILE but with .blogpost file name extensions. A document’s cache file is read before blogpost runs a command and is updated after running the post command. The delete and reset commands delete a document’s cache file.

blogpost uses cache files to ensure only new or modified media files are uploaded to the WordPress server. Because the caching is on a per-document basis, media files are not shared between documents.

In addition to storing media metadata, blogpost cache files also store the blog post ID, URL, title, creation and update timestamps along with the last used value of many of the blogpost command options. This is very handy, it means you don’t have to remember the blog post ID or the options you used to create the blog when you rerun the post command.

MEDIA PROCESSING

The generated HTML content is scanned for HTML anchor (a) and image (img) tags, if these tags refer to local media files then they are processed as follows:

• The BLOG_FILE cache (see METADATA CACHING) is checked to see if the media file has been previously uploaded, if it has then the media file is checked (using an MD5 checksum) to see if it has changed.
• If the media file is new or has changed then it is uploaded to the server.
• Finally the media file reference in the HTML content is replaced with the server URL of the uploaded media file.

You can disable media processing with the –no-media option.

Allowable media file types are: gif, jpg, jpeg, png, pdf, doc, odt, mp3, ogg, wav, m4a, mov, wmv, avi, mpg. Note that not all WordPress servers support all media file types, if you get an Invalid file type the file type is not supported — check with your WordPress hoster, they may have upgrade options which will allow you to upload.

POSTS AND PAGES

There are two types of WordPress content, Posts and Pages. A Post is the WordPress term for a regular blog entry whereas a Page (sometimes called a static page) is an entry that lies outside the normal blog chronology. WordPress manages Posts and Pages separately — use the –pages option to differentiate between the two. See http://codex.wordpress.org/Pages for a detailed explanation.

EXAMPLES

Create, list, update and delete a blog post:

blogpost.py post blogging_with_asciidoc.txt
blogpost.py info blogging_with_asciidoc.txt
blogpost.py list
blogpost.py post blogging_with_asciidoc.txt
blogpost.py delete blogging_with_asciidoc.txt

RESOURCES

Mercurial repository: http://code.google.com/p/blogpost/

Python WordPress library: http://www.blackbirdblog.it/programmazione/progetti/28

AsciiDoc: http://www.methods.co.nz/asciidoc/

WordPress.org: http://wordpress.org/

Rimu Markup: http://rimumarkup.org/

AUTHOR

Written by Stuart Rackham, <srackham@gmail.com>

COPYING

Copyright (C) 2008-2013 Stuart Rackham. Free use of this software is granted under the terms of the MIT License.

Advertisement