Stacknews is a utility program for reading USENET news via MH. Stacknews works in conjunction with the c-shell and MH to permit you to read news at the shell level, without resorting to news readers such as nn or rn.
Stacknews is not itself the command that you invoke to read news; other commands do that on your behalf, such as "news", "g", "z", and "nglist". These commands are c-shell aliases that invoke stacknews with the appropriate options to perform different operations.
To use stacknews, you must add some alias definitions to your .cshrc file. The required code is described in the INSTALLATION section of this man page.
More complete descriptions of the various stacknews-related news reading commands are:
news
Creates the initial conditions necessary to begin reading news at the
shell level: the list of news group folders is built, and the first
folder is selected.
g
Goes to the next news group in the list.
q
Quits a news group and goes to the next one.
This is similar to the "g" command, but before going to the next news group,
the "q" command sets the last message to be current.
u
Updates the current shell so that news reading can pick up where it
left off.
This is useful if you logged out before reading all your news,
or if you switched windows.
z
Clears the list of news groups and permits you to stop reading news
altogether.
nglist
Lists the news groups waiting to be read.
Stacknews allows folders to be used interchangeably with news groups. This facility is of particular use with automatically updated folders, e.g. those folders to which incoming e-mail is automatically redirected via the rcvstore(1) program.
Stacknews requires certain semi-specialized conditions to pertain:
1) Stacknews can be used only on the primary news machine, unless the news spool directory (typically /usr/spool/news) is NFS-mounted. Stacknews does not require that the news spool directory be present if you read NO news groups, and specify only your own folders.
2) Stacknews is written in perl, and therefore perl 4.0 or later must be installed on your system.
3) Stacknews uses certain specialized features of MH, and therefore MH 6.6 or later must be installed on your system.
If you aren't sure whether these conditions pertain, take these steps to find out:
1. Type this command: ls /usr/spool/news
If you don't see anything in that directory, or if it doesn't exist, then you can't use stacknews to read USENET news. If the news spool directory is something other than /usr/spool/news, then you may specify the alternative news spool directory in the stacknews-arts component in your .mh_profile (see the MH PROFILE COMPONENTS section in this document). If you don't have a news spool directory on your machine, you can still use stacknews to read folders.
2. Type this command: perl -v
If the version number displayed isn't 4.0 or later, then you might have problems running stacknews. You can give it a try, but it isn't guaranteed to work.
3. Type this command: folder -help
If the version number of MH displayed at the bottom of the output of the "folder" command isn't 6.6 or greater, then the version of MH on your system may lack the features necessary to support stacknews. You can give it a try, but it isn't guaranteed to work.
The stacknews program itself may be installed anywhere. The directory /usr/local/bin is not a bad choice. If you don't have access to that directory, then choose some directory that occurs in your PATH, e.g. ~/bin.
Add these lines to the .cshrc file in your home directory:
# Define some stacknews-related aliases
if (! $?stacknews) then
set stacknews = "stacknews"
endif
alias sninvo 'setenv MHCONTEXT `$stacknews *`'
alias news 'set stacknews = "stacknews" ; sninvo'
alias g 'setenv MHCONTEXT `$stacknews -next *`'
alias q 'folder -fast last > /dev/null ; g'
alias u 'setenv MHCONTEXT `$stacknews -nopush *`'
alias z '$stacknews -clear *; unsetenv MHCONTEXT'
alias nglist '$stacknews -list *'
If you don't already have a .cshrc file in your home directory, then you must create a .cshrc file to contain the alias definitions above.
If any of the stacknews aliases described above conflict with existing aliases, then you'll have to select new names either for the stacknews aliases or for the previously existing aliases.
After you've modified your .cshrc file, at the c-shell prompt type these commands:
source ~/.cshrc
rehash
Place into the .news-defaults file in your home directory the following lines:
news.announce.newusers
news.announce.important
news.answers
comp.lang.perl
comp.mail.mh
Feel free to add or to delete news groups as needed.
If you have arranged for some of your folders to be updated automatically
via rcvstore(1), you may place folder specifications as well as news groups
into the .news-defaults file, e.g.:
+lists/mh-mime
+lists/com-priv
To find out what news groups are available, type this command: more ~news/newsgroups
Other commands may be necessary to find out what news groups are available on your system.
When you have performed the necessary setups described in the previous section, type this command: news
You should see something like this:
5 news groups selected; topmost: news.announce.newusers
%
Your current folder becomes the news group "news.announce.newusers", which is the first news group listed in your ~/.news-defaults file.
To read the next new message, type next
To scan the available messages, type scan next-last
To move on to the next news group, type g
If you see dots (".") printed, that means that stacknews is discarding news groups in which no new articles have appeared.
To select a completely different news group to read next, e.g. "alt.sex", type news alt.sex
(The aforementioned news group is not available everywhere, so substitute some available news group.)
To return to a news group in which you might have read the last message already, e.g. "news.announce.newusers", type news -nocheck news.newusers
To see the list of news groups to be read, type nglist
If you change windows, or log out and log back in again later, and you wish to resume reading news, then type u
To stop reading news, type z
Stacknews is designed to be invoked via c-shell aliases. Therefore, you should not find it desirable or necessary to invoke stacknews directly. Furthermore, the various options to stacknews are not guaranteed to interoperate, except as they are used in the c-shell aliases listed in the INSTALLATION section.
The default settings are: -check -noclear -nodebug -nonext -push -rigor
Any news groups specified on the command line are pushed onto the news group stack. If no groups are specified, then all default groups are pushed onto the stack (typically from ~/.news-defaults).
Mutually exclusive options: -clear, -list, -next, -push.
The options are:
-check
-nocheck
By default, when stacknews selects a new news group,
it is simply discarded if it has no new articles.
A group is considered to have new articles if there are articles following
the "cur" message sequence.
The -nocheck option prevents the check for new articles; a group is
pushed unconditionally.
The -check option corresponds to the default behavior; it negates
a -nocheck option if -nocheck is present.
-clear
-noclear
The -clear option causes stacknews to clear the news group stack.
The -noclear option simply negates the -clear option when the -clear
option is present.
-debug
-nodebug
The -debug option causes a limited amount of information to be printed
on STDERR that is not normally displayed.
-list
-nolist
The -list option causes the state of the news group stack to be printed.
The -nolist option negates the -list option when the -list option is
present.
-next
-nonext
The -next option pops the news group stack and causes the next news
group that contains new articles to be selected.
If the -nocheck option is present, the check for new articles is suppressed,
and the next news group in the news group stack is selected unconditionally.
The -nonext option negates the -next option when the -next option is
present.
-push
-nopush
The -push option pushes a new news group onto the top of the news group
stack.
The -nopush option in a sense performs no operation,
except that it causes the topmost news group to be selected.
-rigor
-norigor
By default, stacknews functions as a normal MH program does, i.e. it
checks the environment for relevant information and then checks
the user's MH profile file (typically .mh_profile in the home directory).
The -norigor option causes the MH profile to be ignored; only the
environment is considered.
Most USENET news implementations organize news groups as directories. To translate a USENET news group into a directory path, substitute slashes ("/") for dots ("."), and prepend the path of the news spool directory, typically /usr/spool/news.
MH already uses directories relative to a pre-determined path for folders, e.g. the notation "+inbox" refers to the directory "$HOME/Mail/inbox". Fortunately, MH can also use an absolute path in a folder specification. A USENET news group is treated by stacknews as a folder with an absolute path, e.g. "+/usr/spool/news/comp/lang/perl".
For most users, a USENET news group will be treated as a read-only folder. Because of the way MH interacts with read-only folders, certain MH features, such as message annotation (anno), digest bursting (burst), and refiling (refile) should not be expected to work properly when read-only folders are selected, although some work-arounds are possible. The majority of MH features are available, such as pick(1), forw(1), show(1), etc.
Because MH slows down considerably when a large number of private sequences accumulates in the default context file, a separate context is kept for each news group. The prevailing context is specified by setting the environment variable MHCONTEXT, which is recognized by all MH programs.
C-shell aliases are employed to implement the various stacknews-related commands. Using c-shell aliases permits the output of stacknews to be used to set the MHCONTEXT variable.
UNIX presently does not permit environment information to be shared among different "peer" processes. To overcome this problem, the "u" command is provided to "update" the MHCONTEXT variable among different interactive shells, e.g. login sessions and windows.
By invoking the "news" command, you build a stack of news groups or folders that you want to read in sequence. A default list of news groups to be read is taken from a file that you create, ~/.news-defaults. Progression from news group to news group is accomplished by invoking "g", which is a command to "pop" succeeding folders off the top of the list.
Because the default MH folder stack, as used by "folder -push", is kept in the context file, and because the context changes according to the setting of the MHCONTEXT variable, stacknews maintains an entirely separate folder stack.
Stacknews uses many different environment variables, some in common
with MH.
They are:
HOME
Path of home directory.
MH
Path of MH profile file. Used by all MH programs.
Default: ~/.mh_profile.
MHCONTEXT
Path of current MH context file. Used by all MH programs.
Default: ~/Mail/context.
NEWSARTS
Path of top directory containing news articles.
Default: /usr/spool/news.
NEWSCONTEXTS
Path of directory containing folder contexts
Default: ~/.news-contexts.
NEWSGROUPS
List of colon-separated news groups to read.
Defaults: as specified in ~/.news-defaults.
Stacknews reads the MH profile unless the -norigor option is specified.
The MH environment variable is consulted to determine which MH profile file to read. If the MH environment variable is not defined, then the ~/.mh_profile file is read.
The MH profile components relevant to stacknews are:
context:
Path of MH context file.
Default: as specified in the MHCONTEXT environment variable, or
~/Mail/context.
Path:
Path of MH directory.
Default: ~/Mail.
stacknews:
Stacknews options.
Defaults: -check -noclear -nodebug -nonext -push -rigor.
stacknews-arts:
Path of top directory containing news articles.
Default: As specified by the NEWSARTS environment variable or
/usr/spool/news.
stacknews-contexts:
Path of directory containing folder contexts.
Default: As specified by the NEWSCONTEXTS environment variable or
~/.news-contexts.
stacknews-defaults:
Path of file containing list of news groups.
Default: ~/.news-defaults.
stacknews-groups:
List of comma-separated news groups to read.
Defaults: as specified in the NEWSGROUPS environment variable,
or as specified in ~/.news-defaults.
Where "stacknews" is specified in a .mh_profile component, stacknews looks for its invocation name. The relevant MH profile components are therefore normally named stacknews-defaults, stacknews-groups, and stacknews-arts. However, if stacknews were invoked as "stn", then stacknews would instead look for components named stn-defaults, stn-groups, and stn-arts. The variable prefix for components permits different invocations of stacknews to use different sets of options.
$HOME/.mh_profile
Default MH profile.
$HOME/.news-contexts
Default news folder contexts directory.
All of the context files to which MHCONTEXT refers are kept here.
$HOME/.news-contexts/Stack
News folder stack.
$HOME/.news-contexts/FOLDER.*
Context files for folders.
For example, "FOLDER.lists.mh-mime" is the context file for the
folder "+lists/mh-mime".
(This representation has a problem in that dots in folder names
may result in context file name collisions, e.g. in the case
of "+lists.mh-mime".)
$HOME/.news-contexts/[a-z]*
Context files for news groups.
$HOME/.news-defaults
List of default news groups.
$HOME/Mail
Default MH directory.
$HOME/Mail/context
Default MH context file.
Jerry Sweet <jsweet@ics.uci.edu>
This man page describes version 1.5 of stacknews.
It's easy to lose your way if you use "folder -push".
Stacknews doesn't address some of the problems posed by using MH to handle news groups, as well some general problems posed by read-only folders. For example, the problem of posting news versus sending e-mail needs to be addressed at some level between the UA and the MTA. Another problem is that of copying versus linking messages. Some partial work-arounds have been devised by the author, but these are not yet in releasable form. Some tweaks to MH itself (e.g. in the "post" program) might be desirable the better to accommodate news and read-only folders.