[climacs-devel] Re: Climacs - self documenting editor?

[John Q Splittist]

Troels Henriksen <athas <at> sigkill.dk> writes:

> 
> Climacs is severely lacking in the self-documenting aspect of The
> Emacs Way.

True. I present the attached as a start on the other end of the problem, 
knowing that it is easier to edit than compose (and criticise than edit). 
Because I have an ancient climacs tree, this is not presented as a diff. I am 
happy to do the donkey work of moving the strings to the commands once I 
rejoin teh intarweb.

JQS

esa.lisp: com-quit
"Exit climacs, but first ask if you want modified buffers to be saved.
If you decide not to save a modified buffer, you will be asked to confirm your 
decision to exit."

esa.lisp: com-extended-command
"Prompt for a command name and its arguments (if any), then run it."

esa.lisp: com-describe-key-briefly
"Prompt for a key and print the name of the command it invokes."

esa.lisp: com-where-is
"Prompt for a command name and print the key that invokes it."

esa.lisp: com-describe-bindings
"Pop up a help window showing which keys invoke which commands.
Without a numeric prefix, sorts the list by command name. With a numeric 
prefix, sorts by key."

esa.lisp: com-start-kbd-macro
"Start recording keys to define a keyboard macro.
Use C-x ) to finish recording the macro, and C-x e to run it."

esa.lisp: com-end-kbd-macro
"Finish recording keys that define a keyboard macro.
Use C-x ( to start recording a macro, and C-x e to run it."

esa.lisp: com-call-last-kbd-macro
"Run the last keyboard macro that was defined.
Use C-x ( to start and C-x ) to finish recording a keyboard macro."

file-commands.lisp: com-find-file
"Prompt for a filename then edit that file.
If a buffer is already visiting that file, switch to that buffer. Does not 
create a file if the filename given does not name an existing file."

file-commands.lisp: com-find-file-read-only
"Prompt for a filename then open that file readonly.
If a buffer is already visiting that file, switch to that buffer. If the 
filename given does not name an existing file, signal an error."

file-commands.lisp: com-read-only
"Toggle the readonly status of the current buffer.
When a buffer is readonly, attempts to change the contents of the buffer 
signal an error."

file-commands.lisp: com-set-visited-file-name
"Prompt for a filename and set the name of the file visited by the current 
buffer to that name.
The next time the buffer is saved it will be saved to a file with that 
filename."

file-commands.lisp: com-insert-file
"Prompt for a filename and insert the contents of that file at point.
Leaves mark after the inserted contents."

file-commands.lisp: com-revert-buffer
"Replace the contents of the current buffer with the visited file.
Signals an error if the file does not exist."

file-commands.lisp: com-save-buffer
"Write the contents of the buffer to a file.
If there is filename associated with the buffer, write to that file, replacing 
its contents. If not, prompt for a filename."

file-commands.lisp: com-write-buffer
"Prompt for a filename and write the contents of the current buffer to that 
file.
Changes the file visted by the buffer to the given file."

gui.lisp: com-full-redisplay
"Redisplay the contents of the current window.
FIXME: does this really have that effect?"

gui.lisp: com-load-file
"Prompt for a filename and CL:LOAD that file.
Signals and error if the file does not exist."

gui.lisp: com-switch-to-buffer
"Prompt for a buffer name and switch to that buffer.
If the a buffer with that name does not exist, create it. Uses the name of the 
next buffer (if any) as a default."

gui.lisp: com-kill-buffer
"Prompt for a buffer name and kill that buffer.
If the buffer needs saving, will prompt you to do so before killing it. Uses 
the current buffer as a default."

lisp-syntax-commands.lisp: com-eval-defun
""

lisp-syntax-commands.lisp: com-package
"Print the name of the package of the current buffer.
The package is found by looking for the first CL:IN-PACKAGE form in the 
buffer. COMMON-LISP is the default."

lisp-syntax-commands.lisp: com-fill-paragraph
""

misc-commands.lisp: com-overwrite-mode
"Toggle overwrite mode for the current mode.
When overwrite is on, an object entered on the keyboard will replace the 
object after the point. When overwrite is off (the default), objects are 
inserted at point. In both cases point is positioned after the new object."

misc-commands.lisp: com-not-modified
"Clear the modified flag for the current buffer.
The modified flag is automatically set when the contents of the buffer are 
changed. This flag is consulted, for instance, when deciding whether to prompt 
you to save the buffer before killing it."

misc-commands.lisp: com-set-fill-column
"Set the fill column to the specified value.
You must supply a numeric argument. The fill column is the column beyond which 
automatic line-wrapping will occur. The default fill column is 70."

misc-commands.lisp: com-self-insert
""

misc-commands.lisp: com-beginning-of-line
"Move point to the beginning of the current line."

misc-commands.lisp: com-end-of-line
"Move point to the end of the current line."

misc-commands.lisp: com-delete-object
"Delete the object after point.
With a numeric argument, kill that many objects after (or before, if negative) 
point."

misc-commands.lisp: com-backward-delete-object
"Delete the object before point.
With a numeric argument, kills that many objects before (or after, if 
negative) point."

misc-commands.lisp: com-zap-to-object
"Prompt for an object and kill the objects between point and the next 
occurence of that object after point.
Characters can be entered in #\ format."

misc-commands.lisp: com-zap-to-character
"Prompt for a character and kill the objects between point and the next 
occurence of that character after point.
FIXME: Accepts a string (that is, zero or more characters) terminated by a 
#\NEWLINE. If a zero length string signals an error. If a string of length >1, 
uses the first character of the string."

misc-commands.lisp: com-transpose-objects
"Transpose the objects before and after point, advancing point.
At the end of a line transpose the previous two objects without advancing 
point. At the beginning of the buffer do nothing. At the beginning of any line 
other than the first effectively move the first object of that line to the end 
of the previous line.
FIXME: at the end of a single object line at the beginning of the buffer 
deletes that object."

misc-commands.lisp: com-backward-object
"Move point backward one object.
With a numeric argument, move point backward (or forward, if negative) that 
number of objects."

misc-commands.lisp: com-forward-object
"Move point forward one object.
With a numeric argument, move point forward (or backward, if negative) that 
number of objects."

misc-commands.lisp: com-transpose-words
"Transpose the words around point, leaving point at the end of them.
With point in the whitespace between words, transpose the words before and 
after point. With point inside a word, transpose that word with the next one. 
With point before the first word of the buffer, transpose the first two words 
of the buffer.
FIXME: with point after the penultimate word of the buffer, or if there are <2 
words in the buffer, Strange Things (TM) happen (including breaking Climacs)."

misc-commands.lisp: com-transpose-lines
"Transpose current line and previous line, leaving point at the end of them.
If point is in the first line, transpose the first two lines. If point is in 
the last line of the buffer and there is no final #\Newline, add one."

misc-commands.lisp: com-previous-line
"Move point to the previous line.
With a numeric argument, move point up (down, if negative) that many lines. 
Successive line movement commands seek to respect the 'goal column'."

misc-commands.lisp: com-next-line
"Move point to the next line.
With a numeric argument, move point down (up, if negative) that many lines. 
Successive line movement commands seek to respect the 'goal column'."

misc-commands.lisp: com-open-line
"Insert a #\Newline and leave point before it.
With a numeric argument greater than 1, insert that many #\Newlines."

misc-commands.lisp: com-kill-line
"Kill the objects on the current line after point.
When at the end of a line, kill the #\Newline. With a numeric argument of 0, 
kill the objects on the current line before point. With a non-zero numeric 
argument, kill that many lines forward (backward, if negative) from point. 
Successive kills append to the kill ring."

misc-commands.lisp: com-forward-word
"Move point to the next word end.
With a numeric argument, move point forward (backward, if negative) that many 
words."

misc-commands.lisp: com-backward-word
"Move point to the previous word beginning.
With a numeric argument, move point backward (forward, if negative) that many 
words."

misc-commands.lisp: com-delete-word
"Delete from point until the next word end.
With a positive numeric argument, delete that many words forward."

misc-commands.lisp: com-kill-word
"Kill from point until the next word end.
With a numeric argument, kill forward (backward, if negative) that many words. 
Successive kills append to the kill ring."

misc-commands.lisp: com-backward-kill-word
"Kill from point until the previous word beginning.
With a numeric argument, kill backward (forward, if negative) that many words. 
Successive kills append to the kill ring."

misc-commands.lisp: com-mark-word
"Place mark at the next word end.
With a positive numeric argument, place mark at the end of that many words 
forward. With a negative numeric argument, place mark at the beginning of that 
many words backward. Successive invocations extend the selection."

misc-commands.lisp: com-backward-delete-word
"Delete from point until the previous word beginning.
With a positive numeric argument, delete that many words backward."

misc-commands.lisp: com-upcase-region
"Convert the region to upper case."

misc-commands.lisp: com-downcase-region
"Convert the region to lower case."

misc-commands.lisp: com-capitalize-region
"Capitalize each word in the region."

misc-commands.lisp: com-upcase-word
"Convert the characters from point until the next word end to upper case.
Leave point at the word end."

misc-commands.lisp: com-downcase-word
"Convert the characters from point until the next word end to lower case.
Leave point at the word end."

misc-commands.lisp: com-capitalize-word
"Capitalize the next word.
If point is in a word, convert the next character to upper case and the 
remaining letters in the word to lower case. If point is before the start of a 
word, convert the first character of that word to upper case and the rest of 
the letters to lower case. Leave point at the word end."

misc-commands.lisp: com-tabify-region
"Replace runs of spaces with tabs in region where possible.
Uses TAB-SPACE-COUNT of the STREAM-DEFAULT-VIEW of the pane."

misc-commands.lisp: com-untabify-region
"Replace tabs with equivalent runs of spaces in the region.
Uses TAB-SPACE-COUNT of the STREAM-DEFAULT-VIEW of the pane."

misc-commands.lisp: com-indent-line
""

misc-commands.lisp: com-newline-and-indent
""

misc-commands.lisp: com-delete-indentation
"Join current line to previous non-blank line.
Leaves a single space between the last non-whitespace object of the previous 
line and the first non-whitespace object of the current line, and point after 
that space. If there is no previous non-blank line, deletes all whitespace at 
the beginning of the buffer at leaves point there."

misc-commands.lisp: com-auto-fill-mode
"Toggle auto fill mode status.
When auto fill mode is on..."

misc-commands.lisp: com-fill-paragraph
""

misc-commands.lisp: com-beginning-of-buffer
"Move point to the beginning of the buffer."

misc-commands.lisp: com-page-down
""

misc-commands.lisp: com-page-up
""

misc-commands.lisp: com-end-of-buffer
"Move point to the end of the buffer."

misc-commands.lisp: com-mark-whole-buffer
"Place point at the beginning and mark at the end of the buffer."

misc-commands.lisp: com-back-to-indentation
"Move point to the first non-whitespace object on the current line.
If there is no non-whitespace object, leaves point at the end of the line."

misc-commands.lisp: com-delete-horizontal-space
"Delete whitespace around point.
With a numeric argument, only delete whitespace before point."

misc-commands.lisp: com-just-one-space
"Delete whitespace around point, leaving a single space.
With a positive numeric argument, leave that many spaces.
FIXME: should distinguish between types of whitespace."

misc-commands.lisp: com-goto-position
"Prompts for an integer, and sets the offset of point to that integer."

misc-commands.lisp: com-goto-line
"Prompts for a line number, and sets point to the beginning of that line.
The first line of the buffer is 1. Giving a number <1 leaves point at the 
beginning of the buffer. Giving a line number larger than the number of the 
last line in the buffer leaves point at the beginning of the last line of the 
buffer."

misc-commands.lisp: com-browse-url
""

misc-commands.lisp: com-set-mark
"Set mark to the current position of point."

misc-commands.lisp: com-exchange-point-and-mark
"Exchange the positions of point and mark."

misc-commands.lisp: com-set-syntax
"Prompts for a syntax to set for the current buffer.
Setting a syntax will cause the buffer to be reparsed using the new syntax."

misc-commands.lisp: com-yank
"Insert the objects most recently added to the kill ring at point."

misc-commands.lisp: com-kill-region
"Kill the objects between point and mark.
That is, push them onto the kill ring, and delete them from the buffer."

misc-commands.lisp: com-copy-region
"Copy the objects between point and mark to the kill ring."

misc-commands.lisp: com-rotate-yank
"Replace the immediately previously yanked objects with others.
Must be given immediately following a Yank or Rotate Yank command. The 
replacement objects are those before the previously yanked objects in the kill 
ring."

misc-commands.lisp: com-resize-kill-ring
"Prompt for a new size for the kill ring.
The default is 5. A number less than 5 will be replaced by 5."

misc-commands.lisp: com-append-next-kill
"Set the kill ring to append the next kill to the previous one."

misc-commands.lisp: com-undo
""
misc-commands.lisp: com-redo
""

misc-commands.lisp: com-dabbrev-expand
"Expand word before point dynamically.
Search from point (first backward to the beginning of the buffer, then 
forward) for words for which the word before point is a prefix, inserting each 
in turn at point as an expansion."

misc-commands.lisp: com-backward-paragraph
"Move point to the previous paragraph start.
With a numeric argument, move point backward (forward, if negative) that many 
paragraphs."

misc-commands.lisp: com-forward-paragraph
"Move point to the next paragraph end.
With a numeric argument, move point forward (backward, if negative) that many 
paragraphs."

misc-commands.lisp: com-mark-paragraph
"Place point and mark around the current paragraph.
Put point at the beginning of the current paragraph, and mark at the end. With 
a positive numeric argument, put mark that many paragraphs forward. With a 
negative numeric argument, put point at the end of the current paragraph and 
mark that many paragraphs backward. Successive invocations extend the 
selection.
FIXME: when called with point already at the beginning or end of a paragraph 
marks 2 paras."

misc-commands.lisp: com-backward-sentence
"Move point to the previous sentence beginning.
With a numeric argument, move point backward (forward if negative) that many 
sentences."

misc-commands.lisp: com-forward-sentence
"Move point to the next sentence end.
With a numeric argument, move point forward (backward if negative) that many 
sentences."

misc-commands.lisp: com-kill-sentence
"Kill the objects from point to the next sentence end.
With a numeric argument, kill forward (backward if negative) that many 
sentences."

misc-commands.lisp: com-backward-kill-sentence
"Kill the objects from point to the previous sentence beginning.
With a numeric argument, kill backward (forward if negative) that many 
sentences."

misc-commands.lisp: com-forward-page
"Move point to the beginning of the next page.
With a numeric argument, move point forward (backward if negative) that many 
pages. When no page delimeter is found, leave point at the end of the buffer. 
A page is delimited by the sequence #\Newline #\Page."

misc-commands.lisp: com-backward-page
"Move point to the end of the previous page.
With a numeric argument, move point backward (forward if negative) that many 
pages. When no page delimeter is found, leave point at the beginning of the 
buffer. A page is delimited by the sequence #\Newline #\Page."

misc-commands.lisp: com-mark-page
"Place point and mark around the current page.
With a numeric argument, move point that many pages forward (backward if 
negative) before marking the surrounding page. When no page delimeters are 
found, leave point at the beginning and mark at the end of the buffer. A page 
is delimited by the sequence #\Newline #\Page."

misc-commands.lisp: com-count-lines-page
"Print the number of lines in the current page.
Also prints the number of lines before and after point (as '(b + a)').
FIXME: the count is off by one."

misc-commands.lisp: com-count-lines-region
"Print the number of lines in the region.
Also prints the number of objects (as 'o character[s]').
FIXME: line count is off by one."

misc-commands.lisp: com-what-cursor-position
"Print information about point.
Gives the character after point (name and octal, decimal and hexidecimal 
charcode), the offset of point, the total objects in the buffer, and the 
percentage of the buffers objects before point.
FIXME: gives no information at end of buffer."
 
misc-commands.lisp: com-eval-expression
"Prompt for and evaluate a lisp expression.
With a numeric argument inserts the result at point as a string; otherwise 
prints the result."

misc-commands.lisp: com-comment-region
""

misc-commands.lisp: com-backward-expression
"Move point backward one expression.
With a numeric argument, move backward (forward if negative) that many 
expressions. The meaning of 'expression' is given by the relevant syntax. The 
Lisp syntax, for example, uses s-expressions.
FIXME: I'm not sure it does."

misc-commands.lisp: com-forward-expression
"Move point forward one expression.
With a numeric argument, move forward (backward if negative) that many 
expressions. The meaning of 'expression' is given by the relevant syntax. The 
Lisp syntax, for example, uses s-expressions."

misc-commands.lisp: com-mark-expression
"Place mark at the next expression end.
With a numeric argument, place mark forward (backward if negative) that many 
expressions. Successive invocations extend the selection."

misc-commands.lisp: com-kill-expression
"Kill objects up to the next expression end.
With a numeric argument, kill forward (backward if negative) that many 
expressions."

misc-commands.lisp: com-backward-kill-expression
"Kill objects back to the previous expression beginning.
With a numeric argument, kill backward (forward if negative) that many 
expressions."

misc-commands.lisp: com-insert-parentheses
"Insert a pair of parentheses, leaving point in between.
With a numeric argument, enclose that many expressions forward (backward if 
negative).
FIXME: no it doesn't."

misc-commands.lisp: com-forward-list
"Move point forward across a delimited list.
With a numeric argument, move forward (backward if negative) that many lists."

misc-commands.lisp: com-backward-list
"Move point backward across a delimited list.
With a numeric argument, move backward (forward if negative) that many lists."

misc-commands.lisp: com-down-list
"Move point forward down one level of delimited list.
With a numeric argument, move forward (backward if negative) down that many 
lists."

misc-commands.lisp: com-backward-down-list
"Move point backward down one level of delimited list.
With a numeric argument, move backward (forward if negative) down that many 
lists."

misc-commands.lisp: com-backward-up-list
"Move point backward up one level of delimited list.
With a numeric argument, move backward (forward if negative) up that many 
lists."

misc-commands.lisp: com-up-list
"Move point forward up one level of delimited list.
With a numeric argument, move forward (backward if negative) up that many 
lists."

misc-commands.lisp: com-beginning-of-definition
"Move point to the previous definition beginning.
With a numeric argument, move backward (forward if negative) that many 
definitions.
FIXME: negative arg actually does end-of-definition.
FIXME: should take account of CLHS 3.2.3.1 .../HyperSpec/Body/03_bca.htm"

misc-commands.lisp: com-end-of-definition
"Move point to the following definition end.
With a numeric argument, move forward (backward if negative) that many 
defintions.
FIXME: negative arg actually does beginning-of-definition.
FIXME: see second FIXME for com-beginning-of-definition."

misc-commands.lisp: com-mark-definition
"Place point and mark around the current definition.
Successive invocations extend the selection."

misc-commands.lisp: com-visible-mark
"Toggle the visibility of the mark in the current pane.
This is particularly (only?) useful for experimenting with marking commands."

search-commands.lisp: com-isearch-forward
search-commands.lisp: com-isearch-backward
search-commands.lisp: com-isearch-append-char
search-commands.lisp: com-isearch-delete-char
search-commands.lisp: com-isearch-search-forward
search-commands.lisp: com-isearch-search-backward
search-commands.lisp: com-isearch-exit
search-commands.lisp: com-query-replace
search-commands.lisp: com-query-replace-replace
search-commands.lisp: com-query-replace-skip
search-commands.lisp: com-query-replace-exit
search-commands.lisp: com-regex-search-forward
search-commands.lisp: com-regex-search-backward
unicode-commands.lisp: com-insert-charcode
window-commands.lisp: com-split-window-vertically
window-commands.lisp: com-split-window-horizontally
window-commands.lisp: com-other-window
window-commands.lisp: com-single-window
window-commands.lisp: com-scroll-other-window
window-commands.lisp: com-scroll-other-window-up
window-commands.lisp: com-delete-window