Charm is a client for journaling and blogging. It supports:

• LiveJournal and LiveJournal-based sites, such as DeadJournal.
• Atom API-based sites, such as Blogger and Movable Type.
• MetaWeb API-based sites, such as those that utilize WordPress.

Charm is written in Python, which means that it runs on a very wide variety of platforms. It is entirely text-based, and can be used either to post directly from the command line, or via interactive text menus.

Charm is an open-source program licensed under the GNU General Public License (GPL). This means that Charm is free to use and distribute. If you modify the source code in some useful way, please let the author know, so that your changes can be incorporated into the next Charm release.

Installation

Charm runs on Unix systems (Linux, Solaris, the MacOS X Terminal, etc.), as well as Windows. A variety of other operating systems also support Python; follow the Unix installation instructions for these.

Installing Charm on a Unix System

You can simply run Charm out of the directory that you unpacked it into, by typing charm (assuming that it's in your path).

If you'd like to install Charm system-wide, so that any user can use it, you'll need:

1. Access to root, in order to do the installation.
2. Python version 1.6 or later, or the Distutils module.

To install Charm system-wide, do the following:

1. Become root.
2. In the Charm directory, type: python setup.py install

Once you install Charm system-wide, any user can use Charm by typing charm (assuming the program is in his path).

Installing Charm on a Windows System

To install Charm for personal use on your Windows PC, do the following:

1. Rename the charm program to charm.py (this is necessary in order to get Windows to recognize it as a Python script).

2. Create a batchfile with the following lines:

   set HOME=C:\DOCUME~1\YOUR_WINDOWS_LOGIN_NAME
   set EDITOR=notepad
   charm.py

   Replace YOUR_WINDOWS_LOGIN_NAME with whatever your Windows login name is. You can also optionally replace "notepad" with the name of your favorite editor.

In order to run Charm interactively, run the batchfile. Otherwise, you can invoke charm.py directly. Make sure Python is in your Windows path.

Getting Started

Once you have Charm installed, you will need to create a minimal .charmrc file. That file must go in your home directory.

For Unix users, your home directory can be found by typing echo $HOME -- it's normally the directory that you're placed into when you log into the system.

For Windows users, your home directory is normally:
C:\Documents and Settings\YOUR_WINDOWS_LOGIN_NAME

A minimal .charmrc file consists of just one line:
login = Your_Journal_Username Your_Journal_Password
(Fill in your LiveJournal or other LJ-site username and password for Your_Journal_Username and Your_Journal_Password.)

There are a large number of other configuration parameters that you can put in your .charmrc; the sample.charmrc file that's included with the distribution shows you all of them. We'll explore the possibilities later on, including a way to avoid placing your cleartext password in your .charmrc file.

If you ever need a quick reminder of what Charm can do, type charm -h or charm --help
This will show you all of the basic command-line options available for Charm. (Additional options used for posting are shown with charm -o or charm --options)

Most options in Charm have a short, one-letter form, and a verbose word form. You can use either; there's no difference between them. This documentation always uses the one-letter form, when available.

Users and Journals

You can store your usernames and passwords in your .charmrc, so you don't have to type them every time you start Charm. Furthermore, Charm can handle multiple usernames, journals, journal sites, and configuration files.

Specifying Login Information: Sites Using the LiveJournal Protocol

If you are using LiveJournal or a LiveJournal-based site, you can specify login information -- the username that you use for journal activities -- in your .charmrc in one of two ways. The first is the login configuration parameter; the other is the hlogin configuration parameter.

The format of login is very simple:
login = username password
where username is your journal username, and password is your journal password.

However, using login means that you're putting your password, in cleartext, in a file. That's not very secure. So, instead, if you can, you should find your "hash password", by doing the following:

1. Start Python. (Just typing python in Unix, or clicking the Python icon in Windows, should work.)

2. Type import ljcharm

3. Type ljcharm.md5digest("password") (where password is your journal password). You should get back a string of characters between two single quote marks, like 'a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5'.

4. Your hash password is the string of characters between the single quote marks.

Once you've found your hash password, you can put this in your .charmrc file:
hlogin = username hash
where username is your journal username, and hash is your hash password.

Specifying Login Information: Blogger and other Atom API Sites

If you are using Blogger or another Atom API-based blogging site, you can specify login information -- the username that you use for blog activities -- in your .charmrc in one of two ways. The first is the atomblog configuration parameter; the other is the hatomblog configuration parameter.

The format of the atomblog configuration parameter is very simple:
atomblog = username password URIpath
where username is your blog username, password is your blog password, and URIpath is the root URL for feed discovery for your blog. URIpath is optional; Blogger, with a root of https://www.blogger.com/atom/, is the default. If you're using something other than Blogger, you'll need to specify URIpath.

For example:
atomblog = test testpw http://www.typepad.com/t/atom/weblog
is the appropriate login for user test with password testpw on Typepad.

Using the atomblog configuration parameter means that you're putting your password, in cleartext, in a file. That's not very secure. If your blog site doesn't use WSSE, you should instead find your "hash password", by doing the following:

1. Start Python. (Just typing python in Unix, or clicking the Python icon in Windows, should work.)

2. Type import base64

3. Type base64.encodestring("username:password")[:-1] (where username is your blog username and password is your blog site password, and note that the two are separated by a colon). You should get back a string of characters between two single quote marks, like 'dGVzdDp0ZXN0'.

4. Your hash password is the string of characters between the single quote marks.

Once you've found your hash password, you can put this in your .charmrc file:
hatomblog = username hash URIpath
where username is your journal username, hash is your hash password, and URIpath is the root URL for feed discovery.

With either atomblog or hatomblog specified, Charm will assume that it should use basic authentication over SSL if URIpath designates the https protocol; otherwise it will use WSSE authentication over regular HTTP. Blogger, for instance, supports the former, while Movable Type (Typepad) supports the latter. Charm will also try falling back to basic authentication over non-SSL if SSL fails, or falling back to WSSE authentication over SSL if regular HTTP fails. In other words, the protocol you specify in URIpath really matters for determining basic authentication vs. WSSE, more than it does whether SSL is used or not.

Specifying Login Information: MetaWeb API Sites

If you are using a blogging site that uses the MetaWeb API, such as a site that is powered by WordPress, you can specify login information -- the username that you use for blog activities -- in your .charmrc by using the metaweb configuration parameter.

The format of the metaweb configuration parameter is as follows:
metaweb = username password URIpath
where username is your blog username, password is your blog password, and URIpath is the URL of the XML-RPC MetaWeb interface for your blog.

For example:
metaweb = test testpw http://testuser.wordpress.com/xmlrpc.php
is the appropriate login for user test with password testpw on wordpress.com.

Handling Multiple Usernames

You can post under a variety of different usernames, using Charm. If you've specified multiple login, hlogin, atomblog hatomblog, and metaweb parameters in your .charmrc -- because, for instance, you have multiple journal accounts -- you can specify which one to use by default by adding the following line to your .charmrc:
default_user = username

When you start Charm, it reads your .charmrc file, and tries to figure out what journal user you'd like to be, checking sequentially as follows (i.e., things later in the list aren't checked unless things earlier in the list haven't yielded a user):

1. If you don't have a login, hlogin, atomblog, hatomblog, or metaweb parameter in your .charmrc, it will prompt you for a LiveJournal username and password.

2. If you specify the command-line option -u username, it will use that username. If there's no corresponding login, hlogin, atomblog, hatomblog, or metaweb in your .charmrc, you will be prompted for a password.

3. If you have the default_user configuration parameter in your .charmrc, it will use that username. If there's no corresponding login, hlogin, atomblog, hatomblog, or metaweb in your .charmrc, you will be prompted for a password.

4. If you only have a single login, hlogin, atomblog, hatomblog, or metaweb in your .charmc, it will use that username.

5. If you have multiple login, hlogin, atomblog, hatomblog, or metaweb parameters in your .charmrc, it will ask you which one you want to use.

Handling Different LiveJournal-Based Sites

By default, Charm utilizes LiveJournal. However, you can use Charm with any journal site that supports the LJ protcol, such as DeadJournal or Blurty, as well as any blogging site that supports the Atom API, such as Blogger, or that supports the MetaWeb API, such as WordPress-based sites. (Configuring multiple blogs was described in a previous section.)

If you primarily use a LiveJournal-based site other than LiveJournal, put the following line in your .charmrc:
url = http://journalsite/interface/flat
where journalsite is the site's hostname, such as www.deadjournal.com or www.blurty.com.

If you use a mixture of LiveJournal-based sites, you can specify which site to use with a given login name, by providing a third parameter to the login or hlogin configuration options. This third parameter is the hostname of the site. In the case of LiveJournal, this is www.livejournal.com; DeadJournal is www.deadjournal.com, Blurty is www.blurty.com, and so forth. This will look as follows:
login = username password site
hlogin = username hash site

For example:
login = test test www.livejournal.com
is the appropriate login for user test with password test on LiveJournal.

Posting to Some Other Journal by Default

By default, Charm operates on the journal that's associated with your username. However, some people primarily post to a community or to a shared journal and would prefer if Charm defaulted to using that by default. (If you're posting to a community or shared journal, you're still doing so under your own username -- the post's just going somewhere different.)

If you're one of those people, you may find it useful to specify the following in your .charmrc:
journal = journalname
where journalname is the name of the community or shared journal.

This configuration option is only for LiveJournal-based sites. If you have multiple blogs under one Atom or MetaWeb API account, you will always be prompted for which blog you want to work with when you start Charm with that blog username.

Using Multiple Configuration Files

You can start Charm with the -f filename command-line option, where filename is the name of a configuration file to read. This file will be read instead of the .charmrc file.

Configuration files can include other configuration files, with:
include filename
where filename is the name of the additional configuration file to read.

Nested configuration files of this type are particularly useful if you have different configurations for different usernames, particularly if those usernames are spread across several diferent journal sites. You can place the configuration parameters common to all of your usernames into one file, and then, for the special cases, have separate files that include that file.

CheckFriends: Checking Whether Friends Have Posted New Entries

Charm can run in a background mode that will let you know when your friends have posted new journal entries. When there are new posts, you'll see the message:
>> You have new LiveJournal friend updates. <<

Unix users: Invoke Charm in checkfriends mode by typing charm -c -i 15 &
Charm will run as a background job (this is what the ampersand does), and you can continue to work in that terminal window. The new-updates message will be displayed in that window. (If you're a Unix user, for the rest of the examples in this section, always add the & to the end of any charm -c command.)

All other users: Invoke Charm in checkfriends mode by typing charm -c -i 15
Charm will run in a window of its own, and the new-updates message will be displayed in that window.

You can replace the 15 with the number of minutes that you want Charm to wait between each check (the "polling interval"). In order to avoid burdening the journal site's servers, it is strongly suggested that you don't use a value below 5.

By default, Charm checks to see if any of your friends have posted entries. You can restrict this check to just some of your friend groups, however, by specifying a command-line option, -g FRIENDGROUP. You can specify this command-line option as many times as you want. For instance, if you want to check only your friend groups BestBuddies, Interesting, and Outcasts, you would do this:
charm -c -i 15 -g BestBuddies -g Interesting -g Outcasts

To avoid having to specify -i minutes or -g group on the command line, you can put the options you want in your .charmrc file.

To have Charm automatically use a specific polling interval, put the following line in your .charmrc:
checkdelay = 30
(Replace 30 with whatever you want the polling interval to be.)

To have Charm automatically check only a specific set of friend groups, put this line in your .charmrc:
checkgroups = Group1,Group2,Group3
(Substitute a list of the friend groups that you want to check, with the group names separated by commas, in place of Group1 through Group3. You can list as many or as few friend groups as you want.)

Journal Downloads

You can download some or all of your journal entries from within Charm. This is useful if you want to create an offline mirror or backup of your journal.

Creating an Offline Backup of Your Entire Journal

Type charm -z to run a synchronization for the first time. This will download all of your entries and save them to your disk. The entries will be written to your archive directory.

In the future, you can type charm -z to update the synchronization of your journal. This will download all the entries that you have posted or edited since the last time you ran a synchronization.

This feature is particularly handy if you are on a Unix system, and you want to back up your journal nightly; you can just create a crontab entry that runs charm -z once per day.

You can also run a synchronization directly within Charm; to do so, start Charm, then select "A" (archive past journal entries) from the main menu, then "A" again to run the archive.

Downloading Part of Your Journal

Charm can download and save journal entries that are dated between two specified dates. The entries are written to your archive directory.

Start Charm, then select "a" (archive past journal entries). Then, select "s" and enter the date of the first entry that you want to download. If the last day you want to archive isn't today, you should next select "e", and enter the last date that you want entries from.

Select "a" to run the archive. Charm will download all entries that are dated between the start date and the end date, inclusively. It will go month-by-month, and then day-by-day within each month.

This type of archival is less efficient than using Charm's synchronization capabilties. It is best used when you don't want your entire journal, but a much narrower range of posts, such as a period of several weeks.

Archive Options: Archive Directory Location

By default, posts are saved to the .ljarchive directory beneath your home directory. There are three ways to change this, so you can save the archived posts to any place on your system:

1. Use a command-line option, -a directory (where directory is the pathname of the directory you want to use).

2. Add a line to your .charmrc file, like so:
   archive_dir = directory
   (Substitute the directory path you want to use for directory. Unix users can use ~ as shorthand for their home directory, i.e., the default is ~/.ljarchive)

3. Change it in the archive menu from within Charm, via the "d" selection.

Archive Options: Archive Directory Organization

There are three ways that your archive directory can be organized. They are:

1. none. Put all posts in the archive directory, without any subdirectories. Posts will be named YYYYMMDD_hhmm, where YYYY is the year, MM is the month number, DD is the day, hh is the hour, and mm is the minute of the post's date.

2. year. The posts go in the archive directory, with a subdirectory for each year. Posts will be named MMDD_hhmm.

3. month. The posts go in the archive directory, with a subdirectory for each year, and subdirectories for each month within each year's subdirectory. Posts will be named DD_hhmm.

The default is month. You can change this in two ways:

1. Add a line to your .charmrc file, like so:
   organize = type
   (Substitute none, year, or month for type.)

2. Change it in the archive menu from within Charm, via the "o" selection.

Quick Posting

You can post, using Charm, from the command line. This is useful for making quick posts, and for using Charm as a filter (piping the output of some other program to Charm for posting).

Quick posting reads the journal text to post from standard input (stdin). If you're not piping the output of some other program to Charm, that means that you'll be presented with a blank line after invoking Charm in quick mode by using charm -q; type all the text that you want to post, and then press control-d to send the post.

Unix users: If you've got your post written up in a text file and want to send it quickly, you can type:
cat textfilename | charm -q
to do a quick post (replace textfilename with the name of the text file that holds your post). You can replace the part before the pipe (the "|") with any command; for instance, if you've got a filter that writes to stdout, you can pipe its output directly to Charm.

By specifying additional parameters on the command line, you can add various bits of content to your post, as follows:

• -s subject. Specifies the subject line for the post.

• -m mood. Specifies the mood for the post.

• -k picture_keyword. Specifies the userpic to use for the post.

• -p permission. Specifies the security permission for the post, which can be public, friends, private, or the name of a friends group.

• -M music. Specifies the music for the post.

• -A. Auto-detect what music is playing, and use that as the music for the post. (Cannot be used with -M, for obvious reasons.)

You can also specify other ways to treat your post, via the command line. All of these options have a state which can be on or off.

• --autoformat=state. If on, specifies that you're formatting this post yourself (doing your own HTML).

• --backdate=state. If on, backdate this post.

• --comments=state. If off, don't allow comments on this post.

• --noemail=state. If off, don't email comments on this post to you.

You can get a list of all command-line posting options supported by Charm by typing charm -o

Currently, quick posting to blogs via the Atom and MetaWeb APIs is only supported for usernames that have a single associated blog. If you have multiple blogs under the same site and username, you won't be able to quick post to them.

Logging In

By default, when you start Charm in interactive mode for a LiveJournal-based site, it will try to log you in. This will display a banner welcome message, and download your userpic keywords and the server's list of moods. Also, if you are a paid user, this will enable you to use the fast servers for future transactions during this run of Charm.

You can turn this off by putting the following in your .charmrc:
nologin = yes

You can also force logging in, regardless of what's in your .charmrc, by specifying the -l command-line option.

Similarly, you can force skipping the login, regardless of what's in your .charmrc, by specifying the -n command-line option.

Not logging in at startup is useful, if you want to save a little bit of start-up time (there's a brief delay while waiting for the journal server to respond), you're not connected to the network, or you don't plan to do anything in Charm that requires logging in. There's never any harm in not logging in -- if Charm needs data that it would normally get from a login, it will perform the necessary operations automatically.

If you didn't log in when you started Charm (or there was a server that prevented you from logging in), you can select "l" from the main menu in order to log in.

If you start Charm using a blog username rather than a LiveJournal one, Charm will always do the equivalent of logging you in -- it'll attempt to authenticate and download the list of your blogs. You can't turn this off because Charm needs that data before you can perform any operations.

Interactive Posting

To begin posting a new journal entry, start Charm, and then select "p" (post a journal entry) from the main menu. You'll be taking to the post menu, where you can edit your post and change its metadata properties (like its security level, mood, and so forth).

Category Tags and Journals When you use a LiveJournal-based site, you can pick one or more tags to be associated with your post by selecting "c" from the post menu. You can choose as many tags as you'd like. The tags you've used in the past are stored in Charm's cache file, as there's currently no way to retrieve them directly via the LiveJournal protocol; if you sometimes add tags via other clients or via the Web, Charm won't know about them (but you can just add them, and they'll work fine).

When you use an Atom API-based blog that has support for putting a post in a category, like Movable Type, you can choose a category for your post by selecting "c" from the post menu. You can only choose one category. Categories have to be defined on your blogging site before you can use them in Charm.

When you use a MetaWeb API-based blog, you can choose categories for your post by selecting "c" from the post menu. Categories have to be defined on your blogging site before you can use them in Charm (MetaWeb-based sites ignore categories in posts if they haven't been previously defined).

When using a LiveJournal-based site, by default, you'll post to the journal associated with your username (or with the journal configuration parameter). If you'd like this post to go to a community or shared journal, select "j" (change journal to post in) from the post menu.

Journals and UserPics

Choosing "k" from the post menu will allow you to choose one of your userpics; you will get a menu of your picture keywords, as retrieved from the server.

You can automatically set the userpic that you want to default to when you post to a community or shared journal, by putting the following in your .charmrc:
commpic = journal,userpic
where journal is the name of the community or shared journal, and userpic is the picture keyword you want to associate to it. If you haven't selected explicitly selected some other userpic, Charm will automatically choose that one by default for that journal; you can still override it by selecting "k" afterwards.

You can have multiple commpic directives in your .charmrc -- one for every community and shared journal you post to, if you'd like. When you have commpic directives set, when you pick a journal from the journal selection menu, it will tell you what picture will be set by default for that choice.

You can also automatically set the userpic that you want to default to when you give a particular tag to a post, by putting the following in your .charmrc:
tagpic = tag,userpic
where tag is the name of the tag, and userpic is the picture keyword you want to associate with it. If you haven't explicitly selected some other userpic, Charm will automatically choose that one by default when you set the tag. You can still override it by selecting "k" afterwards.

You can have multiple tagpic directives in your .charmrc -- one for every tag that you have, if you'd like. (It's possible to defined tagpics for tags that you don't have yet, too, but of course they won't do anything.) When you have tagpic directives set, when you pick tags from the tag selection menu, it will tell you which picture each tag corresponds to.

Subject, Mood, and Music

Choosing "s" from the post menu will let you change the subject line of your post.

Choosing "m" from the post menu will let you choose a mood for your post. This will give you a sub-menu. You can choose "n" for no mood, "l" to pick a mood from the server's list of pre-defined moods (which usually have moodtheme icons associated with them), or "o" to enter whatever mood text you want.

Choosing "a" from the post menu will allow you to type in whatever you want for "current music" for your post. If you want Charm to automatically figure out what music you are listening to, you can supply the -A command-line option; to always do this, add this line to your .charmrc:
autodetect = yes
If you have auto-detection turned on, and you use the "a" menu option to enter your own music title, auto-detection will be turned off for this run of Charm.

Comments, Auto-Formatting, and Backdating

The "o" (miscellaneous options) selection from the post menu will take you to a menu where you can change other aspects of your post. Note that in this menu the options, with the exception of comment screening, change things to the opposite of what they are -- if you have comments allowed, then the option will read, "Change comments option to: comments disallowed". You can change:

• "a". Auto-formatting. If it's off, you'll need to write your own HTML in the post.

• "b". Backdating. Backdated posts don't show up in friends lists.

• "c". Comments. If it's off, comments are not allowed.

• "e". Email comments. If it's off, you won't receive email when someone comments on your post.

• "s". Screen comments. Screened comments are only visible to you until you unscreen them. There are four possible options:
  • "n". Don't screen any comments.
  • "e". Screen comments posted by everyone (all comments).
  • "a". Only screen comments that have been posted anonymously.
  • "f". Sreen comments posted by users who aren't on your friends list.

You can change all of these options but comment screening via command-line options. You can also set their default values from your .charmrc, as follows:

• Auto-formatting. autoformat = state
• Backdating. backdate = state
• Comments. comments = state
• Email comments. noemail = state

where state is on or off.

Setting Security

By default, the security level of your posts is public -- anyone who goes to the journal site can see it. You can change this default in your .charmrc with:
security = level
where level is public, private, friends, or a list of friends groups whose names are separated by commas, such as BestBuddies,SportsFans.

You can change the security level of a specific post by providing the -p level command-line option. level is the same as above. Make sure that if any friend group name has a space in it, that you enclose level in double-quotes. For instance:
charm -p "BestBuddies,Interesting People,SportsFans".

You can also change the security level of a specific post by selecting "p" from the post menu. You'll be given four choices:

• "d". Set the security level to public (the server's default).
• "p". Make the post readable only by you.
• "f". Make the post readable only by people on your friends list.
• "c". Custom security (use friends groups).

If you select custom security, you'll be shown a list of your friends groups. You can select which friends groups can read your post, by typing in a list of the group numbers.

Displaying Security

Normally, when your post shows up on the server, the only indication that a user gets that the post isn't public to everyone is a lock icon or the like. They don't know how private the post is -- whether it's visible to all your friends, visible to only a smaller group of friends, etc. Some users may simply not notice that the post is private. Thus, it's useful to make it very clear that a post isn't public, and tell your readers how private it is.

Charm supports a .charmrc option to do this automatically. You can enable it with:
show_permissions = yes

When you have that option enabled, Charm automatically places a line at the top of your post. You can delete this line when you write your post, if you'd like. It's also only placed there if you set a security level before you begin writing the post itself. That line reads as follows, based on the security level:

• private: [ Private only. ]
• friends: [ To my friends. ]
• custom: [ To list of friend groups. ]

If it's a list of friend groups, the group names are prepended with "the"; for instance, if you are posting to your "Interesting People" and "Computer Geeks" friend groups, the line will read:
[ To the Interesting People, the Computer Geeks. ]

You can change what a group is called there through a .charmrc option, as follows:
groupheader = GroupName,header text

For instance, if you have a friends group name that's just "cgeeks", it probably won't look very good in the header line. So, if you use:
groupheader = cgeeks,my computer geek buddies
then when you restrict a post to that group, you'll get the much nicer:
[ To my computer geek buddies. ]
at the top of your post.

You can have as many groupheader lines in your .charmrc file as you want.

Writing Your Post

You can write and edit your post by selecting "e" from the post menu. This will start up an editor. Charm figures out which editor to use by sequentially trying the following (i.e., the first thing that works is what it'll do):

1. It checks your .charmrc file for a line like the following:
   editor = editor_program
   where editor_program is the editing program that you want to use. If it finds it, it uses it.

2. It checks your environment for the VISUAL variable, and, if you have it set, it uses that.

3. It checks your environment for the EDITOR variable, and, if you have it set, it uses that.

4. It tries to start the vi editor.

You write your post in your editor, just like editing any file in that editor. You can save and then quit your editor, change other options in Charm's post menu, and come back into the editor, if you want, as many times as you want.

By default, Charm stores drafts of posts in the .ljdrafts directory under your home directory. You can change this in your .charmrc, with:
draft_dir = directory
(Substitute the directory path you want to use for directory. Unix users can use ~ as shorthand for their home directory, i.e., the default is ~/.ljdrafts)

Previewing Your Post

You can read your post, without invoking the editor, by selecting "d" from the post menu. If you've selected a pager program, the post will be displayed page-by-page using it. If you haven't, Charm will try to use the more program; if it can't, the post will simply be dumped to the screen.

You can select a pager program via one of the following methods:

1. Set the pager option in your .charmrc, as follows:
   pager = pager_program
   where pager_program is the pager you want to use.

2. Set the PAGER environment variable.

Spell-Checking

If your editor has a spell-checking mode, you can do all of your spellchecking use that.

If you'd like to use an external spellchecker (or HTML validator or any other "review this text" program), you can select "v" from the post menu. This will invoke the spellchecker on the text of your post. When you're done spellchecking, just quit the spellchecker to return to Charm.

By default, Charm uses aspell as the spellchecking program. To change this, set the following option in your .charmrc:
spellchecker = spellcheck_program
where spellcheck_program is the checker program you want to use.

Applying Filters

You may want to apply one or more filters to your draft before posting it. Examples of such text filters include:

• Markdown (convert simple mark-up into HTML tags)
• SmartyPants (translate plain ASCII characters into typographic HTML)
• Textile (another simple markup-to-HTML filter)
• GNU Talk Filters (chef, jive, etc.)

To do so, select "x" from the post menu.

You will then be prompted to enter the path to your filters. If you have an entire series of filters that you commonly use, you'll probably want to put them into a shell script. Charm passes the text of your draft on standard input (stdin), and reads the filter output on standard out (stdout). For instance, if you're trying to invoke Markdown, you'd enter:
Markdown.pl --html4tags
Markdown.pl would need to be in your path, or you'd need to provide the full path to the command.

If you frequently use the same filter and you want it to be the default when you select a filter, set the following option in your .charmrc:
default_filter = filter
where filter is the filter path and arguments.

Your draft will be saved prior to applying any filters. You can, from the post menu, revert to that pre-filtered draft, by selecting "X". Note that this will not only reverse all filters, it will reverse all manual changes made after you first applied a filter.

Charm permanently saves the pre-filtered draft as draftname.raw

Saving and Resuming Sessions, and Offline Posting

At any time, you can copy your post (both text and posting options) to an arbitrary file, by selecting "f" from the post menu. You'll be prompted for a filename to save the post under.

If you quit Charm while you're halfway through a post, Charm will ask you if you'd like to save your session. If you say yes, then Charm will save the post and all associated posting options. You can resume your post at a later date, in one of two ways.

The first way is to use the -r draft_file command-line option. You'll need to know which draft you want; normally, when you quit Charm midway through a session, it'll tell you what the draft file name is. When you start Charm with this option, it reads in the draft and posting options (so if you go to the post menu, you'll see your draft in progress there).

This first way is especially handy in conjunction with the -q quick-post option, where it's useful for offline posting -- write your post while you're offline, quit, and then use:
charm -q -r draft_file
to post it when your computer is back online.

The other way is to do it interactively, by selecting "r" from the main menu. This will take you to the "resume draft" menu. You'll have two options. The first is to select "f" from the menu, and type in the draft file name. The other is to select "l", which will present you with a menu of all your unposted drafts, showing the time when you began each draft and what their subject lines (or first lines of post text) are. Once you select a draft, you'll be placed in the post menu.

Post Time

When Charm sends a post to the server, it automatically posts it with the current local time. If the post attempt fails due to a server issue, it will retain that time and continue to try to use it on subsequent post attempts.

You may, however, want to post with a different date, probably one from the past. In that case, you can change your post date and time with the "t" selection from the post menu. If you do so, you may also want to select "o" then "b" to turn on backdating (assuming you don't want the post to show up on your friend's lists of posts for today).

Sending Your Post

When you're finished writing up your post, and selecting the posting options, use "u" on the post menu to upload your post to the server.

Once you've successfully sent the post, Charm will erase the draft, but it may keep a copy in the archive (see "Automatic Archival").

Using Post Templates

You can pre-define one or more templates to be used for posting. This lets you save your favorite combination of options, and even define a default post body.

From the main menu, select "t" to enter the name of a template to read, before entering the post menu. This will populate your post with the contents of that template. Then, you're free to change everything, just like any other post.

You can also specify the template to use from the command line. Use: charm -T template_file
where template_file is the path to the template file.

If you want to always use the same default template (except when you specifically select another template), put the following line in your .charmrc:
default_template = template
where template is the full path of your template file.

A template file takes the exact format as an archive file, so you can easily turn an archived post into a template if you want. Here's the format for reference. You can use or skip whatever parameters you'd like.

Subject: subject
Journal: LiveJournal community
Category: blog category tag
Tags: LiveJournal tags or blog keyword tags
Mood: LiveJournal mood
Picture: LiveJournal userpic
Music: LiveJournal music
Security: LiveJournal security
Friends: LiveJournal friend groups for custom security
Options: LiveJournal posting options

Your post body is at the end, separated from the headers by a blank line.

Template options are always overridden by command-line options, and you can always edit everything prior to posting.

Editing Existing Posts

You can use Charm to edit existing posts, by selecting "e" from the main menu. You'll be taken to the previous post selection menu.

There, you should start by selecting "j" to choose what journal to take the post from, if it's not your default journal.

Then, you'll need to decide how to find the post you want. You can select:

• "l". Select your last (most recent) post.

• "n". Select from the last N entries. You'll be asked how many entries you want to select from. Charm will download the times and subject lines of those most recent entries, and show you a menu of them, so you can pick which one you want.

• "d". Select from entries posted on a given day. You'll be asked for a date. Charm will download the times and subject lines of your posts on that date, and show you a menu of them, so you can pick which one you want.

Once you've selected a post in this manner, select "e". Charm will retrieve all the relevant post information from the server. Then, you'll be taking to the editing menu.

The editing menu is essentially identical to the post menu. There's one thing you can't do -- change the journal that this post goes to. And there's one thing that you can only do from this menu: select "w" to wipe out this post from the server, deleting it.

If you quit Charm while in the middle of an edit, it's treated exactly like you quit in the middle of writing a post -- you can opt to save your session and resume it later.

When you select "u" and successfully upload your edited post, Charm erases the draft file, but it may keep a copy in the archive.

Automatic Archival

When you post an entry using Charm, Charm will, by default, save a copy of that post locally, to your archive directory. To turn this behavior off, put the following line in your .charmrc:
archive = no

Similarly, when you edit an existing journal entry using Charm, Charm will, by default, save a copy of that post locally, to your archive directory. To turn this behavior off, put the following line in your .charmrc:
archive_edits = no

When a post is saved after editing, the filename it's saved with is a regular post's filename with _edYYYYMMDDhhmm appended (representing the year, month, date, hour, and minute the post was edited). To just overwrite the original post in the archive, put the following line in your .charmrc:
archive_overwrite = yes

Normally, posts are saved directly under the archive directory. If you post using multiple usernames, post to various communities, and so forth, all of the posts get put together under that single directory. If you'd like to separate posts by username or community name, so that each journal gets a subdirectory of its own, put the following line in your .charmrc:
archive_subdirs = yes
(Any further subdirectories needed by the organize configuration parameter will be placed under the journal name's subdirectory.)

Note that the archive_subdirs configuration parameter is ignored by the synchronization/archival download; it is only used when you post or edit. Consequently, if you have this parameter turned on, and you'd like synchronization/archival to write to the same directory, when you download posts, you'll need to specify the path to that username subdirectory as the archive directory using the -a directory command-line option, or select the directory interactively from the archive menu.

Cross-Posting

You can cross-post to other blogs, from an archive file. To do so, make sure archiving it turned on, then post in quick mode using the cross-post option:
charm -q -u username -x archive-file

You can override any options, such as tags, used in the original post, by supplying different options on the command line.

Friend List Management

From within Charm, you can list your friends, add new friends, remove existing friends, and edit the groups and colors of your current friends. To do this, select "f" from the main menu, and then "f" again from the administration menu.

Listing Friends

Select "l" to list your friends. You'll get back a table of usernames and usernames. Communities will be marked with a C, shared journals will be marked with a S, and syndicated feeds will be marked with a Y.

Adding a New Friend

To add someone as a friend, select "f". Then, enter that person's username. You will then be presented with a list of your friend groups. Enter the list of numbers corresponding to the groups that you want to put your friend in. (Normally, you will want to select at least "Default View", which makes that friend show up on your regular friends page.) Next, you'll be shown a list of colors. You'll be asked to choose a background color to use for that friend's posts. You'll do the same for a foreground color. Then, Charm will tell the server to add that friend.

Removing a Friend

To un-friend someone, select "u", then enter their username. Charm will tell the server to remove that person as your friend.

Editing an Existing Friend

You can edit an existing friend by selecting "e". First, Charm will download some data about your friends, then ask you for the username of the friend that you want to edit. You will be taken to a new menu for editing a friend. From this menu, you can select the following:

• "b". Change this friend's background color.

• "f". Change this friend's foreground color,

• "g". Change the list of groups this friend is part of. You'll be shown a list of your friends groups, and asked to enter a list of numbers corresponding to the groups that you want this friend to be in.

Once you're done changing those options, you can finalize your selection by selecting "u"; Charm will update the server will the new friend information.

Friends Group Management

From within Charm, you can list your friends groups, add new groups, delete existing groups, rename groups, change the sort order of groups, and make groups public or private. To do this, select "f" from the main menu, and then "g" from the administration menu.

Listing Your Groups

When you select "l" to list your friends groups, you are shown a sorted table that has, for each group, the group name, its sort order (lower numbers come first in the list), whether or not it's public (can people other than yourself see http://your_journal_url/friends/groupname), which bit number it uses, and what the group mask is (the group mask is just 2 to the power of the bit number).

Adding a New Friends Group

To add a new friends group, select "a". Charm will retrieve a list of your existing friends groups; if you already have 30 friend groups, you cannot add any more (this is a server restriction). Next, you'll be asked to enter a name for the new group. Then, you'll be prompted for a sort order number. Choose a number that places the group where you want it. For instance, if you want it between groups SportsFans at 10, and Buddies at 15, choose a sort order of 11, 12, 13, or 14. Finally, you'll be asked whether or not you want this group to be public. Then, Charm will tell the server to create the new group.

Deleting a Friends Group

To delete a friend group, select "d". Charm will retrieve a list of your existing groups. You'll be asked to enter the name of the group you want to delete. Charm will then tell the server to delete that group.

Editing the Properties of an Existing Friends Group

To edit an existing friend group, select "e". Charm will retrieve a list of your existing groups, and ask you to enter the name of one. You'll then be taken to a menu where you can select the following:

• "n". Change the name of this group.
• "s". Change the sort order of this group.
• "p". Set whether or not this group is public.

When you're done making your selections, choose "u" to update the server with the edited group information.

Banning Users from Your Journal or Community

Charm supports the ability to ban users, and remove bans on users, from your journal or a community that you control. These bans are run via Charm's interface to the server's administrative console commands.

Select "f" from the main menu, followed by "b", to reach the ban management menu.

When you ban a user from your journal, they are unable to post comments in your journal. You can ban a user by selecting "b" from the ban menu, and remove the ban on a user that you've banned, by selecting "u" from the ban menu. In both cases, you'll be prompted for a username, and then Charm will notify the server of the ban or unban.

When you ban a user from a community, they are unable to post entries or comments in that community. Also, if they are not currently a member of the community, they won't be able to join it. You can execute a community ban by selecting "e" from the ban menu. To remove the ban, thus allow the user back in, select "a" from the ban menu. In both cases, you'll be prompted for the community's name as well as a username.

Managing Access to Communities and Shared Journals

Charm supports the ability to add users to and remove users from communities. It also allows you to manage posting access to shared journals. These capabilities are run via Charm's interface to the server's administrative console commands.

Managing User Memberships in a Community

Select "f" from the main menu, followed by "c" from the administrative menu, to access the community management menu.

You can select "a" to add a user to a community that you control. You will be prompted for both the community name and a username. Note that many journal sites will not allow you to add users to communities, due to the potential for abuse.

You can select "u" to unsubscribe a user from a community that you control, removing them as a member of that community. You will be prompted for both the community name and a username.

Note that removing a user from a community does not prevent them from re-joining that community. In order to prevent a user from joining the community again, you will also need to ban that user from the community.

Managing Posting Access to a Shared Journal

Select "f" from the main menu, followed by "s" from the administrative menu, to access the shared journal management menu.

You can select "a" to allow a user to post to a shared journal that you control. You will be prompted for the shared journal's name and the username.

You can select "d" to disallow a user from posting to a shared journal that you control. You will be prompted for the shared journal's name and the username.

Other Features

You can invoke a browser from within Charm, in order to view your journal. In order to do this, select "v" from the main menu. When you quit the browser, you'll be returned to Charm. To change the browser that Charm uses, set the BROWSER environment variable to the browser program that you want to use.

You can find out more information about Charm by selecting "i" from the main menu. This will give you the name of the current version of Charm that you're running, as well as other information about the program.

Charm supports operating via an HTTP proxy server. To utilize a proxy, set the HTTP_PROXY environment variable to the site:port combination that you want to use.

Getting Help

Charm is supported through LiveJournal's ljcharm community. You can ask questions and receive help if you need it.

More information about Charm, as well as the latest release, is available through its home page and through its SourceForge project page.