changeset 90:9cf0d605465a noffle

[svn] Move INTERNALS to docs/
author bears
date Fri, 19 May 2000 08:59:51 +0100
parents f17eb481c126
children 93cc929329eb
files INTERNALS docs/INTERNALS
diffstat 2 files changed, 115 insertions(+), 115 deletions(-) [+]
line wrap: on
line diff
--- a/INTERNALS	Thu May 18 13:19:32 2000 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,115 +0,0 @@
--------------------------------------------------------------------------------
-NOFFLE Internals
--------------------------------------------------------------------------------
-
-This document is, for the moment, a collection of jottings on aspects
-of Noffle internals.One day it might make it into something resembling
-documentation, but I wouldn't put your money on it. Use the Source,
-Luke!
-
-1. Where do things get stored?
-
-Articles: Articles are held keyed by Message-ID in the articles
-database, articles.gdbm. This is handled by database.[hc]. Articles
-are marked with a status, indicating if they were only partially
-downloaded (think overview mode) or if something went wrong on
-retrieval.
-
-Groups: The list of groups known is held in the groups database,
-groupinfo.gdbm, keyed on group name. This holds the group first and
-last article numbers, the last article number read on the remote
-server, group creation and last access times, plus the group
-description, the name of the server from which the group is drawn and
-a flag indicating if posting to the group is allowed.
-
-Local groups are indicated as belonging to a special server. They are
-for the most part treated identically to remote groups (though the
-whole business of auto-subscribe and auto-unsubscribe obviously
-doesn't apply, and posting operates locally).
-
-The fetchlist (fetchlist.[hc]) holds the list of group names Noffle
-currently subscribes to, and the subscription mode.
-
-Subscribed groups may have a file with their name in the overview
-directory. This file - the overview file - contains details of the
-articles in the group that can currently be read from the server. Each
-entry in the file is an overview (over.[hc]), while a group overview
-file is handled by content.[hc]. If no articles are left in a group,
-the overview file is deleted.
-
-The Noffle server loads the overview for a group into memory when it
-needs to manipulate the group and uses its reckoning on the first and
-last article number from there on. This may not correspond with the
-first and last number given in the groups database entry. Typically,
-the database first and last entries are updated from the overview on
-completion of actions affecting the group.
-
-Outbound articles are placed in a directory under the Noffle spool
-'outgoing' directory.  Each is in its own file, named by the article
-Message-ID, in a directory with the name of the server. outgoing.[hc]
-handle tracking what outbound messages are queued and queueing new ones.
-When Noffle connects to the appropriate server, the message is posted
-on and the file removed.
-
-2. Posting
-
-Posting to remote groups is straightforward; the article is placed in
-the outgoing queue, and will be read back from the server as part of
-collecting new messages for the group. The article is placed once only
-in the queue, regardless of the number of external groups, as it only
-needs to appear once on the remote server. Articles posted only to
-newsgroups unknown to Noffle are rejected.
-
-If the group is marked as 'can't post' ('n' in LIST ACTIVE) the post
-is rejected immediately. Note you can't have moderated local groups at
-the moment; you can have read-only ones, though.
-
-Control message are similarly passed on, unless the control is
-'cancel' and the cancel can be done entirely locally because the
-article is still in the outgoing queue.
-
-Posts to local groups appear in the article database
-immediately. Control messages (control.[hc]) for local groups are
-honoured, though currently only 'cancel' does anything.
-
-Things get more complex when an article is cross-posted to a local and
-remote group. Essentially, both the above happen; if the remote server
-does not change the Message-ID, the local copy will be the definitive
-for both groups. Obviously if the remote server does change the
-Message-ID, Noffle will tread the article coming back from the server
-as a new one.
-
-post.[hc] holds the code for posting local articles.
-
-The posting code in post 1.0 Noffle should (i.e. I'll do it if time
-permits) be rearranged to provide one function to post (or reject) an
-article regardless of original source. This would hopefully make it
-clearer what happens during a post, and make it easy to add a
-command-line article post function, which could remove the necessity
-for Python or Perl intervention gateing mailing lists into local newsgroups.
-
-3. Pseudo articles
-
-Noffle generates various pseudo articles itself (see pseudo.[hc]), to
-inform the user of changes of state or to give instruction. All but
-one are, in fact, done by generating and posting a regular article,
-but one is special; the general information article.
-
-The gen info article is the one shown when one tries to read from a
-currently unsubscribed (Noffle is not subscribed to it, that it)
-newsgroup. It is apparently present in every single group known to
-Noffle, but is faked; it never appears in the article database. LIST
-ACTIVE fakes the first and last article numbers for a group if it
-knows the group is not subscribed to (and not local), and entry to a
-group with the GROUP command will cause an overview to be added to the
-group overview in memory only. If the article is not read, the
-overview is lost unsaved when moving to the next group.
-
-Reading the article triggers stuff happening. If auto-subscribe is on,
-a pseudo article confirming subcription is posted and the group
-overview saved. Gen info articles are not normally saved in overviews,
-but to prevent them vanishing very suddenly their overview is saved
-with other articles in the group if they form part of the sequence of
-the group. In this case it will persist until the subscription confirm
-article expires. This will not stop another gen info being generated
-if (say) the group gets auto-unsubscribed.
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/INTERNALS	Fri May 19 08:59:51 2000 +0100
@@ -0,0 +1,115 @@
+-------------------------------------------------------------------------------
+NOFFLE Internals
+-------------------------------------------------------------------------------
+
+This document is, for the moment, a collection of jottings on aspects
+of Noffle internals.One day it might make it into something resembling
+documentation, but I wouldn't put your money on it. Use the Source,
+Luke!
+
+1. Where do things get stored?
+
+Articles: Articles are held keyed by Message-ID in the articles
+database, articles.gdbm. This is handled by database.[hc]. Articles
+are marked with a status, indicating if they were only partially
+downloaded (think overview mode) or if something went wrong on
+retrieval.
+
+Groups: The list of groups known is held in the groups database,
+groupinfo.gdbm, keyed on group name. This holds the group first and
+last article numbers, the last article number read on the remote
+server, group creation and last access times, plus the group
+description, the name of the server from which the group is drawn and
+a flag indicating if posting to the group is allowed.
+
+Local groups are indicated as belonging to a special server. They are
+for the most part treated identically to remote groups (though the
+whole business of auto-subscribe and auto-unsubscribe obviously
+doesn't apply, and posting operates locally).
+
+The fetchlist (fetchlist.[hc]) holds the list of group names Noffle
+currently subscribes to, and the subscription mode.
+
+Subscribed groups may have a file with their name in the overview
+directory. This file - the overview file - contains details of the
+articles in the group that can currently be read from the server. Each
+entry in the file is an overview (over.[hc]), while a group overview
+file is handled by content.[hc]. If no articles are left in a group,
+the overview file is deleted.
+
+The Noffle server loads the overview for a group into memory when it
+needs to manipulate the group and uses its reckoning on the first and
+last article number from there on. This may not correspond with the
+first and last number given in the groups database entry. Typically,
+the database first and last entries are updated from the overview on
+completion of actions affecting the group.
+
+Outbound articles are placed in a directory under the Noffle spool
+'outgoing' directory.  Each is in its own file, named by the article
+Message-ID, in a directory with the name of the server. outgoing.[hc]
+handle tracking what outbound messages are queued and queueing new ones.
+When Noffle connects to the appropriate server, the message is posted
+on and the file removed.
+
+2. Posting
+
+Posting to remote groups is straightforward; the article is placed in
+the outgoing queue, and will be read back from the server as part of
+collecting new messages for the group. The article is placed once only
+in the queue, regardless of the number of external groups, as it only
+needs to appear once on the remote server. Articles posted only to
+newsgroups unknown to Noffle are rejected.
+
+If the group is marked as 'can't post' ('n' in LIST ACTIVE) the post
+is rejected immediately. Note you can't have moderated local groups at
+the moment; you can have read-only ones, though.
+
+Control message are similarly passed on, unless the control is
+'cancel' and the cancel can be done entirely locally because the
+article is still in the outgoing queue.
+
+Posts to local groups appear in the article database
+immediately. Control messages (control.[hc]) for local groups are
+honoured, though currently only 'cancel' does anything.
+
+Things get more complex when an article is cross-posted to a local and
+remote group. Essentially, both the above happen; if the remote server
+does not change the Message-ID, the local copy will be the definitive
+for both groups. Obviously if the remote server does change the
+Message-ID, Noffle will tread the article coming back from the server
+as a new one.
+
+post.[hc] holds the code for posting local articles.
+
+The posting code in post 1.0 Noffle should (i.e. I'll do it if time
+permits) be rearranged to provide one function to post (or reject) an
+article regardless of original source. This would hopefully make it
+clearer what happens during a post, and make it easy to add a
+command-line article post function, which could remove the necessity
+for Python or Perl intervention gateing mailing lists into local newsgroups.
+
+3. Pseudo articles
+
+Noffle generates various pseudo articles itself (see pseudo.[hc]), to
+inform the user of changes of state or to give instruction. All but
+one are, in fact, done by generating and posting a regular article,
+but one is special; the general information article.
+
+The gen info article is the one shown when one tries to read from a
+currently unsubscribed (Noffle is not subscribed to it, that it)
+newsgroup. It is apparently present in every single group known to
+Noffle, but is faked; it never appears in the article database. LIST
+ACTIVE fakes the first and last article numbers for a group if it
+knows the group is not subscribed to (and not local), and entry to a
+group with the GROUP command will cause an overview to be added to the
+group overview in memory only. If the article is not read, the
+overview is lost unsaved when moving to the next group.
+
+Reading the article triggers stuff happening. If auto-subscribe is on,
+a pseudo article confirming subcription is posted and the group
+overview saved. Gen info articles are not normally saved in overviews,
+but to prevent them vanishing very suddenly their overview is saved
+with other articles in the group if they form part of the sequence of
+the group. In this case it will persist until the subscription confirm
+article expires. This will not stop another gen info being generated
+if (say) the group gets auto-unsubscribed.