1
0
Fork 0

A bit more detail

This commit is contained in:
Miguel de Benito 2012-08-31 16:03:13 +00:00
parent d6db1397dd
commit d185d5e96e
1 changed files with 26 additions and 24 deletions

View File

@ -1,4 +1,4 @@
<TeXmacs|1.0.7.1> <TeXmacs|1.0.7.16>
<style|tmdoc> <style|tmdoc>
@ -10,7 +10,7 @@
complete overview of the program, it is a good practive to associate complete overview of the program, it is a good practive to associate
additional <em|meta-information> to the individual routines and data. This additional <em|meta-information> to the individual routines and data. This
meta-information typically serves documentation purposes, but becomes even meta-information typically serves documentation purposes, but becomes even
more interesting if it can be used in an automized fashion to implement more interesting if it can be used in an automated fashion to implement
more general additional functionality. more general additional functionality.
The <scm|tm-define> macro supports several options for associating The <scm|tm-define> macro supports several options for associating
@ -19,7 +19,7 @@
associate short documentation strings to the function, its arguments and associate short documentation strings to the function, its arguments and
its return value: its return value:
<\scm-fragment> <\scm-code>
(tm-define (square x) (tm-define (square x)
\ \ (:synopsis "Compute the square of @x") \ \ (:synopsis "Compute the square of @x")
@ -29,14 +29,15 @@
\ \ (:returns "The square of @x") \ \ (:returns "The square of @x")
\ \ (* x x)) \ \ (* x x))
</scm-fragment> </scm-code>
This information is exploited by <TeXmacs> in several ways. For instance, This information is exploited by <TeXmacs> in several ways. For instance,
the synopsis of the function can be retrieved by executing <scm|(help the synopsis of the function can be retrieved by executing <scm|(help
square)>. More interestingly, assuming that we defined <scm|square> as square)>. More interestingly, assuming that we defined <scm|square> as
above, typing <shortcut|(interactive exec-interactive-command)> followed by <scm|square> and <shortcut|(kbd-return)> above, typing <shortcut|(interactive exec-interactive-command)> followed by
allows you to execute <scm|square> in an interactive way: you will be <scm|square> and <shortcut|(kbd-return)> allows you to execute <scm|square>
prompted for ``A number'' on the footer. Moreover, after typing <shortcut|(interactive exec-interactive-command)>, in an interactive way: you will be prompted for ``A number'' on the footer.
Moreover, after typing <shortcut|(interactive exec-interactive-command)>,
you will be able to use ``tab-completion'' in order to enter <scm|square>: you will be able to use ``tab-completion'' in order to enter <scm|square>:
typing <key|s q u tab> will usually complete into<nbsp><scm|square>. typing <key|s q u tab> will usually complete into<nbsp><scm|square>.
@ -45,32 +46,32 @@
or when it should give rise to a check-mark when used in a menu. For or when it should give rise to a check-mark when used in a menu. For
instance, the statement instance, the statement
<\scm-fragment> <\scm-code>
(tm-property (choose-file fun text type) (tm-property (choose-file fun text type)
\ \ (:interactive #t)) \ \ (:interactive #t))
</scm-fragment> </scm-code>
in the source code of <TeXmacs> states that <scm|choose-file> is an in the source code of <TeXmacs> states that <scm|choose-file> is an
interactive command. As a consquence, the <menu|File|Load> entry, which is interactive command. As a consquence, the <menu|File|Load> entry, which is
defined by defined by
<\scm-fragment> <\scm-code>
("Load" (choose-file load-buffer "Load file" "")) ("Load" (choose-file load-buffer "Load file" ""))
</scm-fragment> </scm-code>
will be followed by dots <scm|...> in the <menu|File> menu. The interesting will be followed by dots <scm|...> in the <menu|File> menu. The interesting
point here is that, although the command <scm|choose-file> may be reused point here is that, although the command <scm|choose-file> may be reused
several times in different menu entries, we only have to specify once that several times in different menu entries, we only have to specify once that
it is an interactive command. Similarly, consider the definition it is an interactive command. Similarly, consider the definition
<\scm-fragment> <\scm-code>
(tm-define (toggle-session-math-input) (tm-define (toggle-session-math-input)
\ \ (:check-mark "v" session-math-input?) \ \ (:check-mark "v" session-math-input?)
\ \ (session-use-math-input (not (session-math-input?)))) \ \ (session-use-math-input (not (session-math-input?))))
</scm-fragment> </scm-code>
Given a menu item with <scm|(toggle-session-math-input)> as its associated Given a menu item with <scm|(toggle-session-math-input)> as its associated
action, this definition specifies in particular that a check-mark should be action, this definition specifies in particular that a check-mark should be
@ -78,14 +79,15 @@
predicate holds. predicate holds.
Another frequently used option is <scm|:secure>, which specifies that a Another frequently used option is <scm|:secure>, which specifies that a
given routine is secure. For instance, the default implementation of the given routine can be used inside <TeXmacs> documents, in particular inside
<markup|fold> tag allows the user to click on the <markup|extern> and <markup|action> macros. For instance, the default
``<with|mode|math|<op|\<circ\>>>'' before the folded text so as to unfold implementation of the <markup|fold> tag allows the user to click on the
the tag. When doing this, the scheme script <scm|(mouse-unfold)> is ``<math|<op|\<circ\>>>'' before the folded text so as to unfold the tag.
launched. However, for this to work, the <scm|mouse-unfold> function needs When doing this, the scheme script <scm|(mouse-unfold)> is launched.
to be secure: However, for this to work, the <scm|mouse-unfold> function needs to be
secure:
<\scm-fragment> <\scm-code>
(tm-define (mouse-unfold) (tm-define (mouse-unfold)
\ \ (:secure #t) \ \ (:secure #t)
@ -95,11 +97,11 @@
\ \ \ \ (tree-go-to t :start) \ \ \ \ (tree-go-to t :start)
\ \ \ \ (fold))) \ \ \ \ (fold)))
</scm-fragment> </scm-code>
The <scm|:secure> option is also needed in combination with <hlink|other You can read more about the tags which depend on <scheme> scripts in
tags|overview-start.en.tm#markup-scripts> which depend on <scheme> scripts, ``<hlink|Invoking <scheme> scrips from <TeXmacs>
like <markup|extern>. markup|overview-start.en.tm#markup-scripts>''.\
In the future, the number of options for entering meta-information is In the future, the number of options for entering meta-information is
likely to increase. <TeXmacs> also supports an additional mechanism for the likely to increase. <TeXmacs> also supports an additional mechanism for the