path: root/.emacs.d/identica-mode-1.1/doc/identica-mode.texi

\input texinfo @c -*-texinfo-*-

@c %**start of header
@setfilename identica-mode.info
@settitle Identica mode manual
@c %**end of header

@copying
  Copyright @copyright{}  2009  Chris Bryant (@email{chrisbryant@@ucla.edu}).
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.2
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
  Texts.  A copy of the license is included in the section entitled "GNU
  Free Documentation License".
@end copying

@dircategory Emacs
@direntry
* Identica mode: (identica-mode).	Emacs mode for microblogging services.
@end direntry

@titlepage
  @title Identica mode manual
  @subtitle v0.3 for identica-mode.el v0.9
  @author Chris Bryant (@email{chrisbryant@@ucla.edu})
  @page
  @vskip 0pt plus 1filll
  @insertcopying
@end titlepage

@contents

@node Top, About Identica mode and obtaining it, (dir), (dir)
@ifnottex
@top identica-mode
This manual is for identica-mode.el, version 0.9.
@end ifnottex

@menu
* About Identica mode and obtaining it::
* Installation and configuration::
* Using identica-mode.el::
* Credits and contributing::
* GNU Free Documentation License::
@end menu

@node About Identica mode and obtaining it, Installation and configuration, Top, Top
@chapter About Identica mode and obtaining it

@menu
* About identica-mode.el and this manual::
* Getting a copy::
@end menu

@node About identica-mode.el and this manual, Getting a copy, About Identica mode and obtaining it, About Identica mode and obtaining it
@section About identica-mode.el and this manual

@firstparagraphindent none
This manual instructs in the use of identica-mode.el, a major mode for GNU Emacs used to perform useful actions with @uref{http://status.net, StatusNet} microblogging services, like @uref{http://identi.ca, identi.ca}.

@paragraphindent 3
identica-mode.el was developed by @uref{mailto:gsaldana@@gmail.com, Gabriel Saldana} and other contributors (@ref{Credits}). It is originally based on Twittering mode version 0.6 by Y. Hayamizu and Tsuyoshi CHO.

@node Getting a copy,  , About identica-mode.el and this manual, About Identica mode and obtaining it
@section Getting a copy

@firstparagraphindent none
Identica mode can be obtained from the @uref{https://savannah.gnu.org, Savannah} software forge.  The URLs for the Identica mode project are:

@itemize @bullet
@item @uref{http://www.nongnu.org/identica-mode/, http://www.nongnu.org/identica-mode} - Main website
@item @uref{https://savannah.nongnu.org/projects/identica-mode/, https://savannah.nongnu.org/projects/identica-mode} - Software forge
@end itemize

@paragraphindent 3
You can obtain identica-mode.el directly from the git repository at Savannah by executing a git clone command:
@*
@example
git clone git://git.savannah.nongnu.org/identica-mode.git
@end example
@*
@paragraphindent 3
This action will fetch the latest identica-mode.el file as well as the latest manual, located under the @code{doc/} directory.

@node Installation and configuration, Using identica-mode.el, About Identica mode and obtaining it, Top
@chapter Installation and configuration

@menu
* Installing identica-mode.el::
* Configuring GNU Emacs::
@end menu

@node Installing identica-mode.el, Configuring GNU Emacs, Installation and configuration, Installation and configuration
@section Installing identica-mode.el

@firstparagraphindent none
Installation of indentica-mode.el is fairly straightforward.  Like most GNU Emacs customizations, it is recommended you place your identica-mode.el file under your @code{emacs.d} directory.  The location of this directory will vary between OSs, but it is generally under  @code{~/.emacs.d/} for UNIX style systems.  Consult your @uref{http://www.gnu.org/software/emacs/, GNU Emacs} documentation.

@paragraphindent 3
Alternatively, you can create your own directory for this GNU Emacs mode file, and others, if you choose.  Read on for information on how to configure your @code{.emacs} file to find indentica-mode.el.

@node Configuring GNU Emacs,  , Installing identica-mode.el, Installation and configuration
@section Configuring GNU Emacs

@menu
* identica-mode requirements::
* Configuring .emacs::
@end menu

@node identica-mode requirements, Configuring .emacs, Configuring GNU Emacs, Configuring GNU Emacs
@subsection identica-mode requirements

@firstparagraphindent none
The following GNU Emacs libraries are required by identica-mode.el.  A standard GNU Emacs installation should provide these, but if yours does not, fetch a copy of the @uref{http://www.gnu.org/software/emacs/, GNU Emacs} source.  The libraries are generally found under the @code{emacs-<version>/lisp/} directory.

@itemize @bullet
@item cl
@item xml
@item parse-time
@item longlines
@end itemize


@paragraphindent 3
In addition to the library requirements, the following software is currently required:

@itemize @bullet
@item GNU Emacs 22 or later
@item Curl
@item Wget
@item UNIX-like OS (GNU/Linux, BSD, etcetera)
@end itemize

@node Configuring .emacs,  , identica-mode requirements, Configuring GNU Emacs
@subsection Configuring .emacs

@firstparagraphindent none
Some or all or the following settings can be configured from within GNU Emacs or written to your @code{.emacs} file.  To configure within GNU Emacs, execute @command{M-x} and type @command{customize-group}.  When prompted for the group to customize, enter @command{identica-mode}.  The settings are:

@itemize @bullet
@item Identica Idle Time
@item Identica Timer Interval
@item Identica Username
@item Identica Password
@item Laconica Server
@item Identica Default Timeline
@item Identica Display Success Messages
@item Identica Update Status Edit Confirm Cancellation
@item Identica Update Status Method
@item Identica Http Get Timeout
@item Identica Status Format
@end itemize

@paragraphindent 3
For general usage, the defaults for each of these settings (excluding Username and Password) should be fine to get started for use with identi.ca.  If you wish to customize these settings, please see the @uref{http://status.net/wiki/, StatusNet wiki} for documentation of usage.  Management of the customizations can also be performed from within your @code{.emacs} file.  Below is a sample, explicitly calling the identica-mode.el file and with an added global keybinding to allow posting from the minibuffer without having the identica buffer active:
@*
@example
;; Identica Mode
(load "/home/identicauser/.emacs.d/identica-mode.el")
(require 'identica-mode)
(setq identica-username "identicauser")
(setq identica-password "password")
(global-set-key "\C-cip" 'identica-update-status-interactive)
@end example
@*
@node Using identica-mode.el, Credits and contributing, Installation and configuration, Top
@chapter Using identica-mode.el

@menu
* Basic usage::
* Tips and tricks::
@end menu

@node Basic usage, Tips and tricks, Using identica-mode.el, Using identica-mode.el
@section Basic usage

@menu
* Introduction::
* Startup::
* Icons::
* Replies timeline::
* Public timeline::
* Personal timeline::
* Update status::
* Send notice::
* Shorten url::
@end menu

@node Introduction, Startup, Basic usage, Basic usage
@subsection Introduction

@firstparagraphindent none
Identica mode currently works under GNU Emacs in both terminal and graphical mode.  Where there are special considerations for one or the other mode, they will be clearly highlighted.  The purpose of Identica mode is to provide an easy method to send and view updates while working within a GNU Emacs environment.  Thus, the command set detailed below is simple.  If you are interested in more complex functionality, feel free to send suggestions through the Savannah project website.  Additionally, keep up-to-date with the latest releases.  Also, see @ref{Extending identica-mode} for tips on writing your own functions.

@node Startup, Icons, Introduction, Basic usage
@subsection Startup

@firstparagraphindent none
To get started using Identica mode, execute @code{M-x} and type @command{identica-mode}.  This will initiate the identica-mode buffer, *identica*, and display the default timeline.  At any time you wish to refresh the timeline, press the @command{G} key.

@node Icons, Replies timeline, Startup, Basic usage
@subsection Icons

@firstparagraphindent none
If you are using GNU Emacs with a graphical interface, you can toggle the view of user icons by pressing the @command{I} key.

@node Replies timeline, Public timeline, Icons, Basic usage
@subsection Replies timeline

@firstparagraphindent none
To view your Replies timeline execute:
@*
@example
C-c C-r
@end example

@node Public timeline, Personal timeline, Replies timeline, Basic usage
@subsection Public timeline

@firstparagraphindent none
To view the Public timeline execute:
@*
@example
C-c C-g
@end example

@node Personal timeline, Update status, Public timeline, Basic usage
@subsection Personal timeline

@firstparagraphindent none
To view your Personal timeline execute:
@*
@example
C-c C-f
@end example

@node Update status, Send notice, Personal timeline, Basic usage
@subsection Update status

@firstparagraphindent none
To update your Identica status execute:
@*
@example
C-c C-s
@end example

@paragraphindent 3
At the @code{Status:} prompt, type the content of your status, up to 140 characters.  When done, hit the @command{Enter} key.  The message @code{Success: Post} will apper in the minibuffer.

@node Send notice, Shorten url, Update status, Basic usage
@subsection Send notice

@firstparagraphindent none
To send a notice directly to a user execute:
@*
@example
C-c C-d
@end example

@paragraphindent 3
At the @code{To user:} prompt type the exact user name and press the @command{Enter} key.  At the @code{Direct message:} prompt, type your message and press the @command{Enter} key.

@node Shorten url, , Send notice, Basic usage
@subsection Shorten url

@firstparagraphindent none
You can shorten a url while typing your update notice on the
minibuffer by pressing the @command{<F4>} key while the cursor is in
between or at the end of the long url you just typed.

@node Tips and tricks,  , Basic usage, Using identica-mode.el
@section Tips and tricks

@menu
* Run commands after recieving notices::
* Extending identica-mode::
@end menu

@node Run commands after recieving notices,  , Tips and tricks, Tips and tricks
@subsection Run commands after recieving notices

@firstparagraphindent none
You can now create ``hooks'' that will run after recieving new
notices. Just add a hook function to @code{identica-new-dents-hook}.

@firstparagraphindent none
To display a notification message on KDE 4 you can add the following
code on your .emacs file:
@*
@example
;; KDE 4 Notification of new dents with kdialog
(add-hook 'identica-new-dents-hook (lambda ()
   (let ((n identica-new-dents-count))
     (start-process "identica-notify" nil "kdialog"
		    "--title"
		    "Emacs Identica-mode New dents"
		    "--passivepopup"
                    (format "You have %d new dent%s"
                            n (if (> n 1) "s" ""))
		    "3"
))))
@end example

@node Extending identica-mode,  , Tips and tricks, Tips and tricks
@subsection Extending identica-mode

@firstparagraphindent none
Because identica-mode.el is written in Emacs Lisp, there are many options to extend the mode to your liking.  As this is the first release of the Identica mode manual, this section will serve to simply encourage you to experiment with the code, and to see @ref{Contributing} for ways to let us know how you've extended identica-mode.el - maybe we'll add your extensions to the code, and this section, in further releases!

@node Credits and contributing, GNU Free Documentation License, Using identica-mode.el, Top
@chapter Credits and contributing

@menu
* Credits::
* Contributing::
@end menu

@node Credits, Contributing, Credits and contributing, Credits and contributing
@section Credits

@firstparagraphindent none
The following individuals have contributed to the Identica mode project.  See the identica-mode.el file for more information.

@itemize @bullet
@item  Christian Cheng
@item  Alberto Garcia
@item  Bradley M. Kuhn
@item  Jason McBrayer
@item  Carlos A. Perilla
@item  Alex Schröder
@item  Shyam Karanatt
@end itemize

@node Contributing,  , Credits, Credits and contributing
@section Contributing

@firstparagraphindent none
If you have any ideas for features, patches or bug fixes, please add them to the identica-mode @uref{https://savannah.nongnu.org/bugs/?group=identica-mode, bug tracking list}.  If you are submitting something specifically for @ref{Extending identica-mode}, be sure to note this in your ticket.

@node GNU Free Documentation License,  , Credits and contributing, Top
@unnumbered GNU Free Documentation License
@include fdl.texi

@bye