Commit 85c4c3e8 authored by David Byers's avatar David Byers
Browse files

Documented all remaining commands. Now we can start generating a

reference manual (or at least part of one).

Detailed changes:
> 2003-01-08  David Byers  <david.byers@swipnet.se>
>
> 	Documetned the remaining commands:
> 	* remote-control.el: Documented all commands.
>
> 	* mship-edit.el: Documented all commands.
>
> 	* lyskom-rest.el: Documented all commands.
>
> 	* flags.el: Documented all commands.
>
> 	* filter.el: Documented all commands.
> 	(kom-super-jump): Use the standard prefix arguments.
>
> 	* ansaphone.el: Documented all commands.
>
> 	* faqs.el: Documented all commands.
>
> 	* review.el: Documented all commands.
>
parent ca02026c
2003-01-08 David Byers <david.byers@swipnet.se>
Documetned the remaining commands:
* remote-control.el: Documented all commands.
* mship-edit.el: Documented all commands.
* lyskom-rest.el: Documented all commands.
* flags.el: Documented all commands.
* filter.el: Documented all commands.
(kom-super-jump): Use the standard prefix arguments.
* ansaphone.el: Documented all commands.
* faqs.el: Documented all commands.
* review.el: Documented all commands.
2003-01-08 Ulrik Haugen <qha@lysator.liu.se>
* Makefile (DEBIANCLIENTVERSIONSUFFIX): New variable.
......
......@@ -55,7 +55,11 @@
;;;
(def-kom-command kom-change-auto-reply (&optional message)
"Change the default automatic reply message."
"Change the default automatic reply message.
This message is sent in reply to personal messages when auto
reply is turned on.
See `kom-toggle-auto-reply'."
(interactive)
(let ((message (or message
(lyskom-read-from-minibuffer
......@@ -69,7 +73,13 @@
(def-kom-command kom-toggle-auto-reply ()
"Toggle automatic replies to personal messages."
"Toggle automatic replies to personal messages.
When this is turned on, replies will be sent automatically to
personal messages (sent with `kom-send-message'). The reply sent
depents on `kom-ansaphone-default-reply' and `kom-ansaphone-replies'.
Messages received when automatic replies are on may also be recorded.
See `kom-ansaphone-record-messages'"
(interactive)
(setq kom-ansaphone-on (not kom-ansaphone-on))
(lyskom-format-insert (lyskom-get-string 'ansaphone-state-r)
......@@ -85,7 +95,10 @@
(def-kom-command kom-list-messages ()
"List collected messages"
"List messages recorded when automatic replies are on. To erase
recorded messages, use `kom-erase-messages'.
See `kom-toggle-auto-reply' and `kom-ansaphone-record-messages'."
(interactive)
(if (null lyskom-ansaphone-messages)
(lyskom-format-insert (lyskom-get-string 'ansaphone-no-messages))
......@@ -104,7 +117,10 @@
(def-kom-command kom-erase-messages ()
"Erase collected messages"
"Erase messages recorded when automatic replies are on. To list
recorded messages, use `kom-list-messages'.
See `kom-toggle-auto-reply' and `kom-ansaphone-record-messages'."
(interactive)
(lyskom-message "%s" (lyskom-get-string 'ansaphone-messages-gone))
(setq lyskom-ansaphone-messages nil))
......
......@@ -1842,6 +1842,8 @@ environment to one that uses \"%#2s\" to encode text.
(session-to-copy-options-from . "Session to copy options from: ")
(reading-settings-from . "Reeading options from %s...")
(reading-settings-from-done . "Reading options from %s...done")
(super-jump-q . "Super jump which text? ")
))
......
......@@ -77,13 +77,25 @@
;;;
(def-kom-command kom-add-faq (&optional conf-no text-no)
"Add a FAQ to a conference"
"Make an existing text a FAQ of a conference. To write a new FAQ for
a conference that doesn't have one, or change an existing FAQ, use
`kom-change-conf-faq'.
This command accepts text number prefix arguments \(see
`lyskom-read-text-no-prefix-arg')."
(interactive (list (lyskom-read-conf-no 'conf-to-add-faq '(conf pers) nil nil t)
(lyskom-read-text-no-prefix-arg 'text-to-add-as-faq nil 'last-seen-written)))
(lyskom-add-faq conf-no text-no))
(def-kom-command kom-add-server-faq (&optional text-no)
"Add a FAQ to the server"
"Make an existing text a FAQ of the server. To write a new FAQ for
a conference that doesn't have one, or change an existing FAQ, use
`kom-change-server-faq'.
This command accepts text number prefix arguments \(see
`lyskom-read-text-no-prefix-arg')."
(interactive (list (lyskom-read-text-no-prefix-arg 'text-to-add-as-faq nil 'last-seen-written)))
(lyskom-add-faq nil text-no))
......@@ -116,13 +128,15 @@ The text to add is passed in TEXT-NO"
(list aux-item))))))))
(def-kom-command kom-del-server-faq ()
"Remove a FAQ from the server"
"Remove a FAQ from the server. You need administrative rights to
do this. To add a FAQ, use `kom-add-server-faq'."
(interactive)
(lyskom-del-faq nil))
(def-kom-command kom-del-faq ()
"Remove a FAQ from a conference"
"Remove a FAQ from a conference. To add a FAQ, use
`kom-add-conf-faq'."
(interactive)
(let* ((conf-stat (lyskom-read-conf-stat 'conf-to-del-faq
'(conf pers) nil nil t)))
......@@ -169,13 +183,13 @@ The text to add is passed in TEXT-NO"
nil))))))))
(def-kom-command kom-review-server-faq ()
"View the FAQs for the server"
"View the FAQs for the server."
(interactive)
(lyskom-review-faq nil (server-info->aux-item-list
(blocking-do 'get-server-info))))
(def-kom-command kom-review-faq (&optional conf-no)
"View the FAQs for a conference"
"View the FAQs for a particular conference."
(interactive
(list
(let* ((conf-stat (blocking-do 'get-conf-stat lyskom-current-conf))
......@@ -222,14 +236,16 @@ The text to add is passed in TEXT-NO"
lyskom-reading-list t))
(def-kom-command kom-change-server-faq ()
"Change a FAQ for the server."
"Change a FAQ for the server. If the server doesn't have a FAQ,
create a new one. You need administrative rights to do this."
(interactive)
(lyskom-change-faq nil (lyskom-get-aux-item (server-info->aux-item-list
(blocking-do 'get-server-info))
14)))
(def-kom-command kom-change-conf-faq ()
"Change a FAQ fo a conference."
"Change a FAQ fo a conference. If the conference doesn't have a FAQ,
create a new FAQ."
(interactive)
(let* ((conf-no (lyskom-read-conf-no
(lyskom-get-string 'what-to-change-faq-you)
......
......@@ -449,7 +449,12 @@ Otherwise return nil."
;;;
(def-kom-command kom-filter-subject (&optional subject)
"Interactively filter a subject. Optional SUBJECT is subject to filter."
"Interactively filter a subject. This creates a permanent or temporary
filter for a single subject in one conference or all conferences.
An alternative to this is `kom-super-jump'.
To change existing filters, use `kom-filter-edit'."
(interactive)
(if (/= 0 lyskom-current-conf)
(let ((conf-stat (blocking-do 'get-conf-stat lyskom-current-conf)))
......@@ -487,7 +492,11 @@ Otherwise return nil."
(def-kom-command kom-filter-author ()
"Interactively filter an author."
"Interactively filter an author. This creates a permanent or
temporary filter on a single author in one conference or all
conferences.
To change existing filters, use `kom-filter-edit'."
(interactive)
(let (auth-stat author conf filter action permanent)
(blocking-do-multiple ((text-stat (get-text-stat
......@@ -526,7 +535,10 @@ Otherwise return nil."
(cons 'expire (not permanent))))))))
(def-kom-command kom-filter-recipient ()
"Interactively filter a recipient."
"Interactively filter a recipient. This creates a permanent or
temporary filter on a particular recipient.
To change existing filters, use `kom-filter-edit'."
(interactive)
(let ((conf-no (lyskom-read-conf-no 'filter-recipient
'(all)
......@@ -550,10 +562,19 @@ Otherwise return nil."
;;; Superhoppa
;;;
(def-kom-command kom-super-jump ()
"Skip all texts and comments that share the subject and recipient of
the current text"
(interactive)
(def-kom-command kom-super-jump (text-no)
"Skip all texts and comments that share the subject and recipient of
the selected text. This creates a temporary filter on the subject of
the selected text in one of its recipients. The recipient is selected
automatically: if the current conference is a recipient, then filter
in that conference. Otherwise filter in the first recipient that the
user is a member of.
To change existing filters, use `kom-filter-edit'.
This command accepts text number prefix arguments (see
`lyskom-read-text-no-prefix-arg')."
(interactive (lyskom-read-text-no-prefix-arg 'super-jump-q))
(if (or (null lyskom-current-text)
(zerop lyskom-current-text))
(lyskom-insert-string 'have-to-read)
......@@ -630,7 +651,11 @@ the current text"
;;;
(def-kom-command kom-filter-text (&optional text)
"Interactively filter on text contents. Optional TEXT is subject to filter."
"Interactively filter on text contents. This creates a permanent or
temporary filter on the contents of texts in all conferences or in a
single conference.
To change existing filters, use `kom-filter-edit'."
(interactive)
(if (/= 0 lyskom-current-conf)
(let ((conf-stat (blocking-do 'get-conf-stat lyskom-current-conf))
......@@ -670,7 +695,9 @@ the current text"
;;; may not be a good idea, but it works...
(def-kom-command kom-list-filters ()
"Display all filters"
"Display all filters. This lists all filters in the LysKOM buffer.
To change existing filters, use `kom-filter-edit'."
(interactive)
(let ((filters lyskom-filter-list))
(goto-char (point-max))
......
......@@ -48,7 +48,11 @@
local)
(def-kom-command kom-save-options ()
"Save options that have been set somewhere."
"Save all LysKOM settings. This will save settings in the server but
not save anything to your Emacs init file (usually .emacs).
To edit settings, use `kom-customize'. This command can also save
settings to your emacs init file."
(interactive)
(lyskom-save-options (or lyskom-buffer
(current-buffer))
......@@ -57,7 +61,13 @@
(lyskom-get-string 'could-not-save-options)))
(def-kom-command kom-copy-options ()
"Copy options from one setting to another."
"Copy settings from one LysKOM session to another. This is useful if
you have configured on session to your liking and want ths settings to
be used on other servers as well.
This command will save settings to the LysKOM server, but will not
save anything to your Emacs init file. Use `kom-customize' to edit
settings and save them to your emacs init file."
(interactive)
(let* ((completions
(mapcar (lambda (x)
......
......@@ -361,7 +361,9 @@ by design."
;;;; Re-edit text
(def-kom-command kom-re-edit-next-text ()
"Display a buffer containing a failed submission"
"Display a buffer containing a failed text submission. This pseudo
command is only invoked from the prompt after submission of a text
failed."
(interactive)
(let ((el (read-list->first lyskom-reading-list)))
(set-read-list-del-first lyskom-reading-list)
......@@ -374,7 +376,12 @@ by design."
;;;; Go to pri session
(def-kom-command kom-go-to-pri-session ()
"Go to a prioritized session with unreads"
"Go to a prioritized session with unreads. This pseudo command is
generally invoked frmo the prompt when there is a session with unread
texts that has a higher priority than the current session.
See `kom-server-priority' and `kom-server-priority-breaks' for
settings to control session priorities."
(interactive)
(let ((session (lyskom-get-prioritized-session)))
(if (or (null session)
......@@ -410,7 +417,7 @@ by design."
;;; Modified to handle filters
(def-kom-command kom-view-next-text ()
"Display next text (from lyskom-reading-list)."
"Display the next unread text. This is the most common default command."
(interactive)
(lyskom-tell-internat 'kom-tell-read)
(let ((action 'next-text))
......@@ -511,14 +518,12 @@ lyskom-mark-as-read."
(def-kom-command kom-go-to-next-conf (&optional num)
"Go to next conf.
Take first conf from lyskom-to-do-list and copy it to lyskom-reading-list.
Tell server what the user is doing. If the user is reading a conf it is
moved last on lyskom-to-do-list, with priority 0. When a prefix argument
is given, it is interpreted as for kom-list-news; positive numbers set a
lower bound for how many unreads you want in the conference to move to,
a negative argument sets a lower bound instead. You end up in the first
conference in your lyskom-to-do-list that matches the given bounds."
"Go to next conference with unread texts. The current conference is
moved to the end of the list of conferences with unread texts. A
numeric prefix argument is interpreted similar to in `kom-list-news':
with a positive argument go to the next conference with at least that
many unread. With a negative number, go to a conference with at most
that many unread texts."
(interactive "P")
(let ((conf-stat nil)
(num-arg (cond
......@@ -2565,7 +2570,11 @@ A list of pairs means OPTARG will be used as a key to look up the real
(def-kom-command kom-save-text-body (text-no &optional filename)
"Save the body of text TEXT-NO to file FILENAME."
"Save the body of the selected text to a file. This command saves
the contents of the text, without LysKOM information around it to a
file, overwriting any previous contents.
See `kom-save-text' for an alternative command."
(interactive (list (lyskom-read-text-no-prefix-arg 'what-save-no)
nil))
(cond (text-no
......@@ -2610,13 +2619,16 @@ A list of pairs means OPTARG will be used as a key to look up the real
(def-kom-command kom-save-text (arg &optional list-of-texts filename)
"Saves/appends the article before point to a file.
The article is determined by a search-backward the same as backward-text
and then a forward-text.
With an argument ARG the search is done over that number of texts.
If FILENAME is nil, the name of the file is read using the minibuffer
and the default is taken from kom-saved-file-name the first time. Subsequent
calls use the most recently specified file name."
"Append the selected texts to a file. The texts to save are
determined by searching backwards in the buffer. A numeric prefix
argument specifies the number of texts to save. Headers are included
in the file.
The file name to save to is read using the minibuffer, and the default
is taken from kom-saved-file-name the first time. Subsequent calls use
the most recently specified file name.
See `kom-save-text-body' for an alternative to this command."
(interactive "p")
(let ((name nil))
(save-excursion
......
......@@ -1448,7 +1448,9 @@ With prefix arg, contract only those that were created by self."
(def-kom-command kom-handle-membership ()
"Pop up a buffer to manage memberships in"
"Pop up a buffer where you can see and manipulate all your
memberships. This command is not finished. It mostly works, but has
bugs and is somewhat fragile. Handle with care."
(interactive)
(let ((kom-deferred-printing nil))
(set-buffer (lp--create-buffer)))
......
......@@ -60,10 +60,17 @@
;;;
(def-kom-command kom-remote-autoreply (&optional session-no state)
"Remotely turn on or off the auto-reply facility of another client.
Optional argument SESSION-NO specifies the target session.
Optional argument STATE can be one of 'on, 'off or nil. on means
turn auto-reply on, off turn it off and nil toggle its state."
"Remotely turn on or off the auto reply facility of another client.
This is similar to `kom-toggle-auto-reply', but operates on another
session.
You will be prompted for which session to control. For remote control
to work the target session must have remote control turned on, and the
user you are logged on as must have permission to manipulate that
session.
See `kom-remote-controllers' and `kom-self-control' for settings that
affect remote control."
(interactive)
(setq session-no (or session-no
(car (lyskom-read-session-no
......@@ -89,9 +96,17 @@ turn auto-reply on, off turn it off and nil toggle its state."
t)))
(def-kom-command kom-remote-set-message (&optional session-no message)
"Remotely set the default reply message of another client.
Optional argument SESSION-NO specifies the target session.
Optional argument MESSAGE specifies the message."
"Remotely set the default auto reply message of another client. This
is similar to `kom-change-auto-reply', but operates on another
session.
You will be prompted for which session to control. For remote control
to work the target session must have remote control turned on, and the
user you are logged on as must have permission to manipulate that
session.
See `kom-remote-controllers' and `kom-self-control' for settings that
affect remote control."
(interactive)
(setq session-no (or session-no
(car (lyskom-read-session-no
......@@ -109,8 +124,16 @@ Optional argument MESSAGE specifies the message."
t)))
(def-kom-command kom-remote-list-messages (&optional session-no)
"List messages collected from a remote auto-reply facility.
Optional argument SESSION-NO specifies the target session."
"List messages collected from a remote auto reply facility. This is
similar to `kom-list-messages', but operates on another session.
You will be prompted for which session to control. For remote control
to work the target session must have remote control turned on, and the
user you are logged on as must have permission to manipulate that
session.
See `kom-remote-controllers' and `kom-self-control' for settings that
affect remote control."
(interactive)
(setq session-no (or session-no
(car (lyskom-read-session-no
......@@ -126,8 +149,16 @@ Optional argument SESSION-NO specifies the target session."
(def-kom-command kom-remote-erase-messages (&optional session-no)
"Erase stored messages on a remote auto-reply facility.
Optional argument SESSION-NO specifies the target session."
"Erase stored messages on a remote auto reply facility. This is
similar to `kom-erase-messages', but operates on another session.
You will be prompted for which session to control. For remote control
to work the target session must have remote control turned on, and the
user you are logged on as must have permission to manipulate that
session.
See `kom-remote-controllers' and `kom-self-control' for settings that
affect remote control."
(interactive)
(setq session-no (or session-no
(car (lyskom-read-session-no
......@@ -142,8 +173,18 @@ Optional argument SESSION-NO specifies the target session."
(def-kom-command kom-remote-quit (&optional session-no)
"Quit a remote client.
Optional argument SESSION-NO specifies the target session."
"Quit a remote client. The difference between this command and
`kom-force-logout' is that the latter uses server facilities to
forcefully disconnect the session, while the former allows the client
to cleanly disconnect from the server.
You will be prompted for which session to control. For remote control
to work the target session must have remote control turned on, and the
user you are logged on as must have permission to manipulate that
session.
See `kom-remote-controllers' and `kom-self-control' for settings that
affect remote control."
(interactive)
(setq session-no (or session-no
(car (lyskom-read-session-no
......
......@@ -98,14 +98,26 @@ kom-review-marks-texts-as-read toggled."
(def-kom-command kom-review-all ()
"Review every articles of an author written to a conference."
"Review all articles written by a particular author to a particular
conference. This can also be accomplished by using `kom-review-by-to'
and specifying zero texts.
See `kom-review-uses-cache', `kom-review-priority' and
`kom-review-marks-texts-read' for information on settings that affect
all review-related functions."
(interactive)
(lyskom-tell-internat 'kom-tell-review)
(lyskom-review-by-to 0))
(def-kom-command kom-review-more (count)
"Review more articles using the same critera as the last review."
"Review more articles using the same critera as the last review
performed with `kom-review-by-to'. The review will be resumed where
the previous review finished.
See `kom-review-uses-cache', `kom-review-priority' and
`kom-review-marks-texts-read' for information on settings that affect
all review-related functions."
(interactive "P")
(if (not lyskom-have-review)
(lyskom-format-insert 'no-review-done)
......@@ -154,18 +166,19 @@ kom-review-marks-texts-as-read toggled."
nil
(lyskom-insert-string 'no-such-text)))))))
(def-kom-command kom-review-first (&optional count)
"Reviews all articles of author that is written to conference recipient.
If return is given instead of an author then all authors to that conference is
shown. If return is given instead of conference then all conferences for that
person is chosen.
If a negative numeric argument is given then only the last COUNT articles are
chosen. If the argument is positive then the first -COUNT articles are chosen.
If the argument is zero the all articles are chosen.
No argument is equivalent to COUNT 1.
The defaults for this command is the conference that you are in."
"Review the first N articles written by a particular author to some
conference. With no author specified, review texts by all authors.
With zero texts specified, review all text. With no conference
specified, review texts to all conferences. With a negative number of
texts, review the last N texts instead of the first (you can use
`kom-review-by-to' instead.
See `kom-review-uses-cache', `kom-review-priority' and
`kom-review-marks-texts-read' for information on settings that affect
all review-related functions."
(interactive "P")
(lyskom-tell-internat 'kom-tell-review)
(lyskom-review-by-to (- (or count
......@@ -174,15 +187,16 @@ The defaults for this command is the conference that you are in."
(def-kom-command kom-review-by-to (&optional count)
"Reviews all articles of author that is written to conference recipient.
If return is given instead of an author then all authors to that conference is
shown. If return is given instead of conference then all conferences for that
person is chosen.
If a positive numeric argument is given then only the last COUNT articles are
chosen. If the argument is negative then the first -COUNT articles are chosen.
If the argument is zero the all articles are chosen.
No argument is equivalent to COUNT 1.
The defaults for this command is the conference that you are in."
"Review the last N articles written by a particular author to some
conference. With no author specified, review texts by all authors.
With zero texts specified, review all text. With no conference
specified, review texts to all conferences. With a negative number of
texts, review the last N texts instead of the first (you can use
`kom-review-first' instead.
See `kom-review-uses-cache', `kom-review-priority' and
`kom-review-marks-texts-read' for information on settings that affect
all review-related functions."
(interactive "P")
(lyskom-review-by-to (or count
(lyskom-read-number
......@@ -961,8 +975,13 @@ Cannot be called from a callback."
;;;
(def-kom-command kom-review-backward ()
"Toggles the reviewing order.
If reading forward then starts reading backward and the other way round."
"Toggles the reviewing order. If you are currently reviewing texts
oldest to newest, review newest to oldest instead. When reviewing
newest to oldest, change to oldest to newest.
See `kom-review-uses-cache', `kom-review-priority' and
`kom-review-marks-texts-read' for information on settings that affect
all review-related functions."
(interactive)
(cond
((and (not (read-list-isempty lyskom-reading-list))
......@@ -989,11 +1008,17 @@ If reading forward then starts reading backward and the other way round."
(def-kom-command kom-review-tree (&optional text-no)
"Review all comments to this text.
Descends recursively in the comment-tree without marking the texts as read.
The tree is forgotten when a kom-go-to-next-conf command is issued.
If optional prefix argument TEXT-NO is present view tree from that text
instead. In this case the text TEXT-NO is first shown."
"Recursively review all comments to the selected text.
This command will descend recursively in the comment tree, as when
reading texts normally. Unlike when reading normally, filters are
not applied and circular structures are not dealt with gracefully.
This command accepts text number prefix arguments \(see
`lyskom-read-text-no-prefix-arg').
See `kom-review-uses-cache', `kom-review-priority' and
`kom-review-marks-texts-read' for information on settings that affect
all review-related functions."
(interactive (list (lyskom-read-text-no-prefix-arg 'review-tree-q)))
(lyskom-tell-internat 'kom-tell-review)
(if text-no
......@@ -1010,7 +1035,16 @@ instead. In this case the text TEXT-NO is first shown."
(def-kom-command kom-find-root (text-no)
"Finds the root text of the tree containing the text in lyskom-current-text."
"Finds the root text of the tree containing the selected text.
When there is more than one root, all will be included in a review
operation.
This command accepts text number prefix arguments \(see
`lyskom-read-text-no-prefix-arg').
See `kom-review-uses-cache', `kom-review-priority' and
`kom-review-marks-texts-read' for information on settings that affect
all review-related functions."
(interactive (list (lyskom-read-text-no-prefix-arg 'find-root-q)))
(lyskom-tell-internat 'kom-tell-review)
(cond
......@@ -1040,8 +1074,17 @@ instead. In this case the text TEXT-NO is first shown."
(def-kom-command kom-find-root-review (text-no)
"Finds the root text of the tree containing the text in lyskom-current-text and
reviews the whole tree in deep-first order."
"Finds the root of the comment tree containing the selected texts
and then recursively reviews all its comments. For texts with a single
root, this is equivalent to doing `kom-find-root' followed by
`kom-review-tree'.
This command accepts text number prefix arguments \(see
`lyskom-read-text-no-prefix-arg').
See `kom-review-uses-cache', `kom-review-priority' and
`kom-review-marks-texts-read' for information on settings that affect
all review-related functions."
(interactive (list (lyskom-read-text-no-prefix-arg 'find-root-review-q)))
(lyskom-tell-internat 'kom-tell-review)
(cond
......@@ -1142,9 +1185,14 @@ Text is a text-no."
(def-kom-command kom-review-next ()
"Resumes an interupted review by moving all review and review-tree entries in
the lyskom-reading-list to the beginning. i.e by moving all other types to the