# HG changeset patch # User Glenn Morris # Date 1189054880 0 # Node ID bc3b4a05f57f4229c266007515e1a8f95611978e # Parent 8e4bd303e91e2202cc75a67d656b9074374d1799 Move here from ../../man diff -r 8e4bd303e91e -r bc3b4a05f57f doc/misc/newsticker.texi --- /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