========================================
                                jlj 2.12

                             2006 Jan 30

                     jsl@umlautllama.com
        http://jerronimo.livejournal.com


----------------------------------------
                      New for v2.9-v2.12
----------------------------------------

    * tag support


----------------------------------------
                            New for v2.8
----------------------------------------

    * Audio posting! with the -ap <filename> option


----------------------------------------
                            New for v2.7
----------------------------------------

    * added support for external body formatters like "Markdown"
	http://daringfireball.net/projects/markdown/

    * on quick posts, user icon list is printed before editor is spawned
	(just scroll back and snarf-n-barf it into the line


----------------------------------------
                            New for v2.6
----------------------------------------

    * added "opt in" item in the .rc file.  PLEASE READ ABOUT THIS BELOW!

    * added documentation in here about the queue file

    * -bf file   uses "file" as the body of the post

    * prints the url post posting posts

    * no longer local echoes the password when its being typed in
	(Your system must support "stty echo" and "stty -echo".)

    * added the ability to disable email replies to your posts

    * -q   forces a profile named "q".  
		(-q is actually equivalent to "-q -p q" in older versions)
		Use -p afterwards on the command line to override.

    * -lc  to list the user's accessible communities

    * -lfg to list the user's friend group names

    * -lui to list the user's icons and urls to the images

    * -m enables more monkeys

    * +m enables less monkeys / disables more monkeys
	    (Don't disable too many monkeys.  There aren't enough wheelchairs.)



----------------------------------------
                            New for v2.5
----------------------------------------

    * 'autosend' to send messages without asking

    * -e? for command-line based event entry

    * -ne to disable editing of the entry

    * -vc to check the version against the server.
	- it also does this after each post

    * Bugfixes:
	- compensated for the 'database lock' bug on the server
	- rewrote the autolinker to only link urls that start a line
	- removed stray debug messages
	- fixed the ":" in subject(etc) line handling


----------------------------------------
                            New for v2.4
----------------------------------------

    * automatically will retry connections to the server that failed

    * will connect to the 'fast' servers if they are available
	- These two alone should make everything work a lot more
	  reliably now.  

    * 'autodate' added
	- if you're taking a long time to make a post, and want the new
	  date to be used instead of the time you started, just remove
	  the date from the "Date:" line and it will be filled in for
	  you by jlj

    * 'autolink' added
	- just type out things like http://www.umlautllama.com in your
	  event entry and it will be converted into a link for you by
	  jlj!

    * Bugfixes:
	- included RC file was incorrect.  The current .rc file is correct
	    (also now check for 'everyone' as well as 'public'.)
	- the infamous 'flush' bug has been repaired.
	- empty server responses are now handled gracefully
	- ignores files ending with a specific suffix (like "~") 
	    (temp files aren't mistaken for postponed/queued messages anymore)


----------------------------------------
                      Getting it running
----------------------------------------

You should be able to configure it as below, then just type 'jlj.pl'.
You might have to change the path to your "perl" executable in the
first line of jlj.pl, and as well you might want to change the name
of 'jlj.pl' to 'jlj' for ease of use.

If you want to do the check friends option, type 'jlj.pl -c'.  It will
respond with two lines, if all was successful.  ie:

        new=0
        interval=45

new: 0 if there was no new posts in your friends list since you last checked
     1 if there was a post in your friends list

interval:  The number of seconds that the server requests that you wait
            before you check your friends again.
            NOTE: the server may get unhappy with you if you check more
            often than this amount of time.

NOTE: The 'checkfriends' option will not work with livejournal.com
unless you have a paid account.


To use it in 'offline mode', type 'jlj.pl -o'.  This will not
attempt to connect to the server at all, but still will let you
queue up messages to be posted, as well as postponing messages for
completion later.  You will also be able to edit postponed messages
as well.

If you just type 'jlj.pl', it will attempt to log into the server. 

When it is run, you will be given a prompt similar to this:

    [new]/offline/list/<number>?

The selection in brackets, "new" in this case, is the default
selection.  If you just hit return, this is the action that will
be taken.  All of the prompts are arranged such that the first
letter of every selection is different. [*]

You can simply type the first letter of the menu, or hit return if
the selection you want is the default.  I have tried to arrange
the behavior of the first menu to change based on whether you run
it with the -o option, and if there are any postponed entries to
use... So if you have no postponed entries, and you run jlj with
the "-o" option, the prompt won't display at all since there'd be
nothing to do.

When a message is postponed instead of queued or sent to the server,
It goes into a directory so that you can edit it later.  At the
above prompt, if you select 'list', it will display all of the
postponed messages' date, community or user, and subject line, with
a number next to it.  You can type the number of the message to
continue editing that entry.

The journal entries in the 'queue' folder are entries that are in
the queue to be sent to the server.  The next time that jlj is run
with the '-f' option, these will be posted to the server.

The journal entries in the 'postponed' folder are entries that have
been set aside to be edited later by you.  You can re-activate
these using the above menu/prompt.

The journal entries in the 'sent' folder are entries that have been
submitted to the journal server.

[*] This caused a slight change with the 'security' prompt.  Instead
    of selecting if a post is to be: public, private, or friends-only,
    it is now: everyone, private, or friends-only.

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 
NOTE:  If you mangle the date line, the entry might not be submittable anymore!
	- just delete it altogether if you like, and the date/time of
	  when it is sumbitted to the server will be used instead.
= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 
NOTE:  Do not change the line labelled 'do not edit', or it might fail
= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 


----------------------------------------
                    Command Line Options
----------------------------------------

-c
	Check your friends list to see if there were new posts.

-f
	Flush the queue of pending submission entries off to the server.

-h
	Display a help message (showing these options)

-j
	Display a cheat sheet of JerryWiki escapes.
	    To enable JerryWiki, set the "formatted" line 
	    in your .livejournal.rc to have "jerry" as the 
	    first item in the list, rather than "preformatted".

-ap name.wav
	Make an audio post with the passed in audio file
	depends on "lame" to convert to mp3, as well as "scp" to copy the file
	you also need to have hosting space somewhere.

-lc
	Display a list of the communities that the user has access to.

-lfg
	Display a list of the user's friend groups.

-lui
	Display a list of the user icon names and URLs for the user.

-ne
	No-Edit.
	    Skips the step where it lets you edit the file. This is
	    useful for command-line based entries. (See below.)

-o
	Work offline.
	    It does not attempt to contact the server at all.

-p name
	Select a different 'profile'.
	    You can set up two different files for each profile.
	    In your .jlj/profiles directory, create a [name].jlj
	    file for the .rc options you want to use for that
	    profile.  You can also create a [name].txt file for
	    starting text for each of those posts.  (Read more
	    about profiles below.)
	
-q
	Quick mode.
	    It only prompts you for subject, then bounces right
	    into the editor.  It tries to do this online.  You can
	    still postpone the message for completion later.

-s
	autoSend.
	    After a post is edited, JLJ will ask if you want to send
	    it, queue it, postpone it, etc.  This will force the 
	    answer to that question to be "send".

-vc
	Version Check.
	    Checks the main JLJ site to see if there is a new
	    version available.  This is also done after each 
	    event posted to livejournal.


=== Command line event editing ===

    The following command-line options will enable "Quick mode".
    These will override any profile settings.  If you have a default
    body associated with a profile, both bodies will be in the event.

-eb text	Use "text" as your event's body
-ec text	Use "text" as your event's community
-ei text	Use "text" as your event's picture (image)
-em text	Use "text" as your event's mood
-ep text	Use "text" as your event's privacy [public/private/etc]
-es text	Use "text" as your event's subject
-et text	Use "text" as your event's music (tunes)
-ett text	Use "text" as your event's tag

    A typical command-line based entry might be something like:

prompt% jlj.pl -s -ne -es "Cheese Of The Day" -eb "The cheese of today is Gouda"


----------------------------------------
                   Getting it configured
----------------------------------------

Just some notes about configuring JLJ...

edit the enclosed '.livejournal.rc' file.  You will need to set your 
username and password.  There are prompts for most everything else, 
but not your username and password.

You should see something like this:

    user: yourusername
    password: yourpassword

change the text to read your correct username and password.  For example, 
if your username is "bunnyfoobar", and your password is "ilikecheese", then
those two lines should read:

    user: bunnyfoobar
    password: ilikecheese

The rest of the things in that file are fairly self explanatory, but i'll
briefly cover them here just in case. ;)

First of all, you may notice that there are multiple items on each of 
the lines.  JLJ only looks at the first item on each of the lines.  so if
you were to see:

    blah:  yes no

then the setting for 'blah' would be 'yes'.

Be sure to copy the .livejournal.rc file into your home directory, and make
it only readable by you.  ie: 
	chmod 600 .livejournal.rc
	mv .livejournal.rc ~

(assuming you're on a unix system)

--------------------------------------------------------------------------------
Thanks: 
	Scott Meaker <kyaakone@yahoo.com>	- .._noecho prompter
	Adam T. Lindsay <atl@comp.lancs.ac.uk>  -  proxy code
	David Lindes <lindes@daveltd.com>       -  error code ideas
	Alexey Bestciokov <proforg@idbh.ru>     -  Russian language support
	innuend0 <innuend0@onigami.net>		-  $EDITOR/rcfile{"editor"} fix.
	Chip Marshall <chip@setzer.chocobo.cx>	-  ispell support
	Matt Peperell <matt@linux-host.demon.co.uk> - backdate prompt
	Pete Gosious <peter.gousios@savaJe.com> -  empty server response fix
	Heather Norton (Maigrey)		-  original autolink code
	rone@ennui.org (figmentality)		-  suffix ignore idea
	all of you who told me about the flush bug.  oops.

--------------------------------------------------------------------------------

----------------------------------------
                            Known Issues
----------------------------------------

This is currently not very happy with a situation where if you have
a lot of posts queued up, which do not contain a username or password
in their appropriate profile.  It will attempt to log into the
first account, which will probably work (after it prompts the user
for login data)  then it will use that password/username for
subsequent posts that are lacking a username or password.

Solution:
    Put a username and password into your profiles.  Just be sure
    to "chmod 600"  your .livejournal.rc and profile files and
    "chmod 700" your .jlj directory.

    If you are using jlj on a system where someone with superuser
    access can read your files without your knowledge, and you are
    writing something they do not approve of, then you should run
    jlj from a different machine.   (In this situation you should
    also be sure to remove the files in your 'sent' directory,
    since those are the original posts, unencrypted.  Or you can
    use the new "backup" option in the configuration file, and 
    set it to "no".)



----------------------------------------
                                Profiles
----------------------------------------

You can set up multiple profiles, as many as you'd like to use.
Since the profile configuration files get read in after the base
configuration file, it can contain just the differences you want
to use.  For example;

%  jlj.pl -q

will use the default setup, in quick mode.  It will first read in
	~/.livejournal.rc 

After that, it will read in 
        ~/.jlj/profiles/default.jlj

When you do not select a profile, the 'default' profile name is used.

Also, when the post file is created, it will append any text stored in
	~/.jlj/profiles/default.txt

So, if you always want a signature on your posts (for whatever
reason) put it in there.



Another example... If you were to type:

% jlj.pl -q -p angryllama

Then, like the above, it will first read in 
	~/.livejournal.rc

then proceed to read in 
	~/.jlj/profiles/angryllama.jlj

which may contain just the simple override of "allow comments: no",
or may contain other changes like setting the server as such:
"server:  www.deadjournal.com", or the like.  And also, any text
stored in 
	~/.jlj/profiles/angryllama.txt
 will appear as the starting point of the post.


Any number of overrides can be used in the .jlj files.

Both the [profile name].jlj configuration file and the
[profile name].txt file are optional.  You don't need either.

So you could have different username and passwords set for different
accounts, all in the .jlj files.



----------------------------------------
                      Configuration File
----------------------------------------

    This file contains all of the configuration details for how to
	connect to the server, username, as well as things like
	default settings for the posts.  The ~/.livejournal.rc file
	ALWAYS gets parsed at configuration time.  If a profile is
	selected then that profile's configuration file will get
	parsed afterwards, overriding anything already set where
	applicable.


server: www.livejournal.com
postcgi: /interface/flat

    Generally, you shouldn't have to change either of these unless you
    want to use JLJ with another site, such as "deadjournal.com".  This
    is the address for the main server hub and path for the cgi script
    that accepts posts.


user: username

    your username for livejournal


password: password

    your password for livejournal


editor:

    This is the full path to a text editor to use.  You should be 
    able to use anything like 'vi', 'emacs', 'pico', 'nedit' etc.
    Whichever you are comfortable with.  Mine is set to "usr/ucb/vi"


editor offset:

    To make editing easier, we'd like it to start us with the cursor
    at the bottom of the generated file.  This means that we want
    the cursor to be on line 19.  Most editors ('vi', 'emacs',
    'pico', and 'nedit' for example) allow for a command line option
    to set the start point of the cursor in the file.  For those
    just mentioned, it is "+<line number>", so the default value
    for this is "+19".  If your text editor does not support this,
    either delete the line, or set it to the appropriate option
    for your editor.


base dir: %s/.jlj

    where all of the files will be stored.  %s gets replaced with
    $HOME assuming it's set in your shell. (It usually is.)  In
    the above example, it'll save aside your entries in the ~/.jlj
    directory.  This should be an explicit pathname, not a relative
    path.  I have no idea what'll happen if it's a relative path.


backup: yes no

    Keep a backup copy of your posts in ~/.jlj/sent


security: everyone private friends prompt

    What 'security level' to use.  'everyone' 'private' and 'friends'
    will always post under those security levels.  'prompt' will ask
    you every time you run JLJ.  Generally you're probably going to
    want 'everyone'.  NOTE: 'friends' will can be visible to _all_ of
    your friends, or to a specific friend group.  See 'friend0' etc.


friend0: friend group name
friend1: friend group name
...

    If security is set to 'friends', then these are the textual names
    of the friend groups (one per line) to be posted to.  If none of
    these are defined, then the post will go to 'all friends'. 
    This listing MUST be contiguous.  That is to say that if you have
    defined 'friend0', 'friend1' and 'friend3', then 'friend3' will be
    ignored since there was no 'friend2'.


format: preformatted none

    If this is set to 'preformatted', the server will assume you've
    formatted the text yourself, and will do nothing.  If it is
    set to 'none', it will add line breaks at the end of every
    line. (Since you're probably going to be sticking with a certian
    style of posts, there's no reason to prompt you about this, so
    we set it once, and are done with it.)  If you set it to "none",
    then the Mongolian Crack Monkeys will take your post, put <br>'s
    at the end of each line, and do all sorts of other nasty
    automatic HTML code.  You probably will want it set to
    "preformatted"


mood prompt: yes no

    Ask what mood you're in.  This gets cross referenced with the 
    known moods when your entry is posted to the server.  If you type
    a standard mood like "happy", it will get a cute little icon next
    to it.  If you type a non-standard mood like "diagonal", it will
    just submit it as text, and you will get no cute little icon.


music prompt: yes no

    Ask what music you're listening to.


picture prompt: yes no

    Display a list of your pictures, and ask for which you want.
    For best results, put in descriptive keywords for your pictures
    so that you know which is which when you are given this list.


community prompt: yes no

    Display a list of communities and journals you can post to,
    and ask for which to post to.


community: <community name>

    A default community name for quick posts.  If this is set 
    and a non-quick post is made and you have the 'community 
    prompt' set to "yes", JLJ will override this setting with 
    whatever you chose in the configuration file.


backdate entry: no yes prompt

    This will always prompt you for the date and time on startup
    of the client, if you have this set to "yes".  It will not
    ask you if you have switched on 'quick' mode (-q).


allow comments: yes no prompt

    Sets the 'allow comments' field for the posts.  If set to 'yes', 
    it will always allow comments.  If set to 'no', it will always 
    disallow comments.  Prompt will ask you every time.
    The default for this for quick mode is "yes".


email replies: yes no prompt

    Sets the post such that replies to your event will be sent to you
    via email, as defined on the server.  If set to 'yes', the server
    will email you replies to your post.  If set to 'no', the server
    will not email the replies to you.  Prompt will ask you every
    time.  The default for this for quick mode is "yes".


autolink: yes no

    Enables the 'autolink' code.  If this is enabled than text with the
    form 'http://foo' will become a link to that url.  This should work
    with http, ftp, etc.


ignore suffix: ~

    If this is set to something (usualy a tilde '~'), then files with
    that on the end of it will be ignored by the flush and postponed
    code.  Typically, some text editors use this to denote a temporary
    file, and should be ignored by jlj.


fast server: yes no

    Use the "fast servers" if that is an option to the user.  There's
    really no reason to ever turn this off, but if you want to, you
    can.  If you are an unpaid user or for some other reason have been
    disallowed from using the fast servers, this will be ignored.


server retries: 5

    During peak usage times (12am-12pm, 12pm-12am GMT) the servers are
    usually very busy, and may drop requests or otherwise timeout when
    a request is made to them.  If this happens, JLJ can retry the
    request up to this number of tries.  Any number less than 1 is
    converted into 1 by jlj.  You probably shouldn't set this too high
    just to be nice.


opt in: no yes

    When JLJ checks my server for a new version, it sends along the
    version number of your client, as well as your username.  This is 
    only done if you select "yes" here.  

    These statistics are purely for personal curiosity, to find out how
    many distinct users are using which versions of the client, and how
    many users of each of the versions there are.  I will not divulge
    this information to anyone, and I will not send out any email or
    contact you any other method.  This is purely for statistical
    purposes.  

    If you'd rather that it did not send your username, you can leave 
    this option to "no", and instead of your username, the name
    "__opt_out__" will be sent.

    NOTE: The only information I store is the username and version
    number.  I DO NOT STORE YOUR POSTING IP ADDRESS, NOR DO I KEEP
    TRACK OF WHEN POSTS ARE MADE OR THEIR CONTENTS.  The only info I
    keep is some which I can use for personal statistical curiosity.
    There is nothing stored that could be used against you in any way.
    I promise.

    I do appreciate it if you would change this to "yes", but I understand
    if you leave set it to "no".


audio converter: lame --preset 24 _IN_ _OUT_

    This is used in the audio post ("-ap") option.  This is the
    command line that will be run to compress the input wave file
    out to a smaller sized mp3.
    _IN_ gets replaced with an input filename
    _OUT_ gets replaced with the output filename
    The example above depends on the mp3 compressor "lame" to be 
    installed on your system, and be in your path.


audio upload: scp _IN_ user@host:public_html/Audio/voice/

    This is the command line to upload the file to your webspace.
    The trailing slash is required.  An alternate method might be
    via FTP with a .netrc file, but SCP seems to be the best solution
    for this.  It is recommended that you have your SSH Keys set
    up everywhere, so that you don't need to type your password
    over and over.  You are required to have web hosting space for
    this to work.  I recommend Warped.com for inexpensive, reliable
    webhosting.


audio url: http://www.cis.rit.edu/~sdlpci/Audio/voice/

    This is where the above directory appears on the web.  The
    trailing slash is required.  You are required to have web
    hosting space for this to work.  I recommend Warped.com for
    inexpensive, reliable webhosting.


audio icon: http://www.cis.rit.edu/~sdlpci/a.gif

    This is the URL to an image posted with every post.  This
    should be a small icon depicting sound of some kind; a
    speaker, whatever. 


proxy: no yes
    
    Set to yes if you're using a proxy for web connections.


proxy host: yourproxy.dom.tld

    Set it to the address of the web proxy server.


proxy port: 80

    which port on the proxy server is used.


----------------------------------------
                              Queue File
----------------------------------------

    The queue files are stored in ~/.jlj/queue . It is not necessary
    that they have a specific filename, although it is necessary
    that they do not end with the ignore suffix as defined in the
    .rc file.

    This section will describe each line in a typical queue file, 
    as well as what are valid things to put on those lines.

    First of all, the format of the file is basically:
	Header
	Seperator
	Body

    The seperator is usually:
--- Edit your event text below this line.  Do not edit this line. ---
    Do not edit this line.  This is how JLJ knows where the header
    ends.  Everything after this is the body and can contain whatever
    characters you want to put in it.  It will be "webized" and
    sent to the journal server.

    The Header consists of lines with the format of:
	Key: Value
    Whitespace after the first colon is removed, as well as at the
    end of the value.  In the case where a single selection is
    required, only the first entry on the line will be consumed.
    Anything after that is ignored.

    The order of the items in the header is not defined, although
    JLJ creates them in a reasonable order. 


Server:    www.livejournal.com
    This is optional.  Default is provided by the .rc file.
    This is the full name of the machine that will be catching the
    LJ posts.  Do not include the http:// or any other gook.  IP
    numbers are ok.

CGI:       /interface/flat
    This is optional.  Default is provided by the .rc file.
    This is the path to the CGI script that will be catching the
    form from JLJ.  For a typical livejournal server, the above is
    the correct value.

Profile:   cheesemonkey
    This is optional.  There is no default.
    This defines which JLJ profile should be referenced for username,
    password and any other live settings to read in when posting.
    In the example shown here, the profile will be read from
	"cheesemonkey.jlj"
    If none is given, the default in the ".livejournal.rc" file will
    be used.  If none is given there, the user will be prompted for
    a username and password.

Community:
    This is optional.  There is no default.
    This defines the shared journal to post into.  If the user wishes
    to post into their own journal, this should be left blank.

Format:    preformatted (jerry/preformatted/none)
    This is optional.  Default is "none".
    This determines how the body is processed:
	"preformatted"  The LJ server will not do anything to the body.
	"none"          The LJ server will do its magic on the body.
	"jerry"         Experimental jerry-wiki formatter.  Best to not use it.

Security:  everyone     (everyone/private/friends)
    This is optional.  Default is "private".
    This will set who can see the post:
	"everyone"  unrestricted
	"private"   only the user who posted it can see it
	"friends"   either all friends or selected friend groups can see it

Friend0:
    This is optional.  There is no default.
    This is a listing of friend groups.  This is only looked at if
    "Security" is set to "friends".  If no "Friend0" is defined,
    then the post will be visible to all of the defined friends
    for the user.  If the user wanted three friend groups to be
    able to read it, which the user named "A" "B" and "C", then
    the queue file should contain:
	Friend0: A
	Friend1: B
	Friend2: C

Monkeys:   Monkey
    This is optional.  There is no default.
    This adds optional monkeys into the entry.

Backdate:  no   (yes/no)
    This is optional.  Default is "no".
    If this is set to "yes" then the backdate flag will be set in
    the post, causing it to not appear in your friends' friends
    lists.

Comments:  yes  (yes/no)
    This is optional.  Default is "yes".
    If set to "no", then other users will not be able to post replies.

emails:    yes  (yes/no)
    This is optional.  Default is "yes".
    If set to "no", then the user will not get email notifications
    when other users post replies.

Music:
    This is optional.  There is no default.
    This is where the post's currently-playing music selection will
    go.  There is no predefined format for this.

Picture:
    This is optional.  There is no default.
    This is where the name of the associated user icon for the post
    is defined.  If none is defined, the user's default will be
    displayed instead.  A list of names of user icons can be found
    by running "jlj -lui"; the name for this field is to the right
    of the URL listed.

Mood:
    This is optional.  There is no default.
    This name is checked against the list of known moods returned
    by the livejournal server.  If the mood is known by the server,
    then the "mood id number" is sent, otherwise the text will be
    sent to the server as-is.

Date:      2003-02-12 20:29:19
    This is optional.  The default is the time that the post gets
    sent to the server.  The format MUST be in the form of:
	YYYY-MM-DD HH:MM:SS
    The hours are in 24 hour format.  The time is local time.
    There is not proper checking in JLJ to make sure that the date
    is properly formatted, so change this at your own risk.  The
    server will reject posts with incorrect date formats.

Subject:   
    This is optional.  There is no default.
    This is where the post's subject line will go.  There is no
    predefined format for this.  There is a 255 character limit
    for this for some undefined reason.
