[Nym3-commit] r357 - in trunk/nymbaron: Client doc
jr at conuropsis.org
jr at conuropsis.org
Sun Oct 16 13:07:30 CEST 2005
Author: jr
Date: 2005-10-16 13:07:28 +0200 (Sun, 16 Oct 2005)
New Revision: 357
Modified:
trunk/nymbaron/Client/Main.py
trunk/nymbaron/doc/nymbaron.xml
Log:
- Documentation of the client
- Change some incorrect usage strings
Modified: trunk/nymbaron/Client/Main.py
===================================================================
--- trunk/nymbaron/Client/Main.py 2005-10-14 21:51:31 UTC (rev 356)
+++ trunk/nymbaron/Client/Main.py 2005-10-16 11:07:28 UTC (rev 357)
@@ -745,7 +745,10 @@
parser.add_option("-o", "--older", action = "store",
dest = "older", help = "Retrieve only summaries "
"older than msgid, defaults to oldest_mid "
- "(a special mid oldest than any other)")
+ "(a special mid oldest than any other). msgid can "
+ "be a mid or a reference syn:N, where N is the "
+ "index of the msgid in the synbox, obtained "
+ "by list-syn")
(options, args) = parser.parse_args(args[2:])
ui = CLI()
config = Config.Config()
@@ -890,7 +893,7 @@
if args[1] == "resend-command":
parser = OptionParser(usage =
"""nymbaron resend-command [options] [ref1 [ref2 [...]]]
- Resend a command that was sent to the server but that has not yet been
+ Resend commands that were sent to the server but that have not yet been
acknowledged. The references are either mids or journal:N where N is the
index provided by the list-journal command.""")
parser.add_option("-n", "--nickname", action = "store",
Modified: trunk/nymbaron/doc/nymbaron.xml
===================================================================
--- trunk/nymbaron/doc/nymbaron.xml 2005-10-14 21:51:31 UTC (rev 356)
+++ trunk/nymbaron/doc/nymbaron.xml 2005-10-16 11:07:28 UTC (rev 357)
@@ -46,8 +46,29 @@
<term><command>create</command></term>
<listitem>
<para>
- Send an account creation request at specified server.
+ Send an account creation request at specified server. If options are not all
+ provided, nymbaron will ask interactively for the lacking information. The
+ user has to provide:
+ - a local account identifier.
+ - the address of the nymserver she wants to register her account to.
+ - a list of nyms, that is to say anonymous usernames. The server will
+ choose among them the first free name and attribute it to the user.
+ - a return address, the email address where the packet destined to the
+ nymholder will be returned
+ This information can also be provided through this command option.
</para>
+ <para>
+ Additionnaly, the user will be prompted for his passphrase to unlock her
+ private keyring. This is necessary to protect the private keys generated for
+ her account in her private keyring. If the keyring doesn't exist yet, it
+ will be created and a password will be asked to protect it.
+ </para>
+ <para>
+ When this command returns, data for this account are stored in the local
+ file system and registration messages were sent to the nymserver. The user
+ can interrupt the creation of an account when by striking Ctrl-C when
+ prompted for information.
+ </para>
</listitem>
</varlistentry>
@@ -55,8 +76,14 @@
<term><command>send</command></term>
<listitem>
<para>
- Send an email message through a nymserver.
+ Send an email message through a nymserver. If the account from which the
+ user wants to send a message from isn't designed by the appropriate option,
+ returns without doing anything.
</para>
+ <para>
+ The message to be sent is taken from a file pointed by the appropriate
+ option or from standard input.
+ </para>
</listitem>
</varlistentry>
@@ -64,8 +91,27 @@
<term><command>summarize</command></term>
<listitem>
<para>
- Send a request for synopsis for specified account.
+ Send a request for synopses for specified account. The user can request
+ synopses older than a given mid, precised by a mid or a reference in the
+ synbox ('syn:N', where N is the index of the mid in the synbox). The
+ server will send back at most the number of synopses precised by the
+ user. If no value is given by the user, the defalut value present in the
+ configuration file of the user will be used.
</para>
+ <para>
+ In the nymserver protocol, the surbs, single-use reply blocks, are
+ potentially a scarce resource. The protocol design takes this into
+ account : instead of sending each message addressed to a nym directly to
+ the nymholder, it generates summaries of the messages. The priority is
+ given to provide the nymholder with some information on every message he
+ receives. She will then request explicitely the retrieval of the message
+ she is interested in.
+ </para>
+ <para>
+ A synopsis actually contains some basic information about a message :
+ its mid, its order of arrival on the server, truncated RFC-822 headers
+ and the first characters of the body.
+ </para>
</listitem>
</varlistentry>
@@ -73,8 +119,15 @@
<term><command>delete</command></term>
<listitem>
<para>
- Request email deletion.
+ Request email deletion on the server. The account must be precised by
+ the user. The user gives a list of mid, either by mid or by
+ reference ('syn:N', where N is the index of the mid in the synbox).
</para>
+ <para>
+ This command enables the user to authorize a message to be deleted on
+ the server. This will free some space of her reserved space on the
+ server.
+ </para>
</listitem>
</varlistentry>
@@ -82,8 +135,14 @@
<term><command>get</command></term>
<listitem>
<para>
- Retrieve email
+ Retrieve email from the server. The account must be precised by
+ the user. The user gives a list of mid, either by mid or by
+ reference ('syn:N', where N is the index of the mid in the synbox).
</para>
+ <para>
+ This command enables the user to ask explicitely for the retrieval of a
+ list of designed messages.
+ </para>
</listitem>
</varlistentry>
@@ -91,24 +150,44 @@
<term><command>process</command></term>
<listitem>
<para>
- Process returning server messages
+ Process returning server messages. The account must be precised by
+ the user, either by the account name or by an idtag. The location of the
+ message is given by the approprite option.
</para>
+ <para>
+ The message must already have been decrypted and reassembled by
+ mixminion. The mixminion headers must have been removed as well. If you
+ do not understand this lines, you probably want to use mprocess.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>mprocess</command></term>
<listitem>
<para>
- Process returning minion messages
+ Process returning minion messages. The location of the message is given
+ by the approprite option.
</para>
+ <para>
+ This is the command that is used to process a message received from the
+ mixminion network. It will try to reassemble mixminion packets by
+ calling mixminion, and, if successful, will determine the
+ account the message was addressed to and process it.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>list-syn</command></term>
<listitem>
<para>
- List already fetched summaries
+ List already fetched summaries. The account must be precised by the
+ user.
</para>
+ <para>
+ This command prints on the standard output the summarized content of the
+ synbox. The user will use dump-syn to get access to the full content of
+ the synopses.
+ </para>
</listitem>
</varlistentry>
@@ -116,8 +195,15 @@
<term><command>dump-syn</command></term>
<listitem>
<para>
- Dump already fetched summaries
+ Dump already fetched summaries. The account must be precised by the
+ user.
</para>
+ <para>
+ Contrary to the list-syn command, this command will output the whole
+ content of the summaries. This may be used to inspect more thoroughly
+ the content of summaries, for example the beginning of bodies of
+ messages before requesting full messages.
+ </para>
</listitem>
</varlistentry>
@@ -125,8 +211,13 @@
<term><command>list-mbox</command></term>
<listitem>
<para>
- List already fetched emails
+ List already fetched emails. The account must be precised by the user.
</para>
+ <para>
+ This command prints on the standard output the summarized content of the
+ mbox. The user will use export to get access to the full content of a
+ message.
+ </para>
</listitem>
</varlistentry>
@@ -134,8 +225,16 @@
<term><command>list-journal</command></term>
<listitem>
<para>
- List commands recorded in the journal (sent but not acknowledged yet)
+ List commands recorded in the journal (sent but not acknowledged yet).
+ The account must be precised by the user.
</para>
+ <para>
+ Because of the lack of fiability insurance in the mixminion network, in
+ order to keep track of command messages that were sent but not
+ acknowledged and to be able to resend those messages, the sent command
+ messages are recorded in a local journal. This command enables the user
+ to check the journal. Command messages are removed from the journal as
+ they are acknowledged.
</listitem>
</varlistentry>
@@ -143,8 +242,17 @@
<term><command>send-surb</command></term>
<listitem>
<para>
- Send SURBs
+ Send SURBs. The account must be precised by the user. The number of
+ surbs to send can also be precised. If it is not, the default number
+ present in the configuration file will be used.
</para>
+ <para>
+ Surbs, single-use reply blocks, are data that enables the nymserver to
+ return commands to the nymholder through the mixminion network. Thus the
+ server doesn't know the identity of the nymholder. As they can only be
+ used once, the server may run out of them. This command enables the user
+ to provide the nymserver with fresh surbs.
+ </para>
</listitem>
</varlistentry>
@@ -152,8 +260,15 @@
<term><command>export</command></term>
<listitem>
<para>
- Export already fetched emails to a file
+ Export already fetched emails to a file. The account must be precised by
+ the user. The user gives a list of messages, either by mid or by mbox
+ reference('mbox:N', where N is the index of message in the local mbox).
</para>
+ <para>
+ This command enables the user to store messages outside of the nymbaron
+ stores. She will then be able to read them with the viewer of her
+ choice.
+ </para>
</listitem>
</varlistentry>
@@ -161,8 +276,19 @@
<term><command>resend-command</command></term>
<listitem>
<para>
- Resend a command that has been sent but not acknowledged yet
+ Resend a command that has been sent but not acknowledged yet. The
+ account must be precised by the user. The user gives a list of either
+ sequence numbers or journal references ('journal:N') corresponding to
+ commands present in the journal of already sent commands that have not
+ yet been acknowledged.
</para>
+ <para>
+ The mixminion network doesn't garante the fiability of the
+ transmissions. The nymserver protocol takes this into account by
+ providing acknowledgement by the server of received command messages
+ from the client. This command enables the user to resend already sent
+ commands which weren't acknowledged by the server.
+ </para>
</listitem>
</varlistentry>
@@ -170,8 +296,17 @@
<term><command>ldelete</command></term>
<listitem>
<para>
- Delete messages from the local mbox
+ Delete messages from the local mbox. The account must be precised by the
+ user. The user gives a list of messages, either by mid or by mbox
+ reference ('mbox:N', where N is the index of message in the local mbox).
</para>
+ <para>
+ Note than after a deletion of messages, the index designing messages in
+ the local mbox may have changed. Use 'list-mbox' before making further
+ mbox references ('mbox:N' references).
+ </para>
+
+ </para>
</listitem>
</varlistentry>
@@ -179,8 +314,15 @@
<term><command>ldelete-syn</command></term>
<listitem>
<para>
- Delete messages from the local synbox
+ Delete summaries from the local synbox. The account must be precised by
+ the user. The user gives a list of mid, either by mid or by reference
+ ('syn:N', where N is the index of the mid in the synbox).
</para>
+ <para>
+ Note than after a deletion of summaries, the index designing mids in the
+ synbox may have changed. Use 'list-syn' before making further synbox
+ references ('syn:N' references).
+ </para>
</listitem>
</varlistentry>
@@ -188,7 +330,7 @@
<term><command>list-accounts</command></term>
<listitem>
<para>
- List the accounts of the user
+ List the accounts of the user.
</para>
</listitem>
</varlistentry>
@@ -197,7 +339,7 @@
<term><command>passwd</command></term>
<listitem>
<para>
- Change the passphrase that protects the user keyring
+ Change the passphrase that protects the user keyring.
</para>
</listitem>
</varlistentry>
@@ -287,7 +429,7 @@
<refsect1><title>AUTHORS</title>
<para>
- Laurent Fousse <email>laurent at komite.net</email> and Jean-René
+ Laurent Fousse <email>laurent at komite.net</email> and Jean-René
Reinhard
<email>jr at komite.net</email>.
<ulink
@@ -296,7 +438,7 @@
</refsect1>
<refsect1><title>COPYRIGHT</title>
<para>
-Copyright © 2004,2005 Jean-René Reinhard
+Copyright © 2004,2005 Jean-René Reinhard
<email>jr at komite.net</email>
and Laurent Fousse <email>laurent at komite.net</email>.
</para>
More information about the Nym3-commit
mailing list