diff options
Diffstat (limited to 'doc/info/mds.texinfo')
| -rw-r--r-- | doc/info/mds.texinfo | 3314 |
1 files changed, 1664 insertions, 1650 deletions
diff --git a/doc/info/mds.texinfo b/doc/info/mds.texinfo index 0a06874..9fb77c4 100644 --- a/doc/info/mds.texinfo +++ b/doc/info/mds.texinfo @@ -4658,48 +4658,50 @@ Optional. Required if your implement support for @code{Command: configure-screensaver} @item Action: -Reconfigure screensaver settings, or tell the screensaver -server that the screensaver may not start whilst a program -is active. +Reconfigure screensaver settings, or tell the +screensaver server that the screensaver may not start +whilst a program is active. @item Optional header: @code{Screensaver} -The command, in POSIX shell syntax, for the command to run -to start the screensaver. The screensaver server will be -inactive as long as the spawn command has not exited. -To disable screensaving, the value for this header should -be @command{true}. This command always starts without -fail, and does nothing. Which means that the a screensaver -will not start, and the panic action cannot start is it -would if the values as set to @command{false}. The screensaver -server may choose recognise the command @command{true} as -meaning that does not need to start a screensaver. It is -also possible to disable screensaving via the -@code{Activate delay} header. +The command, in POSIX shell syntax, for the command +to run to start the screensaver. The screensaver +server will be inactive as long as the spawn command +has not exited. To disable screensaving, the value +for this header should be @command{true}. This +command always starts without fail, and does nothing. +Which means that the a screensaver will not start, +and the panic action cannot start is it would if the +values as set to @command{false}. The screensaver +server may choose recognise the command +@command{true} as meaning that does not need to start +a screensaver. It is also possible to disable +screensaving via the @code{Activate delay} header. @item Optional header: @code{Activate delay} -The number of seconds the display should be inactive before -the screensaver should start. Floating points are allowed. -The value @code{0} is discouraged, but has the same meaning -as @code{disable}, which means that the screensaver should -never start. +The number of seconds the display should be inactive +before the screensaver should start. Floating points +are allowed. The value @code{0} is discouraged, but +has the same meaning as @code{disable}, which means +that the screensaver should never start. @item Optional header: @code{Lock delay} -The number of seconds to wait after the screensaver starts -before authentication via login passphrase is required to -deactivate the screensaver. Floating points are allowed. -If properly formatted, the environment variable -@env{MDS_SCREENSAVER_LOCK} is set to have this value. -If the value is @code{disable}, the environment variable -@env{MDS_SCREENSAVER_LOCK} will be cleared, which should -be interpreted by the screensaver as that it should not -start the lock mechanism. +The number of seconds to wait after the screensaver +starts before authentication via login passphrase is +required to deactivate the screensaver. Floating +points are allowed. If properly formatted, the +environment variable @env{MDS_SCREENSAVER_LOCK} is +set to have this value. If the value is +@code{disable}, the environment variable +@env{MDS_SCREENSAVER_LOCK} will be cleared, which +should be interpreted by the screensaver as that it +should not start the lock mechanism. @item Optional header: @code{Panic on error} The command, in POSIX shell syntax, to run if the -screensaver exits without another value than 0. -If you do no want anything to happen, choose either -of the values @command{true} or @command{false}. -This is intended as a security measure, in case the +screensaver exits without another value than 0. If +you do no want anything to happen, choose either of +the values @command{true} or @command{false}. This is +intended as a security measure, in case the screensaver fails to start the lock mechanism. @item Optional header: @code{DPMS} @@ -4711,13 +4713,13 @@ TODO The screensaver may not start whilst the client is connected to the server. @item no -Undo the action set by @code{Inhibit: yes} and the same -client. +Undo the action set by @code{Inhibit: yes} and the +same client. @end table @item Conditionally required header: @code{Client ID} -Your ID, provided by the @code{ID assignment} header in -response to a @code{Command: assign-id} header. +Your ID, provided by the @code{ID assignment} header +in response to a @code{Command: assign-id} header. Required if @code{Inhibit} is included in the headers. @item Purpose: @@ -4746,27 +4748,26 @@ Optional. Start the screensaver, either timed or forced. @item Instructions: -The screensaver server should broadcast this -command when the display has been active for -long enough for the screensaver to start. -It should then intercept the message, including -messages with this command that is not send -from the screensaver server itself, with -priority @math{-2^{63}}. The screensaver should -be started when this message is intercepted by -the screensaver server. All servers that need -to perform actions before the switch takes place -must have a priority higher than @math{-2^{63}}, -preferably 0. Server that can perform their -actions asynchronously should intercept the message -without modifying capabilities. +The screensaver server should broadcast this command +when the display has been active for long enough for +the screensaver to start. It should then intercept +the message, including messages with this command +that is not send from the screensaver server itself, +with priority @math{-2^{63}}. The screensaver should +be started when this message is intercepted by the +screensaver server. All servers that need to perform +actions before the switch takes place must have a +priority higher than @math{-2^{63}}, preferably 0. +Server that can perform their actions asynchronously +should intercept the message without modifying +capabilities. @item Purpose: Allow users to force the screensaver to start. @item Purpose: -Allow the screensaver daemon to notify servers -when the screensaver starts. +Allow the screensaver daemon to notify servers when +the screensaver starts. @item Compulsivity: Optional. @@ -4788,40 +4789,40 @@ Optional. Ask servers when they last were active. @item Required header: @code{Last active} -The message broadcaster should set the value of -this header to 0. Any server intercepting this -message should set value to the last time -(monotonic time, preferably raw) the server -observed actions that means that the display -is active, such as usage of the keyboard or rat. -The servers should however not modify the value -if the value they would set it to is lower than -the already set value. Floating points are allowed. +The message broadcaster should set the value of this +header to 0. Any server intercepting this message +should set value to the last time (monotonic time, +preferably raw) the server observed actions that +means that the display is active, such as usage of +the keyboard or rat. The servers should however not +modify the value if the value they would set it to +is lower than the already set value. Floating points +are allowed. @item Instructions: -The screensaver server should broadcast this -message when it thinks it can start the screensaver. -It should intercept this message with priority -@math{-2^{63}}. When intercepted it should read -the @code{Last active} header to determine the -next time the screensaver is allowed to start, -which means that it should add the activate delay -to this value. If the calculate time is in the -past, the screensaver server should broadcast -the @command{start-screensaver} message to start -the screensaver. +The screensaver server should broadcast this message +when it thinks it can start the screensaver. It +should intercept this message with priority +@math{-2^{63}}. When intercepted it should read the +@code{Last active} header to determine the next time +the screensaver is allowed to start, which means that +it should add the activate delay to this value. If +the calculate time is in the past, the screensaver +server should broadcast the +@command{start-screensaver} message to start the +screensaver. @item Purpose: -Allow the screensaver to as servers like -the input device servers whether it is -the for the screensaver to start, instead -of needing to listening on all input devices. +Allow the screensaver to as servers like the input +device servers whether it is the for the screensaver +to start, instead of needing to listening on all +input devices. @item Compulsivity: Optional. @item Reference implementation: -@command{mds-screensaver}, @command{mds-kkbd} +@command{mds-screensaver}, @command{mds-kkbd}, @command{mds-kbd} and @command{mds-rat} @end table @@ -4880,7 +4881,8 @@ Recommended for network enabled servers. @command{Command: kill} @item Action: -Kill and identify processes based on the their windows. +Kill and identify processes based on the their +windows. @item Required header: @code{Client ID} Your ID, provided by the @code{ID assignment} header @@ -4894,21 +4896,20 @@ be identified or signaled. A numerical value of the signal to send to the process. It is up to networking protocols to translate these numbers of the display spans -multiple operating systems. The signal zero -can usually be used if no signal is to be sent, -this is however dependent on the operating system. +multiple operating systems. The signal zero can +usually be used if no signal is to be sent, this is +however dependent on the operating system. @item Response: The server will respond with a @command{Command: error} message. -In this message the server all include an -ad-hoc header: @code{Process ID}@. Its value -will be the ID of the process that owns the -window. +In this message the server all include an ad-hoc +header: @code{Process ID}@. Its value will be the ID +of the process that owns the window. @item Purpose: -Identify and send signal to processes by refering -to them by one of their windows. +Identify and send signal to processes by refering to +them by one of their windows. @item Compulsivity: Optional. @@ -4926,10 +4927,10 @@ libmdsserver is library written for the reference implementation of the @command{mds} servers. llibmdsserver does not contain support or any protocols, rather it contains auxiliary functions, -macros, data structures such as linked lists and -hash tables, and support the basics of the message -passing protocol: receiving message and decode it -into headers and payloads. +macros, data structures such as linked lists and hash +tables, and support the basics of the message passing +protocol: receiving message and decode it into +headers and payloads. @menu * Macros:: Writing macroscopic systems. @@ -4944,10 +4945,10 @@ into headers and payloads. The header file @file{<libmdsserver/macros.h>} contains macros for readability and code reduction, -it also contains macros and definitions for portability; -they may either provide portability by nature, or -provide one place to do modifications to port the -system. +it also contains macros and definitions for +portability; they may either provide portability by +nature, or provide one place to do modifications to +port the system. @table @asis @item @code{xasprintf} [(@code{char* buffer, ...}) @arrow{} @code{int}] @@ -4955,11 +4956,11 @@ system. @cpindex Functions, printing @cpindex Printing fuction This is a wrapper for @code{asprintf} that has two -important properties, the buffer is guaranteed to -be @code{NULL} on failure, and it will return zero -on and only on success. Unlike @code{asprintf}, -@code{xasprintf} takes the buffer's variable as -its first argument rather than the address of that +important properties, the buffer is guaranteed to be +@code{NULL} on failure, and it will return zero on +and only on success. Unlike @code{asprintf}, +@code{xasprintf} takes the buffer's variable as its +first argument rather than the address of that variable. @item @code{xsnprintf} [(@code{char buffer[], ...}) @arrow{} @code{int}] @@ -4967,34 +4968,36 @@ variable. @cpindex Functions, printing @cpindex Printing fuction This is a wrapper for @code{snprintf} that allows you -to forget about the buffer size. When you know how long -a string can be, you should use @code{sprintf}. But when -you cannot know for sure you should use @code{xsnprintf}. -@code{xsnprintf} works exactly as @code{sprintf}, but -it will require that the first argument is defined -using @code{[]} rather than @code{*} because it will use -this to find out how large the buffer is so it can call -@code{snprintf} with that size. +to forget about the buffer size. When you know how +long a string can be, you should use @code{sprintf}. +But when you cannot know for sure you should use +@code{xsnprintf}. @code{xsnprintf} works exactly as +@code{sprintf}, but it will require that the first +argument is defined using @code{[]} rather than +@code{*} because it will use this to find out how +large the buffer is so it can call @code{snprintf} +with that size. @item @code{eprint} [(@code{const char* format}) @arrow{} @code{int}] @fnindex @code{eprint} @cpindex Functions, printing, errors @cpindex Printing fuction, errors @cpindex Error printing function -A wrapper for @code{fprintf} that prints a string prefixed -with the value of @code{*argv} to @code{stderr}. -This wrapper also as a line feed to the end of the text. -Because @code{eprintf} naïvely wraps @code{fprintf}, all -`%':s in the string must be duplicated. +A wrapper for @code{fprintf} that prints a string +prefixed with the value of @code{*argv} to +@code{stderr}. This wrapper also as a line feed to +the end of the text. Because @code{eprintf} naïvely +wraps @code{fprintf}, all `%':s in the string must be +duplicated. @item @code{eprintf} [(@code{const char* format, ...}) @arrow{} @code{int}] @fnindex @code{eprintf} @cpindex Functions, printing, errors @cpindex Printing fuction, errors @cpindex Error printing function -@code{eprint} extends @code{eprint} with variadic arguments -that can be used to insert values into the format string -just like you can do in @code{fprintf}. +@code{eprint} extends @code{eprint} with variadic +arguments that can be used to insert values into the +format string just like you can do in @code{fprintf}. @item @code{iprint} [(@code{const char* format}) @arrow{} @code{int}] @fnindex @code{iprint} @@ -5004,12 +5007,13 @@ just like you can do in @code{fprintf}. @sgindex @code{SIGINFO} @cpindex State dump @cpindex Statistics dump -A wrapper for @code{fprintf} that prints a string prefixed -with the value of @code{*argv}, as well a label telling the -user that the output is part of a state and statistics dump, -to @code{stderr}. This wrapper also as a line feed to the -end of the text. Because @code{eprintf} naïvely wraps -@code{fprintf}, all `%':s in the string must be duplicated. +A wrapper for @code{fprintf} that prints a string +prefixed with the value of @code{*argv}, as well a +label telling the user that the output is part of a +state and statistics dump, to @code{stderr}. This +wrapper also as a line feed to the end of the text. +Because @code{eprintf} naïvely wraps @code{fprintf}, +all `%':s in the string must be duplicated. @item @code{iprintf} [(@code{const char* format, ...}) @arrow{} @code{int}] @fnindex @code{iprintf} @@ -5019,9 +5023,9 @@ end of the text. Because @code{eprintf} naïvely wraps @sgindex @code{SIGINFO} @cpindex State dump @cpindex Statistics dump -@code{eprint} extends @code{iprint} with variadic arguments -that can be used to insert values into the format string -just like you can do in @code{fprintf}. +@code{eprint} extends @code{iprint} with variadic +arguments that can be used to insert values into the +format string just like you can do in @code{fprintf}. @item @code{with_mutex} [(@code{pthread_mutex_t mutex, instructions})] @fnindex @code{with_mutex} @@ -5029,9 +5033,11 @@ just like you can do in @code{fprintf}. @cpindex Multi-threading, synchronisation @cpindex Synchronisation, threading @cpindex Mutex -Wraps @code{instructions} with @code{errno = pthread_mutex_lock(mutex);} -and @code{errno = pthread_mutex_unlock(mutex);}, so a set of -instructions can be invoked inside mutex protection. +Wraps @code{instructions} with +@code{errno = pthread_mutex_lock(mutex);} and +@code{errno = pthread_mutex_unlock(mutex);}, so a set +of instructions can be invoked inside mutex +protection. @item @code{with_mutex_if} [(@code{pthread_mutex_t mutex, condition, instructions})] @fnindex @code{with_mutex_if} @@ -5039,9 +5045,10 @@ instructions can be invoked inside mutex protection. @cpindex Multi-threading, synchronisation @cpindex Synchronisation, threading @cpindex Mutex -An alternative to @code{with_mutex} where @code{instructions} -is wrapped around @code{if (condition)} which in turn is -wrapped inside the mutex protection. +An alternative to @code{with_mutex} where +@code{instructions} is wrapped around +@code{if (condition)} which in turn is wrapped inside +the mutex protection. @item @code{max} [(@code{a, b})] @fnindex @code{max} @@ -5063,9 +5070,8 @@ Returns the lower value of @code{a} and @code{b}. @cpindex Marshalling macros @sgindex @code{SIGUPDATE} Casts @code{buffer} to a @code{type} buffer and -subscripts to the @code{index}:th element. You -can either use this function as a getter or a -setter. +subscripts to the @code{index}:th element. You can +either use this function as a getter or a setter. @item @code{buf_set} [(@code{char* buffer, type, size_t index, type variable}) @arrow{} @code{type}] @fnindex @code{buf_set} @@ -5165,10 +5171,10 @@ may be @code{NULL}@. @cpindex Previleges @cpindex Security, previleges Sets the effective user to the real user and the -effective group to the real group. This is used -by most servers and ensure that they are not -running with unnecessary privileges. Returns zero -on and only on success. +effective group to the real group. This is used by +most servers and ensure that they are not running +with unnecessary privileges. Returns zero on and only +on success. @item @code{monotone} [(@code{struct timespec* time_slot}) @arrow{} @code{int}] @fnindex @code{monotone} @@ -5183,16 +5189,16 @@ success. @cpindex File descriptions, close all @cpindex Close all file descriptions Closes all file descriptors named by a variable -@code{fd} for which @code{condition} evalutes -to non-zero. +@code{fd} for which @code{condition} evalutes to +non-zero. @item @code{xfree} [(@code{void** array, size_t elements}) @arrow{} @code{void}] @fnindex @code{xfree} @cpindex Memory management Calls @code{free} on the first @code{elements} -elements in @code{array}, and than calls -@code{free} on @code{array}. This macro -requires @code{size_t i} is declared. +elements in @code{array}, and than calls @code{free} +on @code{array}. This macro requires @code{size_t i} +is declared. @item @code{xmalloc} [(@code{type* var, size_t elements, type}) @arrow{} @code{int}] @fnindex @code{xmalloc} @@ -5205,235 +5211,225 @@ elements and stores the allocated pointer to @fnindex @code{xbmalloc} @cpindex Memory management Allocates @code{bytes} bytes and stores the allocated -pointer to @code{var}. Returns zero on and only on success. +pointer to @code{var}. Returns zero on and only on +success. @item @code{xcalloc} [(@code{type* var, size_t elements, type}) @arrow{} @code{int}] @fnindex @code{xcalloc} @cpindex Memory management Allocates a zero-initialised @code{type*} with @code{elements} elements and stores the allocated -pointer to @code{var}. Returns zero on and only -on success. +pointer to @code{var}. Returns zero on and only on +success. @item @code{xbcalloc} [(@code{type* var, size_t bytes}) @arrow{} @code{int}] @fnindex @code{xbcalloc} @cpindex Memory management -Allocates and zero-initialises @code{bytes} bytes -and stores the allocated pointer to @code{var}. -Returns zero on and only on success. +Allocates and zero-initialises @code{bytes} bytes and +stores the allocated pointer to @code{var}. Returns +zero on and only on success. @item @code{xrealloc} [(@code{type* var, size_t elements, type}) @arrow{} @code{int}] @fnindex @code{xrealloc} @cpindex Memory management Reallocates @code{var} and updates the variable -@code{var} accordingly. @code{var} will be -allocated to have @code{elements} elements -of the type @code{type}. If @code{var} is -@code{NULL} a new allocation is created. If -@code{elements} is zero, @code{var} will -be deallocated. Returns zero on and only -on success. On failure, @code{var} will be -@code{NULL}, so you must store the @code{var} -into another variable in case this macro -fails. +@code{var} accordingly. @code{var} will be allocated +to have @code{elements} elements of the type +@code{type}. If @code{var} is @code{NULL} a new +allocation is created. If @code{elements} is zero, +@code{var} will be deallocated. Returns zero on and +only on success. On failure, @code{var} will be +@code{NULL}, so you must store the @code{var} into +another variable in case this macro fails. @item @code{xxrealloc} [(@code{type* old, type* var, size_t elements, type}) @arrow{} @code{int}] @fnindex @code{xxrealloc} @cpindex Memory management -Variant of @code{xrealloc} that will -return with @code{old} set to @code{NULL} -on success, and @code{old} set to @code{var} -on error. Like @code{xrealloc}, @code{xxrealloc} -returns zero on and only on success. +Variant of @code{xrealloc} that will return with +@code{old} set to @code{NULL} on success, and +@code{old} set to @code{var} on error. Like +@code{xrealloc}, @code{xxrealloc} returns zero on and +only on success. @item @code{yrealloc} [(@code{type* tmp, type* var, size_t elements, type}) @arrow{} @code{int}] @fnindex @code{yrealloc} @cpindex Memory management -Variant of @code{xrealloc} that will -store @code{var} to @code{tmp} before -reallocating @code{var} and then restore -@code{var} if the reallocation failed. -Like @code{xrealloc}, @code{yrealloc} -returns zero on and only on success. +Variant of @code{xrealloc} that will store @code{var} +to @code{tmp} before reallocating @code{var} and then +restore @code{var} if the reallocation failed. Like +@code{xrealloc}, @code{yrealloc} returns zero on and +only on success. @item @code{growalloc} [(@code{type* old, type* var, size_t elements, type}) @arrow{} @code{int}] @fnindex @code{growalloc} @cpindex Memory management -When using this macro @code{var} should -be a @code{type*} pointer allocated for -@code{elements} elements of the type -@code{type}. This macro will reallocate -@code{var} to contain twice as many elements -and update @code{elements} accordingly. -On failure nothing changes. You must specify -an auxiliary @code{type*} variable and -specify it in as the @code{old} parameter. -Returns zero on and only on success. +When using this macro @code{var} should be a +@code{type*} pointer allocated for @code{elements} +elements of the type @code{type}. This macro will +reallocate @code{var} to contain twice as many +elements and update @code{elements} accordingly. On +failure nothing changes. You must specify a + auxiliary @code{type*} variable and specify it in as +the @code{old} parameter. Returns zero on and only on +success. @item @code{xstrdup} [(@code{char* var, const char* original}) @arrow{} @code{int}] @fnindex @code{xstrdup} @cpindex Memory management -Wrapper for @code{strdup} that -returns zero on and only on success. -@code{original} is duplicate and the -duplicate is stored in the variable -@code{var}. If @code{original} is -@code{NULL}, @code{var} is set to +Wrapper for @code{strdup} that returns zero on and +only on success. @code{original} is duplicate and the +duplicate is stored in the variable @code{var}. If +@code{original} is @code{NULL}, @code{var} is set to @code{NULL} and zero is returned. @item @code{xmemdup} [(@code{void* var, const void* original, size_t elements, type}) @arrow{} @code{int}] @fnindex @code{xmemdup} @cpindex Memory management -Allocates a pointer of the type @code{type*} -with room for @code{elements} elements and -stores the pointer to @code{var}. If successful, -the content of @code{original} (@code{elements} -elements of size @code{sizeof(type*)}) is -copied to @code{var}, and zero is returned. -On failure, a non-zero value is returned. +Allocates a pointer of the type @code{type*} with +room for @code{elements} elements and stores the +pointer to @code{var}. If successful, the content of +@code{original} (@code{elements} elements of size +@code{sizeof(type*)}) is copied to @code{var}, and +zero is returned. On failure, a non-zero value is +returned. @item @code{xperror} [(@code{const char* str}) @arrow{} @code{void}] @fnindex @code{xperror} @cpindex Error management -Invokes @code{perror(str)} if and only if -@code{errno} is non-zero and then sets -@code{errno} to zero. @code{str} should -unless you have a specific reason be -@code{*argv}. +Invokes @code{perror(str)} if and only if @code{errno} +is non-zero and then sets @code{errno} to zero. +@code{str} should unless you have a specific reason +be @code{*argv}. @item @code{fail_if} [(@code{condition}) @arrow{} @code{void}] @fnindex @code{fail_if} @cpindex Error management -If @code{condition} is satisfied, a jump -is made to the label @code{fail}. -Additionally the location of failure will -be printed to standard error. +If @code{condition} is satisfied, a jump is made to +the label @code{fail}. Additionally the location of +failure will be printed to standard error. @item @code{exit_if} [(@code{condition, instructions}) @arrow{} @code{void}] @fnindex @code{exit_if} @cpindex Error management @cpindex Terminating -If @code{condition} is satisfied, -@code{instructions} is invoked and -@code{1} is @code{return}:ed. +If @code{condition} is satisfied, @code{instructions} +is invoked and @code{1} is @code{return}:ed. @end table @cpindex Signals @sgindex @code{SIGDANGER} @sgindex @code{SIGUPDATE} @sgindex @code{SIGINFO} -Additionally, @file{<libmdsserver/macros.h>} -defines any missing signal name: currently -@code{SIGDANGER}, @code{SIGINFO} and -@code{SIGUPDATE}, and by inclusion of -@file{<libmdsserver/macro-bits.h>}, variants -of @code{atoi} for portability and -convenience: +Additionally, @file{<libmdsserver/macros.h>} defines +any missing signal name: currently @code{SIGDANGER}, +@code{SIGINFO} and @code{SIGUPDATE}, and by inclusion +of @file{<libmdsserver/macro-bits.h>}, variants of +@code{atoi} for portability and convenience: @cpindex Integer parsing macros @table @code @item atoz @fnindex @code{atoz} @tpindex @code{size_t} -Parse a human readable @code{const char*} -10-radix integer to a @code{size_t}. +Parse a human readable @code{const char*} 10-radix +integer to a @code{size_t}. @item atosz @fnindex @code{atosz} @tpindex @code{ssize_t} -Parse a human readable @code{const char*} -10-radix integer to a @code{ssize_t}. +Parse a human readable @code{const char*} 10-radix +integer to a @code{ssize_t}. @item atoh @fnindex @code{atoh} @tpindex @code{short int} @tpindex @code{signed short int} -Parse a human readable @code{const char*} -10-radix integer to a @code{short int}. +Parse a human readable @code{const char*} 10-radix +integer to a @code{short int}. @item atouh @fnindex @code{atouh} @tpindex @code{unsigned short int} -Parse a human readable @code{const char*} -10-radix integer to an @code{unsigned short int}. +Parse a human readable @code{const char*} 10-radix +integer to an @code{unsigned short int}. @item atou @fnindex @code{atou} @tpindex @code{unsigned int} -Parse a human readable @code{const char*} -10-radix integer to an @code{unsigned int}. +Parse a human readable @code{const char*} 10-radix +integer to an @code{unsigned int}. @item atoul @fnindex @code{atoul} @tpindex @code{unsigned long int} -Parse a human readable @code{const char*} -10-radix integer to an @code{unsigned long int}. +Parse a human readable @code{const char*} 10-radix +integer to an @code{unsigned long int}. @item atoull @fnindex @code{atoull} @tpindex @code{unsigned long long int} -Parse a human readable @code{const char*} -10-radix integer to an @code{unsigned long long int}. +Parse a human readable @code{const char*} 10-radix +integer to an @code{unsigned long long int}. @item ato8 @fnindex @code{ato8} @tpindex @code{int8_t} -Parse a human readable @code{const char*} -10-radix integer to an @code{int8_t}. +Parse a human readable @code{const char*} 10-radix +integer to an @code{int8_t}. @item atou8 @fnindex @code{atou8} @tpindex @code{uint8_t} -Parse a human readable @code{const char*} -10-radix integer to an @code{uint8_t}. +Parse a human readable @code{const char*} 10-radix +integer to an @code{uint8_t}. @item ato16 @fnindex @code{ato16} @tpindex @code{int16_t} -Parse a human readable @code{const char*} -10-radix integer to an @code{int16_t}. +Parse a human readable @code{const char*} 10-radix +integer to an @code{int16_t}. @item atou16 @fnindex @code{atou16} @tpindex @code{uint16_t} -Parse a human readable @code{const char*} -10-radix integer to an @code{uint16_t}. +Parse a human readable @code{const char*} 10-radix +integer to an @code{uint16_t}. @item ato32 @fnindex @code{ato32} @tpindex @code{int32_t} -Parse a human readable @code{const char*} -10-radix integer to an @code{int32_t}. +Parse a human readable @code{const char*} 10-radix +integer to an @code{int32_t}. @item atou32 @fnindex @code{atou32} @tpindex @code{uint32_t} -Parse a human readable @code{const char*} -10-radix integer to an @code{uint32_t}. +Parse a human readable @code{const char*} 10-radix +integer to an @code{uint32_t}. @item ato64 @fnindex @code{ato64} @tpindex @code{int64_t} -Parse a human readable @code{const char*} -10-radix integer to an @code{int64_t}. +Parse a human readable @code{const char*} 10-radix +integer to an @code{int64_t}. @item atou64 @fnindex @code{atou64} @tpindex @code{uint64_t} -Parse a human readable @code{const char*} -10-radix integer to an @code{uint64_t}. +Parse a human readable @code{const char*} 10-radix +integer to an @code{uint64_t}. @item atoj @fnindex @code{atoj} @tpindex @code{intmax_t} -Parse a human readable @code{const char*} -10-radix integer to an @code{intmax_t}. +Parse a human readable @code{const char*} 10-radix +integer to an @code{intmax_t}. @item atouj @fnindex @code{atouj} @tpindex @code{uintmax_t} -Parse a human readable @code{const char*} -10-radix integer to an @code{uintmax_t}. +Parse a human readable @code{const char*} 10-radix +integer to an @code{uintmax_t}. @end table @@ -5442,8 +5438,8 @@ Parse a human readable @code{const char*} @section Auxiliary Functions In the header file @file{<libmdsserver/util.h>}, -libmdsserver defines common functions to help -write servers more concisely. +libmdsserver defines common functions to help write +servers more concisely. @table @asis @item @code{parse_client_id} [(@code{const char* str}) @arrow{} @code{uint64_t}] @@ -5468,8 +5464,8 @@ the variable's value is an empty string. @cpindex Version update @sgindex @code{SIGUSR1} @sgindex @code{SIGUPDATE} -Prepare the server so that it can re-execute into -a newer version of the executed file. +Prepare the server so that it can re-execute into a +newer version of the executed file. This is required for two reasons: @@ -5483,8 +5479,8 @@ could also hinter its use. @item The kernel appends @samp{ (deleted)} to -@file{/proc/self/exe} once it has been removed, -so it cannot be replaced. +@file{/proc/self/exe} once it has been removed, so it +cannot be replaced. @end enumerate Returns zero on success and @code{-1} on error. @@ -5498,9 +5494,9 @@ Returns zero on success and @code{-1} on error. @sgindex @code{SIGUSR1} @sgindex @code{SIGUPDATE} Re-execute the server. If @code{prepare_reexec} -failed or has not been called, @code{argv[0]} -will be used as a fallback. This functions -has three input parameters: +failed or has not been called, @code{argv[0]} will be +used as a fallback. This functions has three input +parameters: @table @code @item argc @@ -5508,7 +5504,7 @@ The number of elements in @code{argv}. @item argv The command line arguments. @item reexeced -Whether the server has previously been re-executed +Whether the server has previously been re-executed. @end table This function only returns on failure. @@ -5518,56 +5514,58 @@ This function only returns on failure. @fnindex @code{sigaction} @fnindex @code{signal} @cpindex Signals -@code{sigaction} with the same parameters as @code{signal}. -This function should only be used for common @command{mds} -signals and signals that does not require any special settings. -This function may choose to add additional behaviour depending -on the signal, such as blocking other signals. Returns zero +@code{sigaction} with the same parameters as +@code{signal}. This function should only be used for +common @command{mds} signals and signals that does +not require any special settings. This function may +choose to add additional behaviour depending on the +signal, such as blocking other signals. Returns zero on success and @code{-1} on error. @item @code{send_message} [(@code{int socket, const char* message, size_t length}) @arrow{} @code{size_t}] @fnindex @code{send_message} @cpindex Communication over sockets @cpindex Socket communication -Send the message @code{messsage}, of length @code{length} -over the socket that is access with the file descriptor -@code{socket}. Returns the number of bytes that have been -sent, even on error. +Send the message @code{messsage}, of length +@code{length} over the socket that is access with the +file descriptor @code{socket}. Returns the number of +bytes that have been sent, even on error. @item @code{strict_atoi} [(@code{const char* str, int* value, int min, int max}) @arrow{} @code{int}] @fnindex @code{strict_atoi} @fnindex @code{atoi} @cpindex Integer parsing @cpindex Error management -A version of @code{atoi} that is strict about the syntax -and bounds. Parses the string @code{str} into an @code{int} -and stores it in @code{*value}. If the string is not a -10-radix integer or has a value outside [@code{min}, -@code{max}], @code{-1} is returned, otherwise zero is -returned. +A version of @code{atoi} that is strict about the +syntax and bounds. Parses the string @code{str} into +an @code{int} and stores it in @code{*value}. If the +string is not a 10-radix integer or has a value +outside [@code{min}, @code{max}], @code{-1} is +returned, otherwise zero is returned. @item @code{full_write} [(@code{int fd, const char* buffer, size_t length}) @arrow{} @code{int}] @fnindex @code{full_write} @cpindex File writing -Send the buffer @code{buffer}, with the length @code{length}, -into the file whose file descriptor is @code{fd} and ignores -interruptions. Returns zero on success and @code{-1} on error. +Send the buffer @code{buffer}, with the length +@code{length}, into the file whose file descriptor is +@code{fd} and ignores interruptions. Returns zero on +success and @code{-1} on error. @item @code{full_read} [(@code{int fd, size_t* length}) @arrow{} @code{char*}] @fnindex @code{full_read} @cpindex File reading -Read the file whose file descriptor is @code{fd} completely -and ignore interruptions. If @code{length} if not @code{NULL}, -the length of the read file is stored in @code{*length}. -On success, the read content is retured, on error @code{NULL} -is returned. +Read the file whose file descriptor is @code{fd} +completely and ignore interruptions. If @code{length} +if not @code{NULL}, the length of the read file is +stored in @code{*length}. On success, the read +content is retured, on error @code{NULL} is returned. @item @code{startswith_n} [(@code{const char*, const char*, size_t, size_t}) @arrow{} @code{int}] @fnindex @code{startswith_n} @cpindex String comparison Check whether a string begins with a specific string, -where neither of the strings are necessarily NUL-terminated. -The parameters are: +where neither of the strings are necessarily +NUL-terminated. The parameters are: @table @code @item const char* haystack @@ -5580,17 +5578,17 @@ The length of @code{haystack}. The length of @code{needle}. @end table -Returns 1 if @code{haystack} beings with @code{needle}, -otherwise zero is returned. +Returns 1 if @code{haystack} beings with +@code{needle}, otherwise zero is returned. @item @code{uninterruptable_waitpid} [(@code{pid_t pid, int* restrict status, int options}) @arrow{} @code{pid_t}] @fnindex @code{uninterruptable_waitpid} @fnindex @code{waitpid} @cpindex Process management Wrapper around @code{waitpid} that never returns on an -interruption unless it is interrupted one hundred times -within the same clock second. The parameters and return -value are exactly those of @code{waitpid}. +interruption unless it is interrupted one hundred +times within the same clock second. The parameters +and return value are exactly those of @code{waitpid}. @item @code{verify_utf8}[(@code{const char* string, int allow_modified_nul}) @arrow{} @code{int}] @fnindex @code{verify_utf8} @@ -5633,18 +5631,18 @@ these are written with marshal-functionallity. @tpindex @code{struct client_list} @cpindex Client ID, lists @cpindex Lists of client ID:s -In the header file @file{<libmdsserver/client-list.h>}, -libmdsserver defines a dynamic list for storing -client ID:s. +In the header file +@file{<libmdsserver/client-list.h>}, libmdsserver +defines a dynamic list for storing client ID:s. @item @code{linked_list_t} @{also known as @code{struct linked_list}@} @tpindex @code{linked_list_t} @tpindex @code{struct linked_list} @cpindex Lists, linked @cpindex Linked lists -In the header file @file{<libmdsserver/linked-list.h>}, -libmdsserver defines a linear array sentinel doubly -linked list. +In the header file +@file{<libmdsserver/linked-list.h>}, libmdsserver +defines a linear array sentinel doubly linked list. @item @code{hash_table_t} @{also known as @code{struct hash_table}@} @tpindex @code{hash_table_t} @@ -5665,24 +5663,25 @@ libmdsserver defines a hash table. @cpindex File descriptor table In the header file @file{<libmdsserver/fd-table.h>}, libmdsserver defines a lookup table for small -positive integer keys, intended as an alternative -to hash tables for file descriptors as keys. +positive integer keys, intended as an alternative to +hash tables for file descriptors as keys. @item @code{mds_message_t} @{also known as @code{struct mds_message}@} @tpindex @code{mds_message_t} @tpindex @code{struct mds_message} @cpindex Message passing, data structure -In the header file @file{<libmdsserver/mds-message.h>}, -libmdsserver defines a data structure for message -between the server or client and the master server, -with the capability of reading for a socket. +In the header file +@file{<libmdsserver/mds-message.h>}, libmdsserver +defines a data structure for message between the +server or client and the master server, with the +capability of reading for a socket. @end table These data structures share a common set of associated function. However, they do not use the same functions; they are identical except they are are named with the -associated data structure. We will use @code{X_t} -as an example. +associated data structure. We will use @code{X_t} as +an example. @table @asis @item @code{X_destroy} [(@code{X_t* restrict this}) @arrow{} @code{void}] @@ -5692,8 +5691,8 @@ as an example. @fnindex @code{fd_table_destroy} @fnindex @code{mds_message_destroy} @cpindex Memory management -Releases all resouces in @code{*this}, -@code{this} itself is however not @code{free}:d. +Releases all resouces in @code{*this}, @code{this} +itself is however not @code{free}:d. However, @code{hash_table_destory} and @code{fd_table_destory} have another signature. @@ -5705,8 +5704,8 @@ However, @code{hash_table_destory} and @fnindex @code{fd_table_clone} @fnindex @code{mds_message_clone} @cpindex Memory management -Create a deep duplicate of @code{*this} and store -it in @code{*out}. +Create a deep duplicate of @code{*this} and store it +in @code{*out}. @item @code{X_marshal_size} [(@code{const X_t* restrict this}) @arrow{} @code{size_t}] @fnindex @code{client_list_marshal_size} @@ -5722,10 +5721,9 @@ it in @code{*out}. @cpindex Version update @sgindex @code{SIGUSR1} @sgindex @code{SIGUPDATE} -Calculates the exact allocate size needed for -the parameter @code{data} in the function -@code{X_marshal} if called with the same -@code{this} parameter. +Calculates the exact allocate size needed for the +parameter @code{data} in the function @code{X_marshal} +if called with the same @code{this} parameter. @item @code{X_marshal} [(@code{const X_t* restrict this, char* restrict data}) @arrow{} @code{void}] @fnindex @code{client_list_marshal} @@ -5741,10 +5739,10 @@ the parameter @code{data} in the function @cpindex Version update @sgindex @code{SIGUSR1} @sgindex @code{SIGUPDATE} -Marshal the state of @code{*this} into -@code{data}. The number of bytes that -will be stored (contiguously) in @code{data} -can be calculated with @code{X_marshal_size}. +Marshal the state of @code{*this} into @code{data}. +The number of bytes that will be stored (contiguously) +in @code{data} can be calculated with +@code{X_marshal_size}. @item @code{X_unmarshal} [(@code{X_t* restrict this, char* restrict data)}) @arrow{} @code{int}] @fnindex @code{client_list_unmarshal} @@ -5760,13 +5758,12 @@ can be calculated with @code{X_marshal_size}. @cpindex Version update @sgindex @code{SIGUSR1} @sgindex @code{SIGUPDATE} -Unmarshal a @code{X_t} from -@code{data} into @code{*this}. Returns -zero on success and @code{-1} on error. -The number of bytes read from @code{data} -should, if required, have been precalculated -with @code{X_marshal_size} and stored in an -earlier location of @code{data}. +Unmarshal a @code{X_t} from @code{data} into +@code{*this}. Returns zero on success and @code{-1} +on error. The number of bytes read from @code{data} +should, if required, have been precalculated with +@code{X_marshal_size} and stored in an earlier +location of @code{data}. However, @code{hash_table_unmarshal} and @code{fd_table_unmarshal} have another signature. @@ -5791,42 +5788,41 @@ However, @code{hash_table_unmarshal} and @cpindex Lists of client ID:s @fnindex @code{client_list_create} To create a client list, allocate a -@code{client_list_t*} or otherwise obtain -a @code{client_list_t*}, and call -@code{client_list_create} with that -pointer as the first argument, and -the @code{0} as the second argument, -unless you want to tune the initialisation. -@code{client_list_create} will return -zero on and only on successful initialisation. -@code{client_list_create}'s second parameter ---- @code{size_t capacity} --- can be used -to specify how many element the list should -initially fit. It will grow when needed, but -it is a good idea to tell it how many elements -you are planning to populate it with. - -@code{client_list_t} has two associated -functions for manipulating its content: +@code{client_list_t*} or otherwise obtain a +@code{client_list_t*}, and call +@code{client_list_create} with that pointer as the +first argument, and the @code{0} as the second +argument, unless you want to tune the initialisation. +@code{client_list_create} will return zero on and +only on successful initialisation. +@code{client_list_create}'s second parameter --- +@code{size_t capacity} --- can be used to specify how +many element the list should initially fit. It will +grow when needed, but it is a good idea to tell it +how many elements you are planning to populate it +with. + +@code{client_list_t} has two associated functions for +manipulating its content: @table @asis @item @code{client_list_add} [(@code{client_list_t* restrict this, uint64_t client}) @arrow{} @code{int}] @fnindex @code{client_list_add} -This function will add the element @code{client} -to the list @code{*this}, and return zero on -and only on success. +This function will add the element @code{client} to +the list @code{*this}, and return zero on and only on +success. @item @code{client_list_remove} [(@code{client_list_t* restrict this, uint64_t client}) @arrow{} @code{void}] @fnindex @code{client_list_remove} This function will remove exactly one occurrence, -provided that there is at least on occurrence, -of the element @code{client} for the list @code{*this}. +provided that there is at least on occurrence, of the +element @code{client} for the list @code{*this}. @end table -To retrieve the number elements stored in -a list, reads its variable @code{size_t size}. -The variable @code{uint64_t* clients} is -used to retrieve stored elements. +To retrieve the number elements stored in a list, +reads its variable @code{size_t size}. The variable +@code{uint64_t* clients} is used to retrieve stored +elements. @ifset AFOURPAPER_OR_USLETTER_OR_SMALLBOOK_WITH_SMALLFONT @example @@ -5871,26 +5867,28 @@ three arrays: The value stored in each node. @item @code{next} [@code{ssize_t*}] -The next node for each node, @code{edge} if the current -node is the last node, and @code{LINKED_LIST_UNUSED} if -there is no node on this position. +The next node for each node, @code{edge} if the +current node is the last node, and +@code{LINKED_LIST_UNUSED} if there is no node on this +position. @item @code{previous} [@code{ssize_t*}] -The previous node for each node, @code{edge} if the current -node is the first node, and @code{LINKED_LIST_UNUSED} if -there is no node on this position. +The previous node for each node, @code{edge} if the +current node is the first node, and +@code{LINKED_LIST_UNUSED} if there is no node on this +position. @end table -The linked list has a sentinel node that joins -boths ends of the list. The index of this node -is stored in the variable @code{edge}. +The linked list has a sentinel node that joins boths +ends of the list. The index of this node is stored in +the variable @code{edge}. @cpindex Memory management @fnindex @code{linked_list_pack} Because the list is implemented using arrays, if the number of elements in it shinks considerably, it will -not be able to automatically free unused space. Instead -you must call @code{linked_list_pack}: +not be able to automatically free unused space. +Instead you must call @code{linked_list_pack}: @table @asis @item @code{linked_list_pack} [(@code{linked_list_t* restrict this}) @arrow{} @code{int}] @@ -5899,44 +5897,46 @@ and reduce the capacity to the smallest capacity that can be used. Note that values (nodes) returned by the list's methods will become invalid. Additionally (to reduce the complexity) the list will be defragment so -that the nodes' indices are continuous. This method has -linear time complexity and linear memory complexity. +that the nodes' indices are continuous. This method +has linear time complexity and linear memory +complexity. @end table @fnindex @code{linked_list_create} To create a linked list list, allocate a -@code{linked_list_t*} or otherwise obtain -a @code{linked_list_t*}, and call -@code{linked_list_create} with that -pointer as the first argument, and -the @code{0} as the second argument, -unless you want to tune the initialisation. -@code{linked_list_create} will return -zero on and only on successful initialisation. -@code{linked_list_create}'s second parameter ---- @code{size_t capacity} --- can be used -to specify how many element the list should -initially fit. It will grow when needed, but -it is a good idea to tell it how many elements -you are planning to populate it with. - -There are five functions adding and removing -items to and from a linked list: +@code{linked_list_t*} or otherwise obtain a +@code{linked_list_t*}, and call +@code{linked_list_create} with that pointer as the +first argument, and the @code{0} as the second +argument, unless you want to tune the initialisation. +@code{linked_list_create} will return zero on and +only on successful initialisation. +@code{linked_list_create}'s second parameter --- +@code{size_t capacity} --- can be used to specify how +many element the list should initially fit. It will +grow when needed, but it is a good idea to tell it +how many elements you are planning to populate it +with. + +There are five functions adding and removing items to +and from a linked list: @table @asis @item @code{linked_list_insert_after} [(@code{this, size_t value, ssize_t predecessor}) @arrow{} @code{ssize_t}] @fnindex @code{linked_list_insert_after} -Create a new node with the value @code{value} and add it -to the list @code{*this} after the node @code{predecessor}. -On success, the new node is returned, on failure -@code{LINKED_LIST_UNUSED} is returned. +Create a new node with the value @code{value} and add +it to the list @code{*this} after the node +@code{predecessor}. On success, the new node is +returned, on failure @code{LINKED_LIST_UNUSED} is +returned. @item @code{linked_list_insert_before} [(@code{this, size_t value, ssize_t successor}) @arrow{} @code{ssize_t}] @fnindex @code{linked_list_insert_before} -Create a new node with the value @code{value} and add it -to the list @code{*this} before the node @code{successor}. -On success, the new node is returned, on failure -@code{LINKED_LIST_UNUSED} is returned. +Create a new node with the value @code{value} and add +it to the list @code{*this} before the node +@code{successor}. On success, the new node is +returned, on failure @code{LINKED_LIST_UNUSED} is +returned. @item @code{linked_list_remove_after} [(@code{this, ssize_t predecessor}) @arrow{} @code{ssize_t}] @fnindex @code{linked_list_remove_after} @@ -5950,7 +5950,8 @@ directly before the node @code{predecessor}. @item @code{linked_list_remove} [(@code{this, ssize_t node}) @arrow{} @code{void}] @fnindex @code{linked_list_remove} -Remove the node @code{node} from the list @code{*this}. +Remove the node @code{node} from the list +@code{*this}. @end table The data type for @code{this} is @code{linked_list_t*} @@ -5968,8 +5969,8 @@ behaviour. @file{<libmdsserver/linked_list.h>} defines two macros for inserting nodes at the edges of a linked -list and two macros for removing nodes from the -edges of a linked list: +list and two macros for removing nodes from the edges +of a linked list: @table @asis @item @code{linked_list_insert_beginning} [(@code{linked_list_t* this, size_t value}) @arrow{} @code{ssize_t}] @@ -5982,25 +5983,24 @@ On success, the new node is returned, on failure @item @code{linked_list_insert_end} [(@code{linked_list_t* this, size_t value}) @arrow{} @code{ssize_t}] @fnindex @code{linked_list_insert_end} Create a new node with the value @code{value} in -insert it to the end of the list @code{*this}. -On success, the new node is returned, on failure +insert it to the end of the list @code{*this}. On +success, the new node is returned, on failure @code{LINKED_LIST_UNUSED} is returned. @item @code{linked_list_remove_beginning} [(@code{linked_list_t* this}) @arrow{} @code{ssize_t}] @fnindex @code{linked_list_remove_beginning} -Remove and return the first node in the -list @code{*this}. +Remove and return the first node in the list +@code{*this}. @item @code{linked_list_remove_end} [(@code{linked_list_t* this}) @arrow{} @code{ssize_t}] @fnindex @code{linked_list_remove_end} -Remove and return the node node in the -list @code{*this}. +Remove and return the node node in the list +@code{*this}. @end table -Additionally the library defines a macro that -wrappes the @code{for} keyword to iterate over -all nodes (except the sentinel node) the a -linked list: +Additionally the library defines a macro that wrappes +the @code{for} keyword to iterate over all nodes +(except the sentinel node) the a linked list: @table @asis @item @code{foreach_linked_list_node} [(@code{linked_list_t this, ssize_t node})] @@ -6019,8 +6019,8 @@ void print_linked_list_values(linked_list_t* list) @} @end example -Note that the data type for @code{this} in the -macro is not a pointer. +Note that the data type for @code{this} in the macro +is not a pointer. @end table There is also a function intended for debugging: @@ -6028,8 +6028,8 @@ There is also a function intended for debugging: @table @asis @item @code{linked_list_dump} [(@code{linked_list_t* restrict this, FILE* restrict output}) @arrow{} @code{void}] @fnindex @code{linked_list_dump} -The all internal data of the list @code{*this} -into the stream @code{output}. +The all internal data of the list @code{*this} into +the stream @code{output}. @end table @@ -6050,16 +6050,15 @@ into the stream @code{output}. @cpindex Dictionary, hash @cpindex Hash table libmdsserver defines two similar data structures: -@code{fd_table_t} and @code{hash_table_t}. Whenever -a function exists for both data structures we will +@code{fd_table_t} and @code{hash_table_t}. Whenever a +function exists for both data structures we will write @code{X_table} instead of @code{fd_table} and @code{hash_table}. Additionally, unless otherwise -stated, a function's parameter named @code{this} -will be of the type @code{hash_table_t*} if the -function's name start with @code{hash_table} and -@code{fd_table_t*} if the function's name start -with @code{fd_table}, with the @code{restrict} -modifier. +stated, a function's parameter named @code{this} will +be of the type @code{hash_table_t*} if the function's +name start with @code{hash_table} and +@code{fd_table_t*} if the function's name start with +@code{fd_table}, with the @code{restrict} modifier. @table @asis @item @code{X_table_create} [(@code{this}) @arrow{} @code{int}] @@ -6075,8 +6074,8 @@ These functions are defined as macros. @fnindex @code{fd_table_create_tuned} Initialises @code{*this} so it can be used as a table, and makes its initial capacity at least -@code{initial_capacity}. Returns zero on and only -on success. +@code{initial_capacity}. Returns zero on and only on +success. @code{hash_table_create_tuned} is defined as a macro. @@ -6085,25 +6084,25 @@ on success. Initialises @code{*this} so it can be used as a table, and makes its initial capacity at least @code{initial_capacity} and its load factor -@code{load_factor}. Returns zero on and only -on success. +@code{load_factor}. Returns zero on and only on +success. @item @code{X_table_destroy} [(@code{this, free_func* key_freer, free_func* value_freer}) @arrow{} @code{void}] @fnindex @code{hash_table_destroy} @fnindex @code{fd_table_destroy} -Release all resources in the table @code{*this}, -but do not @code{free} @code{this} itself. -Should be called even if construction fails. -If @code{keys_freer} is not @code{NULL}, this -function will be called for each key. -If @code{values_freer} is not @code{NULL}, this -function will be called for each value. +Release all resources in the table @code{*this}, but +do not @code{free} @code{this} itself. Should be +called even if construction fails. If +@code{keys_freer} is not @code{NULL}, this function +will be called for each key. If @code{values_freer} +is not @code{NULL}, this function will be called for +each value. @item @code{X_table_contains_value} [(@code{const this, size_t value}) @arrow{} @code{int}] @fnindex @code{hash_table_contains_value} @fnindex @code{fd_table_contains_value} -Check whether the value @code{value} is stored -in the table @code{*this}. +Check whether the value @code{value} is stored in the +table @code{*this}. @item @code{X_table_contains_key} [(@code{const this, key}) @arrow{} @code{int}] @fnindex @code{hash_table_contains_key} @@ -6118,25 +6117,25 @@ for @code{fd_table}. @item @code{X_table_get} [(@code{const this, key}) @arrow{} @code{size_t}] @fnindex @code{hash_table_get} @fnindex @code{fd_table_get} -Look up a value by its key @code{key} in the -table @code{*this}. Zero will be returned if -the key was not used. +Look up a value by its key @code{key} in the table +@code{*this}. Zero will be returned if the key was +not used. @item @code{hash_table_get_entry} [(@code{const this, size_t key}) @arrow{} @code{hash_entry_t*}] @fnindex @code{hash_table_get_entry} -Look up an entry by its key @code{key} in the -table @code{*this}. @code{NULL} will be returned -if the key was not used. +Look up an entry by its key @code{key} in the table +@code{*this}. @code{NULL} will be returned if the key +was not used. @item @code{X_table_put} [(@code{this, key, size_t value}) @arrow{} @code{size_t}] @fnindex @code{hash_table_put} @fnindex @code{fd_table_put} -Map the value @code{value} to the key @code{key} -in the talbe @code{*this}. If a value was already -mapped to the key, that value will be returned, -otherwise zero will be returned. Zero will also -be returned on error. @code{errno} will be set to -zero on and only on success. +Map the value @code{value} to the key @code{key} in +the talbe @code{*this}. If a value was already mapped +to the key, that value will be returned, otherwise +zero will be returned. Zero will also be returned on +error. @code{errno} will be set to zero on and only +on success. The data type for the parameter @code{key} is @code{size_t} for @code{hash_table} and @code{int} @@ -6146,8 +6145,8 @@ for @code{fd_table}. @fnindex @code{hash_table_remove} @fnindex @code{fd_table_remove} Unmaps the key @code{key} for the table @code{*this}. -If a value was mapped to the key, that value will -be returned, otherwise zero will be returned. +If a value was mapped to the key, that value will be +returned, otherwise zero will be returned. The data type for the parameter @code{key} is @code{size_t} for @code{hash_table} and @code{int} @@ -6163,23 +6162,22 @@ Unmaps all keys in the table @code{*this}. @fnindex @code{fd_table_unmarshal} As described in @ref{Data Structures} but with one additional parameter: @code{remapper}. If this -parameter is not @code{NULL} this function is used -to edit values. It will be called once for each -value and the output of the function will be used -inplace of the input value. +parameter is not @code{NULL} this function is used to +edit values. It will be called once for each value +and the output of the function will be used inplace +of the input value. @end table -@file{<libmdsserver/hash-table.h>} also defines -as wrapper macro for the @code{for} keyword: +@file{<libmdsserver/hash-table.h>} also defines as +wrapper macro for the @code{for} keyword: @table @asis @item @code{foreach_hash_table_entry} [(@code{hash_table_t this, size_t i, hash_entry_t* entry})] @fnindex @code{foreach_hash_table_entry} Iterates over entry element in the hash table -@code{*this}. On each iteration, the entry will -be stored to the variable @code{entry} and the -bucket index will be stored to the variable -@code{i}. +@code{*this}. On each iteration, the entry will be +stored to the variable @code{entry} and the bucket +index will be stored to the variable @code{i}. @ifset AFOURPAPER_OR_USLETTER_OR_SMALLBOOK_WITH_SMALLFONT @example @@ -6212,15 +6210,17 @@ is not a popinter. @vrindex @code{value_comparator} @vrindex @code{hash_table_t.value_comparator} @vrindex @code{fd_table_t.value_comparator} -The structures @code{hash_table_t} and @code{fd_table_t} -contain the variable @code{value_comparator} which by -default is @code{NULL}@. If this variable is set to @code{NULL}, -two values will be considered equal if and only if they are -numerically identical; otherwise two values will be considered -equal if and only if @code{value_comparator} returned a -non-zero value if those two values are used for the function's -arguments. The data type for @code{value_comparator} is -@code{compare_func*}. +The structures @code{hash_table_t} and +@code{fd_table_t} contain the variable +@code{value_comparator} which by default is +@code{NULL}@. If this variable is set to @code{NULL}, +two values will be considered equal if and only if +they are numerically identical; otherwise two values +will be considered equal if and only if +@code{value_comparator} returned a non-zero value if +those two values are used for the function's +arguments. The data type for @code{value_comparator} +is @code{compare_func*}. @code{hash_table_t} also contains two other variables: @@ -6228,23 +6228,25 @@ arguments. The data type for @code{value_comparator} is @item @code{key_comparator} [@code{compare_func*}] @vrindex @code{ket_comparator} @vrindex @code{hash_table_t.ket_comparator} -Identical to @code{value_comparator}, except it is used for -keys rather the values. +Identical to @code{value_comparator}, except it is +used for keys rather the values. @item @code{hasher} [@code{hash_func*}] @vrindex @code{hasher} @vrindex @code{hash_table_t.hasher} -By default, the hash value for key is identical to the key -itself. However, if this variable is not @code{NULL}, it -will be used to calculate the hash value for keys. +By default, the hash value for key is identical to +the key itself. However, if this variable is not +@code{NULL}, it will be used to calculate the hash +value for keys. @end table @tpindex @code{hash_entry_t} @tpindex @code{struct hash_entry} -There is a secondary data structure defined for hash tables: -@code{hash_entry_t} @{also known as @code{struct hash_entry}@}. -It is the data structure used for entries in a hash table. -@code{hash_entry_t} contain three variables you may be interested in: +There is a secondary data structure defined for hash +tables: @code{hash_entry_t} @{also known as +@code{struct hash_entry}@}. It is the data structure +used for entries in a hash table. @code{hash_entry_t} +contain three variables you may be interested in: @table @asis @item @code{key} [@code{size_t}] @@ -6258,8 +6260,9 @@ The hash value of the key. @end table By inclusion of @file{<libmdsserver/table-common.h>}, -@file{<libmdsserver/hash-table.h>} and @file{<libmdsserver/fd-table.h>} -defines four @code{typedef}:s for function signatures: +@file{<libmdsserver/hash-table.h>} and +@file{<libmdsserver/fd-table.h>} defines four +@code{typedef}:s for function signatures: @table @asis @item @code{compare_func} [(@code{size_t a, size_t b}) @arrow{} @code{int}] @@ -6271,8 +6274,8 @@ context. @item @code{hash_func} [(@code{size_t value}) @arrow{} @code{size_t}] @tpindex @code{hash_func} -A function that hashes an object or a value. -Should return the hash value for @code{value}. +A function that hashes an object or a value. Should +return the hash value for @code{value}. @item @code{free_func} [(@code{size_t obj}) @arrow{} @code{void}] @tpindex @code{free_func} @@ -6283,28 +6286,32 @@ releases the object @code{obj}'s resources and @item @code{remap_func} [(@code{size_t obj}) @arrow{} @code{size_t}] @tpindex @code{remap_func} A function that translates a object into a new object. -The function should return new object that should replace -the object @code{obj}. +The function should return new object that should +replace the object @code{obj}. @end table If you are working with strings, you may consider -including the header file @file{<libmdsserver/hash-help.h>}. -It defines to useful functions: +including the header file +@file{<libmdsserver/hash-help.h>}. It defines to +useful functions: @table @asis @item @code{string_hash} [(@code{const char* str}) @arrow{} @code{size_t}] @fnindex @code{string_hash} -Calculate and returns the hash value of the string @code{str}. +Calculate and returns the hash value of the string +@code{str}. @item @code{string_comparator} [(@code{char* str_a, char* str_b}) @arrow{} @code{int}] @fnindex @code{string_comparator} @cpindex String comparison -Returns non-zero if either both @code{str_a} and @code{str_b} -are @code{NULL} or neither are @code{NULL} but are identical -strings by content upto their first NUL characters (or by address). +Returns non-zero if either both @code{str_a} and +@code{str_b} are @code{NULL} or neither are +@code{NULL} but are identical strings by content upto +their first NUL characters (or by address). @end table -These functions are defined as pure and @code{static inline}. +These functions are defined as pure and +@code{static inline}. @@ -6314,35 +6321,35 @@ These functions are defined as pure and @code{static inline}. @tpindex @code{mds_message_t} @tpindex @code{struct mds_message} @cpindex Message passing, data structure -Apart from internal data @code{mds_message_t} contains four -variables: +Apart from internal data @code{mds_message_t} +contains four variables: @table @asis @item @code{headers} [@code{char**}] The headers in the message, each element in this list as an unparsed header, it consists of both the header -name and its associated value, joined by `: '. A header -cannot be @code{NULL} (unless its memory allocation failed,) -but @code{headers} itself is @code{NULL} if there are -no headers. The `Length' header should be included in -this list. +name and its associated value, joined by `: '. A +header cannot be @code{NULL} (unless its memory +allocation failed,) but @code{headers} itself is +@code{NULL} if there are no headers. The `Length' +header should be included in this list. @item @code{header_count} [@code{size_t}] The number of headers in the message. @item @code{payload} [@code{char*}] -The payload of the message, @code{NULL} if -none (of zero-length). +The payload of the message, @code{NULL} if none (of +zero-length). @item @code{payload_size} [@code{size_t}] -The length of the message's payload. -This value will be the same as the value -of the `Length' header. +The length of the message's payload. This value will +be the same as the value of the `Length' header. @end table -There are six functions specific to @code{mds_message_t}. -The @code{this}-parameter's data type for this functions -are @code{mds_message_t*} with the @code{restrict} modifier. +There are six functions specific to +@code{mds_message_t}. The @code{this}-parameter's +data type for this functions are @code{mds_message_t*} +with the @code{restrict} modifier. @table @asis @item @code{mds_message_initialise} [(@code{this}) @arrow{} @code{int}] @@ -6354,27 +6361,29 @@ using @code{mds_message_destroy}. @item @code{mds_message_zero_initialise} [(@code{this}) @arrow{} @code{void}] @fnindex @code{mds_message_zero_initialise} -This function is similar to @code{mds_message_initialise}, -however it cannot fail and thus have no return value. -The difference it is action is that it will not allocate -an internal buffer. +This function is similar to +@code{mds_message_initialise}, however it cannot fail +and thus have no return value. The difference it is +action is that it will not allocate an internal +buffer. @item @code{mds_message_extend_headers} [(@code{this, size_t extent}) @arrow{} @code{int}] @fnindex @code{mds_message_extend_headers} -Ensures that @code{extent} additional headers can -be stored in the @code{*this}. Returns zero on -and only on success. +Ensures that @code{extent} additional headers can be +stored in the @code{*this}. Returns zero on and only +on success. @item @code{mds_message_read} [(@code{this, int fd}) @arrow{} @code{int}] @fnindex @code{mds_message_read} Reads the next message from the socket file descriptor @code{fd} and stores it in @code{*this}. Returns zero -on success and non-zero on error or interruption. @code{*this} -should be destroyed using @code{mds_message_destroy} on -error but not on interruption. If @code{-2} is returned -@code{errno} will not have been set; @code{-2} indicates -that the message is malformated, which is a state that -cannot be recovered from. +on success and non-zero on error or interruption. +@code{*this} should be destroyed using +@code{mds_message_destroy} on error but not on +interruption. If @code{-2} is returned @code{errno} +will not have been set; @code{-2} indicates that the +message is malformated, which is a state that cannot +be recovered from. @item @code{mds_message_compose_size} [(@code{const this}) @arrow{} @code{size_t}] @fnindex @code{mds_message_compose_size} @@ -6384,10 +6393,11 @@ This function is to @code{mds_message_compose} as @item @code{mds_message_compose} [(@code{const this, char* restrict data}) @arrow{} @code{void}] @fnindex @code{mds_message_compose} -This function is similar to @code{mds_message_marshal}. -The only difference is that it will not store internal -data and instead create a message that can be broadcasted -in the display server message passing system. +This function is similar to +@code{mds_message_marshal}. The only difference is +that it will not store internal data and instead +create a message that can be broadcasted in the +display server message passing system. @end table @@ -6402,8 +6412,8 @@ filepair whose purpose is similar to libmdsserver. servers and implements common procedures including @code{main}. It also complements procedures that are weakly defined, that is, if the server implementation -also defines them, the server implementations procedure -replaces @file{mds-base}'s implementation at +also defines them, the server implementations +procedure replaces @file{mds-base}'s implementation at compile-time. @file{mds-base} defines one function that you can @@ -6414,8 +6424,8 @@ be implement depending on specified conditions: @item @code{trap_signals} [(@code{void}) @arrow{} @code{int}] @fnindex @code{trap_signals} @cpindex Signals -Set up signal traps for all especially handled signals. -Returns zero on and only on success. +Set up signal traps for all especially handled +signals. Returns zero on and only on success. @end table @file{mds-base} weakly defines functions that you can @@ -6426,8 +6436,8 @@ replace if they do not suit your needs: @fnindex @code{parse_cmdline} @cpindex Parse command line @cpindex Command line, parse -Parses command line arguments. -Returns zero on and only on success. +Parses command line arguments. Returns zero on and +only on success. This function will parse the following options: @@ -6448,8 +6458,8 @@ The server is re-executing. @item --alarm=SECONDS @opindex @option{--alarm} @sgindex @code{SIGALRM} -Kill the process after @var{SECONDS} seconds. -At most one minute. +Kill the process after @var{SECONDS} seconds. At most +one minute. @item --on-init-fork @opindex @option{--on-init-fork} @@ -6458,21 +6468,21 @@ the server has been initialised. @item --on-init-sh=COMMAND @opindex @option{--on-init-sh} -When the server has been initialised, run the -command @var{COMMAND}@. +When the server has been initialised, run the command +@var{COMMAND}@. @item --immortal @opindex @option{--immortal} The server should do its best not to die. For example -do not die if @code{SIGDANGER} is received even if that -is the server's default action. +do not die if @code{SIGDANGER} is received even if +that is the server's default action. @end table @item @code{connect_to_display} [(@code{void}) @arrow{} @code{int}] @fnindex @code{connect_to_display} @cpindex Connecting to the display -Connects to the display. -Returns zero on and only on success. +Connects to the display. Returns zero on and only on +success. @item @code{server_initialised} [(@code{void}) @arrow{} @code{int}] @fnindex @code{server_initialised} @@ -6487,10 +6497,10 @@ Returns zero on and only on success. @cpindex Signals, multi-threading @cpindex Multi-threading, signals @cpindex Treading, signals -This function should be implemented by the actual server -implementation if the server is multi-threaded. It sends -the singal @code{signo} to all threads except the current -thread. +This function should be implemented by the actual +server implementation if the server is multi-threaded. +It sends the singal @code{signo} to all threads +except the current thread. @item @code{received_danger} [(@code{int signo}) @arrow{} @code{void}] @fnindex @code{received_danger} @@ -6504,12 +6514,13 @@ thread. @cpindex Releasing memory @vrindex @code{danger} This function is called when a signal that signals the -system is running out of memory has been received. The exact -received signal is specified by the parameter @code{signo}. -When this function is invoked, the server should free up -all memory it can spare. When this function is invoked, it -should set the variable @code{danger} to a non-zero value. -If @code{server_characteristics.danger_is_deadly} is set, +system is running out of memory has been received. +The exact received signal is specified by the +parameter @code{signo}. When this function is +invoked, the server should free up all memory it can +spare. When this function is invoked, it should set +the variable @code{danger} to a non-zero value. If +@code{server_characteristics.danger_is_deadly} is set, this function will never be called. @item @code{received_reexec} [(@code{int signo}) @arrow{} @code{void}] @@ -6524,9 +6535,10 @@ this function will never be called. @sgindex @code{SIGUPDATE} This function is called when a signal that signals the server to re-execute has been received. The exact -received signal is specified by the parameter @code{signo}. -When this function is invoked, it should set the variables -@code{reexecing} and @code{terminating} to a non-zero value. +received signal is specified by the parameter +@code{signo}. When this function is invoked, it +should set the variables @code{reexecing} and +@code{terminating} to a non-zero value. @item @code{received_terminate} [(@code{int signo}) @arrow{} @code{void}] @fnindex @code{received_terminate} @@ -6535,10 +6547,11 @@ When this function is invoked, it should set the variables @sgindex @code{SIGTERM} @sgindex @code{SIGINT} This function is called when a signal that signals the -server to terminate has been received. The exact received -signal is specified by the parameter @code{signo}. When -this function is invoked, it should set the variable -@code{terminating} to a non-zero value. +server to terminate has been received. The exact +received signal is specified by the parameter +@code{signo}. When this function is invoked, it +should set the variable @code{terminating} to a +non-zero value. @item @code{received_info} [(@code{int signo}) @arrow{} @code{void}] @fnindex @code{received_info} @@ -6546,27 +6559,28 @@ this function is invoked, it should set the variable @cpindex State dump @cpindex Statistics dump This function is called when a signal that signals the -server to dump state information and statistics has been -received. The exact received signal is specified by the -parameter @code{signo}. +server to dump state information and statistics has +been received. The exact received signal is specified +by the parameter @code{signo}. @item @code{fork_cleanup} [(@code{int status}) @arrow{} @code{void}] @fnindex @code{fork_cleanup} @vrindex @code{server_characteristics.fork_for_safety} @vrindex @code{fork_for_safety} @cpindex Initialisation -This function should be implemented by the actual server -implementation if the server has set +This function should be implemented by the actual +server implementation if the server has set @code{server_characteristics.fork_for_safety} to be a -non-zero value. This function is called by the parent server -process when the child server process exits, if the server -has completed its initialisation. The parameter @code{status} -specifies the child process exit status as returned by -@code{waitpid}. +non-zero value. This function is called by the parent +server process when the child server process exits, +if the server has completed its initialisation. The +parameter @code{status} specifies the child process +exit status as returned by @code{waitpid}. @end table -Additionally, @file{mds-base} expects the server implementation -to define and implement a set of functions: +Additionally, @file{mds-base} expects the server +implementation to define and implement a set of +functions: @table @asis @item @code{preinitialise_server} [(@code{void}) @arrow{} @code{int}] @@ -6574,24 +6588,27 @@ to define and implement a set of functions: @fnindex @code{initialise_server} @fnindex @code{unmarshal_server} @cpindex Initialisation -This function will be invoked before @code{initialise_server} -(if not re-executing) or before @code{unmarshal_server} -(if not re-executing). Returns zero on and only on success. +This function will be invoked before +@code{initialise_server} (if not re-executing) or +before @code{unmarshal_server} (if not re-executing). +Returns zero on and only on success. @item @code{initialise_server} [(@code{void}) @arrow{} @code{int}] @fnindex @code{initialise_server} @cpindex Initialisation -This function should initialise the server. It not invoked -after a re-execution. Returns zero on and only on success. +This function should initialise the server. It not +invoked after a re-execution. Returns zero on and +only on success. @item @code{postinitialise_server} [(@code{void}) @arrow{} @code{int}] @fnindex @code{postinitialise_server} @fnindex @code{initialise_server} @fnindex @code{unmarshal_server} @cpindex Initialisation -This function will be invoked after @code{initialise_server} -(if not re-executing) or after @code{unmarshal_server} (if -re-executing). Returns zero on and only on success. +This function will be invoked after +@code{initialise_server} (if not re-executing) or +after @code{unmarshal_server} (if re-executing). +Returns zero on and only on success. @item @code{marshal_server_size} [(@code{void}) @arrow{} @code{size_t}, pure] @fnindex @code{marshal_server_size} @@ -6602,12 +6619,14 @@ re-executing). Returns zero on and only on success. @cpindex Version update @sgindex @code{SIGUSR1} @sgindex @code{SIGUPDATE} -Calculate and returns the number of bytes that will be stored -by @code{marshal_server}. On failure the server should call -@code{abort} or exit with failure status by other means. -However it should not be possible for this function to fail. -@code{marshal_server_size} must be pure@footnote{That is, -define with and conforming to @code{__attribute__((pure))}.}. +Calculate and returns the number of bytes that will +be stored by @code{marshal_server}. On failure the +server should call @code{abort} or exit with failure +status by other means. However it should not be +possible for this function to fail. +@code{marshal_server_size} must be pure@footnote{That +is, define with and conforming to +@code{__attribute__((pure))}.}. @item @code{marshal_server} [(@code{char* state_buf}) @arrow{} @code{int}] @fnindex @code{marshal_server} @@ -6617,8 +6636,9 @@ define with and conforming to @code{__attribute__((pure))}.}. @cpindex Version update @sgindex @code{SIGUSR1} @sgindex @code{SIGUPDATE} -Marshal server implementation specific data into the buffer -@code{state_buf}. Returns zero on and only on success. +Marshal server implementation specific data into the +buffer @code{state_buf}. Returns zero on and only on +success. @item @code{unmarshal_server} [(@code{char* state_buf}) @arrow{} @code{int}] @fnindex @code{unmarshal_server} @@ -6633,11 +6653,12 @@ buffer @code{state_buf} and update the servers state accordingly. Returns zero on and only on success. @fnindex @code{reexec_failure_recover} -On critical failure the program should call @code{abort} -or exit with failure status by other means. That is, do not -let @code{reexec_failure_recover} run successfully, if it -unrecoverable error has occurred or one severe enough that -it is better to simply respawn. +On critical failure the program should call +@code{abort} or exit with failure status by other +means. That is, do not let +@code{reexec_failure_recover} run successfully, if it +unrecoverable error has occurred or one severe enough +that it is better to simply respawn. @item @code{reexec_failure_recover} [(@code{void}) @arrow{} @code{int}] @fnindex @code{reexec_failure_recover} @@ -6647,17 +6668,20 @@ it is better to simply respawn. @cpindex Version update @sgindex @code{SIGUSR1} @sgindex @code{SIGUPDATE} -Attempt to recover from a re-execution failure that has been -detected after the server successfully updated it execution -image. Returns zero on and only on success. +Attempt to recover from a re-execution failure that +has been detected after the server successfully +updated it execution image. Returns zero on and only +on success. @item @code{master_loop} [(@code{void}) @arrow{} @code{int}] @fnindex @code{master_loop} @cpindex Initialisation -Perform the server's mission. Returns zero on and only on success. +Perform the server's mission. Returns zero on and +only on success. @end table -@file{mds-base} also defines a number of global variables. +@file{mds-base} also defines a number of global +variables. @table @asis @item @code{argc} [@code{int}] @@ -6687,7 +6711,8 @@ as @code{is_reexec}. @cpindex Version update @sgindex @code{SIGUSR1} @sgindex @code{SIGUPDATE} -Whether the server is continuing from a self-reexecution. +Whether the server is continuing from a +self-reexecution. @item @code{is_immortal} [@code{int}] @vrindex @code{is_immortal} @@ -6735,7 +6760,8 @@ Whether the server has been signaled to re-execute. @cpindex Automated memory release @cpindex Forcing memory release @cpindex Releasing memory -Whether the server has been signaled to free unneeded memory. +Whether the server has been signaled to free unneeded +memory. @item @code{socket_fd} [@code{int}] @vrindex @code{socket_fd} @@ -6745,26 +6771,26 @@ to the server. @end table @cpindex Server characteristics -@file{mds-base} expects the server implementation to define -a variable that specifies how @file{mds-base} should behave: +@file{mds-base} expects the server implementation to +define a variable that specifies how @file{mds-base} +should behave: @table @asis @item @code{server_characteristics} [@code{server_characteristics_t}] @vrindex @code{server_characteristics} This variable should declared by the actual server -implementation. It must be configured before @code{main} -is invoked. That is, it should be configured by a -constructor. If it is configured at its definition, -it is configured by a constructor; that is normally -how you want to configured it. +implementation. It must be configured before +@code{main} is invoked. That is, it should be +configured by a constructor. If it is configured at +its definition, it is configured by a constructor; +that is normally how you want to configured it. @end table @tpindex @code{server_characteristics_t} @tpindex @code{struct server_characteristics} @code{server_characteristics_t} @{also known as @code{struct server_characteristics}@} is a packed -@footnote{That is, define with @code{__attribute__((packed))}.} -with the following fields: +@footnote{That is, define with @code{__attribute__((packed))}.} with the following fields: @table @asis @item @code{require_privileges} [@code{unsigned : 1}] @@ -6777,35 +6803,37 @@ privileges as a security precaution. @item @code{require_display} [@code{unsigned : 1}] @vrindex @code{require_display} @cpindex Connecting to the display -Setting this to non-zero will cause the server to connect -to the display. +Setting this to non-zero will cause the server to +connect to the display. @item @code{require_respawn_info} [@code{unsigned : 1}] @vrindex @code{require_respawn_info} @opindex @option{--initial-spawn} @opindex @option{--respawn} @cpindex Initialisation -Setting this to non-zero will cause the server to refuse -to start unless either @option{--initial-spawn} or -@option{--respawn} is used. +Setting this to non-zero will cause the server to +refuse to start unless either @option{--initial-spawn} +or @option{--respawn} is used. @item @code{sanity_check_argc} [@code{unsigned : 1}] @vrindex @code{sanity_check_argc} @cpindex Command line, security @cpindex Security, command line -Setting this to non-zero will cause the server to refuse to -start if there are too many command line arguments. +Setting this to non-zero will cause the server to +refuse to start if there are too many command line +arguments. @item @code{fork_for_safety} [@code{unsigned : 1}] @vrindex @code{fork_for_safety} @cpindex Initialisation @fnindex @code{fork_cleanup} -Setting this to non-zero will cause the server to place -itself in a fork of itself when initialised. This can be -used to let the server clean up fatal stuff after itself -if it crashes. When the child exits, no matter how it -exits, the parent will call @code{fork_cleanup} and then -die in the same manner as the child. +Setting this to non-zero will cause the server to +place itself in a fork of itself when initialised. +This can be used to let the server clean up fatal +stuff after itself if it crashes. When the child +exits, no matter how it exits, the parent will call +@code{fork_cleanup} and then die in the same manner +as the child. @item @code{danger_is_deadly} [@code{unsigned : 1}] @vrindex @code{danger_is_deadly} @@ -6817,15 +6845,16 @@ die in the same manner as the child. @cpindex Automated memory release @cpindex Forcing memory release @cpindex Releasing memory -Setting this to non-zero without setting a signal action -for @code{SIGDANGER} will cause the server to die if -@code{SIGDANGER} is received. It is safe to set both -@code{danger_is_deadly} and @code{fork_for_safety} to -non-zero, during the call of @code{server_initialised} -the signal handler for @code{SIGDANGER} in the parent -process will be set to @code{SIG_IGN} independently of -the value of @code{danger_is_deadly} if -@code{fork_for_safety} is set to non-zero. +Setting this to non-zero without setting a signal +action for @code{SIGDANGER} will cause the server to +die if @code{SIGDANGER} is received. It is safe to +set both @code{danger_is_deadly} and +@code{fork_for_safety} to non-zero, during the call +of @code{server_initialised} the signal handler for +@code{SIGDANGER} in the parent process will be set to +@code{SIG_IGN} independently of the value of +@code{danger_is_deadly} if @code{fork_for_safety} is +set to non-zero. @opindex @option{--immortal} This setting will be treated as set to zero if @@ -6839,13 +6868,13 @@ This setting will be treated as set to zero if @cpindex Scancodes Keyboard servers receive scancodes from keyboard -drivers. A scancode can either be comprised of -one byte or three bytes. In each byte, the most -significant bit (assuming unsigned bytes) is -ignore, however for it first byte in the scancode -it signifies whether the key was released: it is -set of the key is released, and not set if the key -was pressed or is being held down. +drivers. A scancode can either be comprised of one +byte or three bytes. In each byte, the most +significant bit (assuming unsigned bytes) is ignore, +however for it first byte in the scancode it +signifies whether the key was released: it is set of +the key is released, and not set if the key was +pressed or is being held down. A scancode is comprised of three bytes if the lower 7-bits of the first byte is are all cleared, and the @@ -6853,11 +6882,11 @@ highest bit in the two following bytes are set. @cpindex Keycodes Ignoring the most significant bit in all bytes, the -keycode is the value of the byte if the scancode -is a single byte scancode. If the scancode is comprised -of three bytes, the first byte is ignored and the -keycode is @math{a \cdot 128 + b} where @math{a} is the -value of the second byte and @math{b} is the value +keycode is the value of the byte if the scancode is a +single byte scancode. If the scancode is comprised of +three bytes, the first byte is ignored and the +keycode is @math{a \cdot 128 + b} where @math{a} is +the value of the second byte and @math{b} is the value of the third byte. @menu @@ -6869,15 +6898,15 @@ of the third byte. @node 105-keys Keycodes @section 105-keys Keycodes -This is a list of keyboards for the -105-keys keyboards, using QWERTY-layout -for reference. +This is a list of keyboards for the 105-keys +keyboards, using QWERTY-layout for reference. @table @asis @item @code{1} @key{Escape} key @item @code{2}--@code{11} -Keys: @key{1}, @key{2}, @key{3}, @key{4}, @key{5}, @key{6}, @key{7}, @key{8}, @key{9}, @key{0} +Keys: @key{1}, @key{2}, @key{3}, @key{4}, @key{5}, +@key{6}, @key{7}, @key{8}, @key{9}, @key{0} @item @code{12} Key right of @key{0}. @item @code{13} @@ -6887,7 +6916,8 @@ Key left of @key{Backspace} @item @code{15} @key{Tab} key @item @code{16}--@code{25} -Keys: @key{q}, @key{w}, @key{e}, @key{r}, @key{t}, @key{y}, @key{u}, @key{i}, @key{o}, @key{p} +Keys: @key{q}, @key{w}, @key{e}, @key{r}, @key{t}, +@key{y}, @key{u}, @key{i}, @key{o}, @key{p} @item @code{26} Key right of @key{p}, once removed @item @code{27} @@ -6897,7 +6927,8 @@ Key right of @key{p}, twice removed @item @code{29} Left @key{Control} key @item @code{30}--@code{38} -Keys: @key{a}, @key{s}, @key{d}, @key{f}, @key{g}, @key{h}, @key{j}, @key{k}, @key{l} +Keys: @key{a}, @key{s}, @key{d}, @key{f}, @key{g}, +@key{h}, @key{j}, @key{k}, @key{l} @item @code{39} Key right of @key{l}, once removed @item @code{40} @@ -6909,7 +6940,8 @@ Left @key{Shift} key @item @code{43} Key right of @key{l}, three times removed @item @code{44}--@code{50} -Keys: @key{z}, @key{x}, @key{c}, @key{v}, @key{b}, @key{n}, @key{m} +Keys: @key{z}, @key{x}, @key{c}, @key{v}, @key{b}, +@key{n}, @key{m} @item @code{51} Key right of @key{m}, once removed @item @code{52} @@ -7002,8 +7034,8 @@ Right @key{Super} key Keyboard layouts are compiled from one or more files. When compiling a layout from multiple files, it is important that the files are specified in the correct -order. The general rule is that the layout file, -for example the Swedish QWERTY-keyboard, is specified +order. The general rule is that the layout file, for +example the Swedish QWERTY-keyboard, is specified first and is followed by add-ons such as the compose table and layout modifiers. @command{mds-kbdc} is used to compile layouts. @@ -7015,10 +7047,11 @@ hacking in the source tree, you will find this under subdirectory @file{layout}, modifiers are located in the subdirectory @file{mods} and compose tables are located in the subdirectory @file{compose}. -@command{mds-kbdc} prefixes @file{/usr/share/mds/keyboard} -unless the specifed files starts with @file{/}, @file{./} -or @file{../}. Dead keys are implemented by compose tables -and not in the layouts. +@command{mds-kbdc} prefixes +@file{/usr/share/mds/keyboard} unless the specifed +files starts with @file{/}, @file{./} or @file{../}. +Dead keys are implemented by compose tables and not +in the layouts. @menu * Keyboard Layout Syntax:: How to write your how layouts. @@ -7033,23 +7066,25 @@ and not in the layouts. @cpindex Keyboard layout, files, syntax @cpindex Syntax of keyboard layout file Similar to the C programming language, keyboard layout -files are parsed from the top down. This means that any -function or macro can only be used from lines below -the definition of said callable. However, the order of -the mapping statements themself, in respect to each -other, does not matter. Additionally, the layout files -are parsed line by line, and leading whitespace is ignored. -Comment can be started with a #-character and end at the -end of the line. It is important to know that modifiers -like @key{Shift} and @key{Control} needs to be mapped from -a keycode, this and similar that many keyboards have in -common, except dead key composition and compose sequences, -is already available in the @file{layout/common} directory -and can be included from the layout file. Compositions are -implement in the @file{compose} directory and should be -selected by the user at compile-time. Keyboard layout files -must be written in UTF-8 (without UTF-8 BOM) and with -line feeds for new lines. +files are parsed from the top down. This means that +any function or macro can only be used from lines +below the definition of said callable. However, the +order of the mapping statements themself, in respect +to each other, does not matter. Additionally, the +layout files are parsed line by line, and leading +whitespace is ignored. Comment can be started with a +#-character and end at the end of the line. It is +important to know that modifiers like @key{Shift} and +@key{Control} needs to be mapped from a keycode, this +and similar that many keyboards have in common, +except dead key composition and compose sequences, is +already available in the @file{layout/common} +directory and can be included from the layout file. +Compositions are implement in the @file{compose} +directory and should be selected by the user at +compile-time. Keyboard layout files must be written +in UTF-8 (without UTF-8 BOM) and with line feeds for +new lines. @menu * Mapping Statements:: Mapping keycodes to logical keys and text. @@ -7066,11 +7101,11 @@ line feeds for new lines. @node Mapping Statements @subsection Mapping Statements -The most fundamental part of the layout files are mapping -statements. These specify which keycode the keys have -and what happens when certain keys pressed, combined or -pressed and a sequence. If we want to map keycode 57 to -the space key we write +The most fundamental part of the layout files are +mapping statements. These specify which keycode the +keys have and what happens when certain keys pressed, +combined or pressed and a sequence. If we want to map +keycode 57 to the space key we write @example <keycode 57> : <space> @@ -7105,8 +7140,9 @@ matter we can just as well write @code{" "} represents a text string with one blank space, but it is possible to have multiple characters. -If we want to extend this to @kbd{altgr+space} producing -a no-break space, we can add either of the lines +If we want to extend this to @kbd{altgr+space} +producing a no-break space, we can add either of the +lines @example @group @@ -7131,28 +7167,26 @@ If we want to add a mapping to @kbd{ultra} from @end group @end example -@code{-altgr} means that @kbd{altgr} should -not be reported as held down. +@code{-altgr} means that @kbd{altgr} should not be +reported as held down. @cpindex Lock keys @cpindex Keys, lock -As can be seen in these examples it is not -possible to distinguish between modifiers -and keys. It is up to the keyboard layout -server and keyboard layout compiler to -know this. However, it is defined in the -keyboard layout files whether modifiers keys -are lock keys or not. To map the keycode -58 to @kbd{caps lock} write +As can be seen in these examples it is not possible +to distinguish between modifiers and keys. It is up +to the keyboard layout server and keyboard layout +compiler to know this. However, it is defined in the +keyboard layout files whether modifiers keys are lock +keys or not. To map the keycode 58 to @kbd{caps lock} +write @example <keycode 58> : <caps lock> @end example -But if you do not want it be a lock key, -but instead be required to be held down, -similar to how is normal for @key{Shift}, -instead write +But if you do not want it be a lock key, but instead +be required to be held down, similar to how is normal +for @key{Shift}, instead write @example <keycode 58> : <caps> @@ -7160,13 +7194,12 @@ instead write Any modifier may be a lock key. -Another, just as important, use of mappings -to is map letter keys. Unlike @key{Control} keys -like @key{Space} and @key{Shift}, there are no -predefined letters@footnote{With letters with -mean any character other than space.}. Therefore -the letter is prefixed with the word `letter'. -For example: +Another, just as important, use of mappings to is map +letter keys. Unlike @key{Control} keys like +@key{Space} and @key{Shift}, there are no predefined +letters@footnote{With letters with mean any character +other than space.}. Therefore the letter is prefixed +with the word `letter'. For example: @ifset AFOURPAPER_OR_USLETTER @example @@ -7202,14 +7235,14 @@ sign must be escaped with a prepending backslash. @cpindex Keys, dead @cpindex Keys, compose @cpindex Keys, modifiers -Many keyboard layouts also have dead keys. -Dead keys are keys that affect the next key-press. -For example, `´' followed by `e' may product `é'. -@kbd{compose} may be a dead key, just like it is in X.org, -but it can also be a modifer. +Many keyboard layouts also have dead keys. Dead keys +are keys that affect the next key-press. For example, +`´' followed by `e' may product `é'. @kbd{compose} +may be a dead key, just like it is in X.org, but it +can also be a modifer. -To define @kbd{´}, with keycode 13, @kbd{compose}, with -keycode 125, as a dead keys write +To define @kbd{´}, with keycode 13, @kbd{compose}, +with keycode 125, as a dead keys write @example @group @@ -7221,8 +7254,9 @@ keycode 125, as a dead keys write @cpindex Duplicate keys @cpindex Keys, duplicates Some may appear on multiple locations on the keyboard, -for example, there may be a left and a right @key{Shift} -key, and a normal @key{Return} key and one on the keypad: +for example, there may be a left and a right +@key{Shift} key, and a normal @key{Return} key and +one on the keypad: @example <keycode 42> : <left shift> @@ -7233,14 +7267,13 @@ key, and a normal @key{Return} key and one on the keypad: @cpindex Arrow keys @cpindex Keys, arrows -Because @code{<left>} and @code{<right>} are -valid keys --- they are arrow keys --- it is -importatn to place them directly before the -key, and not after. For instance @code{<left shift>} -denotes the left @key{Shift} key, whilst -@code{<shift left>} denotes the @key{Left} arrow -key with a @key{Shift} key held down. Modifiers -goes first. +Because @code{<left>} and @code{<right>} are valid +keys --- they are arrow keys --- it is important to +place them directly before the key, and not after. +For instance @code{<left shift>} denotes the left +@key{Shift} key, whilst @code{<shift left>} denotes +the @key{Left} arrow key with a @key{Shift} key held +down. Modifiers goes first. @@ -7254,16 +7287,16 @@ goes first. @cpindex Compose tables @cpindex Key sequences @cpindex Sequence, keys -Compose tables use mapping statements to map -key sequences. For example the compose key -followed by two `s':es makes an `ß': +Compose tables use mapping statements to map key +sequences. For example the compose key followed by +two `s':es makes an `ß': @example <dead compose> "s" "s" : "ß" @end example -It is also possible to map a sequence to -another sequence: +It is also possible to map a sequence to another +sequence: @example <dead compose> <tab> : <tab> <tab> <tab> <tab> @@ -7276,11 +7309,11 @@ a sequence: <super tab> : <tab> <tab> <tab> <tab> @end example -An alternative to @key{Compose} as a dead key, -is @key{Compose} as a modifier. If you use this, -the compose table need to be written for just -that. There two ways do this this. Either you -can write for example +An alternative to @key{Compose} as a dead key, is +@key{Compose} as a modifier. If you use this, the +compose table need to be written for just that. There +two ways do this this. Either you can write for +example @example <compose "s"> <compose "s"> : "ß" @@ -7297,9 +7330,9 @@ The other way is to write This also requires that @kbd{compose} is not released between the key-presses. -The compose table is filled with compositions -where it does not matter in which order you -press some of the keys. For example, instead of +The compose table is filled with compositions where +it does not matter in which order you press some of +the keys. For example, instead of @example @group @@ -7319,9 +7352,9 @@ you can write @cpindex Unordered subsequence, keys @cpindex Alternation, keys @cpindex Key alternations -@code{( )} denotes an unordered subsequence. -You can also use @code{[ ]} for alternation. -For example, instead of +@code{( )} denotes an unordered subsequence. You can +also use @code{[ ]} for alternation. For example, +instead of @example @group @@ -7336,9 +7369,8 @@ you can write <dead compose> (["S" "s"] "|") : "$" @end example -Inside an alternation you can use a dot -for specify that no key press is needed. -For example, instead of +Inside an alternation you can use a dot for specify +that no key press is needed. For example, instead of @example @group @@ -7353,28 +7385,25 @@ you can write <dead compose> "|" ["|" .] "S" : "$" @end example -It is undefined in which order alternations -and unordered subsequences are expanded; -neither sequencewise or levelwise. -Thus, there should not be side-effects where -either one is used, nor does it make since -to nest the two constructs in any other -way than alternation or unordered subsequence -inside unordered subsequence. The compiler -may however choose to discourage unordered -subsequence inside unordered subsequence -because of readability issues. - -Unordered subsequences longer than 5 elements -cannot compile under normal circumstances. -Eliminiation of unordered subsequences grows -superexponentially, and thus is probably an error -than can cause memory exhaustion and unrealistic -compilation-time. Therefore, if an unordered -subsequences longer than 5 elements is used the -compiler required that the @option{--force} flag -is used and that the unordered subsequences uses -double brackets: +It is undefined in which order alternations and +unordered subsequences are expanded; neither +sequencewise or levelwise. Thus, there should not be +side-effects where either one is used, nor does it +make since to nest the two constructs in any other +way than alternation or unordered subsequence inside +unordered subsequence. The compiler may however +choose to discourage unordered subsequence inside +unordered subsequence because of readability issues. + +Unordered subsequences longer than 5 elements cannot +compile under normal circumstances. Eliminiation of +unordered subsequences grows superexponentially, and +thus is probably an error than can cause memory +exhaustion and unrealistic compilation-time. +Therefore, if an unordered subsequences longer than 5 +elements is used the compiler required that the +@option{--force} flag is used and that the unordered +subsequences uses double brackets: @ifset AFOURPAPER_OR_USLETTER @example @@ -7412,20 +7441,19 @@ double brackets: @cpindex Keyboard layout identification @cpindex Identification of keyboard layouts -Whilst it is possible to write a comment -that states what keyboard layout a file -implements, there is a standardise way -to do this in code. The intention with -this is to make it possible for graphical -tools to easily list the layouts and -easy to understand descriptions. +Whilst it is possible to write a comment that states +what keyboard layout a file implements, there is a +standardise way to do this in code. The intention with +this is to make it possible for graphical tools to +easily list the layouts and easy to understand +descriptions. -There are three things a keyboard layout -file should specify: the language, the -country where it is used, and the variant. +There are three things a keyboard layout file should +specify: the language, the country where it is used, +and the variant. -For example the Swedish QWERTY layout used -in Sweden would have the code. +For example the Swedish QWERTY layout used in Sweden +would have the code. @example information @@ -7441,10 +7469,9 @@ end information @cpindex Country, keyboard layout @cpindex Language, keyboard layout @cpindex Variant, keyboard layout -If the layout is used multiple countries, -or even for multiple lanuages, @code{country} -and @code{language} may be specified on -multiple lines. For example: +If the layout is used multiple countries, or even for +multiple lanuages, @code{country} and @code{language} +may be specified on multiple lines. For example: @example information @@ -7497,21 +7524,21 @@ When writing generic compose tables it can be helpful to let the compiler assume that a certain set of keys will be provided by the layout file and not making other assumptions. This is helpful because if you want -to make an compose table that can compose all characters -given only the ASCII letters, modifiers and a compose -key, rather than written a phony layout file and select -it each time you compile to compose table you can state -in the compose table file that the compiler should as -that those keys are provided when the compose table file -is compile by itself. If this is done, the compiler can -warn when one of the compositions cannot be reached from -those basic keys. - -If we want to make the compiler assume that @key{compose} -is available as a dead key, that @key{shift}, @key{altgr} -and @key{space} are available and that the ASCII letter, -digits and some basic special characters are available we -can write. +to make an compose table that can compose all +characters given only the ASCII letters, modifiers +and a compose key, rather than written a phony layout +file and select it each time you compile to compose +table you can state in the compose table file that +the compiler should as that those keys are provided +when the compose table file is compile by itself. If +this is done, the compiler can warn when one of the +compositions cannot be reached from those basic keys. + +If we want to make the compiler assume that +@key{compose} is available as a dead key, that +@key{shift}, @key{altgr} and @key{space} are +available and that the ASCII letter, digits and some +basic special characters are available we can write. @example assumption @@ -7534,16 +7561,16 @@ end assumption @cpindex Keyboard layout, file inclusion @cpindex File inclusion, keyboard layout @cpindex Inclusion of file, keyboard layout -Writing layout files from scratch is probably something -you want to avoid. For instance you would we need to -create mappings for `A' to `Z' and `0' to `9' (assuming -its a latin-based language), and map up all specific key, -like modifiers, space, arrow keys, and the keypad. And -you would have to make sure do only that the keys are -mapped but that they are mapped to the text the should -product and that they word correcly with the modifiers. -These are things most keyboards have in common with many -other layouts. +Writing layout files from scratch is probably +something you want to avoid. For instance you would +we need to create mappings for `A' to `Z' and `0' to +`9' (assuming its a latin-based language), and map up +all specific key, like modifiers, space, arrow keys, +and the keypad. And you would have to make sure do +only that the keys are mapped but that they are +mapped to the text the should product and that they +word correcly with the modifiers. These are things +most keyboards have in common with many other layouts. For instance @file{layout/sv/qwerty} has two include statements to implement its basics: @@ -7562,10 +7589,10 @@ include "../common/base" @cpindex Keyboard layout, macros @cpindex Macros, keyboard layout -There is a lot of repetitive work in layouts, for instance -all letters need mapping for any combination of use of -@key{shift} and @key{compose}. To reduce this, you can -define macros. +There is a lot of repetitive work in layouts, for +instance all letters need mapping for any combination +of use of @key{shift} and @key{compose}. To reduce +this, you can define macros. For example instead of writing @@ -7598,14 +7625,13 @@ letter("b" "B") # and so on ... @end example -The name of this macro is @code{letter/2}, -but it is called with the name @code{letter} -and two arguments. The @code{/2}-suffix means -that it is invoked with exactly two arguments. -You can use this do define multiple version -of the same macro, with the same invocation -name but with different number of arguments. -For example: +The name of this macro is @code{letter/2}, but it is +called with the name @code{letter} and two arguments. +The @code{/2}-suffix means that it is invoked with +exactly two arguments. You can use this do define +multiple version of the same macro, with the same +invocation name but with different number of +arguments. For example: @example macro letter/2 @@ -7627,7 +7653,8 @@ letter("ö" "Ö") @end example @code{\add( )} and @code{\sub( )} are calls to two -built-in functions named @code{add/2} and @code{sub/2}. +built-in functions named @code{add/2} and +@code{sub/2}. @cpindex Alternation, keys @cpindex Key alternations @@ -7654,14 +7681,13 @@ letter(["u" "v" "w" "x" "y" "z"]) @cpindex Alternation, keys @cpindex Key alternations You may use @code{.} in an alternation, in that case -macro is called once with the argument, causing it -to invoke for example @code{letter/0} instead of +macro is called once with the argument, causing it to +invoke for example @code{letter/0} instead of @code{letter/1}. -A related issue are for-loops. If we for example -want to call the macro @code{letter/1} for all -letters between and including `a' and `z' -we can just write +A related issue are for-loops. If we for example want +to call the macro @code{letter/1} for all letters +between and including `a' and `z' we can just write @example @group @@ -7698,9 +7724,9 @@ end for @code{continue} can be used to stop the iteration of the innermost for-loop and skip to the next iteration. You can also use @code{break}, but it also has the -effect to stop the entire loop. Similarly, @code{return} -can be used to break an entire macro call, or function -call. +effect to stop the entire loop. Similarly, +@code{return} can be used to break an entire macro +call, or function call. You can also use @code{if} for more example things, and use @code{else if} and @code{else if}: @@ -7717,26 +7743,25 @@ macro latter/1 end macro @end example -Note that there is no quotes around the `a' -in @code{letter(\1 \sub(\1 1))}. This means -that the argument will be than value 1 rather -than the code point of the character `1'. Note -however that values lower than zero or equals -to or greater than 2 to the power of 31 not -allowed and can either cause compile-time -error or erroneous compiled files. +Note that there is no quotes around the `a' in +@code{letter(\1 \sub(\1 1))}. This means that the +argument will be than value 1 rather than the code +point of the character `1'. Note however that values +lower than zero or equals to or greater than 2 to the +power of 31 not allowed and can either cause +compile-time error or erroneous compiled files. @cpindex Keyboard layout, macros @cpindex Macros, keyboard layout -Functions are similar to function macros, -the difference is that a function is called -inline and is prefixed with slash, and rather -than inline the code inside it, the evalutes -to the last value it evaluted before it returned. +Functions are similar to function macros, the +difference is that a function is called inline and is +prefixed with slash, and rather than inline the code +inside it, the evalutes to the last value it evaluted +before it returned. For example instead of @code{\not(\greater(\1 "z"))} -you can write @code{\less_eq(\1 "z")} after you -have defined the function @code{less_eq/2} with the +you can write @code{\less_eq(\1 "z")} after you have +defined the function @code{less_eq/2} with the following code: @example @@ -7747,9 +7772,9 @@ end function @end group @end example -A final construct to make layout code less -repetitive is let-statements. This can be -used to assign values to variables. +A final construct to make layout code less repetitive +is let-statements. This can be used to assign values +to variables. The code @@ -7786,12 +7811,11 @@ It is also possible to declare arrays: let \1 : @{ "å" "ä" "ö" "à" "é" "ü" @} @end example -Arrays may however not have arrays for -values. +Arrays may however not have arrays for values. Because arrays can be very large, they, but only -them, may span multiple lines. For example -you may write +them, may span multiple lines. For example you may +write @example @group @@ -7814,13 +7838,13 @@ See @ref{Builtin Functions} for how they are used. Variable names can only be numerical and most not start with a zero. `0' is not valid variable name, -and thus @code{\0} does not address a variable. -Macro and function names, may only include -`0'--`9', `a'--`z', `A'--`Z' and `_', but must and -not start with `0'--`9'. Additionally, when declared -macro and function names must be suffixed with `/' -follwed by the exact number of arguments the macro -or function takes. +and thus @code{\0} does not address a variable. Macro +and function names, may only include `0'--`9', +`a'--`z', `A'--`Z' and `_', but must and not start +with `0'--`9'. Additionally, when declared macro and +function names must be suffixed with `/' follwed by +the exact number of arguments the macro or function +takes. Variable indices are constrained to the 31:th power of 2, exclusively. Attempts to use higher variable @@ -7843,22 +7867,23 @@ restricted to the 31:th power of 2. Similar to most, if not all, programming language, a backslash inside quotes can be used to parse the next character with special meaning. For instance, `\"' is -parsed as a literal `"', and `\\' is parsed as a literal -`\'. `\>' is too parsed as a literal `>', for example -you may need to write @code{<letter \>>}. The characters -`(', `)', `[', `]', `@{', `@}', `<' and `,' also follow -this rule to make those character accesible inside -a @code{< >}. But `\' can also be used to specify -characters by their code point, for example if you want -an `æ' you can write @code{"\u00E6"} or @code{"\uE6"}, -instead of @code{"æ"}. You can also write @code{"\0346"}, -the difference between @code{\0} and @code{\u} is that -@code{\0} uses octal whereas @code{\u} uses hexadecimal. -A noteworthy side-effect of this is that function names -cannot start with a lower case `u'. - -`\' can also be used to access variables and parameters. -For example @code{\1} in +parsed as a literal `"', and `\\' is parsed as a +literal `\'. `\>' is too parsed as a literal `>', for +example you may need to write @code{<letter \>>}. The +characters `(', `)', `[', `]', `@{', `@}', `<' and +`,' also follow this rule to make those character +accesible inside a @code{< >}. But `\' can also be +used to specify characters by their code point, for +example if you want an `æ' you can write +@code{"\u00E6"} or @code{"\uE6"}, instead of +@code{"æ"}. You can also write @code{"\0346"}, the +difference between @code{\0} and @code{\u} is that +@code{\0} uses octal whereas @code{\u} uses +hexadecimal. A noteworthy side-effect of this is that +function names cannot start with a lower case `u'. + +`\' can also be used to access variables and +parameters. For example @code{\1} in @example macro letter/2 @@ -7877,13 +7902,13 @@ to an `Å'. you want to call the function @code{f/0} you write @code{\f()}. -Because numerical (possibly prefixed with an `u') are of -variable length, it is possible to specify the escape's -termination point with a dot. For instance, if you want -the value of the first variable (@code{\1}) followed by -two zeroes, you do not write @code{\100} as that would -expand to the value of the hundredth variable. Instead -you write @code{\1.00}. +Because numerical (possibly prefixed with an `u') are +of variable length, it is possible to specify the +escape's termination point with a dot. For instance, +if you want the value of the first variable +(@code{\1}) followed by two zeroes, you do not write +@code{\100} as that would expand to the value of the +hundredth variable. Instead you write @code{\1.00}. Use of function calls and variables inside @code{include}-statments invokes undefined behaviour. @@ -7898,9 +7923,9 @@ power of 2 also invoke undefined behaviour. @cpindex Keyboard layout, builtin functions @cpindex Functions, builtin, keyboard layout @cpindex Builtin functions, keyboard layout -To help you write meaningful functions in your keyboard -layout files, the compiler defines an almost minimal set -of basic functions: +To help you write meaningful functions in your +keyboard layout files, the compiler defines an almost +minimal set of basic functions: @table @code @item add/2 @@ -7925,14 +7950,14 @@ Like @code{add/2} but division. Like @code{add/2} but modulo. @item rsh/2 @fnindex @code{rsh/2} -Like @code{add/2} but rightward bitwise shift. -If a character in @code{\2} is has a code point -greater than 30, undefined behaviour is invoked. +Like @code{add/2} but rightward bitwise shift. If a +character in @code{\2} is has a code point greater +than 30, undefined behaviour is invoked. @item lsh/2 @fnindex @code{lsh/2} -Like @code{add/2} but leftward bitwise shift. -If a character in @code{\2} is has a code point -greater than 30, undefined behaviour is invoked. +Like @code{add/2} but leftward bitwise shift. If a +character in @code{\2} is has a code point greater +than 30, undefined behaviour is invoked. @item or/2 @fnindex @code{or/2} Like @code{add/2} but bitwise OR@. @@ -7944,18 +7969,18 @@ Like @code{add/2} but bitwise AND@. Like @code{add/2} but bitwise XOR@. @item not/1 @fnindex @code{not/1} -For each character in @code{\1}, evaluate -to zero if the character is not zero, and -one if the character is zero. +For each character in @code{\1}, evaluate to zero if +the character is not zero, and one if the character +is zero. @item equals/2 @fnindex @code{equals/2} -For each character, evalute to one if -the characters in @code{\1} and @code{\2} -are equal and zero otherwise. +For each character, evalute to one if the characters +in @code{\1} and @code{\2} are equal and zero +otherwise. @item greater/2 @fnindex @code{greater/2} -Like @code{equals/2} but @code{\1} greater -than @code{\2} rather than @code{\1} equals +Like @code{equals/2} but @code{\1} greater than +@code{\2} rather than @code{\1} equals @code{\2}. @item less/2 @fnindex @code{less/2} @@ -7963,18 +7988,16 @@ Like @code{equals/2} but @code{\1} less than @code{\2} rather than @code{\1} equals @code{\2}. @item set/3 @fnindex @code{set/3} -Set the element with index @code{\2}, in -the array with variable index @code{\1}, to -@code{\3}, and return @code{\3}. -For example @code{\set(1 0 4)} sets the -first element in @code{\1} to 4. +Set the element with index @code{\2}, in the array +with variable index @code{\1}, to @code{\3}, and +return @code{\3}. For example @code{\set(1 0 4)} sets +the first element in @code{\1} to 4. @item get/2 @fnindex @code{get/2} -Return the element with index @code{\2} in -the array with variable index @code{\1}. -For example after @code{\set(1 0 4)} or -@code{let \1 : @{ 4 3 2 1 0 @}} has been -used, @code{\get(1 0)} evaluates to 4. +Return the element with index @code{\2} in the array +with variable index @code{\1}. For example after +@code{\set(1 0 4)} or @code{let \1 : @{ 4 3 2 1 0 @}} +has been used, @code{\get(1 0)} evaluates to 4. @end table @@ -8280,20 +8303,20 @@ If the two glyphs are identical the glyph becomes heavy. More general, common parts of the glyphs become heavy. -Glyphs that contain a heavy part be transformed -so that the heavy parts become double stroked. -Glyphs that do not contain heavy parts be transformed -so the entire glyphs becomes double stroked. -This is done by typing @kbd{<dead compose>} followed -by, in any order, @kbd{"+"} and the glyph to modify. -Note that this is not possible for all glyphs, as not -all glyphs have a double stroked variant, but all -double stroked glyphs can be composed this way. +Glyphs that contain a heavy part be transformed so +that the heavy parts become double stroked. Glyphs +that do not contain heavy parts be transformed so the +entire glyphs becomes double stroked. This is done by +typing @kbd{<dead compose>} followed by, in any +order, @kbd{"+"} and the glyph to modify. Note that +this is not possible for all glyphs, as not all +glyphs have a double stroked variant, but all double +stroked glyphs can be composed this way. The horizontal and the vertical light glyphs, as well -as the combination of the two, can be made double stroked -by typing @kbd{<dead compose>} followed by, in any order, -@kbd{"="} and the glyph. +as the combination of the two, can be made double +stroked by typing @kbd{<dead compose>} followed by, +in any order, @kbd{"="} and the glyph. The light corners can be made rounded by by typing @kbd{<dead compose>} followed by, in any order, @@ -8309,8 +8332,8 @@ starting either with @kbd{<shift dead compose> "b"} or @kbd{<shift dead compose> "B"}. The former creates light glyphs, and the latter creates heavy glyphs. Note that glyphs with diagonal lines do not have an -heavy variants. The base sequences are followed by -a sequence describing the glyphs to compose. +heavy variants. The base sequences are followed by a +sequence describing the glyphs to compose. @table @kbd @item "-" Horizontal line. @@ -8333,14 +8356,15 @@ Right part of a horizontal line. @item "v" Lower part of a vertical line. @end table -Simple arrows can be used instead of @kbd{"<"}, @kbd{"^"}, -@kbd{">"} and @kbd{"v"}. +Simple arrows can be used instead of @kbd{"<"}, +@kbd{"^"}, @kbd{">"} and @kbd{"v"}. -@kbd{"-"}, @kbd{"|"} can be prefixed with a key -to modify the lines. +@kbd{"-"}, @kbd{"|"} can be prefixed with a key to +modify the lines. @table @kbd @item "=" -Double stroke. This modifier is also available for @kbd{"+"}. +Double stroke. This modifier is also available for +@kbd{"+"}. @item "." Triple dash. @item ":" @@ -8348,11 +8372,11 @@ Quadruple dash. @end table Double dashed horizonal line is composed with -@kbd{<shift dead compose> "b" "." "."} for the -light variant and @kbd{<shift dead compose> "B" "." "."} +@kbd{<shift dead compose> "b" "." "."} for the light +variant and @kbd{<shift dead compose> "B" "." "."} for the heavy. variant. @kbd{"." ":"}, or a broken pipe, instead of @kbd{"." "."} can be used to create -a douebl dashed vertical line. +a double dashed vertical line. @@ -8373,11 +8397,11 @@ keys between @kbd{"1"} and @kbd{"8"}, representing the indices of the dots. More complex braille patterns are composed by -overlaying two braille patterns. This is done -by typing @kbd{<dead compose>} followed by the -two braille patterns to overlay. If the two -braille patterns are identical, the braille pattern -will be overlays with its mirror pattern. +overlaying two braille patterns. This is done by +typing @kbd{<dead compose>} followed by the two +braille patterns to overlay. If the two braille +patterns are identical, the braille pattern will be +overlays with its mirror pattern. @@ -8386,26 +8410,24 @@ will be overlays with its mirror pattern. @c TODO compose tiles together There are two types of domino tile glyphs: -horizontal and vertical. Each tile has two -halfs with 0 to 6 dots. Additonally there -is one horizontal tile, and one vertical tile, -with the back facing the user. +horizontal and vertical. Each tile has two halfs with +0 to 6 dots. Additonally there is one horizontal +tile, and one vertical tile, with the back facing the +user. Horizontal tiles are composed with -@kbd{<shift dead compose> "d" "t" "-"} followed -by the number of dots on the left side and the -number of dots on the right side. Horizontal tile -with the back facing the user is composed with -either @kbd{"-"} or @kbd{<space>} instead of the -two digits. +@kbd{<shift dead compose> "d" "t" "-"} followed by +the number of dots on the left side and the number of +dots on the right side. Horizontal tile with the back +facing the user is composed with either @kbd{"-"} or +@kbd{<space>} instead of the two digits. Vertical tiles are composed with -@kbd{<shift dead compose> "d" "t" "|"} followed -by the number of dots on the top and the -number of dots on the bottom. Vertical tile -with the back facing the user is composed with -either @kbd{"|"} or @kbd{<space>} instead of the -two digits. +@kbd{<shift dead compose> "d" "t" "|"} followed by +the number of dots on the top and the number of dots +on the bottom. Vertical tile with the back facing +the user is composed with either @kbd{"|"} or +@kbd{<space>} instead of the two digits. @@ -8482,9 +8504,9 @@ two digits. @node Mahjong Tiles @subsection Mahjong Tiles -Unnumbered mahjong tiles are composed -with @kbd{<shift dead compose> "m" "t"} -followed by one additional key: +Unnumbered mahjong tiles are composed with +@kbd{<shift dead compose> "m" "t"} followed by one +additional key: @table @kbd @item < West tile @@ -8523,11 +8545,10 @@ The back of a mahjong tile @end table The numbered tiles are composed with -@kbd{<shift dead compose> "m" "t"} followed -by with additional keys: one for the suit, -and one for the value. The value is is -encoded with either @kbd{"1"} to @kbd{"9"}. -The suits is encoded +@kbd{<shift dead compose> "m" "t"} followed by with +additional keys: one for the suit, and one for the +value. The value is is encoded with either @kbd{"1"} +to @kbd{"9"}. The suits is encoded @table @kbd @item W Characters (wan) @@ -8577,11 +8598,11 @@ Circles (bing) @node Playing Cards @subsection Playing Cards -@kbd{<shift dead compose> "p" "c"} composes the character -presenting the back of a playing card. +@kbd{<shift dead compose> "p" "c"} composes the +character presenting the back of a playing card. -Jokers and trumps are composed using the playing -card back and two additional characters. +Jokers and trumps are composed using the playing card +back and two additional characters. @table @asis @item joker, red @@ -8600,15 +8621,15 @@ the sequence @kbd{<shift dead compose> "p" "c"}. The trumps are number 1 through 21, and are composed with @kbd{<dead compose> <playing card back> "1" <space>} through @kbd{<dead compose> <playing card back> "2" "1"}. -Additionally, the fool card is composed with -through @kbd{<dead compose> <playing card back> "0" <space>}. - -The Playing Cards block in Unicode also contains -ace, 2--10, jack, knight, queen och king for the -suits spades/swords, hearts/cups, diamonds/pentacles -and clubs/wands. These are composed with the -@kbd{<dead compose>} followed by, in any order, -the suit and value. The values are encoded +Additionally, the fool card is composed with through +@kbd{<dead compose> <playing card back> "0" <space>}. + +The Playing Cards block in Unicode also contains ace, +2--10, jack, knight, queen och king for the suits +spades/swords, hearts/cups, diamonds/pentacles and +clubs/wands. These are composed with the +@kbd{<dead compose>} followed by, in any order, the +suit and value. The values are encoded @table @asis @item Ace @kbd{"A"}, @kbd{"a"} or @kbd{"1"} @@ -8677,8 +8698,9 @@ Black or white clubs symbol @node Tags @subsection Tags -The ``Tags'' block in Unicode has been deprecated. Characters -in this block is therefore not mapped in the compose table. +The ``Tags'' block in Unicode has been deprecated. +Characters in this block is therefore not mapped in +the compose table. @@ -8686,14 +8708,15 @@ in this block is therefore not mapped in the compose table. @subsection Variation Selectors @c TODO Variation Selectors, Variation Selectors Supplement -There are 256 variation selectors, numbered 1 through 256. -These can be composed with the sequence -@kbd{<shift dead compose> "v" "s"} followed by exactly three -digits. These digits should form the index of the variation -selector. Indices lower than 100, require leading @kbd{"0"}:s. -Alternatively, variation selectors with an index lower than 100, -can be composed with a trailing @kbd{<space>} instead of leading -@kbd{"0"}:s. +There are 256 variation selectors, numbered 1 through +256. These can be composed with the sequence +@kbd{<shift dead compose> "v" "s"} followed by +exactly three digits. These digits should form the +index of the variation selector. Indices lower than +100, require leading @kbd{"0"}:s. Alternatively, +variation selectors with an index lower than 100, +can be composed with a trailing @kbd{<space>} instead +of leading @kbd{"0"}:s. @@ -8719,9 +8742,9 @@ can be composed with a trailing @kbd{<space>} instead of leading @cpindex Keyboard, accessibility @cpindex Accessibility, keyboard Sticky keys is an accessibility feature that lets the -user process modifier keys instead of holding them down. -Sticky keys is implemented by the @command{mds-keystick} -server. +user process modifier keys instead of holding them +down. Sticky keys is implemented by the +@command{mds-keystick} server. When @command{mds-keystick} is active, any key that is mapped in @command{mds-keystick} to be a modifier @@ -8736,27 +8759,31 @@ keys, and is a modifier, that key released until it is pressed again. Note that @command{mds-keystick} is not aware of which -keys are considered modifiers by @command{mds-keytrans}, -but it is affected of remappings in @command{mds-kbd} -and @command{mds-kkbd}, therefore it is better to swap, +keys are considered modifiers by +@command{mds-keytrans}, but it is affected of +remappings in @command{mds-kbd} and +@command{mds-kkbd}, therefore it is better to swap, for example, @kbd{control} and @kbd{caps lock} in the keyboard servers than in @command{mds-keytrans}. Doing so means that you do not have to configure -@command{mds-keystick} to know the original @kbd{caps lock} -is a modifier but the original @kbd{control} is not. +@command{mds-keystick} to know the original +@kbd{caps lock} is a modifier but the original +@kbd{control} is not. @cpindex Mode lock key @cpindex Keys, mode lock -For greater accessibility you can, in @command{mds-keytrans}, -replace a key with the @kbd{mode lock}-key. If this is done, -pressing a sequence of modifiers and then the -@kbd{mode lock}-key will caused those modifiers to be locked -until the next time you press @kbd{mode lock}. Any modifier +For greater accessibility you can, in +@command{mds-keytrans}, replace a key with the +@kbd{mode lock}-key. If this is done, pressing a +sequence of modifiers and then the @kbd{mode lock}-key +will caused those modifiers to be locked until the +next time you press @kbd{mode lock}. Any modifier pressed directly before, optionally with intermediate -modifiers, the second @kbd{mode lock} will stay locked. The -action of @kbd{mode lock} is to release all modifiers it is -locked and the lock those that are currently held down; active -stickly keys are artificially held down and thus included. +modifiers, the second @kbd{mode lock} will stay +locked. The action of @kbd{mode lock} is to release +all modifiers it is locked and the lock those that +are currently held down; active stickly keys are +artificially held down and thus included. @@ -8767,9 +8794,9 @@ stickly keys are artificially held down and thus included. @cpindex Bounce keys @cpindex Keyboard, accessibility @cpindex Accessibility, keyboard -Bounce keys is an accessibility feature that filters out -rapidly repeated key strokes. Bounce keys is implemented -by the @command{mds-keybounce} server. +Bounce keys is an accessibility feature that filters +out rapidly repeated key strokes. Bounce keys is +implemented by the @command{mds-keybounce} server. @@ -8796,10 +8823,11 @@ brief key strokes. Slow keys is implemented by the Loud keys is an accessibility feature that can emulate key clicking sounds when a key is pressed or generate tones when certain keys are pressed. For example if -@kbd{caps lock} is actived by a key stroke a high-pitched -tone can be generated when when it is deactived by a key -stroke a low-pitched tone can be generated. Loud keys is -implemented by the @command{mds-keycue} server. +@kbd{caps lock} is actived by a key stroke a +high-pitched tone can be generated when when it is +deactived by a key stroke a low-pitched tone can be +generated. Loud keys is implemented by the +@command{mds-keycue} server. @@ -8810,11 +8838,12 @@ implemented by the @command{mds-keycue} server. @cpindex Keyboard to rat bindings @cpindex Rat keys @cpindex Mouse keys -Rat keys (also known as mouse keys) is an accessibility -and usability feature that lets the user use the keyboard -as a pointing device. This feature is implemented by the -@command{mds-kbd2rat} server, and this section covers the -details of that server. +Rat keys (also known as mouse keys) is an +accessibility and usability feature that lets the +user use the keyboard as a pointing device. This +feature is implemented by the @command{mds-kbd2rat} +server, and this section covers the details of that +server. If @command{mds-kbd2rat} is used, the keypad acts as a pointing device when @kbd{num lock} is not active. It @@ -8822,10 +8851,10 @@ is also possible to configure @command{mds-kbd2rat} to disregard @kbd{num lock} and always be active, until it receives a signal to toggle its state. For example, if @command{mds-kbd2rat} is configured to disregard -@kbd{num lock}, @command{mds-kbdtrans} can be configured -to send to fauxkey @kbd{rat} when @kbd{alt+shift+num} -is pressed, and this key can be caught by -@command{mds-keybind} that sends a signal to +@kbd{num lock}, @command{mds-kbdtrans} can be +configured to send to fauxkey @kbd{rat} when +@kbd{alt+shift+num} is pressed, and this key can be +caught by @command{mds-keybind} that sends a signal to @command{mds-kbd2rat} to toggle. When @command{mds-kbd2rat} is active, it maps the @@ -8852,10 +8881,9 @@ Cancel actions waiting by @kbd{0} and @kbd{5}. @item 0 -Hold down the next selected rat button -until that rat button is selected again. -This is a dead key, that is, you do not -have to hold it down. +Hold down the next selected rat button until that rat +button is selected again. This is a dead key, that +is, you do not have to hold it down. @item 1 Cursor left down. @@ -8892,56 +8920,55 @@ Cursor right up. @end table This table is not affected by mappings in -@command{mds-keytrans}, but it is affected -by remappings in @command{mds-kbd} and +@command{mds-keytrans}, but it is affected by +remappings in @command{mds-kbd} and @command{mds-kkbd}. -@command{mds-kbd2rat} can be configured to -permute the rat button keys. It is independent -of permutations in @command{mds-rat}. +@command{mds-kbd2rat} can be configured to permute +the rat button keys. It is independent of +permutations in @command{mds-rat}. -If multiple direction keys@footnote{@kbd{1}, -@kbd{2}, @kbd{3}, @kbd{3}, @kbd{4}, @kbd{6}, -@kbd{7}, @kbd{8} and @kbd{9}} are used, the -average direction is used. +If multiple direction keys@footnote{@kbd{1}, @kbd{2}, +@kbd{3}, @kbd{3}, @kbd{4}, @kbd{6}, @kbd{7}, @kbd{8} +and @kbd{9}} are used, the average direction is used. -@command{mds-kbd2rat} is five parameters that -control with which speed it moves the cursor: +@command{mds-kbd2rat} is five parameters that control +with which speed it moves the cursor: @table @asis @item delay -The delay it takes before the first time a -mouse event is repeated when a key is held -down. The default is for the server to wait -for the keyboard to send another key press. +The delay it takes before the first time a mouse +event is repeated when a key is held down. The +default is for the server to wait for the keyboard to +send another key press. @item interval -The time it takes before a mouse event is -repeated since its previous repear when a -key is held down. The default is for the -server to wait for the keyboard to send -another key press. +The time it takes before a mouse event is repeated +since its previous repear when a key is held down. +The default is for the server to wait for the +keyboard to send another key press. @item max speed The maximum speed with which the cursor can move. @item time to max speed -The time a key has to be held down before -the maximum speed is reached. The cursor -accelerate with each mouse event repeat. +The time a key has to be held down before the maximum +speed is reached. The cursor accelerate with each +mouse event repeat. @item curve Ramp used to reach pointer speed. @end table -The pointer's speed, not taking caps into consideration, -is calculated by +The pointer's speed, not taking caps into +consideration, is calculated by @iftex @math{max~speed \left ( hold~down~time ~-~ delay \over time~to~max~speed \right)^{1 ~+~ curve}} @end iftex @ifnottex -max speed ((hold down time - delay) / time to max speed)^(1 + curve) +max speed ((hold down time - delay) / time to max +speed)^(1 + curve) @end ifnottex @@ -8960,26 +8987,30 @@ max speed ((hold down time - delay) / time to max speed)^(1 + curve) @node Rat Cursors @section Rat Cursors -Rat cursor themes should not add shadows to the cursors. -Shadows are added by the @command{mds-cursorshadow} server -according to the user's specifications. +Rat cursor themes should not add shadows to the +cursors. Shadows are added by the +@command{mds-cursorshadow} server according to the +user's specifications. @command{mds}'s rat cursors specifications is based on @url{http://www.freedesktop.org/wiki/Specifications/cursor-spec}. -All rat cursor themes should include the cursors listed below. -The icons are conceptual examples of how they can look. - -In addition to the cursors below, each of the may be accompanied -with @code{X-press}, @code{X-hold} and @code{X-release}, where -@code{X} is the name of the master icon. @code{X-press} is -an animation from @code{X} to @code{X-hold} and is used when -the cursor should transition from @code{X} to @code{X-hold}. -@code{X-hold} is the version of @code{X} that should be used -if any rat button is held down. @code{X} is an animation from -@code{X-release} to @code{X} and is used when the cursor should -transition from @code{X-release} to @code{X}@. Clients should -not set the cursor to either of them, it is up to the server +All rat cursor themes should include the cursors +listed below. The icons are conceptual examples of +how they can look. + +In addition to the cursors below, each of the may be +accompanied with @code{X-press}, @code{X-hold} and +@code{X-release}, where @code{X} is the name of the +master icon. @code{X-press} is an animation from +@code{X} to @code{X-hold} and is used when the cursor +should transition from @code{X} to @code{X-hold}. +@code{X-hold} is the version of @code{X} that should +be used if any rat button is held down. @code{X} is +an animation from @code{X-release} to @code{X} and is +used when the cursor should transition from +@code{X-release} to @code{X}@. Clients should not set +the cursor to either of them, it is up to the server to do this based on events from the rat device. @ifset AFIVEPAPER @@ -8987,19 +9018,21 @@ to do this based on events from the rat device. @end ifset @table @code @item default -This is the default cursor. It is used as a fallback if no -more fitting cursor is found; for example if a programs -wants the cursor to be @command{pointer}, but the server -is unable to find it, it will fallback to @command{default}. -The server should provide its own fallback in case the theme -is missing this cursor too. - -This cursor indicates that the interface is idle and prepared -to accept commands from the user. - -This cursor is usually a north-west or north-north-west -pointing arrow. For left-handed themes this cursor is -usually a north-east or north-north-east pointing arrow. +This is the default cursor. It is used as a fallback +if no more fitting cursor is found; for example if a +programs wants the cursor to be @command{pointer}, +but the server is unable to find it, it will fallback +to @command{default}. The server should provide its +own fallback in case the theme is missing this cursor +too. + +This cursor indicates that the interface is idle and +prepared to accept commands from the user. + +This cursor is usually a north-west or +north-north-west pointing arrow. For left-handed +themes this cursor is usually a north-east or +north-north-east pointing arrow. @example @group ## @@ -9023,13 +9056,13 @@ usually a north-east or north-north-east pointing arrow. @page @item context-menu -This cursor indicates the same state as @command{default} -with he addition that the object beneath it can be -right-clicked (left-clicked if left-handed) to open a -context menu. +This cursor indicates the same state as +@command{default} with he addition that the object +beneath it can be right-clicked (left-clicked if +left-handed) to open a context menu. -This cursor is typically @command{default} combined with a -small menu. +This cursor is typically @command{default} combined +with a small menu. @example @group ## ############ @@ -9056,8 +9089,9 @@ small menu. @page @end ifset @item text -This cursor should be used when the rat pointers is above -an horizontal text that can be selected and possibly edited. +This cursor should be used when the rat pointers is +above an horizontal text that can be selected and +possibly edited. This cursor is usually a vertical I-beam. @example @@ -9086,11 +9120,12 @@ This cursor is usually a vertical I-beam. @page @end ifclear @item vertical-text -This cursor should be used when the rat pointers is above -an vertical text that can be selected and possibly edited. +This cursor should be used when the rat pointers is +above an vertical text that can be selected and +possibly edited. -If this cursor is missing, @code{text} should be used as -the first fallback. +If this cursor is missing, @code{text} should be used +as the first fallback. This cursor is usually a horizontal I-beam. @example @@ -9110,13 +9145,13 @@ This cursor is usually a horizontal I-beam. @page @end ifset @item progress -This cursor indicates that the interface can -be used as when @command{default} is used. -But that the program is working in the background -with command the user previously issued. +This cursor indicates that the interface can be used +as when @command{default} is used. But that the +program is working in the background with command the +user previously issued. -This cursor is usually rendered as a combination -of @command{default} and @command{wait}. +This cursor is usually rendered as a combination of +@command{default} and @command{wait}. @example @group ## ############ @@ -9143,13 +9178,12 @@ of @command{default} and @command{wait}. @page @end ifclear @item wait -This cursor indicates that the interface cannot -be used because it is working or is blocked by -an external resource. +This cursor indicates that the interface cannot be +used because it is working or is blocked by an +external resource. -This cursor is typically rendered as a -hourglass, watch, sundial or some sort -of animated ring. +This cursor is typically rendered as a hourglass, +watch, sundial or some sort of animated ring. @example @group #################### @@ -9176,11 +9210,11 @@ of animated ring. @page @end ifset @item pointer -This cursor indicates that the object beneath it -is clickable. Typically a link in a web browser. -However, it should not be used for pushbuttons -and other user interface elements where it is -apparent by design that the object is clickable. +This cursor indicates that the object beneath it is +clickable. Typically a link in a web browser. +However, it should not be used for pushbuttons and +other user interface elements where it is apparent by +design that the object is clickable. This cursor is usually a right hand (left hand if left-handed) pointing with the index-finger. @@ -9240,11 +9274,10 @@ with a question mark next to it. @vskip 0pt plus 1filll @item drag -This cursor indicates that an object is -being dragged. +This cursor indicates that an object is being dragged. -This cursor is usually a closed right hand, -or closed left hand if left-handed. +This cursor is usually a closed right hand, or closed +left hand if left-handed. @example @group #### #### #### @@ -9263,14 +9296,14 @@ or closed left hand if left-handed. @page @item copy -This cursor indicates that the dragged object -will be copied or listed upon release. +This cursor indicates that the dragged object will be +copied or listed upon release. -If this cursor is missing, @code{drag} should -be used as the first fallback. +If this cursor is missing, @code{drag} should be used +as the first fallback. -This cursor is usually rendered as -@code{drag} with a plus-sign next to it. +This cursor is usually rendered as @code{drag} with a +plus-sign next to it. @example @group ## @@ -9297,17 +9330,15 @@ This cursor is usually rendered as @page @end ifset @item move -This cursor indicates that the dragged object -will be moved upon release, or otherwise -acted upon. +This cursor indicates that the dragged object will be +moved upon release, or otherwise acted upon. -If this cursor is missing, @code{drag} should -be used as the first fallback. +If this cursor is missing, @code{drag} should be used +as the first fallback. -This cursor is usually rendered as -@code{drag} with an arrow next to it. -The arrow is usually point north east, -or north west if left-handed. +This cursor is usually rendered as @code{drag} with +an arrow next to it. The arrow is usually point north +east, or north west if left-handed. @example @group ###### @@ -9332,16 +9363,16 @@ or north west if left-handed. @page @item alias -This cursor indicates that the dragged object -will be aliased upon release, or otherwise -acted upon. This may entail creating a symlink. +This cursor indicates that the dragged object will be +aliased upon release, or otherwise acted upon. This +may entail creating a symlink. -If this cursor is missing, @code{drag} should -be used as the first fallback. +If this cursor is missing, @code{drag} should be used +as the first fallback. -This cursor is usually rendered as -@code{drag} with an two or three linked -links next to it, or an arced arrow. +This cursor is usually rendered as @code{drag} with +an two or three linked links next to it, or an arced +arrow. @example @group #### #### @@ -9372,18 +9403,17 @@ links next to it, or an arced arrow. @end ifclear @end ifclear @item no-drop -This cursor indicates that the dragged object -cannot be release where the rat pointer is -located, but that the object beneath it usually -allow drops of objects with similar class to -the dragged object. +This cursor indicates that the dragged object cannot +be release where the rat pointer is located, but that +the object beneath it usually allow drops of objects +with similar class to the dragged object. -If this cursor is missing, @code{not-allowed} -should be used as the first fallback, and -@code{drag} should be used as the second fallback. +If this cursor is missing, @code{not-allowed} should +be used as the first fallback, and @code{drag} should +be used as the second fallback. -This cursor is typically rendered as a -combination of @code{drag} and @code{not-allowed}. +This cursor is typically rendered as a combination of +@code{drag} and @code{not-allowed}. @example @group ######## @@ -9408,12 +9438,11 @@ combination of @code{drag} and @code{not-allowed}. @page @item not-allowed -This cursor indicates that the region beneath -the rat pointer is invalid for the current -operation. +This cursor indicates that the region beneath the rat +pointer is invalid for the current operation. -This cursor is often rendered as a circle with -a diagonal line through it. +This cursor is often rendered as a circle with a +diagonal line through it. @example @group ######## @@ -9440,12 +9469,11 @@ a diagonal line through it. @page @end ifset @item not-allowed -This cursor is used to indicate that moving -the rat will also move the object beneath -below the cursor +This cursor is used to indicate that moving the rat +will also move the object beneath below the cursor -This cursor is often rendered as a combined -vertical and horizontal twin-headed arrow. +This cursor is often rendered as a combined vertical +and horizontal twin-headed arrow. @example @group ## @@ -9523,8 +9551,9 @@ It is typically rendered as a thick plus-sign. @page @end ifclear @item col-resize -This cursor is used to indicate the the cursor is within a region -that allows it rat to be used to resize a column. +This cursor is used to indicate the the cursor is +within a region that allows it rat to be used to +resize a column. If this cursor is missing, @code{ew-resize} should be used as the first fallback, and @code{ew-select} @@ -9564,11 +9593,12 @@ horizontally towards it. @page @end ifset @item row-resize -This cursor is used to indicate the the cursor is within a region -that allows it rat to be used to resize a column. +This cursor is used to indicate the the cursor is +within a region that allows it rat to be used to +resize a column. -If this cursor is missing, @code{ns-resize} should -be used as the first fallback, and @code{ns-select} +If this cursor is missing, @code{ns-resize} should be +used as the first fallback, and @code{ns-select} should be used as the second fallback. This cursor is typically rendered as a horizontal bar @@ -9633,17 +9663,15 @@ This cursor typically a thin crosshair. @vskip 0pt plus 1filll @item w-resize -If this cursor is missing, @code{w-select} -should be used as the first fallback, -@code{ew-resize} should be used as the -second fallback, @code{ew-select} should -be used as the third fallback, and -@code{col-resize}. should be used as -the fourth fallback. +If this cursor is missing, @code{w-select} should be +used as the first fallback, @code{ew-resize} should +be used as the second fallback, @code{ew-select} +should be used as the third fallback, and +@code{col-resize}. should be used as the fourth +fallback. -This cursor is typically rendered as a -west pointing arrow, optionally with a -wall at the arrow head. +This cursor is typically rendered as a west pointing +arrow, optionally with a wall at the arrow head. @example @group ## ## @@ -9661,16 +9689,15 @@ wall at the arrow head. @page @end ifset @item w-select -If this cursor is missing, @code{w-resize} -should be used as the first fallback, -@code{ew-select} should be used as the -second fallback, @code{ew-resize} should -be used as the third fallback, and -@code{col-resize}. should be used as -the fourth fallback. +If this cursor is missing, @code{w-resize} should be +used as the first fallback, @code{ew-select} should +be used as the second fallback, @code{ew-resize} +should be used as the third fallback, and +@code{col-resize}. should be used as the fourth +fallback. -This cursor is typically rendered as a -west pointing arrow. +This cursor is typically rendered as a west pointing +arrow. @example @group ## @@ -9693,17 +9720,15 @@ west pointing arrow. @page @end ifset @item e-resize -If this cursor is missing, @code{e-select} -should be used as the first fallback, -@code{ew-resize} should be used as the -second fallback, @code{ew-select} should -be used as the third fallback, and -@code{col-resize}. should be used as -the fourth fallback. +If this cursor is missing, @code{e-select} should be +used as the first fallback, @code{ew-resize} should +be used as the second fallback, @code{ew-select} +should be used as the third fallback, and +@code{col-resize}. should be used as the fourth +fallback. -This cursor is typically rendered as a -east pointing arrow, optionally with a -wall at the arrow head. +This cursor is typically rendered as a east pointing +arrow, optionally with a wall at the arrow head. @example @group ## ## @@ -9723,16 +9748,15 @@ wall at the arrow head. @end ifclear @end ifset @item e-select -If this cursor is missing, @code{e-resize} -should be used as the first fallback, -@code{ew-select} should be used as the -second fallback, @code{ew-resize} should -be used as the third fallback, and -@code{col-resize}. should be used as -the fourth fallback. +If this cursor is missing, @code{e-resize} should be +used as the first fallback, @code{ew-select} should +be used as the second fallback, @code{ew-resize} +should be used as the third fallback, and +@code{col-resize}. should be used as the fourth +fallback. -This cursor is typically rendered as a -east pointing arrow. +This cursor is typically rendered as a east pointing +arrow. @example @group ## @@ -9755,17 +9779,15 @@ east pointing arrow. @page @end ifset @item n-resize -If this cursor is missing, @code{n-select} -should be used as the first fallback, -@code{ns-resize} should be used as the -second fallback, @code{ns-select} should -be used as the third fallback, and -@code{row-resize}. should be used as -the fourth fallback. +If this cursor is missing, @code{n-select} should be +used as the first fallback, @code{ns-resize} should +be used as the second fallback, @code{ns-select} +should be used as the third fallback, and +@code{row-resize}. should be used as the fourth +fallback. -This cursor is typically rendered as a -north pointing arrow, optionally with a -wall at the arrow head. +This cursor is typically rendered as a north pointing +arrow, optionally with a wall at the arrow head. @example @group ############## @@ -9797,16 +9819,15 @@ wall at the arrow head. @page @end ifset @item n-select -If this cursor is missing, @code{n-resize} -should be used as the first fallback, -@code{ns-select} should be used as the -second fallback, @code{ns-resize} should -be used as the third fallback, and -@code{row-resize}. should be used as -the fourth fallback. +If this cursor is missing, @code{n-resize} should be +used as the first fallback, @code{ns-select} should +be used as the second fallback, @code{ns-resize} +should be used as the third fallback, and +@code{row-resize}. should be used as the fourth +fallback. -This cursor is typically rendered as a -north pointing arrow. +This cursor is typically rendered as a north pointing +arrow. @example @group ## @@ -9834,17 +9855,15 @@ north pointing arrow. @page @end ifset @item s-resize -If this cursor is missing, @code{s-select} -should be used as the first fallback, -@code{ns-resize} should be used as the -second fallback, @code{ns-select} should -be used as the third fallback, and -@code{row-resize}. should be used as -the fourth fallback. +If this cursor is missing, @code{s-select} should be +used as the first fallback, @code{ns-resize} should +be used as the second fallback, @code{ns-select} +should be used as the third fallback, and +@code{row-resize}. should be used as the fourth +fallback. -This cursor is typically rendered as a -south pointing arrow, optionally with a -wall at the arrow head. +This cursor is typically rendered as a south pointing +arrow, optionally with a wall at the arrow head. @example @group ## @@ -9873,16 +9892,15 @@ wall at the arrow head. @end ifclear @end ifclear @item s-select -If this cursor is missing, @code{s-resize} -should be used as the first fallback, -@code{ns-select} should be used as the -second fallback, @code{ns-resize} should -be used as the third fallback, and -@code{row-resize}. should be used as -the fourth fallback. +If this cursor is missing, @code{s-resize} should be +used as the first fallback, @code{ns-select} should +be used as the second fallback, @code{ns-resize} +should be used as the third fallback, and +@code{row-resize}. should be used as the fourth +fallback. -This cursor is typically rendered as a -south pointing arrow. +This cursor is typically rendered as a south pointing +arrow. @example @group ## @@ -9909,15 +9927,14 @@ south pointing arrow. @item nw-resize If this cursor is missing, @code{nw-select} should be used as the first fallback, -@code{nwse-resize} should be used as the -second fallback, @code{nwse-select} should -be used as the third fallback, and -@code{all-resize}. should be used as -the fourth fallback. +@code{nwse-resize} should be used as the second +fallback, @code{nwse-select} should be used as the +third fallback, and @code{all-resize}. should be used +as the fourth fallback. -This cursor is typically rendered as a -north-west pointing arrow, optionally -with a corner at the arrow head. +This cursor is typically rendered as a north-west +pointing arrow, optionally with a corner at the +arrow head. @example @group ################## @@ -9946,16 +9963,15 @@ with a corner at the arrow head. @end ifclear @end ifclear @item nw-select -If this cursor is missing, @code{nw-resize} -should be used as the first fallback, -@code{nwse-select} should be used as the -second fallback, @code{nwse-resize} should -be used as the third fallback, and -@code{all-resize}. should be used as -the fourth fallback. +If this cursor is missing, @code{nw-resize} should be +used as the first fallback, @code{nwse-select} should +be used as the second fallback, @code{nwse-resize} +should be used as the third fallback, and +@code{all-resize}. should be used as the fourth +fallback. -This cursor is typically rendered as a -north-west pointing arrow. +This cursor is typically rendered as a north-west +pointing arrow. @example @group ############ @@ -9979,17 +9995,16 @@ north-west pointing arrow. @page @end ifset @item se-resize -If this cursor is missing, @code{se-select} -should be used as the first fallback, -@code{nwse-resize} should be used as the -second fallback, @code{nwse-select} should -be used as the third fallback, and -@code{all-resize}. should be used as -the fourth fallback. +If this cursor is missing, @code{se-select} should be +used as the first fallback, @code{nwse-resize} should +be used as the second fallback, @code{nwse-select} +should be used as the third fallback, and +@code{all-resize}. should be used as the fourth +fallback. -This cursor is typically rendered as a -south-east pointing arrow, optionally -with a corner at the arrow head. +This cursor is typically rendered as a south-east +pointing arrow, optionally with a corner at the arrow +head. @example @group ## @@ -10018,16 +10033,15 @@ with a corner at the arrow head. @end ifclear @end ifclear @item se-select -If this cursor is missing, @code{se-resize} -should be used as the first fallback, -@code{nwse-select} should be used as the -second fallback, @code{nwse-resize} should -be used as the third fallback, and -@code{all-resize}. should be used as -the fourth fallback. +If this cursor is missing, @code{se-resize} should be +used as the first fallback, @code{nwse-select} should +be used as the second fallback, @code{nwse-resize} +should be used as the third fallback, and +@code{all-resize}. should be used as the fourth +fallback. -This cursor is typically rendered as a -south-east pointing arrow. +This cursor is typically rendered as a south-east +pointing arrow. @example @group ## @@ -10051,17 +10065,16 @@ south-east pointing arrow. @page @end ifset @item ne-resize -If this cursor is missing, @code{ne-select} -should be used as the first fallback, -@code{nesw-resize} should be used as the -second fallback, @code{nesw-select} should -be used as the third fallback, and -@code{all-resize}. should be used as -the fourth fallback. +If this cursor is missing, @code{ne-select} should be +used as the first fallback, @code{nesw-resize} should +be used as the second fallback, @code{nesw-select} +should be used as the third fallback, and +@code{all-resize}. should be used as the fourth +fallback. -This cursor is typically rendered as a -north-east pointing arrow, optionally -with a corner at the arrow head. +This cursor is typically rendered as a north-east +pointing arrow, optionally with a corner at the arrow +head. @example @group ################## @@ -10090,16 +10103,15 @@ with a corner at the arrow head. @end ifclear @end ifclear @item ne-select -If this cursor is missing, @code{ne-resize} -should be used as the first fallback, -@code{nesw-select} should be used as the -second fallback, @code{nesw-resize} should -be used as the third fallback, and -@code{all-resize}. should be used as -the fourth fallback. +If this cursor is missing, @code{ne-resize} should be +used as the first fallback, @code{nesw-select} should +be used as the second fallback, @code{nesw-resize} +should be used as the third fallback, and +@code{all-resize}. should be used as the fourth +fallback. -This cursor is typically rendered as a -north-east pointing arrow. +This cursor is typically rendered as a north-east +pointing arrow. @example @group ############ @@ -10123,17 +10135,16 @@ north-east pointing arrow. @page @end ifset @item sw-resize -If this cursor is missing, @code{sw-select} -should be used as the first fallback, -@code{nesw-resize} should be used as the -second fallback, @code{nesw-select} should -be used as the third fallback, and -@code{all-resize}. should be used as -the fourth fallback. +If this cursor is missing, @code{sw-select} should be +used as the first fallback, @code{nesw-resize} should +be used as the second fallback, @code{nesw-select} +should be used as the third fallback, and +@code{all-resize}. should be used as the fourth +fallback. -This cursor is typically rendered as a -south-west pointing arrow, optionally -with a corner at the arrow head. +This cursor is typically rendered as a south-west +pointing arrow, optionally with a corner at the arrow +head. @example @group ## @@ -10162,16 +10173,15 @@ with a corner at the arrow head. @end ifclear @end ifclear @item sw-select -If this cursor is missing, @code{sw-resize} -should be used as the first fallback, -@code{nesw-select} should be used as the -second fallback, @code{nesw-resize} should -be used as the third fallback, and -@code{all-resize}. should be used as -the fourth fallback. +If this cursor is missing, @code{sw-resize} should be +used as the first fallback, @code{nesw-select} should +be used as the second fallback, @code{nesw-resize} +should be used as the third fallback, and +@code{all-resize}. should be used as the fourth +fallback. -This cursor is typically rendered as a -south-west pointing arrow. +This cursor is typically rendered as a south-west +pointing arrow. @example @group ## @@ -10192,14 +10202,13 @@ south-west pointing arrow. @vskip 0pt plus 1filll @item ew-resize -If this cursor is missing, @code{ew-select} -should be used as the first fallback, and -@code{col-resize}. should be used as the -second fallback. +If this cursor is missing, @code{ew-select} should be +used as the first fallback, and @code{col-resize}. +should be used as the second fallback. -This cursor is typically rendered as a -east and west pointing twin-arrow, -optionally with a wall at the arrow heads. +This cursor is typically rendered as a east and west +pointing twin-arrow, optionally with a wall at the +arrow heads. @example @group ## ## ## ## @@ -10219,13 +10228,12 @@ optionally with a wall at the arrow heads. @end ifset @end ifset @item ew-select -If this cursor is missing, @code{ew-resize} -should be used as the first fallback, and -@code{col-resize}. should be used as the -second fallback. +If this cursor is missing, @code{ew-resize} should be +used as the first fallback, and @code{col-resize}. +should be used as the second fallback. -This cursor is typically rendered as a -east and west pointing twin-arrow. +This cursor is typically rendered as a east and west +pointing twin-arrow. @example @group ## ## @@ -10243,14 +10251,13 @@ east and west pointing twin-arrow. @page @end ifclear @item ns-resize -If this cursor is missing, @code{ns-select} -should be used as the first fallback, and -@code{row-resize}. should be used as the -second fallback. +If this cursor is missing, @code{ns-select} should be +used as the first fallback, and @code{row-resize}. +should be used as the second fallback. -This cursor is typically rendered as a -north and south pointing twin-arrow, -optionally with a wall at the arrow heads. +This cursor is typically rendered as a north and +south pointing twin-arrow, optionally with a wall at +the arrow heads. @example @group ############## @@ -10274,13 +10281,12 @@ optionally with a wall at the arrow heads. @vskip 0pt plus 1filll @item ns-select -If this cursor is missing, @code{ns-resize} -should be used as the first fallback, and -@code{row-resize}. should be used as the -second fallback. +If this cursor is missing, @code{ns-resize} should be +used as the first fallback, and @code{row-resize}. +should be used as the second fallback. -This cursor is typically rendered as a -north and south pointing twin-arrow. +This cursor is typically rendered as a north and +south pointing twin-arrow. @example @group ## @@ -10311,12 +10317,12 @@ north and south pointing twin-arrow. @page @end ifset @item nwse-resize -If this cursor is missing, @code{all-resize} -should be used as the first fallback. +If this cursor is missing, @code{all-resize} should +be used as the first fallback. -This cursor is typically rendered as a -north-west and south-east pointing twin-arrow, -optionally with a corner at the arrow heads. +This cursor is typically rendered as a north-west and +south-east pointing twin-arrow, optionally with a +corner at the arrow heads. @example @group ################## @@ -10343,12 +10349,12 @@ optionally with a corner at the arrow heads. @page @end ifset @item nesw-resize -If this cursor is missing, @code{all-resize} -should be used as the first fallback. +If this cursor is missing, @code{all-resize} should +be used as the first fallback. -This cursor is typically rendered as a -north-east and south-west pointing twin-arrow, -optionally with a corner at the arrow heads. +This cursor is typically rendered as a north-east and +south-west pointing twin-arrow, optionally with a +corner at the arrow heads. @example @group ################## @@ -10373,11 +10379,10 @@ optionally with a corner at the arrow heads. @page @item all-resize -This cursor is typically rendered as a cross -between a north-east and south-west pointing -twin-arrow and a north-west and south-east -pointing twin-arrow, optionally with a corner -at the arrow heads. +This cursor is typically rendered as a cross between +a north-east and south-west pointing twin-arrow and a +north-west and south-east pointing twin-arrow, +optionally with a corner at the arrow heads. @example @group ########## ########## @@ -10410,21 +10415,20 @@ at the arrow heads. @cpindex Applications, embedding @vrindex @env{MDS_EMBED} Applications that want to embed another other -application within it, should create a socket -and start the other application with the -environment variable @env{MDS_EMBED} set to -the windows ID of the socket that the application -should be embedded in. - -All @command{mds} applications must be aware -of the environment variable @env{MDS_EMBED}@. -The application may choose not to embed itself -in the announced socket, however it should have -good reason for not doing this. +application within it, should create a socket and +start the other application with the environment +variable @env{MDS_EMBED} set to the windows ID of the +socket that the application should be embedded in. + +All @command{mds} applications must be aware of the +environment variable @env{MDS_EMBED}@. The +application may choose not to embed itself in the +announced socket, however it should have good reason +for not doing this. All @command{mds} application must unset the -environment variable @env{MDS_EMBED} before -it starts any other program. +environment variable @env{MDS_EMBED} before it starts +any other program. @comment TODO @c How do we solve this for compatibility with X, Wayland and Mir? @@ -10443,23 +10447,22 @@ it starts any other program. @cpindex Compatibility layers @vrindex @env{PREFERRED_DISPLAY} The environment variable @env{PREFERRED_DISPLAY}, -should be set with the value @code{mds}, -if and only if @command{mds} is started -as a display server and not as a compatibility -layer. +should be set with the value @code{mds}, if and only +if @command{mds} is started as a display server and +not as a compatibility layer. @env{PREFERRED_DISPLAY} is a space-separated (U+0020) -list of supported display server protocol, ordered -by preference. +list of supported display server protocol, ordered by +preference. If @command{mds} is started as a compatibility layer, @code{mds} should be added to @env{PREFERRED_DISPLAY} if and only if @env{PREFERRED_DISPLAY} lists any other display protocol. -If a compatibility server is successfully started, -it shoul be listed in @env{PREFERRED_DISPLAY}@. -Be sure to keep the list ordered by preference. +If a compatibility server is successfully started, it +shoul be listed in @env{PREFERRED_DISPLAY}@. Be sure +to keep the list ordered by preference. @table @code @item mir @@ -10481,8 +10484,8 @@ like @command{mds-wmds}. @cpindex Compatibility layer, X.org @cpindex X.org compatibility layer Should be added if you are running an -@command{X}-to-@command{mds} server, -like @command{mds-xmds}. +@command{X}-to-@command{mds} server, like +@command{mds-xmds}. @end table @@ -10503,23 +10506,23 @@ like @command{mds-xmds}. @pgindex @code{mds-meta} @cpindex Display server, meta @cpindex Multi-display systems -A metadisplay server is a server that is connected -to one or more display server's simultaneously. -Additionally, it is acting as a display server on -its own. Any server, or even client, running in -this display will effectively be running in all -of the displays connected to the metadisplay. - -The idea of the the metadisplay server came from -the idea of letting the user have the clipboard -shared across any number of @emph{selected} -display server. Rather than having a clipboard -server written specifically for this, it was -seen as more appropriate to have a server than -could let any server run inside any number of -display server. Not only will this let the user -run any server this way. It also makes it possible -to run them across any number of computers. +A metadisplay server is a server that is connected to +one or more display server's simultaneously. +Additionally, it is acting as a display server on its +own. Any server, or even client, running in this +display will effectively be running in all of the +displays connected to the metadisplay. + +The idea of the the metadisplay server came from the +idea of letting the user have the clipboard shared +across any number of @emph{selected} display server. +Rather than having a clipboard server written +specifically for this, it was seen as more +appropriate to have a server than could let any +server run inside any number of display server. Not +only will this let the user run any server this way. +It also makes it possible to run them across any +number of computers. @pgindex @code{@command{mds-host}} @pgindex @command{mds-remote} @@ -10528,13 +10531,13 @@ If a hosting server, like @command{mds-host}, runs inside a metadisplay, any number of computers can connect to the metadisplay using a server like @command{mds-remote}. This creates a metadisplay -with multiple display from multiple computers. -If a clipboard server runs in this metadisplay, -all of these display on all of these computers -will share clipboard server. +with multiple display from multiple computers. If a +clipboard server runs in this metadisplay, all of +these display on all of these computers will share +clipboard server. -Whilst not removing or degrading any functionality. -A negative property of this setup it that it is +Whilst not removing or degrading any functionality. A +negative property of this setup it that it is centralised rather than distributed. If the computer hosting the metadisplay crashes, the other computers will no longer share this metadisplay, and lose the @@ -10567,10 +10570,9 @@ output servers, and even windowing servers. @cpindex Server architecture @cpindex Architecture, servers This chapter aims to enumerate advantages and -disadvantages with micro-display servers, -traditional monolithic display servers and -other possible designs. Please chime in with -any insight. +disadvantages with micro-display servers, traditional +monolithic display servers and other possible +designs. Please chime in with any insight. @menu * The Microserver Architecture:: The microserver architecture. @@ -10591,8 +10593,8 @@ any insight. @cpindex Architecture, microserver @cpindex Microdisplay servers Description: The display server is implement with -multiple binaries that speak with each other using -a well defined protocol. +multiple binaries that speak with each other using a +well defined protocol. @noindent Implementations: mds. @@ -10604,44 +10606,43 @@ Advantages: @item @cpindex Code quality @cpindex Quality of code -Knowing the names of the servers you use and -their purpose makes it very easy to find where -you want to do patching in the source code. +Knowing the names of the servers you use and their +purpose makes it very easy to find where you want to +do patching in the source code. @item @cpindex Code quality @cpindex Quality of code Spaghetti code to a larger extent is virtually -impossible; the microserver architecture guarantees -a certain quality of the code architecture for -the display server. +impossible; the microserver architecture guarantees a +certain quality of the code architecture for the +display server. @item @cpindex Flexibility If the message passing used in the display server allows for message modification and retrieval ordering, extending, modifying and using the display -server in unforeseen ways becomes much easier, -and will often not require any modifications to -the existing servers. +server in unforeseen ways becomes much easier, and +will often not require any modifications to the +existing servers. @item @cpindex Flexibility Replacing the display server is easier for a micro-display server than it is for a monolithic -display server, because the servers could be -replaced one by one and could even support running -under two distinct protocol during the transitional -period. +display server, because the servers could be replaced +one by one and could even support running under two +distinct protocol during the transitional period. @item @cpindex Code quality @cpindex Quality of code -Not as many subprotocols needs to be defined. -For example, recording the output of the display -does not require a special protocol, one only -needs to write a server that listens on messages -passed between servers. +Not as many subprotocols needs to be defined. For +example, recording the output of the display does not +require a special protocol, one only needs to write a +server that listens on messages passed between +servers. @item @cpindex Stability @@ -10658,13 +10659,13 @@ want the performance of @code{weston} but then flexibility and functionallity of @code{mds}, you could start @code{mds} inside @code{weston} and replace a small set of the servers with variants -written to running on top of Wayland; of course -with some functionallity of @code{mds} missing. +written to running on top of Wayland; of course with +some functionallity of @code{mds} missing. @item @cpindex Security -It is trivial to only have setuid on for the -part of the display server where it is required. +It is trivial to only have setuid on for the part of +the display server where it is required. @end itemize @@ -10675,8 +10676,8 @@ part of the display server where it is required. @cpindex Monolithic server architecture @cpindex Architecture, monolithic server @cpindex Monolithic display servers -Description: The display server is implemented -as one binary. +Description: The display server is implemented as one +binary. @noindent @cpindex X11 @@ -10691,13 +10692,14 @@ as one binary. @cpindex OS X, Quartz Compositor @cpindex Desktop Window Manager @cpindex Windows, Desktop Window Manager -Implementations: X11@footnote{X11 is a protocol, I beleave -all X11 servers are monolithic, atleast the major ones are}, -Mir, Wayland@footnote{Wayland is not actually monolithic, -it is just a protocol. But Wayland is written with a -monolithic mindset, and it is preferred that the display -server implementation is monolithic.}, Surface Flinger, -Quartz Compositor, Desktop Window Manager. +Implementations: X11@footnote{X11 is a protocol, I +beleave all X11 servers are monolithic, atleast the +major ones are}, Mir, Wayland@footnote{Wayland is not +actually monolithic, it is just a protocol. But +Wayland is written with a monolithic mindset, and it +is preferred that the display server implementation +is monolithic.}, Surface Flinger, Quartz Compositor, +Desktop Window Manager. @noindent Advantages: @@ -10708,11 +10710,11 @@ Advantages: @cpindex Privacy @cpindex Security @cpindex Flexibility -The monolithic architecture makes it trivial -to isolate information for clients to achieve -confidentiality. Prioritising confidentiality -however leads to problems implementing features -such as screenshooting and global hotkeys. +The monolithic architecture makes it trivial to +isolate information for clients to achieve +confidentiality. Prioritising confidentiality however +leads to problems implementing features such as +screenshooting and global hotkeys. @item @cpindex Performance @@ -10740,22 +10742,22 @@ footprint than its full-fledged counterparts. @cpindex Macroserver architecture @cpindex Architecture, macroserver @cpindex Macrodisplay servers -Description: The display server is implmeneted -with the microserver architecture except some -components are built into the master server for -performance or security reasons. +Description: The display server is implmeneted with +the microserver architecture except some components +are built into the master server for performance or +security reasons. @noindent Hybrid display server could arguably be called milli-display servers to emphasis that they are -small, but not as small as micro-display servers, -are much more closely related to micro-display -servers than monolithic display servers, and, in -constrast with OS kernels, have a proper distinction -from monolithic systems and microsystems. -@footnote{I don't know about calling them -macro-display servers, that implies that they are -the total opposite of micro-display servers.} +small, but not as small as micro-display servers, are +much more closely related to micro-display servers +than monolithic display servers, and, in constrast +with OS kernels, have a proper distinction from +monolithic systems and microsystems. @footnote{I +don't know about calling them macro-display servers, +that implies that they are the total opposite of +micro-display servers.} @noindent Implementations: none? @@ -10781,11 +10783,12 @@ features such as screenshooting and global hotkeys. @item @cpindex Performance -Large and high frequency messages does not need to -be passed around to other servers if they are integrated -into the master server. This lets hybrid display server -achieve the same perfomance performance as monolithic -display servers for tasks where it is desirable. +Large and high frequency messages does not need to be +passed around to other servers if they are integrated +into the master server. This lets hybrid display +server achieve the same perfomance performance as +monolithic display servers for tasks where it is +desirable. @end itemize @noindent @@ -10834,7 +10837,8 @@ Disadvantages: @item @cpindex Code quality @cpindex Quality of code -Imposes restrictions on which languages applications can use. +Imposes restrictions on which languages applications +can use. @item @cpindex Flexibility @@ -10849,19 +10853,21 @@ display server protocol. @item @cpindex Stability -The display becomes more crash prune; if an application -crashes it is likely to crash the entire display. +The display becomes more crash prune; if an +application crashes it is likely to crash the entire +display. @item @cpindex Security -Applications will run with the same privileges as the display -server, which is root on most operating systems. +Applications will run with the same privileges as the +display server, which is root on most operating +systems. @end itemize @noindent @cpindex Gaming -Megalithic display servers could be interesting for high -performing gaming consoles. +Megalithic display servers could be interesting for +high performing gaming consoles. @@ -10871,9 +10877,10 @@ performing gaming consoles. @cpindex Modular server architecture @cpindex Architecture, modular server @cpindex Modular display servers -Description: A monolithic display server where server-like -programs can be loaded as modules into the display server -but applicates are connected with interprocess communication. +Description: A monolithic display server where +server-like programs can be loaded as modules into +the display server but applicates are connected with +interprocess communication. @noindent Implementations: none?@footnote{Desktop Window Manager @@ -10901,10 +10908,10 @@ as megalithic kernels, however with the same caveats. @end itemize @noindent -With a little work the mds protocol could be transformed -into a modular server display protocol, and with some work -the reference implementation could be made into a modular -server display. +With a little work the mds protocol could be +transformed into a modular server display protocol, +and with some work the reference implementation could +be made into a modular server display. @@ -10915,9 +10922,9 @@ server display. @cpindex Architecture, modular microserver @cpindex Modular microdisplay servers Description: A modular display server with a module -that enables clients to act as modules that communicates -via interprocess communication rather than being loaded -into the display server. +that enables clients to act as modules that +communicates via interprocess communication rather +than being loaded into the display server. @noindent Implementations: none? @@ -10931,17 +10938,18 @@ The modular microserver architecture seem to provide all of the advantages of the other architecture but none of the disadvantages. However, modules can still crash and bring down the display server, but the idea -is to not load unstable modules but let the be servers. -Therefore exo-diplay server are slightly more robust. +is to not load unstable modules but let the be +servers. Therefore exo-diplay server are slightly +more robust. @end itemize @noindent -With a little work the mds protocol could be transformed -into a modular server display protocol, and with some work -the reference implementation could be made into a modular -server display. Then the untransformed version of -@command{mds-server} cound be made into a module for the -transformed version. +With a little work the mds protocol could be +transformed into a modular server display protocol, +and with some work the reference implementation could +be made into a modular server display. Then the +untransformed version of @command{mds-server} could +be made into a module for the transformed version. @@ -11016,32 +11024,35 @@ issues and discuss how they can be avoided in mds. @cpindex Cleanup, automatic @cpindex Resolution change @cpindex Games -A common critique of X.org is that the monitor resolution -is not restored if a game change the resolution and for -some reason, for instance a software crash, does not switch -back before exiting. This problem is not intrinsic to the -protocol, but rather because of a lacking protocol. You -can run a program like @command{xrandr} to change the -monitor resolution for the entirety of the session and -@command{xrandr} can exit when the resolution has changed. -This is how it should be. However, there is no way to tell -an X.org server to switch back if the connection between -the program and server is lost. This is easily fixed by -adding a lifespan parameter as found in @ref{set-gamma}. +A common critique of X.org is that the monitor +resolution is not restored if a game change the +resolution and for some reason, for instance a +software crash, does not switch back before exiting. +This problem is not intrinsic to the protocol, but +rather because of a lacking protocol. You can run a +program like @command{xrandr} to change the monitor +resolution for the entirety of the session and +@command{xrandr} can exit when the resolution has +changed. This is how it should be. However, there is +no way to tell an X.org server to switch back if the +connection between the program and server is lost. +This is easily fixed by adding a lifespan parameter +as found in @ref{set-gamma}. @cpindex Gamma correction -A similar critique of X.org is that gamma ramps are not -restored when an application exits. Either the ones -complaining about this do not understand why gamma ramps -exists, namely so you can calibrate the monitor's output -in respect to the colours, and just think it is a way -to make the video in games brighter. Or they think we -should have daemons running idly to have gamma adjustments. -Or, more likely and more validly, its is poorly phrased -and they actually want a way for applications, like games, -to inform the display server to undo its modifications to -the gamma ramps when the program exits. This is already -supported by the mds protocol. +A similar critique of X.org is that gamma ramps are +not restored when an application exits. Either the +ones complaining about this do not understand why +gamma ramps exists, namely so you can calibrate the +monitor's output in respect to the colours, and just +think it is a way to make the video in games +brighter. Or they think we should have daemons +running idly to have gamma adjustments. Or, more +likely and more validly, its is poorly phrased and +they actually want a way for applications, like +games, to inform the display server to undo its +modifications to the gamma ramps when the program +exits. This is already supported by the mds protocol. @@ -11052,46 +11063,49 @@ supported by the mds protocol. @cpindex Keyboard, grab @cpindex Mouse, grab @cpindex Input grabbing -X11 allows programs to exclusively grab keyboard -and mouse input. When a program that does this -misbehaves or become unresponsive, you cannot do -anything but manage it from another computer or -restart the computer. In mds exclusively grabbing -is achieved by setting the client priority for -the related message to the highest priority. -@footnote{If multiple clients do this, it is -arbitrary who gets the message first and can stop -the others from getting it.} This is however not -allowed (but nothing will stop you) as the idea is -that clients should either select a predefined -priority, select a priority between servers it to -be between, or select a priority of 50 percent or -150 percent of another servers priority. Thus, -unless a client breaks this rule, you can always -have your server for switching to the TTY at a -higher priority than other programs. - -A similar, and probably related, problem in X.org -is that global keybindings don't work when a -popup or menu has focus. (Thankfully GTK+ will -close that item if it receives unexpected input.) -I have hard time seeing how this could become -an issue in mds. +X11 allows programs to exclusively grab keyboard and +mouse input. When a program that does this misbehaves +or become unresponsive, you cannot do anything but +manage it from another computer or restart the +computer. In mds exclusively grabbing is achieved by +setting the client priority for the related message +to the highest priority. @footnote{If multiple +clients do this, it is arbitrary who gets the message +first and can stop the others from getting it.} This +is however not allowed (but nothing will stop you) as +the idea is that clients should either select a +predefined priority, select a priority between +servers it to be between, or select a priority of 50 +percent or 150 percent of another servers priority. +Thus, unless a client breaks this rule, you can always +have your server for switching to the TTY at a higher +priority than other programs. + +A similar, and probably related, problem in X.org is +that global keybindings don't work when a popup or +menu has focus. (Thankfully GTK+ will close that item +if it receives unexpected input.) I have hard time +seeing how this could become an issue in mds. +@cpindex Hotkeys +@cpindex Keyboard bindings +@cpindex Bindings, keyboard +@cpindex Keyboard shortcuts +@cpindex Shortcuts, keyboard Another issue related to the keyboard in X.org is that hotkeys in programs do not work in a few -situtations because the program was not designed -with another keyboard layout in mind than the -keyboard layout the developer used. I suggest -that programs restrain themself from including -Alternative Graph in their hotkeys and only use -Shift for A through Z and space. However, what -I would really like to see is that toolkits lets -users modify all hotkeys. If program additionally -restrain themself to having all hotkeys contain -control or alt the keyboard layouts with non-latin -alphabets would not suffer because they do not -use the latin alphabet. +situtations because the program was not designed with +another keyboard layout in mind than the keyboard +layout the developer used. I suggest that programs +restrain themself from including +@key{Alternative Graph} in their hotkeys and only use +@key{Shift} for @key{a} through @key{Z} and +@key{Space}. However, what I would really like to see +is that toolkits lets users modify all hotkeys. If +program additionally restrain themself to having all +hotkeys contain control or alt the keyboard layouts +with non-latin alphabets would not suffer because +they do not use the latin alphabet. @@ -11109,11 +11123,11 @@ otherwise replace graphics drivers online. Or other parts of it. X11 display servers could allow you to send a signal, for instance @code{SIGUSR1}, to upgrade the whole server, however this is not favourable, and -X.org does not do this. The reference implemention -of the mds protocol lets you safely upgrade any part -of it online by sending @code{SIGUSR1} to the server -that should be upgraded. On catastrophic failure in -this process the server would restart and lose volatile +X.org does not do this. The reference implemention of +the mds protocol lets you safely upgrade any part of +it online by sending @code{SIGUSR1} to the server that +should be upgraded. On catastrophic failure in this +process the server would restart and lose volatile data, but the server should be upgraded and it would ask all running clients for resend information the server lost. @@ -11126,10 +11140,10 @@ Another issue with X.org is that it is not multithreaded, which can cased intensive programs to freeze your desktop. mds is inherently pervasively parallel and only subsystems, rather than the whole -system, can suffer from this. It is however easy -for mds servers to implement pervasive threading, -that is, letting each request spin up a new thread -in the server. +system, can suffer from this. It is however easy for +mds servers to implement pervasive threading, that +is, letting each request spin up a new thread in the +server. @@ -11137,42 +11151,41 @@ in the server. @section Why Not Wayland @cpindex Wayland -Development of @command{mds} started out of -concern that Wayland would not meet our needs, -and the knowledge that X does not. We are now -however aware that Wayland meets our needs even -less than X@.@footnote{Not even counting that -the documentation for Wayland is way more lacking -that X's documentation.} +Development of @command{mds} started out of concern +that Wayland would not meet our needs, and the +knowledge that X does not. We are now however aware +that Wayland meets our needs even less than X@. +@footnote{Not even counting that the documentation +for Wayland is way more lacking that X's +documentation.} @cpindex Flexibility -Wayland only has protocols for drawing onto a -buffer and input devices, and some very limited -output protocols. Wayland is inherently inflexible. -If anyone wants to add additional functionally, must -do so in the compositor --- the window manager --- -and publish the protocol. It is then up to all -other compostors (window managers) to implement -the protocol. - -It should be noted that Wayland does not even -have an official protocol for applying gamma -corrects. Some compositors (window managers) -choose to implement it by using @command{colord}. - -Additionally, screenshooting, screen recording -and global hotkeys must be implemented in the -compositor (window manager). Why? Because of -security. In Wayland, security always trumps -useability and usefulness. - -Another huge limitation of Wayland is that it -does not have any network protocol. For it to -be network, the compositor must implement a -network protocol --- and there is no official -network protocol. When this is all done, a -compositor proxy must be written that can -communicate with it. +Wayland only has protocols for drawing onto a buffer +and input devices, and some very limited output +protocols. Wayland is inherently inflexible. If +anyone wants to add additional functionally, must do +so in the compositor --- the window manager --- and +publish the protocol. It is then up to all other +compostors (window managers) to implement the +protocol. + +It should be noted that Wayland does not even have an +official protocol for applying gamma corrects. Some +compositors (window managers) choose to implement it +by using @command{colord}. + +Additionally, screenshooting, screen recording and +global hotkeys must be implemented in the compositor +(window manager). Why? Because of security. In +Wayland, security always trumps useability and +usefulness. + +Another huge limitation of Wayland is that it does +not have any network protocol. For it to be network, +the compositor must implement a network protocol --- +and there is no official network protocol. When this +is all done, a compositor proxy must be written that +can communicate with it. @@ -11181,9 +11194,9 @@ communicate with it. @cpindex Mir The major problem with Mir, and why we need -@command{mds} instead, is that contributions -to Mir are subject Canonical's -contributions-limiting agreement (CLA). +@command{mds} instead, is that contributions to Mir +are subject Canonical's contributions-limiting +agreement (CLA). @cpindex Flexibility Mir, like Wayland, is very limited. Mir is however @@ -11191,10 +11204,10 @@ easier to extend. Ignoring the CLA, Mir is better Wayland, but for similar reasons it is still not good enough. -Mir is however licensed under the GNU General -Public License version 3 and GNU Lesser General -Public License version 3. Much better than the -MIT license, and hopefully we can steal some stuff. +Mir is however licensed under the GNU General Public +License version 3 and GNU Lesser General Public +License version 3. Much better than the MIT license, +and hopefully we can steal some stuff. @@ -11204,11 +11217,11 @@ MIT license, and hopefully we can steal some stuff. @cpindex Goals of @command{mds} @cpindex Desktop environments @cpindex Environment, desktop -A design goal of @command{mds} is to bring unity -to the graphical environment. Something desktop +A design goal of @command{mds} is to bring unity to +the graphical environment. Something desktop environments traditionally have been impairing. -Traditionally a desktop environment would -implement, or implement some of: +Traditionally a desktop environment would implement, +or implement some of: @itemize @bullet{} @item Window layout management (window manager) @@ -11248,16 +11261,16 @@ Their own graphical toolkit A bunch of random graphical tools @end itemize -This is absolute madness, a waste of time -and creates fragmentation. +This is absolute madness, a waste of time and creates +fragmentation. There is no problem for a desktop environment -development team to implement all this for -their desktop environment for @command{mds}. -However doing so is discourage for the mentioned -reasons as well as because doing so means that -the user needs to know what not to launch, -that is, what the desktop environment will start. +development team to implement all this for their +desktop environment for @command{mds}. However doing +so is discourage for the mentioned reasons as well as +because doing so means that the user needs to know +what not to launch, that is, what the desktop +environment will start. @menu * Window Management:: Window management in mds. @@ -11276,39 +11289,41 @@ that is, what the desktop environment will start. @cpindex Hotkeys @cpindex Keyboard bindings @cpindex Bindings, keyboard +@cpindex Keyboard shortcuts +@cpindex Shortcuts, keyboard @pgindex @command{mds-keybind} -For @command{mds}, a desktop environment should -not have its own window layout manager. A better -solution is to have a few well written window -layout manager that are different from each -other in how windows are layed out. These should -not listen for keyboard actions to figure out -how it shall rearrange the windows. Instead -they should listen on the display server's -messaging system for such commands, and -@command{mds-keybind} or similar server should -be configured with all hotkeys. +For @command{mds}, a desktop environment should not +have its own window layout manager. A better solution +is to have a few well written window layout manager +that are different from each other in how windows are +layed out. These should not listen for keyboard +actions to figure out how it shall rearrange the +windows. Instead they should listen on the display +server's messaging system for such commands, and +@command{mds-keybind} or similar server should be +configured with all hotkeys. @cpindex Window decorators @cpindex Decorators, windows -There are a few classes of window decorator. -A desktop environment still do not need its -own. They can however create themes for existing -decorators. What we need here is a small set -of window decorators that are very customisable. +There are a few classes of window decorator. A +desktop environment still do not need its own. They +can however create themes for existing decorators. +What we need here is a small set of window decorators +that are very customisable. @cpindex Workspaces @cpindex Pagers Workspaces in X is poorly done. Window managers -implement it, and pagers are window manager -dependent@footnote{Well, there is Extended Window -Manager Hints (EWMH), but it is very restricted.}. -Yet there are very few properties they can have: +implement it, and pagers are window manager dependent +@footnote{Well, there is Extended Window Manager +Hints (EWMH), but it is very restricted.}. Yet there +are very few properties they can have: @itemize @bullet{} @item Do workspaces span outputs, screens or the display? @item -Are workspaces dependent on outputs, screens or displays? +Are workspaces dependent on outputs, screens or +displays? @item Do workspaces have a geometrical position? @item @@ -11316,8 +11331,8 @@ Are new workspaces created when needed? @end itemize Clearly what we need is one workspace manager where these can be configured. And the desktop environments -can create their own pagers if they see fit, but -all pagers work everywhere. +can create their own pagers if they see fit, but all +pagers work everywhere. @cpindex Compositors @cpindex Fancy effects @@ -11325,11 +11340,11 @@ all pagers work everywhere. Traditionally desktop environments wrote their own compositor for flash or otherwise fancy effects, or write a quirks to a common one so the common on could -be used. With all other parts, of what has traditionally -be the window manager, independent of the desktop -environment, creating one universal compositor with -plugin support for effects the desktop environment -want to have, such be no problem. +be used. With all other parts, of what has +traditionally be the window manager, independent of +the desktop environment, creating one universal +compositor with plugin support for effects the +desktop environment want to have, such be no problem. @@ -11342,11 +11357,11 @@ want to have, such be no problem. @cpindex EWMH (Extended Window Manager Hints) Many X desktop environments provide taskbars, where all windows are listed. However because of Extended -Window Manager Hints (EWMH), and the ability to -read windows' position and wait for windows to -move, this is not actually necessary. Of course, -desktop environments may need to do this to theme -the environment. A taskbar for @command{mds} should: +Window Manager Hints (EWMH), and the ability to read +windows' position and wait for windows to move, this +is not actually necessary. Of course, desktop +environments may need to do this to theme the +environment. A taskbar for @command{mds} should: @itemize @bullet{} @item be about to restrict listed windows a those under @@ -11361,22 +11376,22 @@ workspaces. @cpindex Tray, status icons Traditionally, status icon trays have been implemented with window embed method. And apart -from there being two competing standard, this -is pretty sane. But ther have been some -restrictions @command{mds} does not suffer: +from there being two competing standard, this is +pretty sane. But ther have been some restrictions +@command{mds} does not suffer: @itemize @bullet{} @item icons should not be rearranged, and @item -embedder did not know of the background -looked where the icon was added. +embedder did not know of the background looked where +the icon was added. @end itemize -Desktop environments should feel free to create -their own themed application launchers and -application menus. This functionally is already -de facto standardised, and there is no reason to -change anything. +Desktop environments should feel free to create their +own themed application launchers and application +menus. This functionally is already de facto +standardised, and there is no reason to change +anything. @cpindex Startup of applications, automatic @cpindex Automatic startup of application @@ -11385,8 +11400,8 @@ change anything. Some desktop environments provide a method to for automatically starting applications during the startup of a desktop environment. This is -discouraged. It is better to teach the user to -edit @file{~/.mdsinitrc}. +discouraged. It is better to teach the user to edit +@file{~/.mdsinitrc}. @@ -11398,14 +11413,16 @@ edit @file{~/.mdsinitrc}. @cpindex Hotkeys @cpindex Keyboard bindings @cpindex Bindings, keyboard +@cpindex Keyboard shortcuts +@cpindex Shortcuts, keyboard @pgindex @command{mds-keybind} -Many desktop environments and window managers -for X implement global keyboard bindings. -This is not how you should do this. The servers -should recognise commands passed via -@command{mds}'s interprocess communication. -Configurations of the keyboard bindings should -be done in a server like @command{mds-keybind}. +Many desktop environments and window managers for X +implement global keyboard bindings. This is not how +you should do this. The servers should recognise +commands passed via @command{mds}'s interprocess +communication. Configurations of the keyboard +bindings should be done in a server like +@command{mds-keybind}. @pgindex @command{mds-ratbind} @cpindex Rat bindings @@ -11419,10 +11436,10 @@ be done in a server like @command{mds-keybind}. @cpindex Pointer barriers @cpindex Screen edges, barriers @cpindex Barriers, rat -Similarily some desktop environments implement -rat bindings@footnote{Notably hot corners.} and -rat barriers. This too should be done via servers -like like @command{mds-ratbind} and like +Similarily some desktop environments implement rat +bindings@footnote{Notably hot corners.} and rat +barriers. This too should be done via servers like +like @command{mds-ratbind} and like @command{mds-ratbarrier}. @@ -11437,30 +11454,27 @@ like like @command{mds-ratbind} and like @cpindex Window, root Desktop environments provide their own desktop because they want it to fit the rest of the -environment. For example, it can use components -of the desktop environment's file manager. -This practice is however problematic, because -they also implement the background, which is -also implemented on top of the root windows. -@command{mds} desktops should use a transparent -background and let the root window be used for -implementing the background. +environment. For example, it can use components of +the desktop environment's file manager. This practice +is however problematic, because they also implement +the background, which is also implemented on top of +the root windows. @command{mds} desktops should use a +transparent background and let the root window be +used for implementing the background. @cpindex Desktop widgets @cpindex Widgets, desktop Additionally, some desktop environments provide -desktop widgets. These can either be drawn on -the root window, the desktop window or as -always-on-bottom windows. In @command{mds}, -windows can have Z-order priority. That is, you -can specify how important it is that your window -is at the bottom or at the top. For widgets -with input, it is recommended to use this -to put the widget just above the desktop window. -For windows without input, it is recommended -draw on the root windows. However doing so -requires that be listen for updates to the -backgrund. +desktop widgets. These can either be drawn on the +root window, the desktop window or as +always-on-bottom windows. In @command{mds}, windows +can have Z-order priority. That is, you can specify +how important it is that your window is at the bottom +or at the top. For widgets with input, it is +recommended to use this to put the widget just above +the desktop window. For windows without input, it is +recommended draw on the root windows. However doing so +requires that be listen for updates to the backgrund. |