code formatting cleanups

[gregoa/bti.git] / bti.xml

diff --git a/bti.xml b/bti.xml
index cbda742f8feea01a324922a16ea452367cb66cc3..ae08e4f8b47949b6c2267a4f53fd92394de6a552 100644 (file)
--- a/bti.xml
+++ b/bti.xml
@@ -19,7 +19,8 @@
       </refmeta>
 
       <refnamediv>
       </refmeta>
 
       <refnamediv>

-        <refname>bti</refname><refpurpose>send a tweet to twitter.com from stdinput</refpurpose>
+        <refname>bti</refname>
+        <refpurpose>send a tweet to twitter.com or identi.ca from the command line</refpurpose>

       </refnamediv>
 
       <refsynopsisdiv>
       </refnamediv>
 
       <refsynopsisdiv>


@@ -27,16 +28,28 @@
           <command>bti</command>
           <arg><option>--account account</option></arg>
           <arg><option>--password password</option></arg>
           <command>bti</command>
           <arg><option>--account account</option></arg>
           <arg><option>--password password</option></arg>

-         <arg><option>--quiet</option></arg>
+          <arg><option>--action action</option></arg>
+          <arg><option>--user screenname</option></arg>
+          <arg><option>--host HOST_NAME</option></arg>
+          <arg><option>--proxy PROXY:PORT</option></arg>
+          <arg><option>--logfile LOGFILE</option></arg>
+          <arg><option>--config CONFIGFILE</option></arg>
+          <arg><option>--replyto ID</option></arg>
+          <arg><option>--retweet ID</option></arg>
+          <arg><option>--page PAGENUMBER</option></arg>
+          <arg><option>--bash</option></arg>
+          <arg><option>--shrink-urls</option></arg>

           <arg><option>--debug</option></arg>
           <arg><option>--debug</option></arg>

+          <arg><option>--dry-run</option></arg>
+          <arg><option>--verbose</option></arg>

           <arg><option>--version</option></arg>
           <arg><option>--help</option></arg>
         </cmdsynopsis>
       </refsynopsisdiv>
 
       <refsect1><title>DESCRIPTION</title>
           <arg><option>--version</option></arg>
           <arg><option>--help</option></arg>
         </cmdsynopsis>
       </refsynopsisdiv>
 
       <refsect1><title>DESCRIPTION</title>

-        <para>bti sends a twitter message to twitter.com.
-       </para>
+        <para>bti sends a tweet message to twitter.com or identi.ca.
+        </para>

       </refsect1>
 
       <refsect1><title>OPTIONS</title>
       </refsect1>
 
       <refsect1><title>OPTIONS</title>


@@ -45,7 +58,7 @@
             <term><option>--account account</option></term>
             <listitem>
               <para>
             <term><option>--account account</option></term>
             <listitem>
               <para>

-               Specify the twitter.com account name.
+               Specify the twitter.com or identi.ca account name.

              </para>
             </listitem>
           </varlistentry>
              </para>
             </listitem>
           </varlistentry>


@@ -53,7 +66,123 @@
             <term><option>--password password</option></term>
             <listitem>
               <para>
             <term><option>--password password</option></term>
             <listitem>
               <para>

-               Specify the password of your twitter.com account.
+                Specify the password of your twitter.com or identi.ca account.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><option>--action action</option></term>
+            <listitem>
+              <para>
+               Specify the action which you want to perform.  Valid options
+               are "update" to send a message, "friends" to see your friends
+               timeline, "public" to track public timeline, "replies" to see
+               replies to your messages and "user" to see a specific user's
+               timeline.  Default is "update".
+              </para>
+            </listitem>
+          </varlistentry>
+         <varlistentry>
+            <term><option>--user screenname</option></term>
+            <listitem>
+              <para>
+               Specify the user whose messages you want to see when the
+               action is "user".
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><option>--host HOST_NAME</option></term>
+            <listitem>
+              <para>
+               Specify the host which you want to send your message to.  Valid
+               options are "twitter" to send to twitter.com and "identica" to
+        send to identi.ca.
+
+        If you want to send the message to a custom laconi.ca installation,
+        you should specify the API URI. For example identi.ca's URI is:
+        https://identi.ca/api/statuses
+              </para>
+              <para>
+               If no host is specified, the default is to send to twitter.com.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><option>--proxy PROXY:PORT</option></term>
+            <listitem>
+              <para>
+               Specify a http proxy value.  This is not a required option, and
+               only needed by systems that are behind a http proxy.
+              </para>
+              <para>
+               If --proxy is not specified but the environment variable
+                'http_proxy' is set the latter will be used.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><option>--logfile LOGFILE</option></term>
+            <listitem>
+              <para>
+               Specify a logfile for bti to write status messages to.  LOGFILE
+               is in relation to the user's home directory, not an absolute
+               path to a file.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><option>--config CONFIGFILE</option></term>
+            <listitem>
+              <para>
+               Specify a config file for bti to read from.  By default, bti
+               looks in the ~/.bti file for config values.  This default
+               location can be overridden by setting a specific file with this
+               option.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><option>--replyto ID</option></term>
+            <listitem>
+              <para>
+               Status ID of a single post to which you want to create a threaded
+               reply to.
+             </para>
+             <para>
+               For twitter, this is ignored unless the message starts with the
+               @name of the owner of the post with the status ID.
+             </para>
+             <para>
+               For status.net, this can link any two messages into context with
+               each other. Status.net will also link a message that contains an
+               @name without this without regard to context.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><option>--retweet ID</option></term>
+            <listitem>
+              <para>
+               Status ID of a single post which you want to retweet.
+             </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><option>--shrink-urls</option></term>
+            <listitem>
+              <para>
+                Scans the tweet text for valid URL patterns and passes each
+                through the supplied bti-shrink-urls script.  The script will
+                pass the URL to a web service that shrinks the URLs, making it
+                more suitable for micro-blogging.
+              </para>
+              <para>
+                The following URL shrinking services are available:
+                http://2tu.us/ (default) and http://bit.ly / http://j.mp
+              </para>
+              <para>
+                See the documentation for bti-shrink-urls for the configuration options.

               </para>
             </listitem>
           </varlistentry>
               </para>
             </listitem>
           </varlistentry>


@@ -63,6 +192,58 @@
               <para>Print a whole bunch of debugging messages to stdout.</para>
             </listitem>
           </varlistentry>
               <para>Print a whole bunch of debugging messages to stdout.</para>
             </listitem>
           </varlistentry>

+          <varlistentry>
+            <term><option>--page PAGENUMBER</option></term>
+            <listitem>
+              <para>
+               When the action is to retrieve updates, it usually retrieves
+               only one page.  If this option is used, the page number can be
+               specified.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><option>--dry-run</option></term>
+            <listitem>
+              <para>
+                Performs all steps that would normally be done for a given
+                action, but will not connect to the service to post or retrieve data.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><option>--verbose</option></term>
+            <listitem>
+              <para>
+                Verbose mode. Print status IDs and timestamps.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><option>--bash</option></term>
+            <listitem>
+              <para>
+                Add the working directory and a '$' in the tweet message to
+                help specify it is coming from a command line.  Don't put the
+                working directory and the '$' in the tweet message.
+             </para>
+
+              <para>
+                 This option implies <option>--background</option>.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><option>--background</option></term>
+            <listitem>
+             <para>
+                Do not report back any errors that might have
+                happened when sending the message, and send it in the
+                background, returning immediately, allowing the user
+                to continue on.
+              </para>
+            </listitem>
+          </varlistentry>

           <varlistentry>
             <term><option>--version</option></term>
             <listitem>
           <varlistentry>
             <term><option>--version</option></term>
             <listitem>


@@ -78,9 +259,184 @@
         </variablelist>
       </refsect1>
 
         </variablelist>
       </refsect1>
 

-      <refsect1><title>AUTHOR</title>
-        <para>Written by Greg Kroah-Hartman <email>greg@kroah.com</email>.</para>
-      </refsect1>
+      <refsect1>
+        <title>DESCRIPTION</title>
+        <para>
+          bti provides an easy way to send tweet messages direct from the
+          command line or any script.  It reads the message on standard
+          input and uses the account and password settings either from the
+          command line options, or from a config file, to send the message
+          out.
+        </para>
+        <para>
+          Its primary focus is to allow you to log everything that you
+          type into a bash shell, in a crazy, "this is what I'm doing right
+          now!" type of way, letting the world follow along with you
+          constant moving between directories and refreshing your email
+          queue to see if there's anything interesting going on.
+        </para>
+        <para>
+          To hook bti up to your bash shell, export the following variable:
+        </para>
+        <para>
+            <literal>  PROMPT_COMMAND='history 1 | sed -e "s/^\s*[0-9]*\s*//" | bti --bash'</literal>
+        </para>
+        <para>
+          This example assumes that you have the
+          <filename>~/.bti</filename> set up with your account and password
+          information already in it, otherwise you can specify them as an
+          option.
+        </para>
+       </refsect1>
+
+       <refsect1>
+         <title>CONFIGURATION</title>
+         <para>
+           The account and password can be stored in a configuration file
+           in the users home directory in a file named
+           <filename>.bti</filename>.  The structure of this file is as
+           follows:
+         </para>
+         <variablelist>
+           <varlistentry>
+             <term><option>account</option></term>
+             <listitem>
+               <para>
+                 The twitter.com or identi.ca account name you wish to use to send this
+                 message with.
+               </para>
+             </listitem>
+           </varlistentry>
+           <varlistentry>
+             <term><option>password</option></term>
+             <listitem>
+               <para>
+                 The twitter.com or identi.ca password for the account you wish to use
+                 to send this message with.
+               </para>
+             </listitem>
+           </varlistentry>
+          <varlistentry>
+            <term><option>--action action</option></term>
+            <listitem>
+              <para>
+               Specify the action which you want to perform.  Valid options
+               are "update" to send a message, "friends" to see your friends
+               timeline, "public" to track public timeline, "replies" to see
+               replies to your messages and "user" to see a specific user's
+               timeline.
+              </para>
+            </listitem>
+           </varlistentry>
+          <varlistentry>
+            <term><option>--user screenname</option></term>
+            <listitem>
+              <para>
+               Specify the user you want to see his/her messages while the
+               action is "user".
+              </para>
+            </listitem>
+           </varlistentry>
+           <varlistentry>
+             <term><option>host</option></term>
+             <listitem>
+               <para>
+                The host you want to use to send the message to.  Valid
+                options are either "twitter" or "identica" to send to
+                twitter.com or identi.ca respectively.
+
+         If you want to send the message to a custom laconi.ca installation,
+         you should specify the API URI. For example identi.ca's URI is:
+         https://identi.ca/api/statuses.
+               </para>
+             </listitem>
+           </varlistentry>
+           <varlistentry>
+             <term><option>proxy</option></term>
+             <listitem>
+               <para>
+                The http proxy needed to send data out to the Internet.
+               </para>
+             </listitem>
+           </varlistentry>
+           <varlistentry>
+             <term><option>logfile</option></term>
+             <listitem>
+               <para>
+                The logfile name for bti to write what happened to.
+                This file is relative to the user's home directory.  If this
+                file is not specified here or on the command line, no logging
+                will be written to the disk.
+               </para>
+             </listitem>
+           </varlistentry>
+           <varlistentry>
+             <term><option>replyto</option></term>
+             <listitem>
+               <para>
+                The status ID to which all notices will be linked to.
+               </para>
+              <para>
+                There is no sane reason for a need to have this set in a
+                config file. One such reason is to have all your messages
+                as children to a particular status.
+              </para>
+             </listitem>
+           </varlistentry>
+           <varlistentry>
+             <term><option>shrink-urls</option></term>
+             <listitem>
+               <para>
+                 Setting this variable to 'true' or 'yes' will enable the URL
+                 shrinking feature.  This is equivalent to using the
+                 --shrink-urls option.
+               </para>
+             </listitem>
+           </varlistentry>
+           <varlistentry>
+             <term><option>verbose</option></term>
+             <listitem>
+               <para>
+                   Setting this variable to 'true' or 'yes' will enable the
+                   verbose mode.
+               </para>
+             </listitem>
+           </varlistentry>
+        </variablelist>
+         <para>
+           There is an example config file called
+           <filename>bti.example</filename> in the source tree that shows
+           the structure of the file if you need an example to work off of.
+         </para>
+         <para>
+           Configuration options have the following priority:
+        </para>
+         <variablelist>
+           <varlistentry>
+             <term></term>
+             <listitem><para>command line option</para></listitem>
+           </varlistentry>
+           <varlistentry>
+            <term></term>
+            <listitem><para>config file option</para></listitem>
+           </varlistentry>
+           <varlistentry>
+             <term></term>
+             <listitem><para>environment variables</para></listitem>
+           </varlistentry>
+         </variablelist>
+        <para>
+          For example, command line options always override any config file
+          option, or any environment variables.  Unless a config file is
+          specified by the command line.  At that point, the new config file is
+          read, and any previous options set by a command line option, would be
+          overridden.
+         </para>
+       </refsect1>
+
+       <refsect1><title>AUTHOR</title>
+         <para>Written by Greg Kroah-Hartman &lt;<email>greg@kroah.com</email>&gt; and Amir Mohammad Saied &lt;<email>amirsaied@gmail.com</email>&gt;.</para>
+       </refsect1>

 
     </refentry>
   </section>
 
     </refentry>
   </section>