Commit a3ea7b71 authored by David Byers's avatar David Byers
Browse files

Some more documentation

parent 409ecf58
;;;;;
;;;;; $Id$
;;;;; Copyright (C) 1991 Lysator Academic Computer Association.
;;;;;
;;;;; This file is part of the LysKOM server.
;;;;;
;;;;; LysKOM is free software; you can redistribute it and/or modify it
;;;;; under the terms of the GNU General Public License as published by
;;;;; the Free Software Foundation; either version 1, or (at your option)
;;;;; any later version.
;;;;;
;;;;; LysKOM is distributed in the hope that it will be useful, but WITHOUT
;;;;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
;;;;; FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
;;;;; for more details.
;;;;;
;;;;; You should have received a copy of the GNU General Public License
;;;;; along with LysKOM; see the file COPYING. If not, write to
;;;;; Lysator, c/o ISY, Linkoping University, S-581 83 Linkoping, SWEDEN,
;;;;; or the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,
;;;;; MA 02139, USA.
;;;;;
;;;;; Please mail bug reports to bug-lyskom@lysator.liu.se.
;;;;;
;;;; Let's start with a minor investigation: Where are strings stored?
;;;; Variable (LIT = literal) Use (ERRor message, INSert, PROmpt)
;;;; -----------------------------------------------------------------
;;;; lyskom-header-separator "--- Skriv texten nedanf|r denna rad "
;;;; lyskom-text-start "/rader/"
;;;; lyskom-commands Commands under 'a'
;;;; LIT lyskom PRO "LysKOM server? ("
;;;; INS "LysKOM elisp-klient version "
;;;; INS "F|rs|ker koppla upp mot "
;;;; LIT lyskom-connect-filter ERR "Protocol error. Servers says: "
;;;; LIT lyskom-server-info INS "Uppkopplingen klar. Serverns ver"
;;;; LIT kom-start-anew PRO "Vad heter du? "
;;;; LIT lyskom-start-anew-loginERR " returned "
;;;; LIT lyskom-start-anew-login-1-5
;;;; PRO "L\senord? "
;;;; LIT lyskom-start-anew-login-2
;;;; ERR "Fel l|sen."
;;;; INS "Du {r nu inloggad. V{nta ett tag"
;;;; LIT lyskom-start-anew-new-person
;;;; INS "Det tycks vara f|rsta g}ngen du "
;;;; PRO "[r det f|rsta g}ngen du anv{nder"
;;;; PRO "Ange personligt l|sen"
;;;; PRO "Repetera f|r kontroll: "
;;;; INS "Du angav inte samma password b{g"
;;;; LIT lyskom-start-anew-create-handler
;;;; INS "Det gick inte att skapa personen"
;;;; LIT lyskom-mode INS (mode-line) "LysKOM (server: %b)"
;;;; LIT kom-queue-resume ERR "kom-queue-resume called on an un"
;;;; LIT lyskom-resume ERR "lyskom-resume called on an unuse"
;;;; ERR "lyskom-resume:" "(not halted)"
;;;; LIT lyskom-process-send-string
;;;; INS "Nu n}r jag inte servern. TCP/IP-"
;;;; INS "Jag f|rs|ker igen."
;;;; LIT lyskom-check-call ERR "unknown key:"
;;;; lyskom-parse-incomplete ERR "LysKOM internal error: Parse inc"
;;;; LIT lyskom-expect-char ERR "Expecting " " but got "
;;;; LIT lyskom-parse-num ERR "Expected number, got "
;;;; LIT lyskom-parse-misc-info-list
;;;; ERR "Expected * or {, got "
;;;; LIT lyskom-parse-misc-info-list-sub
;;;; ERR "Unknown misc-type "
;;;; LIT lyskom-parse-misc-recipient
;;;; ERR "No loc-no after recipient."
;;;; LIT kom-get-appreciation INS "F} Uppmuntran"
;;;; INS "Du {r mycket vacker och mycket k"
;;;; LIT kom-get-abuse INS "F} Sk{ll"
;;;; INS "Du {r mycket ful och mycket dum."
;;;; LIT kom-delete-conf PRO "Vilket m|te/person vill du utpl}"
;;;; LIT lyskom-delete-conf PRO "Ta bort " "personen " "m|tet" "?"
;;;; INS "Utpl}ningen avbruten"
;;;; INS "N}gon annan tog precis bort m|te"
;;;; LIT lyskom-delete-conf-2 INS "Ok, nu {r " " utpl}nad"
;;;; INS " kunde inte utpl}nas av dig."
;;;; LIT kom-delete-text PRO "Vilket inl{gg skall tas bort?"
;;;; INS "Radering av text %d..."
;;;; LIT lyskom-delete-text INS "klart."
;;;; INS "det gick inte."
;;;; LIT kom-review-presentationINS "]terse presentation"
;;;; PRO "Vilket m|te/person? "
;;;; LIT lyskom-review-presentation
;;;; INS " har ingen presentation."
;;;; INS "N}gon tog precis bort m|tet."
;;;; LIT lyskom-view-commented-text
;;;; INS "]terse text nummer %d."
;;;; INS "Det finns inget kommenterat inl{"
;;;; LIT kom-send-letter PRO "Vem vill du skicka brev till? "
;;;; LIT lyskom-send-letter-2 INS " har en lapp p} d|rren:"
;;;; LIT lyskom-send-letter-3 PRO "Vill du fortfarande skicka breve"
;;;; LIT lyskom-do-send-letter PRO "[rende: "
;;;; LIT kom-add-member PRO "Vem vill du addera? "
;;;; LIT lyskom-add-member PRO "Vilket m|te skall han/hon addera"
;;;; LIT kom-add-self PRO "Vilket m|te vill du bli medlem i"
;;;; LIT lyskom-add-member-3 PRO "Prioritet p} m|tet? (0 (l}g) - 2"
;;;; PRO "Placering p} listan? (0-%d) "
;;;; INS "Bli medlem i "
;;;; INS "Addera " " till "
;;;; LIT lyskom-add-member-answer
;;;; INS "Det gick inte."
;;;; INS "klart"
;;;; LIT kom-sub-member PRO "Vem vill du subtrahera? "
;;;; LIT lyskom-sub-member PRO "Vilket m|te skall han/hon subtra"
;;;; LIT kom-sub-self PRO "Vilket m|te vill du g} ur? "
;;;; LIT lyskom-sub-member-3 INS "Fel i personh{mtningen"
;;;; INS "Fel i m|tesh{mtningen."
;;;; INS "Uttr{da ur "
;;;; INS "Subtrahera " " fr}n "
;;;; LIT lyskom-sub-member-answer
;;;; INS "Det gick inte."
;;;; INS "Du" "var kanske aldrig medlem i "
;;;; INS "klart"
;;;; LIT kom-create-conf PRO "Vad ska m|tet heta? "
;;;; PRO "F}r vem som helst bli medlem? "
;;;; PRO "Hemligt m|te? "
;;;; PRO "F}r man skriva kommentarer? "
;;;; LIT lyskom-create-conf-handler
;;;; INS "M|tet " " kunde ej skapas."
;;;; INS "Felkod: %d."
;;;; INS "M|te nummer %d, " ", skapat."
;;;; LIT kom-write-comment INS "Jag f|rst}r inte vilken text du "
;;;; LIT lyskom-write-comment-soon
;;;; INS "Du f}r inte l{sa text %d."
;;;; LIT lyskom-write-comment INS "Jag f|rst}r inte vilken text du "
;;;; LIT kom-private-answer INS "Jag f|rst}r inte vems inl{gg du "
;;;; LIT lyskom-private-answer INS "Jag f|rst}r inte vilken text du "
;;;; LIT kom-quit PRO "Vill du verkligen avsluta sessio"
;;;; INS "Lyskom-sessionen {r avslutad."
;;;; LIT kom-change-presentationPRO "Vilket m|te/person vill du {ndra"
;;;; LIT kom-change-conf-motd PRO "Vilket m|te/person vill du s{tta"
;;;; LIT lyskom-change-pres-or-motd-2
;;;; INS "Kan ej h{mta m|tesstatus f|r m|t"
;;;; INS "Du {r inte organisat|r f|r "
;;;; LIT kom-unset-conf-motd PRO "Vilket m|te/person vill du ta bo"
;;;; LIT lyskom-unset-conf-motd INS "Kan ej h{mta m|tesstatus f|r m|t"
;;;; INS "Du {r inte organisat|r f|r "
;;;; LIT kom-go-to-conf PRO "G} till m|te: "
;;;; LIT lyskom-go-to-conf-handler
;;;; INS "G} till "
;;;; INS "Du f}r inte g} till " "s brevl}d"
;;;; INS "Du {r inte medlem i "
;;;; INS "Vill du bli medlem? "
;;;; INS "Nehej."
;;;; LIT lyskom-do-go-to-conf INS "N}gon raderade precis det m|tet."
;;;; LIT lyskom-go-to-empty-confINS "Du har sett alla texter i detta "
;;;; LIT kom-write-text INS "Du {r inte n{rvarande i n}got m|"
;;;; INS "[rende: "
;;;; LIT kom-list-persons PRO "Ange s|kvillkor (RETURN f|r alla"
;;;; LIT kom-list-conferences PRO "Ange s|kvillkor (RETURN f|r alla"
;;;; LIT kom-change-name PRO "Ange det namn som skall {ndras: "
;;;; LIT lyskom-change-name-2 INS "M|tet eller personen finns ej."
;;;; PRO "Nytt namn: "
;;;; LIT lyskom-change-name-3 PRO "Klart. Nytt namn: "
;;;; INS "Det gick inte bra. Kanske n}got "
;;;; LIT kom-mark-text PRO "Vilket inl{gg vill du markera? "
;;;; LIT kom-unmark-text PRO "Vilket inl{gg vill du avmarkera?"
;;;; LIT lyskom-mark-text PRO "Vilken markering vill du s{tta? "
;;;; INS "%s av text %d..."
;;;; INS "Avmarkering"
;;;; INS "Markering"
;;;; LIT lyskom-mark-text-answerINS "klart"
;;;; INS " Det gick inte."
;;;; LIT kom-review-marked-textsPRO "Vilken markering vill du }terse? "
;;;; INS "Du har inga markerade inl{gg"
;;;; INS " med markeringen %d"
;;;; LIT kom-change-password PRO "Mata in det gamla l|senordet: "
;;;; lyskom-protocol-error ERR "LysKOM protocol error:"
;;;; lyskom-internal-error ERR "LysKOM internal error:"
;;;; kom-tell-phrases what-am-i-doing messages
;;;; LIT kom-extended-command PRO "LysKOM: "
;;;; LIT lyskom-next-command-or-scroll
;;;; ERR "V{nta p} prompten"
;;;; LIT kom-view PRO "]terse text nummer: "
;;;; LIT kom-view INS "]terse text nummer %d.\n"
;;;; LIT kom-view-next-text INS "Du har sett alla texter i detta "
;;;; LIT kom-view-next-text INS "Du l{ser inte n}got m|te just nu"
;;;; LIT lyskom-go-to... etc
LYSKOM BUFFER MANAGEMENT
David Byers
This file describes the functions used for managing buffers.
Anyone who creates buffers needs to know this. All developers
should.
The elisp client uses special functions for managing buffers,
implemented in buffers.el. These should (almost) always be used in
place of standard Emacs functions for buffer management.
The LysKOM functions implement a buffer hierarchy, so that every
buffer except the root buffer (the LysKOM session) has a parent
buffer and zero or more children. When a parent buffer is killed,
all children are also killed, unless the parent or one of the
children has a kill-buffer-query-function that prohibits killing
the buffer.
The code is divided into a low-level, a mid-level part and a
high-level part. You should not have to call low-level functions
directly and rarely (if ever) call mid-level code.
OVERVIEW
The client organized buffers in a tree structure. The root buffer
is the session buffer. It's children are the edit buffers,
prioritization buffers, customization buffers, and other buffers
popped up by the client. These in turn may have children. For
example, the edit buffer can create a buffer to view the commented
text.
Variables can be inherited automatically from buffer parent to
buffer child when a new buffer is created. Inherited variables are
buffer local, and their initial values are copied from the parent
buffer. To define an inherited variable, use def-kom-var (see the
"variables" file).
When a buffer is displayed (lyskom-display-buffer), how it is
displayed is specified by a variable (kom-write-texts-in-window is
an example of such a variable). When buffers are undisplayed
(lyskom-undisplay-buffer) or killed, the undisplay code tries to
restore windows and frames appropriately (a frame popped up for
the buffer is deleted if it is only displaying that buffer; the
window configuration in a frame is restored if a window was
created and so forth).
Every LysKOM buffer must belong to a category. Currently the
following categories are used. Make up new ones as needed:
view-commented For viewing commented texts.
list-membership For listing memberships.
write-texts For writing texts.
prioritize For prioritizing memberships.
customize For customizing the client.
*lyskom-enriched Don't know.
*lyskom-text For reformatting texts.
*temp Temporary buffer.
An asterisk means that buffers of this type are never displayed.
They are for internal use.
When creating a buffer (lyskom-get-buffer-create) you specify the
category and name of the buffer. You can also specify if there can
be only one buffer of that particular category. If a buffer of the
requested category already exists and is a child of the current
LysKOM session, that buffer is renamed, cleared and has all local
variables killed, so it looks like a new buffer.
Unique buffers are used for prioritization, customization and a
few other things. UTSL if you need to know exactly what (look for
lyskom-get-buffer-create).
Note that there can be several buffers of the same category, even
if the unique flag is used, as long as they belong to different
sessions. For example, you can have three prioritization buffers
as long as they belong to three different sessions.
Typically, creating a buffer will look something like this:
(let ((buffer (lyskom-get-buffer-create 'hello-world
"*Hello World*" t)))
(save-excursion
(set-buffer buffer)
(lyskom-format-insert "%#1P sez Hello World!"
lyskom-pers-no)
(lyskom-display-buffer buffer)))
This code creates a buffer of category hello-world, inserts a
string in it and then displays it. Ther will be only one
hello-world buffer per LysKOM session (provided all calls to
lyskom-get-buffer-create with category hello-world specify the
unique flag).
The following high-level functions are defined:
lyskom-generate-new-buffer
Like generate-new-buffer, but does MULE-ish things to the name if
required. IIRC this was necessary when the buffer name was a
multibyte string but multibyte support had been turned off.
lyskom-get-buffer-create
Get or create a buffer. Similar in spirit to get-buffer-create,
but makes the new buffer a child of the current buffer, inherits
variables, records the buffer internally and reuses old buffers of
the specified category if requested. This is what you want to use
to create almost all of your buffers, and certainly all buffers
the user will interact with.
lyskom-display-buffer
Displays a buffer. If the buffer is a LysKOM buffer the variable
kom-CATEGORY-in-window (where CATEGORY is the buffer's category)
specifies how to display the buffer. Read the docstring for
details. This is what you want to use to display all buffers.
lyskom-undisplay-buffer
Undisplays a buffer. Agan, kom-CATEGORY-in-window controls how the
buffer is undisplayed. This function takes care of restoring
window configurations, frames and things like that when removing a
buffer from display. lyskom-undisplay-buffer is called
automatically when a buffer is killed (unless you mess up
kill-buffer-hooks).
lyskom-buffers-of-category
Return a list of all buffers of a particular category. This is
useful if you want to switch to a buffer of a particular category
but don't want to clear it, or if you want to iterate over, say,
all write-texts buffers.
LOW-LEVEL FUNCTIONS
The low-level part handles attaching buffers to each other and
killing buffers. You should never have to call these functions
directly. These functions are independent of LysKOM.
The low-level functions are:
lyskom-set-buffer-parent
lyskom-remove-buffer-child
lyskom-add-buffer-child
lyskom-get-buffer-parent
lyskom-get-buffer-children
lyskom-buffer-root-ancestor
lyskom-map-buffer-children
lyskom-buffer-hierarchy-query-kill-function
lyskom-buffer-hierarchy-kill-hook
The low-level code depends on kill-buffer-query-functions and
kill-buffer-hooks. If you modify these, make sure you do *not*
remove the functions added by these low-level functions.
MID-LEVEL FUNCTIONS
The mid-level functions handle LysKOM buffer categories. The code
is fairly independent of the elisp client itself. You should not
have to call these functions directly since they are called for
you when you create or remove buffers.
The mid-level functions are:
lyskom-clean-up-buffer-category
lyskom-set-buffers-of-category
lyskom-add-buffer-of-category
lyskom-fix-buffer-name
lyskom-update-inherited-variables
lyskom-undisplay-buffer-hook
lyskom-set-partial-window-configuration
lyskom-quit-query
......@@ -46,7 +46,7 @@
use-local-map * lyskom-use-local-map
ignore-errors * lyskom-ignore-errors
save-excursion lyskom-save-excursion
generate-new-buffer * lyskom-generate-new-buffer [2]
generate-new-buffer * lyskom-generate-new-buffer
get-buffer-create * lyskom-get-buffer-create [2]
display-buffer * lyskom-display-buffer [2]
delete-window * lyskom-undisplay-buffer [2]
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment