keycap vs keysym

What is the difference please, semantically?

Context, texinfo has key (a label on a key)
but it also has key which my keyboard doesn't
have.

Which is the more general docbook 4.5 markup please?

regards


-- 
Dave Pawson
XSLT, XSL-FO and Docbook FAQ
http://www.dpawson.co.uk



------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

HI DAVE,

ON MONTAG, 24. SEPTEMBER 2007, DAVE PAWSON WROTE:
> WHAT IS THE DIFFERENCE PLEASE, SEMANTICALLY?

ACCORDING TO THE TDG:

  KEYCAP €” THE TEXT PRINTED ON A KEY ON A KEYBOARD
  KEYSYM €” THE SYMBOLIC NAME OF A KEY ON A KEYBOARD

THE TDG GIVES YOU AN EXAMPLE:

<PARA>
THE <KEYCAP>F1</KEYCAP> KEY ON AN IBM PC
KEYBOARD GENERATES THE
SCAN CODE <KEYCODE>0X3B</KEYCODE> WHEN PRESSED. 
THIS VALUE
IS DEFINED AS <KEYSYM>KEY_F1</KEYSYM> IN 
<FILENAME
CLASS="HEADERFILE">KEYBOARD.H</FILENAME>.

</PARA>

OR IN OTHER WORDS, ROUGHLY SPOKEN: USE KEYCAP IF YOUR READER
HAS TO PRESS 
A KEY. USE KEYSYM IF YOU "DEVELOP" A PROGRAM AND
TALK ABOUT A SYMBOLIC 
NAME OF A KEY.


> CONTEXT, TEXINFO HAS KEY (A LABEL ON A
KEY)
> BUT IT ALSO HAS KEY WHICH MY KEYBOARD DOESN'T
HAVE.
>
> WHICH IS THE MORE GENERAL DOCBOOK 4.5 MARKUP PLEASE?

I AM NOT SURE, BUT MAYBE THIS IS AN OPTION:

  <KEYCAP FUNCTION="OTHER"
OTHERFUNCTION="...">PRIOR</KEYCAP>

INVENT YOUR MEANING FOR THE OTHERFUNCTION ATTRIBUTE.


BYE,
TOM

-- 
THOMAS SCHRAITLE

------------------------------------------------------------
---------
TO UNSUBSCRIBE, E-MAIL: DOCBOOK-UNSUBSCRIBELISTS.OASIS-OPEN.ORG
FOR ADDITIONAL COMMANDS, E-MAIL: DOCBOOK-HELPLISTS.OASIS-OPEN.ORG

Thomas Schraitle wrote:
> Hi Dave,
> 
> On Montag, 24. September 2007, Dave Pawson wrote:
>> What is the difference please, semantically?
> 
> According to the TDG:
> 
>   keycap — The text printed on a key on a keyboard
>   keysym — The symbolic name of a key on a keyboard
> 
> The TDG gives you an example:


> Or in other words, roughly spoken: Use keycap if your
reader has to press 
> a key. Use keysym if you "develop" a program
and talk about a symbolic 
> name of a key.
> 
> 
>> Context, texinfo has key (a label on a
key)
>> but it also has key which my
keyboard doesn't have.
>>
>> Which is the more general docbook 4.5 markup
please?
> 
> I am not sure, but maybe this is an option:
> 
>   <keycap function="other"
otherfunction="...">PRIOR</keycap>
> 
> Invent your meaning for the otherfunction attribute.

Emacs is very heavy on key bindings.
M-C-F1  is press ALT, control and F1.

How might that be marked up?
M-x revert-buffer is another command.

It seems a mix between user input and key|sym|cap
There is no 'M' key (stands for META).

regards




-- 
Dave Pawson
XSLT, XSL-FO and Docbook FAQ
http://www.dpawson.co.uk



------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

Quoting Dave Pawson <davepdpawson.co.uk>:

> Emacs is very heavy on key bindings.
> M-C-F1  is press ALT, control and F1.
>
> How might that be marked up?
> M-x revert-buffer is another command.
>
> It seems a mix between user input and key|sym|cap
> There is no 'M' key (stands for META).
>

The Emacs meta key is especially weird as it depends on the
keyboard  
and your environment. E.g. on a PC running a graphical
interface, the  
Alt key works ok if you press it simultaneously with another
key. When  
running in a terminal, Alt may not work, and you have to
resort to  
pressing the Esc key as a prefix key, followed by the next
key. The  
former might be represented as:

<keycombo><keycap>Alt</keycap><keycap&g
t;x</keycap></keycombo>

whereas the latter would be something like:

<keycap>Esc</keycap><keycap>x</keycap&g
t;

So even if you would move away from the key caps to not
depend on what  
is printed on the key, you'd still be wrong about pressing
the keys at  
the same time or one after the other in 50% of the cases.
But I also  
think if you're writing about Emacs for end users, the key
caps are  
what counts.

regards,
Markus



-- 
Markus Hoenicka
markus.hoenickacats.de
(Spam-protected email: replace the quadrupeds with
"mhoenicka")
http://www.mhoenicka.de


------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

Hi Dave,

On Montag, 24. September 2007, Dave Pawson wrote:
> [...]
> Emacs is very heavy on key bindings.
> M-C-F1  is press ALT, control and F1.
>
> How might that be marked up?

 <keycombo action="press">
    <keycap
function="meta">M</keycap>
    <keycap
function="control">Ctrl</keycap>
    <keycap>F1</keycap>
 </keycombo>


> M-x revert-buffer is another command.

 <keycombo>
   <keycap function="meta">M</keycap>
   <keycap>x</keycap>
 </keycombo>
 <command>revert-buffer</command>


> It seems a mix between user input and key|sym|cap
> There is no 'M' key (stands for META).

Use the "action" attribute with the value
"meta" (as shown above). 


Bye,
Tom

-- 
Thomas Schraitle

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

Thomas Schraitle wrote:
> Hi Dave,
> 
> On Montag, 24. September 2007, Dave Pawson wrote:
>> [...]
>> Emacs is very heavy on key bindings.
>> M-C-F1  is press ALT, control and F1.
>>
>> How might that be marked up?
> 
>  <keycombo action="press">
>     <keycap
function="meta">M</keycap>
>     <keycap
function="control">Ctrl</keycap>
>     <keycap>F1</keycap>
>  </keycombo>


Yes. I like that. Looks right to me! Thanks.
Markus, I agree about Meta not being a 'key'... but
in the emacs manuals I think it would be plain.
Given that caveat, can you improve on Thomas' input above?

> 
> 
>> M-x revert-buffer is another command.
> 
>  <keycombo>
>    <keycap
function="meta">M</keycap>
>    <keycap>x</keycap>
>  </keycombo>
>  <command>revert-buffer</command>

Less sure about this. revert-buffer isn't a command...
This is why I mentioned <userinput>... except you
can't have userinput within keycombo, so it would
need to be external, i.e. not in the same wrapper.

Also, emacs has this idea that Meta X is written M-x
Control X is written C-X to indicate that they
are pressed together?
Is the hyphen 'styling' (i.e. introduce at the xslt stage?)

Another example

C-x w r    means  unhighlight-regexp

<keycombo> seems wrong with the combinations?
<keycombo>C-x</keycombo><userinput>w
r</

Still missing the wrapper.

Is the content model wrong? I.e. allow CDATA within
keycombo?

regards

-- 
Dave Pawson
XSLT, XSL-FO and Docbook FAQ
http://www.dpawson.co.uk



------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

Quoting Dave Pawson <davepdpawson.co.uk>:

> Markus, I agree about Meta not being a 'key'... but
> in the emacs manuals I think it would be plain.
> Given that caveat, can you improve on Thomas' input
above?
>

No, looks good to me too.

> C-x w r    means  unhighlight-regexp
>
> <keycombo> seems wrong with the combinations?
> <keycombo>C-x</keycombo><userinput>w
r</
>

My gut feeling is that in this case "w r" should
not be treated as  
userinput, but as keypresses that belong to a command
sequence. This  
is different from pressing M-x, which gets you into a
command prompt  
in the minibuffer. So, the former should be like (leaving
out the  
attribute tinsel):

<keycombo><keycap>Ctrl</keycap><keycap&
gt;x</keycap></keycombo><keycap>w</keyc
ap><keycap  
 >r</keycap>

whereas I'd write the latter as:

<keycombo><keycap>Alt</keycap><keycap&g
t;x</keycap></keycombo><keycap>revert-buff
er</keycap>

regards,
Markus

-- 
Markus Hoenicka
markus.hoenickacats.de
(Spam-protected email: replace the quadrupeds with
"mhoenicka")
http://www.mhoenicka.de


------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

Hi Dave,

On Montag, 24. September 2007, Dave Pawson wrote:
> [...]
> >> How might that be marked up?
> >
> >  <keycombo action="press">
> >     <keycap
function="meta">M</keycap>
> >     <keycap
function="control">Ctrl</keycap>
> >     <keycap>F1</keycap>
> >  </keycombo>
>
> Yes. I like that. Looks right to me! Thanks.
> Markus, I agree about Meta not being a 'key'... but

But why can I markup it in keycap with the
"function" attribute? It looks 
right to me. 


> in the emacs manuals I think it would be plain.
> Given that caveat, can you improve on Thomas' input
above?
>
> >> M-x revert-buffer is another command.
> >
> >  <keycombo>
> >    <keycap
function="meta">M</keycap>
> >    <keycap>x</keycap>
> >  </keycombo>
> >  <command>revert-buffer</command>
>
> Less sure about this. revert-buffer isn't a command...

I wasn't sure either.  See also
the next paragraph.


> This is why I mentioned <userinput>... except
you
> can't have userinput within keycombo, so it would
> need to be external, i.e. not in the same wrapper.

This is probably a matter of interpretation. Some would 
see "revert-buffer" as a command, others as
userinput. I interpreted the 
words as an Emacs command. 


> Also, emacs has this idea that Meta X is written M-x
> Control X is written C-X to indicate that they
> are pressed together?

Use action="press" in keycombo. It seems the
DocBook stylesheets use this 
as default.


> Is the hyphen 'styling' (i.e. introduce at the xslt
stage?)
>
> Another example
>
> C-x w r    means  unhighlight-regexp
>
> <keycombo> seems wrong with the combinations?
> <keycombo>C-x</keycombo><userinput>w
r</
>
> Still missing the wrapper.

Try this:

 <keycombo action="seq">
    <keycombo action="press">
      <keycap
function="control">Ctrl</keycap>
      <keycap>x</keycap>
    </keycombo>
    <keycap>w</keycap>
    <keycap>r</keycap>
 </keycombo>

After transformation it is shown as: Ctrl-x w r


> Is the content model wrong? I.e. allow CDATA within
keycombo?

No, CDATA is not allowed inside keycombo. The content modell
is:

  keycombo ::= ((keycap|keycombo|keysym|mousebutton)+)


Bye,
Tom

-- 
Thomas Schraitle

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

On 24/09/2007, Dave Pawson <davepdpawson.co.uk> wrote:
> C-x w r    means  unhighlight-regexp
>
> <keycombo> seems wrong with the combinations?
> <keycombo>C-x</keycombo><userinput>w
r</

You can use the action attribute of keycombo to distinguish
between
sequences of keys and keys pressed together. So this could
be written
as:

  <keycombo action="seq">
    <keycombo action="simul">
      <keycap
function="control">Ctrl</keycap>
      <keycap>x</keycap>
    </keycombo>
    <keycap>w</keycap>
    <keycap>r</keycap>
  </keycombo>

> Less sure about this. revert-buffer isn't a command...
> This is why I mentioned <userinput>... except
you
> can't have userinput within keycombo, so it would
> need to be external, i.e. not in the same wrapper.

You could use <keycombo action="seq"> as
above, since the user has to
press r, e, v, etc in sequence, but it would be good to use
different
markup for a sequence of conceptually separate keys (as in
C-x w r)
and for a sequence where you're typing a word. This
distinction is
useful for presentation as well as semantics - normally in
Emacs
documentation you see spaces between keys in sequences like
"C-x w r"
but not between letters in command names like "M-x
revert-buffer". You
could use something like <keycombo
action="other" otheraction="type">
where the meaning of the otheraction attribute is defined by
the user
or style sheet. But if you're treating the sequence
"revert-buffer" as
a keycombo you should probably have a separate keycap
element for each
letter, which is a bit cumbersome. I would probably use
something
like:

  <phrase>
    <keycombo action="simul">
      <keycap
action="meta">Meta</keycap>
      <keycap>x</keycap>
    </keycombo>
    <function>revert-buffer</function>
  </phrase>

Although maybe there's a better wrapping element than
phrase. I used
the function element for "revert-buffer" since
it's an Emacs Lisp
function, but maybe command or userinput would also be
appropriate.

> Also, emacs has this idea that Meta X is written M-x
> Control X is written C-X to indicate that they
> are pressed together?
> Is the hyphen 'styling' (i.e. introduce at the xslt
stage?)

I'd say it is. Then you can use different style sheet
settings or
customisations depending on the conventions for the
documentation
you're producing. The key combination of control and X
together could
be written as "C-x", "Ctrl-X",
"Control+X", "^X", etc and it seems to
me that the markup should be the same and the rendering
governed by
the style sheet.

Hope this helps,

Andy

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

Quoting Markus Hoenicka <markus.hoenickamhoenicka.de>:

>
<keycombo><keycap>Alt</keycap><keycap&g
t;x</keycap></keycombo><keycap>revert-buff
er</keycap>
>

This should of course have been:

<keycombo><keycap>Alt</keycap><keycap&g
t;x</keycap></keycombo><userinput>revert-b
uffer</userinput>

sorry for the confusion

Markus

-- 
Markus Hoenicka
markus.hoenickacats.de
(Spam-protected email: replace the quadrupeds with
"mhoenicka")
http://www.mhoenicka.de


------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org