Commit 0f283021 authored by David Byers's avatar David Byers
Browse files

Mostly documentation updates.

Detailed changes:
> 2003-01-12  David Byers  <david.byers@swipnet.se>
>
> 	* vars.el.in: More documentation updates.
>
> 	* lyskom-rest.el (lyskom-beep): List arguments were not handled
> 	correctly (the default key, t, was not used).
>
> 2003-01-11  David Byers  <david.byers@swipnet.se>
>
> 	* vars.el.in: Documented some more variables. Variables that have
> 	been documented properly have "**" at the start of the docstring.
>
parent d2e58b01
2003-01-12 David Byers <david.byers@swipnet.se>
* vars.el.in: More documentation updates.
* lyskom-rest.el (lyskom-beep): List arguments were not handled
correctly (the default key, t, was not used).
2003-01-11 David Byers <david.byers@swipnet.se>
* vars.el.in: Documented some more variables. Variables that have
been documented properly have "**" at the start of the docstring.
2003-01-09 David Byers <david.byers@swipnet.se>
* vars.el.in: Started working on variable documentation.
......
......@@ -34,6 +34,26 @@
;;; TO DO
;;;
;;; Variable documentation requires considerably more flexibility
;;; than command documentation:
;;;
;;; * Generate segmentedlist elements. Look for two-column
;;; indented parts in the documentation.
;;;
;;; * Highlight code (e.g. `t', `nil', `other' usw. Handle
;;; references to elisp functions and elisp variables.
;;;
;;; * Format examples. I don't think we can do this consistently
;;; without any markup. MAybe by looking for indented blocks
;;; where some line in a block does not match a segmentedlist
;;; format.
;;;
;;; In variables, warn for undocumented (no **) def-kom-vared
;;; variables that start with kom-
;;;
;;; Generate DTD fragments so we can use entities for command and
;;; variable references (e.g. &fn:kom-mark-text;) in XML.
;;;
;;; Read templates from a file, so we don't hard-code the
;;; format here.
;;;
......
......@@ -2519,7 +2519,9 @@ A list of pairs means OPTARG will be used as a key to look up the real
((and (listp arg)
(or (assq optarg arg)
(assq t arg)))
(lyskom-beep (cdr (assq optarg arg)) optarg))
(lyskom-beep (cdr (or (assq optarg arg)
(assq t arg)))
optarg))
(t (beep))))
(defun lyskom-face-default-p (f1)
......
......@@ -102,7 +102,7 @@ Inheritance only works with the LysKOM buffer handling functions."
(def-kom-var kom-dont-read-saved-variables '(kom-dont-read-saved-variables
lyskom-login-hook)
"'*Determines which LysKOM variables to not store in the server.
"**Determines which LysKOM variables to not store in the server.
For the most part you do not have to modify this variable. Any variables
set before LysKOM is loaded will not be read from the server.
......@@ -201,353 +201,642 @@ the priority among links that match the same text is undefined."
"Obsolete: Alias for kom-old-farts-text-prompt-strategy.")
(def-kom-var kom-pick-text-no-strategy-alist
'((kom-comment-previous . ((t . lyskom-get-previous-text)
(nil . lyskom-get-previous-text)))
(kom-private-answer-previous . ((t . lyskom-get-previous-text)
(nil . lyskom-get-previous-text)))
(t . ((t . lyskom-get-text-at-point) ; default for prompts
(nil . lyskom-get-text-at-point) ; no prefix arg
(0 . lyskom-prompt-for-text-no)
(- lyskom-get-text-above-point (lambda (&optional arg) 1))
(listp lyskom-get-text-at-point-ancestor
(lambda (arg) (/ (logb (car arg)) 2)))
(lyskom-plusp . lyskom-get-text-below-point)
(lyskom-minusp lyskom-get-text-above-point abs))))
"*Defines how prefix arguments are used to find a text-no to operate on.
The cars on the list are either one of the functions which invokes
`lyskom-read-text-no-prefix-arg' (typically the one of the kom-* functions),
or the value t for the strategy common to all such functions. For functions in
the list, the strategy is chosen from the cdr of that entry and, if and when
no matching rule was found that way, from the common strategy.
Each cdr on the list is an alist specifying when to do how when mapping a
prefix argument to a text-no.
The cars on this alist are the predicates for which the cdrs map functions that
retrieve the text-no to operate on. Each predicate is tested in turn on the
prefix argument, and when one returns non-nil, the cdr gets invoked, until the
list is empty or one cdr returned some non-nil value, whichever comes first. If
you like, the cars can also be the actual prefix-arg values (-, 0 or nil, for
example) that you want to invoke some special rule for. The value t means that
the behaviour given by the cdr stipulates the DEFAULT value for the prompt,
when one is shown.
'((kom-comment-previous . ((t . lyskom-get-previous-text)
(nil . lyskom-get-previous-text)))
(kom-private-answer-previous . ((t . lyskom-get-previous-text)
(nil . lyskom-get-previous-text)))
(t . ((t . lyskom-get-text-at-point) ; default for prompts
(nil . lyskom-get-text-at-point) ; no prefix arg
(0 . lyskom-prompt-for-text-no)
(- lyskom-get-text-above-point (lambda (&optional arg) 1))
(listp lyskom-get-text-at-point-ancestor
(lambda (arg) (/ (logb (car arg)) 2)))
(lyskom-plusp . lyskom-get-text-below-point)
(lyskom-minusp lyskom-get-text-above-point abs))))
"**Defines how prefix arguments are used by commands to find a text to operate on.
The keys \(cars) of the list are either one of the functions that
invoke `lyskom-read-text-no-prefix-arg' or the value `t' for the
strategy common to all such functions. For functions in the list, the
strategy is chosen from the cdr of that entry and, if and when no
matching rule was found that way, from the common strategy.
Each value \(cdr) of the list is an alist specifying how to do when
mapping a prefix argument to a text number.
The keys \(cars) of this alist are the predicates for which the values
\(cdrs) map functions that retrieve the text number to operate on.
Each predicate is tested in turn on the prefix argument, and when one
returns non-nil, the cdr gets invoked. This process is repeated until
all predicates have been tested or a cdr returned a non-nil value,
whichever comes first. If you like, the cars can also be the actual
prefix-arg values (-, 0 or nil, for example) that you want to invoke
some special rule for. The value `t' means that the behaviour given by
the cdr stipulates the default value for the prompt, when one is
shown.
The cdrs on the list may be either of:
* a function, in which case it gets called with four parameters: the prefix
argument, the PROMPT that would be used to ask the user for a text-no, a
(possibly nil) DEFAULT choice for that prompt, and a CONSTRAINT value, all
as provided in the call to `lyskom-read-text-no-prefix-arg' (see its docs)
Returning a positive integer means return that text-no. Returning a common
lyskom format string aborts, showing your helpful error description. A nil
return value means try successive rules instead to get a text-no.
* a function, in which case it gets called with four parameters: the
prefix argument, the `PROMPT' that would be used to ask the user for a
text number, a (possibly nil) `DEFAULT' choice for that prompt, and a
`CONSTRAINT' value, all as provided in the call to
`lyskom-read-text-no-prefix-arg' (see its docs). Returning a positive
integer means return that text number. Returning a common lyskom
format string aborts, showing your helpful error description. A
`nil' return value means try the next rule to get a text number.
* a list of two functions, optionally followed by additional list items,
in which case the second function is called to change the prefix argument
parameter for the first function, which is then called as above. Any extra
items on the argument list will be appended to its argument list. Hence, a
'(my-get-text-no abs 17 4711) entry would result in a my-get-text-no call
(funcall my-get-text-no (abs prefix-arg) prompt default nil 17 4711)."
`\(my-get-text-no abs 17 4711)' entry would result in the following call:
`\(funcall my-get-text-no (abs prefix-arg) prompt default nil 17 4711)'."
)
(def-kom-var kom-url-transformation-rules
'(
("^http://[^/]*aftonbladet\\.se/.*/story/.*html?$" . "\\&.")
)
"*An alist specifying transformations to be applied to URLs.
"**An alist specifying transformations to be applied to URLs.
Elements in this list are of the form `(PATTERN . REPLACEMENT)'.
Before an URL is opened, it is transformed by matching the URL against
each `PATTERN' in turn, and when a match is found, generating a new
URL according to `REPLACEMENT'.
Elements in this list are of the form `(REGEXP . NEWTEXT)'. Before an
URL is opened, it is transformed by replacing REGEXP with NEWTEXT.
Each element in the list is applied in order.
All characters in `REPLACEMENT' except \ are copied verbatim. The
backslash character starts one of the following sequences:
The list elements REGEXP and NEWTEXT correspond to the REGEXP and
NEWTEXT arguments to `replace-in-string'."
Sequence Meaning
\& Substitute the matched text
\N Substitute match for text matching the Nth (...)
group in `PATTERN'
\\ Insert one backslash.
"
server
)
(def-kom-var kom-check-configuration-on-startup t
"*When non-nil, check Emacs configuration on client startup.")
"**When non-nil, check Emacs configuration on client startup.
Valid values for this variable are `t' and `nil'. All other values are
reserved for future extensions. When non-nil, several checks will be
performed:
* Check that multibyte character support is enabled, if available.
* Check that the character coding Emacs uses matches the coding system
used by the server.
Warnings will be shown in the LysKOM buffer on logon.
")
(def-kom-var kom-keyboard-menu-immediate-selection nil
"*When non-nil, typing a keyboard shortcut in a keyboard menu selects
the item immediately, without requiring the user to press RET to confirm."
"**Controls how keyboard menus work.
When displaying text-based menus (typically by pressing the `=' key
when the cursor is on an active area), there are two modes of
selection. Setting this variable to `t' means pressing the letter
corresponding to an item selects that item. When this variable is
`nil', selection has to be confirmed by pressing enter.
Values other tha `t' and `nil' are reserved for future use."
server)
(def-kom-var kom-edit-hide-add-button nil
"*If non-nil, hide the add button shown after the headers when editing
a text."
"**Controls the \"add\" button in the edit buffer.
When set to `t', hide the add button shown after the headers when
editing a text. When set to `nil' (the default), show the button.
Values other than `t' and `nil' are reserved for future use."
server
)
(def-kom-var kom-max-overlays 120
"*Maximum number of overlays to use to highlight texts.
Each text uses one, two, three or four overlays, depending on settings.
Must be a positive integer or nil. If nil, the number of overlays will
be unlimited. Behavior of non-positive and non-nil values is undefined."
"**Maximum number of overlays to use to highlight texts.
When a text is displayed with its own background color (see
`kom-highlight-text-body', `kom-highlight-first-line',
`kom-highligh-dashed-linse', `kom-async-highlight-text-body' and
`kom-async-highlight-dashed-lines') one or more overlays are created.
Since a large number of overlays has a serious impact on performance,
the total number of overlays in the buffer can be limited using this
variable.
When set to a positive integer, limit the number of overlays to that
number. When set to `nil', do not limit the number of overlays. Values
other than a positive integer and `nil' are reserved for future use
and may cause unpredictible results."
server
)
(def-kom-var kom-highlight-text-body t
"*If t, overlay kom-text-body-face on printed text bodies in LysKOM.
"**Controls highlighting of text bodies.
If `t', overlay `kom-text-body-face' on printed text bodies in LysKOM.
When this is enabled, an overlay or extent will be created that may
override certain aspects of the underlying text's formatting. Values
other than t or nil are reserved for future use."
other than `t' or `nil' are reserved for future use.
See `kom-max-overlays' for information on how to limit the number of
overlays."
server
)
(def-kom-var kom-highlight-first-line t
"*If t, overlay kom-first-line-face on the first header line of texts.
When this is enabled, an overlay or extent will be created that may
override certain aspects of the underlying text's formatting. Values
other than t or nil are reserved for future use."
"**Controls highlighting of the first line of text headers.
If `t', overlay `kom-first-line-face' on the first header line of
texts. When this is enabled, an overlay or extent will be created that
may override certain aspects of the underlying text's formatting.
Values other than `t' or `nil' are reserved for future use.
See `kom-max-overlays' for information on how to limit the number of
overlays."
server
)
(def-kom-var kom-highlight-dashed-lines t
"*If t, overlay kom-dashed-lines-face on the lines surrounding texts.
When this is enabled, an overlay or extent will be created that may
override certain aspects of the underlying text's formatting. Values
other than t or nil are reserved for future use."
"**Controls highlighting of dashed lines around texts.
If `t', overlay `kom-dashed-lines-face' on the lines surrounding
texts. When this is enabled, an overlay or extent will be created that
may override certain aspects of the underlying text's formatting.
Values other than `t' or `nil' are reserved for future use.
See `kom-max-overlays' for information on how to limit the number of
overlays."
server
)
(def-kom-var kom-async-highlight-text-body t
"*If t, overlay kom-text-body-face on asynchronous messages in LysKOM.
When this is enabled, an overlay or extent will be created that may
override certain aspects of the underlying text's formatting. Values
other than t or nil are reserved for future use."
"**Controls highlighting of asynchronous messages.
If `t', overlay `kom-async-text-body-face' on asynchronous messages in
LysKOM. When this is enabled, an overlay or extent will be created
that may override certain aspects of the underlying text's formatting.
Values other than `t' or `nil' are reserved for future use.
See `kom-max-overlays' for information on how to limit the number of
overlays."
server
)
(def-kom-var kom-async-highlight-dashed-lines t
"*If t, overlay kom-dashed-lines-face on the lines surrounding messages.
When this is enabled, an overlay or extent will be created that may
override certain aspects of the underlying text's formatting. Values
other than t or nil are reserved for future use."
"**Controls highlighting of dashed lines around asynchronous messages.
If `t', overlay `kom-dashed-lines-face' on the lines surrounding
messages. When this is enabled, an overlay or extent will be created
that may override certain aspects of the underlying text's formatting.
Values other than `t' or `nil' are reserved for future use.
See `kom-max-overlays' for information on how to limit the number of
overlays."
server
)
(def-kom-var kom-extended-status-information nil
"*If t, list extended status information for all objects in LysKOM.
Extended status information include such information as read FAQs.
Values other than t or nil are reserved for future extensions."
server
)
"**Controls display of extra information when displaying LysKOM objects.
If `t', extended status information is listed for all objects in
LysKOM. The information controlled by this variable is the kind of
data that most users are not interested in, and, if displayed, would
make more important information hard to find.
Currently this includes read FAQs (on conferences).
Values other than `t' or `nil' are reserved for future extensions."
server )
(def-kom-var kom-auto-list-faqs t
"*If non-nil, list unread FAQs when entering a conference or logging
on to the server."
"**Controls automatic display of FAQs.
When this variable is set to `t', list unread FAQs when entering a
conference or logging on to the server. When entering a conference,
list FAQs for that conference that have not been read. When logging
on, list FAQs for the server that have not been read.
Values other than `t' or `nil' are reserved for future extension."
server
)
(def-kom-var kom-auto-review-faqs t
"*If non-nil, automatically review unread FAQs when entering a
conference or logging on to the server."
"**Controls automatic review of FAQs.
When set to `t', automatically review unread FAQs when entering a
conference or logging on to the server. When entering a conference,
FAQs that are unread for that conference will be reviewed. When
logging on, FAQs that are unread for the server will be reviewed.
Values other than `t' or `nil' are reserved for future use."
server
)
(def-kom-var kom-allow-incompleteness nil
"*If nil, commands like kom-list-news will wait for the prefetch.
If this flag is set to t, some commands may give incomplete answers,
but it might make them faster, especially during the login phase."
"**Allow or disallow operation on incomplete membership information.
If `nil', commands like `kom-list-news' will wait for all membership
information to be read. If this flag is set to `t', commands will not
wait for all membership information. Not waiting for complete
information allows certain commands to execute faster, particularly
during the login phase, but may result in incorrect or incomplete
answers.
Values other than `t' or `nil' are reserved for future use."
server
)
(def-kom-var kom-bury-buffers t
"*Controls the behaviour of kom-next-kom and its cousins.
If this variable is non-nil the current buffer is sent to the back
of the buffer list when one of the commands `kom-next-kom',
`kom-previous-kom' or `kom-next-unread-kom' is invoked."
"**Controls the behaviour of `kom-next-kom' and its cousins.
If this variable is `t' the current buffer is sent to the back of the
buffer list when one of the commands `kom-next-kom',
`kom-previous-kom' or `kom-next-unread-kom' is invoked.
Values other than `t' or `nil' are reserved for future use."
server)
(def-kom-var kom-write-texts-in-window nil
"*Where to edit texts. One of nil, 'other, 'new-frame, 'other-frame, a string
or a buffer.
"**Determines where to edit texts.
The value must be one of `nil', `other', `new-frame', `other-frame', a
string or a buffer.
nil means edit texts in the same window as the LysKOM buffer.
'other means edit in another window, creating it if necessary.
'other-frame means edit in another frame, if there is one.
'new-frame means create a new frame for editing. The frame will be removed
when editing is finished.
A string or buffer means edit in the indicated buffer."
When set to `nil', edit texts in the same window as the LysKOM buffer.
When set to `other', edit in another window, creating it if necessary.
When set to `other-frame', edit in another frame, if there is one
\(otherwise edit in the same window as the LysKOM buffer). When set to
`new-frame', create a new frame for editing. This frame will be
removed when editing is finished. A string means edit in the buffer
with that name. A buffer means edit in that buffer."
server)
(def-kom-var kom-view-commented-in-window 'other
"*Where to view commented texts. See kom-write-texts-in-window for details."
"**Where to view commented texts.
See the documentation for `kom-write-texts-in-window' for details."
server)
(def-kom-var kom-edit-filters-in-window nil
"*Where to edit filters. See kom-write-texts-in-window for
more information."
"**Where to edit filters with `kom-filter-edit'.
See the documentation for `kom-write-texts-in-window' for details."
server)
(def-kom-var kom-list-membership-in-window 'other
"*Where to list membership. See kom-write-texts-in-window for
more information."
"**Where to list membership with `kom-list-membership'.
See the documentation for `kom-write-texts-in-window' for details."
server)
(def-kom-var kom-personal-messages-in-window 'other
"*Where to display personal messages. See kom-write-texts-in-window
for more information."
"**Where to display personal messages.
See the documentation for `kom-write-texts-in-window' for details."
server)
(def-kom-var kom-customize-format 'long
"*Format of the customize buffer. Must be long or short."
"**Determines the format of the customize buffer.
This variable currently only controls initial display of documentation
in the customize buffer (the buffer shown by `kom-customize'. When set
to the symbol `long', display documentation. When set to the symbol
`short', don't display documentation.
Values other than `long' or `short' are reserved for future use."
server)
(def-kom-var kom-user-prompt-format "%[%c% %m%] - "
"*Format of LysKOM prompt when waiting for input."
"**Format of LysKOM prompt when waiting for input.
The value of this variable must be a string, which is displayed as the
LysKOM prompt, while waiting for a command. The string may contain the
following special sequences:
Sequence Meaning
%c Inserts the current default command.
%[ Inserts `[' if the ansaphone is on.
%] Inserts `]' is the ansaphone is on.
%m Inserts information about recorded messages.
%s Inserts the name of the LysKOM system
%S Inserts the server name.
%p Inserts the name of the user currently logged on.
%w Inserts the name of the current conference.
%a Inserts `anonymous' in the current language.
%A Inserts `Anonymous' in the current language.
%# Inserts the current session number.
% Inserts a space if it seems necessary (percent SPC).
%% Inserts a percent sign.
Here are a few examples:
\"%[%c% %m%] - \" The default prompt
\"%[%s: %c% %m%] - \" Could display \"LysKOM: Time - \"
Note that multiline prompts are not supported."
server)
(def-kom-var kom-user-prompt-format-executing "%[%c% %m%]."
"*Format of LysKOM prompt when executing a default command"
"**Format of LysKOM prompt when executing a default command.
The value of this variable must be a string. See
`kom-user-prompt-format' for details."
server)
(def-kom-var kom-enabled-prompt-format "%[%c% %m%] # "
"*Format of LysKOM prompt when in enabled mode."
"**Format of LysKOM prompt when privileges are enabled..
The value of this variable must be a string. See
`kom-user-prompt-format' for details."
server)
(def-kom-var kom-enabled-prompt-format-executing "%[%c% %m%]."
"*Format of LysKOM prompt when executing a default command in
enabled mode."
"*Format of LysKOM prompt when executing a default command when
privileges are enabled.
The value of this variable must be a string. See
`kom-user-prompt-format' for details."
server)
(def-kom-var kom-anonymous-prompt-format "%[%c% %m%] (%a) - "
"*Format of the LysKOM prompt when running anonymously."
"**Format of the LysKOM prompt when running anonymously.
The value of this variable must be a string. See
`kom-user-prompt-format' for details. See `kom-become-anonymous' for
information on anonymous mode.
"
server)
(def-kom-var kom-anonymous-prompt-format-executing "%[%c% %m%] (%a)."
"*Format of the LysKOM prompt when executing a command anonymously."
"**Format of the LysKOM prompt when executing a command anonymously.
The value of this variable must be a string. See
`kom-user-prompt-format' for details. See `kom-become-anonymous' for
information on anonymous mode."
server)
(def-kom-var kom-show-week-number t
"*If non-nil show the ISO week number when displaying the time."
"**Controls display of week numbers in `kom-display-time'.
If set to `t' show the ISO week number when displaying the time. If
set to `nil', don't display the time. All other values are reserved
for future use.
For this feature to work, the calendar package must be installed."
server)
(def-kom-var kom-cite-string ">"
"*String to insert before each line of a commented text."
"**String to insert before each line of a commented text.
When citing a text in edit-mode, this string will be inserted before
each line. Although citing is not common and usually not useful in
LysKOM, there is occasionally reason to cite a commented text."
server)
(def-kom-var kom-created-texts-are-saved nil
"*If non-nil, save all created texts to a file.
The value of this variable is the file name on which to save new texts."
"**If non-`nil', save all created texts to a file.
The value of this variable is the file name on which to save new
texts. Each time a text is created, it is appended to this file.
Values other than a string may produce unpredictible results, and are
reserved for future extensions."
server
inherited)
(def-kom-var kom-created-texts-are-read nil
"*Non-nil means automatically mark texts that you create as read."
"**Non-`nil' means automatically mark texts that you create as read.
When set to `t', all text you write are automatically marked as read,
except when running in anonymous mode. When set to `nil', your texts
will be shown as all others.
Values other than `t' and `nil' are reserved for future extensions."
server)
(def-kom-var kom-mark-read-texts-as-read-in-new-recipient t
"*When t, silently mark texts as read when they are added to a new
recipient, if they have been read in any conference. When nil, do not
mark as read. Values other than t or nil are reserved for future
extensions."
"**Controls whether to mark read texts as read in new recipients the acquire.
When this is set to `t', silently mark texts as read when they are
added to a new recipient, if they have been read in any conference.
When `nil', do not mark as read. This feature only works when you are
logged on. Texts added to new conferences while you are not logged on
will not be marked as read in the new recipient.
Values other than `t' or `nil' are reserved for future extensions."
server)
(def-kom-var kom-customize-in-window nil
"*Where to customize LysKOM. See kom-write-texts-in-window."
"**Where to customize LysKOM with `kom-customize'.
See the documentation for `kom-write-texts-in-window' for details."
server)
(def-kom-var kom-prioritize-in-window nil
"*Where to prioritize conferences. See kom-write-texts-in-window."
"**Where to prioritize conferences with `kom-prioritize'.
See the documentation for `kom-write-texts-in-window' for details."
server)
(def-kom-var kom-default-mark nil
"*If non-nil (must be an integer), the user is not asked for type of mark."
"**The default mark used by `kom-mark-text'.