diff doc/misc/newsticker.texi @ 84307:bc3b4a05f57f

Move here from ../../man

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/misc/newsticker.texi	Thu Sep 06 05:01:20 2007 +0000
@@ -0,0 +1,290 @@
+\input texinfo   @c -*-texinfo-*-
+@comment %**start of header
+@setfilename ../info/newsticker
+@set VERSION 1.9
+@set UPDATED November 2005
+@settitle Newsticker @value{VERSION}
+@syncodeindex vr cp
+@syncodeindex fn cp
+@syncodeindex pg cp
+@comment %**end of header
+
+@copying
+This manual is for Newsticker (version @value{VERSION}, @value{UPDATED}).
+
+@noindent
+Copyright @copyright{} 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+
+@quotation
+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, with the Front-Cover texts being ``A GNU Manual'',
+and with the Back-Cover Texts as in (a) below.  A copy of the license
+is included in the section entitled ``GNU Free Documentation License''
+in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software.  Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License.  If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Newsticker: (newsticker). A Newsticker for Emacs.
+@end direntry
+
+@titlepage
+@title Newsticker -- a Newsticker for Emacs
+@subtitle for version @value{VERSION}, @value{UPDATED}
+@author Ulf Jasper
+@author @email{ulf.jasper@@web.de}
+@author @uref{http://de.geocities.com/ulf_jasper}
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top Newsticker
+@end ifnottex
+
+@menu
+* Overview::        General description of newsticker.
+* Requirements::    Requirements for using newsticker.
+* Installation::    Installing newsticker on your system.
+* Usage::           Basic newsticker instructions.
+* Configuration::   Customizable newsticker settings.
+* Remarks::         Remarks about newsticker.
+* GNU Free Documentation License:: The license for this documentation.
+* Index::           Variable, function, and concept index.
+@end menu
+
+@node Overview
+@chapter Overview
+
+Newsticker provides a newsticker for Emacs. A newsticker is a thing
+that asynchronously retrieves headlines from a list of news sites,
+prepares these headlines for reading, and allows for loading the
+corresponding articles in a web browser.
+
+
+Headlines consist of a title and (possibly) a small description.  They
+are contained in "RSS" (RDF Site Summary) or "Atom" files.  Newsticker
+should work with the following RSS formats:
+
+@itemize
+@item RSS 0.91 (see @uref{http://backend.userland.com/rss091} or
+@uref{http://my.netscape.com/publish/formats/rss-spec-0.91.html}),
+@item RSS 0.92 (see @uref{http://backend.userland.com/rss092}),
+@item RSS 1.0 (see @uref{http://purl.org/rss/1.0/spec}
+@item RSS 2.0 (see @uref{http://blogs.law.harvard.edu/tech/rss}),
+@end itemize
+@itemize
+as well as the following Atom formats:
+@item Atom 0.3
+@item Atom 1.0 (see
+@uref{http://www.ietf.org/internet-drafts/draft-ietf-atompub-format-11.txt}).
+@end itemize
+
+That makes Newsticker.el an "Atom aggregator, "RSS reader", or "RSS
+aggregator".
+
+Newsticker provides several commands for reading headlines, navigating
+through them, marking them as read/unread, hiding old headlines etc.
+Headlines can be displayed as plain text or as rendered HTML.
+
+Headlines can be displayed in the echo area, either scrolling like
+messages in a stock-quote ticker, or just changing.
+
+Newsticker allows for automatic processing of headlines by providing
+hooks and (sample) functions for automatically downloading images and
+enclosed files (as delivered by podcasts, e.g.).
+
+@ifhtml
+Here are screen shots of the @uref{newsticker-1.7.png, version 1.7
+(current version)} and some older screen shots:
+@uref{newsticker-1.6.png, version 1.6},
+@uref{newsticker-1.5.png, version 1.5}, 
+@uref{newsticker-1.4.png, version 1.4}
+@uref{newsticker-1.3.png, version 1.3}, 
+@uref{newsticker-1.0.png, version 1.0}.
+@end ifhtml
+
+@node Requirements
+@chapter Requirements
+
+Newsticker can be used with
+@uref{http://www.gnu.org/software/emacs/emacs.html, GNU Emacs} version
+21.1 or later as well as @uref{http://www.xemacs.org, XEmacs}.  It
+requires an XML-parser (@file{xml.el}) which is part of GNU Emacs.  If
+you are using XEmacs you want to get the @file{net-utils} package
+which contains @file{xml.el} for XEmacs.
+
+Newsticker requires a program which can retrieve files via http and
+prints them to stdout.  By default Newsticker will use
+@uref{http://www.gnu.org/software/wget/wget.html, wget} for this task.
+
+
+@node Installation
+@chapter Installation
+
+As Newsticker is part of GNU Emacs there is no need to perform any
+installation steps in order to use Newsticker.
+
+However, if you are using imenu, which allows for navigating with the
+help of a menu, you should add the following to your Emacs startup file
+(@file{~/.emacs}).
+
+@lisp
+(add-hook 'newsticker-mode-hook 'imenu-add-menubar-index)
+@end lisp
+
+That's it.
+
+@node Usage
+@chapter Usage
+
+@findex newsticker-show-news
+The command @code{newsticker-show-news} will display all available
+headlines in a special buffer, called @samp{*newsticker*}.  It will
+also start the asynchronous download of headlines.  The modeline in
+the @samp{*newsticker*} buffer informs whenever new headlines have
+arrived.  Clicking mouse-button 2 or pressing RET in this buffer on a
+headline will call @code{browse-url} to load the corresponding news
+story in your favourite web browser.
+
+@findex newsticker-start-ticker
+@findex newsticker-stop-ticker
+The scrolling, or flashing of headlines in the echo area, can be
+started with the command @code{newsticker-start-ticker}. It can be
+stopped with @code{newsticker-stop-ticker}.
+
+@findex newsticker-start
+@findex newsticker-stop
+If you just want to start the periodic download of headlines use the
+command @code{newsticker-start}. Calling @code{newsticker-stop} will
+stop the periodic download, but will call
+@code{newsticker-stop-ticker} as well.
+
+@node Configuration
+@chapter Configuration
+
+All Newsticker options are customizable, i.e. they can be changed with
+Emacs customization methods: Call the command
+@code{customize-group} and enter @samp{newsticker} for the customization
+group.
+
+All Newsticker options have reasonable default values, so that in most
+cases it is not necessary to customize settings before starting Newsticker
+for the first time.
+
+Newsticker options are organized in the following groups.
+
+@itemize
+
+@item
+@code{newsticker-feed} contains options that define which news
+feeds are retrieved and how this is done.  
+
+@itemize
+@item
+@vindex newsticker-url-list
+@code{newsticker-url-list} defines the list of headlines which are
+retrieved.
+@item
+@vindex newsticker-retrieval-interval
+@code{newsticker-retrieval-interval} defines how often headlines
+are retrieved.
+@end itemize
+
+@item
+@code{newsticker-headline-processing} contains options that define
+how the retrieved headlines are processed.
+
+@itemize
+@item
+@vindex newsticker-keep-obsolete-items
+@code{newsticker-keep-obsolete-items} decides whether unread
+headlines that have been removed from the feed are kept in the
+Newsticker cache.
+@end itemize
+
+@item
+@code{newsticker-layout} contains options that define how the
+buffer for reading news headlines is formatted.
+
+@itemize
+@item
+@vindex newsticker-heading-format
+@code{newsticker-item-format} defines how the title of a headline
+is formatted.
+@end itemize
+
+@item
+@code{newsticker-ticker} contains options that define how headlines
+are shown in the echo area.
+
+@itemize
+@item
+@vindex newsticker-display-interval
+@vindex newsticker-scroll-smoothly
+@code{newsticker-display-interval} and
+@code{newsticker-scroll-smoothly} define how headlines are shown in
+the echo area.
+@end itemize
+
+@item
+@code{newsticker-hooks} contains options for hooking other Emacs
+commands to newsticker functions. 
+@itemize
+@item
+@vindex newsticker-new-item-functions
+@code{newsticker-new-item-functions} allows for automatic
+processing of headlines. See `newsticker-download-images', and
+`newsticker-download-enclosures' for sample functions.
+@end itemize
+
+@item
+@code{newsticker-miscellaneous} contains other Newsticker options.
+
+@end itemize
+
+Please have a look at the customization buffers for the complete list
+of options.
+
+@node Remarks
+@chapter Remarks
+
+This newsticker is designed do its job silently in the background
+without disturbing you.  However, it is probably impossible to prevent
+such a tool from slightly attenuating your Editor's responsiveness
+every once in a while.
+
+Byte-compiling newsticker.el is recommended.
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@bye
+
+
+
+@ignore
+   arch-tag: 7a4de539-117c-4658-b799-0b9e3d0ccec0
+@end ignore