mirror of
https://git.lyx.org/repos/lyx.git
synced 2024-11-06 11:23:45 +00:00
1778 lines
33 KiB
Plaintext
1778 lines
33 KiB
Plaintext
#LyX 2.2 created this file. For more info see http://www.lyx.org/
|
|
\lyxformat 503
|
|
\begin_document
|
|
\begin_header
|
|
\origin unavailable
|
|
\textclass article
|
|
\use_default_options false
|
|
\maintain_unincluded_children false
|
|
\language british
|
|
\language_package default
|
|
\inputencoding auto
|
|
\fontencoding global
|
|
\font_roman "default" "default"
|
|
\font_sans "default" "default"
|
|
\font_typewriter "default" "default"
|
|
\font_math "auto" "auto"
|
|
\font_default_family default
|
|
\use_non_tex_fonts false
|
|
\font_sc false
|
|
\font_osf false
|
|
\font_sf_scale 100 100
|
|
\font_tt_scale 100 100
|
|
\graphics default
|
|
\default_output_format default
|
|
\output_sync 0
|
|
\bibtex_command default
|
|
\index_command default
|
|
\paperfontsize default
|
|
\spacing single
|
|
\use_hyperref false
|
|
\papersize default
|
|
\use_geometry false
|
|
\use_package amsmath 1
|
|
\use_package amssymb 1
|
|
\use_package cancel 1
|
|
\use_package esint 1
|
|
\use_package mathdots 0
|
|
\use_package mathtools 1
|
|
\use_package mhchem 0
|
|
\use_package stackrel 1
|
|
\use_package stmaryrd 1
|
|
\use_package undertilde 1
|
|
\cite_engine basic
|
|
\cite_engine_type default
|
|
\biblio_style plain
|
|
\use_bibtopic false
|
|
\use_indices false
|
|
\paperorientation portrait
|
|
\suppress_date false
|
|
\justification true
|
|
\use_refstyle 0
|
|
\index Index
|
|
\shortcut idx
|
|
\color #008000
|
|
\end_index
|
|
\secnumdepth 3
|
|
\tocdepth 3
|
|
\paragraph_separation indent
|
|
\paragraph_indentation default
|
|
\quotes_language english
|
|
\papercolumns 1
|
|
\papersides 1
|
|
\paperpagestyle default
|
|
\tracking_changes false
|
|
\html_math_output 0
|
|
\html_css_as_file 0
|
|
\output_changes false
|
|
\html_be_strict false
|
|
\end_header
|
|
|
|
\begin_body
|
|
|
|
\begin_layout Title
|
|
Dynamic Macros for \SpecialChar LyX
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Author
|
|
Stefan Schimanski
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
|
|
\begin_inset Flex URL
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
|
|
sts@1stein.org
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Date
|
|
21.10.2007
|
|
\end_layout
|
|
|
|
\begin_layout Section
|
|
The old system
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
\SpecialChar LyX
|
|
has the concept of math macros for quite some time.
|
|
In \SpecialChar LyX
|
|
1.4 or 1.5 you can create one in your document by calling the
|
|
\family typewriter
|
|
math-macro
|
|
\family default
|
|
command in the mini buffer.
|
|
Visually this results in something equivalent to a \SpecialChar TeX
|
|
macro:
|
|
\begin_inset listings
|
|
inline false
|
|
status open
|
|
|
|
\begin_layout Plain Layout
|
|
|
|
|
|
\backslash
|
|
newcommand{
|
|
\backslash
|
|
foo}{
|
|
\backslash
|
|
frac{1}{2}}
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
After \SpecialChar LyX
|
|
processed this, the command is available in math environments in
|
|
the same documents.
|
|
But internally there is nothing more than
|
|
\series bold
|
|
one
|
|
\series default
|
|
global macro table.
|
|
The position inside the document does not matter.
|
|
The command is available even in front of the definition.
|
|
But even worse, this global macro table is global for all opened documents.
|
|
If two buffers use the same macro name with different definitions, you
|
|
are in trouble.
|
|
The behaviour is undefined.
|
|
If you are lucky \SpecialChar LyX
|
|
will not crash.
|
|
Nothing must be said about redefining a macro later in the document: the
|
|
behaviour of \SpecialChar LyX
|
|
will not be what you expect.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
\SpecialChar LyX
|
|
1.4 and 1.5 do not show the support for this kind of macro very prominently.
|
|
In fact it is described in the
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
Extended Features
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
manual.
|
|
But there is no menu item to create macros.
|
|
Next to the mentioned method with the mini buffer you can use the
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
Ctrl-L
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
short cut to convert a raw
|
|
\backslash
|
|
newcommand into a \SpecialChar LyX
|
|
math macro.
|
|
Hence the role of macro is more of a power user tool for users who know
|
|
what they are doing.
|
|
\end_layout
|
|
|
|
\begin_layout Section
|
|
A wish list for a new macro implementation
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
In the following usecases are shown which can be wished to be supported
|
|
if macros are reimplemented.
|
|
Most of them are not possible in the old implementation, or at least very
|
|
hard to do.
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Define a
|
|
\series bold
|
|
new macro
|
|
\series default
|
|
with a known arity ("arity" = number of arguments).
|
|
Use instances later on in the document.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
|
|
\series bold
|
|
Redefine
|
|
\series default
|
|
a macro to use the same macro name with different definitions in different
|
|
areas of the document.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Have
|
|
\family typewriter
|
|
|
|
\backslash
|
|
newcommand
|
|
\family default
|
|
in the preamble (i.e.
|
|
by importing tex code) or
|
|
\series bold
|
|
not accessible
|
|
\series default
|
|
as a \SpecialChar LyX
|
|
macro in another way, and then define the command as a native \SpecialChar LyX
|
|
math
|
|
macro later.
|
|
All the uses of the old command should then turn into instances of the
|
|
\SpecialChar LyX
|
|
math macro.
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
|
|
\series bold
|
|
Rename
|
|
\series default
|
|
a macro and also adapt all the instance of the macro in the document.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
|
|
\series bold
|
|
Change the arity
|
|
\series default
|
|
of a macro (normally probably increase it), maybe with a default value
|
|
used in instances of the macro (possibly empty).
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
|
|
\series bold
|
|
Removal
|
|
\series default
|
|
of a macro.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Insertion of a macro via the
|
|
\series bold
|
|
menu
|
|
\series default
|
|
like "Insert->MathMacro".
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
|
|
\series bold
|
|
Moving
|
|
\series default
|
|
of a macro.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
|
|
\series bold
|
|
\begin_inset CommandInset label
|
|
LatexCommand label
|
|
name "subsec:listedit"
|
|
|
|
\end_inset
|
|
|
|
|
|
\series default
|
|
Editing of a macro instance as a
|
|
\series bold
|
|
list
|
|
\series default
|
|
of #1: __, #2: __, i.e.
|
|
it
|
|
\series bold
|
|
unfold
|
|
\series default
|
|
s when the cursor goes inside.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Editing of macros
|
|
\series bold
|
|
inline
|
|
\series default
|
|
(the macro definition will be read-only, only the arguments as holes are
|
|
editable).
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Changing of the
|
|
\series bold
|
|
editing behaviour
|
|
\series default
|
|
of
|
|
\series bold
|
|
|
|
\begin_inset CommandInset ref
|
|
LatexCommand ref
|
|
reference "subsec:listedit"
|
|
|
|
\end_inset
|
|
|
|
|
|
\series default
|
|
for certain macros, not only globally.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Defining dynamic
|
|
\series bold
|
|
macros inside of macros
|
|
\series default
|
|
.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Using macros with the
|
|
\series bold
|
|
same name
|
|
\series default
|
|
, but different definitions in different open documents or parts of the
|
|
same document.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Using macros from the
|
|
\series bold
|
|
master document
|
|
\series default
|
|
.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Using the same argument, e.g.
|
|
#1, (
|
|
\series bold
|
|
non-linearly
|
|
\series default
|
|
) more than once in the definition, like
|
|
\family typewriter
|
|
|
|
\backslash
|
|
newcommand{
|
|
\backslash
|
|
ntothen}[1]{#1^#1}
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
|
|
\series bold
|
|
Patterns
|
|
\series default
|
|
like
|
|
\family typewriter
|
|
|
|
\backslash
|
|
def
|
|
\backslash
|
|
foo #1/#2{
|
|
\backslash
|
|
frac{#1}{#2}}
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
|
|
\series bold
|
|
Higher order
|
|
\series default
|
|
substitution (or call-by-name text substitution) like
|
|
\family typewriter
|
|
|
|
\backslash
|
|
def
|
|
\backslash
|
|
foo #1{#1 12}
|
|
\family default
|
|
, which is applicable like
|
|
\family typewriter
|
|
|
|
\backslash
|
|
foo
|
|
\backslash
|
|
frac
|
|
\family default
|
|
to give
|
|
\family typewriter
|
|
1/2
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
|
|
\series bold
|
|
Optional
|
|
\series default
|
|
parameters like
|
|
\family typewriter
|
|
|
|
\backslash
|
|
newcommand{
|
|
\backslash
|
|
foo}[2][x]{#2_#1}
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The old implementation supports the following:
|
|
\series bold
|
|
new macro
|
|
\series default
|
|
,
|
|
\series bold
|
|
moving
|
|
\series default
|
|
,
|
|
\series bold
|
|
list
|
|
\series default
|
|
,
|
|
\series bold
|
|
master document
|
|
\series default
|
|
,
|
|
\series bold
|
|
non-linear.
|
|
|
|
\series default
|
|
Though support of master documents is more or less an coincidence by the
|
|
global table.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The implementation described later (short: the new implementation) supports
|
|
the following:
|
|
\series bold
|
|
new macro
|
|
\series default
|
|
,
|
|
\series bold
|
|
redefine
|
|
\series default
|
|
,
|
|
\series bold
|
|
not accessible
|
|
\series default
|
|
,
|
|
\series bold
|
|
change the arity
|
|
\series default
|
|
,
|
|
\series bold
|
|
removal
|
|
\series default
|
|
,
|
|
\series bold
|
|
menu
|
|
\series default
|
|
,
|
|
\series bold
|
|
moving
|
|
\series default
|
|
,
|
|
\series bold
|
|
unfolds
|
|
\series default
|
|
,
|
|
\series bold
|
|
inline
|
|
\series default
|
|
,
|
|
\series bold
|
|
same name
|
|
\series default
|
|
,
|
|
\series bold
|
|
master documents
|
|
\series default
|
|
,
|
|
\series bold
|
|
non-linearly
|
|
\series default
|
|
,
|
|
\series bold
|
|
optional
|
|
\series default
|
|
.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
Not supported are:
|
|
\series bold
|
|
patterns
|
|
\series default
|
|
,
|
|
\series bold
|
|
higher order
|
|
\series default
|
|
,
|
|
\series bold
|
|
macros inside of macros
|
|
\series default
|
|
,
|
|
\series bold
|
|
editing behaviour
|
|
\series default
|
|
,
|
|
\series bold
|
|
list
|
|
\series default
|
|
,
|
|
\series bold
|
|
rename
|
|
\series default
|
|
.
|
|
The last 3 should be doable without much work, maybe also
|
|
\series bold
|
|
patterns
|
|
\series default
|
|
.
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
Main deficiencies of the old system
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The main problem of the old implementation is that it is not dynamic at
|
|
all.
|
|
A macro is resolved (i.e.
|
|
the lookup in the global table takes place) when the internal object is
|
|
created, e.g.
|
|
while parsing of the
|
|
\family typewriter
|
|
.lyx
|
|
\family default
|
|
document or when typing
|
|
\family typewriter
|
|
|
|
\backslash
|
|
foo
|
|
\family default
|
|
.
|
|
If no macro definition of the right name exists at this time, an ERT is
|
|
created.
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
Moreover there is no position awareness of the definition, only during loading
|
|
of a document there is something like that because macro definitions are
|
|
put into the global table at the point in the document where it appears.
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Section
|
|
A new approach
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The goal of a new macro approach must be to support as many use cases subsection
|
|
1.2 as possible, or at least make an implementation possible of the remaining
|
|
ones.
|
|
Moreover a proper implementation better brings most of \SpecialChar TeX
|
|
's power of math
|
|
command into \SpecialChar LyX
|
|
.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
In a few words the new approach could be described as follow:
|
|
\end_layout
|
|
|
|
\begin_layout Itemize
|
|
A macro is a dynamic inset which can
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
eat up
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
or
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
spit out
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
insets which follow the macro, depending on the success to resolve it and
|
|
the arity of the macro definition at the position in the document.
|
|
\end_layout
|
|
|
|
\begin_layout Itemize
|
|
Macros are resolved again every time it is redrawn on screen if the macro
|
|
definition changed which is valid at the position.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
This
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
eat up
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
and
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
spit out
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
process is the key idea.
|
|
Imagine a macro definition
|
|
\family typewriter
|
|
|
|
\backslash
|
|
newcommand{
|
|
\backslash
|
|
foo}[2]{a#1b#2c}
|
|
\family default
|
|
which is valid when a macro
|
|
\family typewriter
|
|
|
|
\backslash
|
|
foo
|
|
\family default
|
|
appears in the context
|
|
\family typewriter
|
|
|
|
\backslash
|
|
foo ABCD
|
|
\family default
|
|
.
|
|
When the macro is drawn the definition is checked and the arity is compared
|
|
to the number of
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
eaten
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
insets.
|
|
At the beginning the latter will be zero.
|
|
Because the arity of
|
|
\family typewriter
|
|
|
|
\backslash
|
|
foo
|
|
\family default
|
|
is 2, the macro inset will eat up 2 insets (the
|
|
\family typewriter
|
|
A
|
|
\family default
|
|
and the
|
|
\family typewriter
|
|
B
|
|
\family default
|
|
), hence internally the macro
|
|
\family typewriter
|
|
|
|
\backslash
|
|
foo
|
|
\family default
|
|
is changed to arity 2 and
|
|
\family typewriter
|
|
A
|
|
\family default
|
|
and
|
|
\family typewriter
|
|
B
|
|
\family default
|
|
are moved into it.
|
|
The visual representation of macro is that of the definition with the arguments
|
|
replaced by the eaten insets.
|
|
So eventually you will see
|
|
\family typewriter
|
|
aAbBcCD
|
|
\family default
|
|
on screen.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
When you change the macro definition at the position into a unary macro,
|
|
e.g.
|
|
|
|
\family typewriter
|
|
|
|
\backslash
|
|
newcommand{
|
|
\backslash
|
|
foo}[1]{a#1b}
|
|
\family default
|
|
, the macro inset will spit out the second eaten inset, here the
|
|
\family typewriter
|
|
B
|
|
\family default
|
|
.
|
|
Hence you will eventually see
|
|
\family typewriter
|
|
aAbBCD
|
|
\family default
|
|
.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
This process is done automatically, transparent to the user and in a fast
|
|
way every time the macro is rendered and the definition has changed.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
If you look at the produced \SpecialChar TeX
|
|
code of the
|
|
\family typewriter
|
|
|
|
\backslash
|
|
foo ABCD
|
|
\family default
|
|
you will notice that it didn't change during all this eating and spitting.
|
|
This is what you expect from a macro in \SpecialChar TeX
|
|
.
|
|
There the whole sense of command (i.e.
|
|
macros) is that you keep the same \SpecialChar TeX
|
|
code, independently from the macro definitio
|
|
n.
|
|
This approach carries this over to the \SpecialChar LyX
|
|
world.
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
The implementation
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
MathData
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
When a MathData object is drawn, more precisely when the metrics are computed,
|
|
all math macros in the
|
|
\family typewriter
|
|
MathData
|
|
\family default
|
|
are processed in the way described in the previous section.
|
|
If the arity of definition of a macro is changed the spitting/eating process
|
|
takes place.
|
|
This is implemented in
|
|
\family typewriter
|
|
MathData::updateMacros
|
|
\family default
|
|
, in a quite straight forward way.
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
Some complexity comes into the game by the necessary updating of the current
|
|
cursor.
|
|
If the user unfolds a macro the arity practically changes to zero, hence
|
|
the arguments are spit out.
|
|
If the cursor was inside an argument before, it should be in the same argument
|
|
after the unfolding.
|
|
The same should be the case for folding.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The metrics calculation is, by its typing, a const method, i.e.
|
|
it shouldn't change the
|
|
\family typewriter
|
|
MathData
|
|
\family default
|
|
object.
|
|
The macro updating though does changes of course.
|
|
Technically this is true, semantically (taking the produced \SpecialChar TeX
|
|
code as semantics)
|
|
it is not because nothing changes by eating/spitting or folding/unfolding
|
|
with the later output.
|
|
To still allow these changes in
|
|
\family typewriter
|
|
MathData::metrics
|
|
\family default
|
|
a
|
|
\family typewriter
|
|
const_cast
|
|
\family default
|
|
is used.
|
|
This is somewhat ugly and a cleaner solution should be found.
|
|
Maybe one day the drawing and metrics will merge, then it would make sense
|
|
to think about the
|
|
\family typewriter
|
|
const_cast
|
|
\family default
|
|
as well again.
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
Macro Table
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
How does the
|
|
\family typewriter
|
|
MathData
|
|
\family default
|
|
know which macro definitions are known at its position in the buffer? During
|
|
the metrics call a
|
|
\family typewriter
|
|
MacroContext
|
|
\family default
|
|
is passed around as an element of the
|
|
\family typewriter
|
|
MetricsInfo
|
|
\family default
|
|
class.
|
|
This context can be asked to resolve a macro name.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
To make this possible it has to know about a position in the buffer.
|
|
In fact it knows about the paragraph in the buffer, and in addition it
|
|
has a
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
local
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
|
|
\family typewriter
|
|
MacroTable
|
|
\family default
|
|
.
|
|
The latter is used to also resolve macros correctly which are defined in
|
|
the paragraph where the macro appears.
|
|
The inset loop in the
|
|
\family typewriter
|
|
TextMetrics::redoParagraph
|
|
\family default
|
|
creates and updates the
|
|
\family typewriter
|
|
MacroContext
|
|
\family default
|
|
and the local macros in the expected way.
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
All the other macros are resolved by the
|
|
\family typewriter
|
|
MacroContext
|
|
\family default
|
|
by asking the buffer directly.
|
|
For this the
|
|
\family typewriter
|
|
MacroContext
|
|
\family default
|
|
, as written above, knows the paragraph it belongs to.
|
|
It passes this information to the buffer (via
|
|
\family typewriter
|
|
Buffer::hasMacro(docstring name, Paragraph par)
|
|
\family default
|
|
) and the buffer then uses the
|
|
\family typewriter
|
|
par.macrocontextPosition()
|
|
\family default
|
|
information to lookup the defined macros at the position in the map
|
|
\family typewriter
|
|
Buffer::pimpl->macros
|
|
\family default
|
|
.
|
|
This maps macro names and positions to the macro definitions.
|
|
which are defined at the position or before.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The missing bit is how the buffer creates this map.
|
|
This is done in the same way as in the old macro implementation, namely
|
|
by the Buffer::updateMacros method which iterates over the top-level inset
|
|
of the buffer.
|
|
It is called from
|
|
\family typewriter
|
|
BufferView::processUpdateFlags
|
|
\family default
|
|
very often.
|
|
This sounds slow, but it turned out that it is not noticable in fact.
|
|
In \SpecialChar LyX
|
|
1.5 the same is done as well already.
|
|
Maybe some optimisation could help though, but was not investigated.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
To support master documents there will a last lookup (if the previous lookup
|
|
were not successful) by asking the master buffer.
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
File Format
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The file format concerning macros in the old macro implementation is not
|
|
well defined.
|
|
As described above there is a big difference between the visual semantics
|
|
(what the user sees inside \SpecialChar LyX
|
|
1.5) and the latex semantics (what \SpecialChar LaTeX
|
|
will make
|
|
out of the document) are not the same.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The new approach changes this for most documents (if the user does not do
|
|
any dirty tricks at least) to be the same.
|
|
So from the file format point of view there probably should not be any
|
|
conversion needed to a new file format.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
One exception of this comes from the support for optional arguments in the
|
|
new implementation.
|
|
Those were not available in the old format.
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
Simple Macros
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
Macro definitions are stored in the following way:
|
|
\begin_inset listings
|
|
inline false
|
|
status open
|
|
|
|
\begin_layout Plain Layout
|
|
|
|
|
|
\backslash
|
|
begin_inset FormulaMacro
|
|
\end_layout
|
|
|
|
\begin_layout Plain Layout
|
|
|
|
|
|
\backslash
|
|
newcommand{
|
|
\backslash
|
|
abc}[1]{
|
|
\backslash
|
|
sin
|
|
\backslash
|
|
left(
|
|
\backslash
|
|
frac{-3}{#1}
|
|
\backslash
|
|
right)}
|
|
\end_layout
|
|
|
|
\begin_layout Plain Layout
|
|
|
|
|
|
\backslash
|
|
end_inset
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The resulting \SpecialChar LaTeX
|
|
code is as expected:
|
|
\begin_inset listings
|
|
inline false
|
|
status open
|
|
|
|
\begin_layout Plain Layout
|
|
|
|
|
|
\backslash
|
|
newcommand{
|
|
\backslash
|
|
abc}[1]{
|
|
\backslash
|
|
sin
|
|
\backslash
|
|
left(
|
|
\backslash
|
|
frac{-3}{#1}
|
|
\backslash
|
|
right)}
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
One Optional Argument
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
With one optional argument the \SpecialChar LyX
|
|
code looks like this:
|
|
\begin_inset listings
|
|
inline false
|
|
status open
|
|
|
|
\begin_layout Plain Layout
|
|
|
|
|
|
\backslash
|
|
begin_inset FormulaMacro
|
|
\end_layout
|
|
|
|
\begin_layout Plain Layout
|
|
|
|
|
|
\backslash
|
|
newcommand{
|
|
\backslash
|
|
abc}[1][42]{
|
|
\backslash
|
|
sin
|
|
\backslash
|
|
left(
|
|
\backslash
|
|
frac{-3}{#1}
|
|
\backslash
|
|
right)}
|
|
\end_layout
|
|
|
|
\begin_layout Plain Layout
|
|
|
|
|
|
\backslash
|
|
end_inset
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
and the \SpecialChar LaTeX
|
|
code again is the same:
|
|
\begin_inset listings
|
|
inline false
|
|
status open
|
|
|
|
\begin_layout Plain Layout
|
|
|
|
|
|
\backslash
|
|
newcommand{
|
|
\backslash
|
|
abc}[1][42]{
|
|
\backslash
|
|
sin
|
|
\backslash
|
|
left(
|
|
\backslash
|
|
frac{-3}{#1}
|
|
\backslash
|
|
right)}
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
Multi Optional Argument Macro
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
More than one optional argument is not supported by \SpecialChar LaTeX
|
|
.
|
|
There are several solutions to allow them by defining some custom
|
|
\family typewriter
|
|
|
|
\backslash
|
|
newcommand
|
|
\family default
|
|
, but this is not standardized.
|
|
It might make sense for \SpecialChar LyX
|
|
to also support those when importing, but this
|
|
is not implemented.
|
|
Instead the new implementation will create valid standard \SpecialChar LaTeX
|
|
code by outputting
|
|
what the user sees on screen in \SpecialChar LyX
|
|
:
|
|
\begin_inset listings
|
|
inline false
|
|
status open
|
|
|
|
\begin_layout Plain Layout
|
|
|
|
|
|
\backslash
|
|
begin_inset FormulaMacro
|
|
\end_layout
|
|
|
|
\begin_layout Plain Layout
|
|
|
|
|
|
\backslash
|
|
newcommand{
|
|
\backslash
|
|
xyz}[2][42][28]{
|
|
\backslash
|
|
sqrt{#1}+
|
|
\backslash
|
|
ln
|
|
\backslash
|
|
left(
|
|
\backslash
|
|
frac{#2}{82}
|
|
\backslash
|
|
right)}
|
|
\end_layout
|
|
|
|
\begin_layout Plain Layout
|
|
|
|
|
|
\backslash
|
|
end_inset
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
with the \SpecialChar LaTeX
|
|
code:
|
|
\begin_inset listings
|
|
inline false
|
|
status open
|
|
|
|
\begin_layout Plain Layout
|
|
|
|
|
|
\backslash
|
|
newcommand{
|
|
\backslash
|
|
xyz}[2][42]{
|
|
\backslash
|
|
sqrt{#1}+
|
|
\backslash
|
|
ln
|
|
\backslash
|
|
left(
|
|
\backslash
|
|
frac{#2}{82}
|
|
\backslash
|
|
right)}
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
When the user creates an instance of
|
|
\backslash
|
|
xyz without substituting the optional argument, e.g.
|
|
by
|
|
\begin_inset listings
|
|
inline false
|
|
status open
|
|
|
|
\begin_layout Plain Layout
|
|
|
|
|
|
\backslash
|
|
xyz
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
\SpecialChar LyX
|
|
will create the following \SpecialChar LaTeX
|
|
code when exporting to \SpecialChar LaTeX
|
|
:
|
|
\begin_inset listings
|
|
inline false
|
|
status open
|
|
|
|
\begin_layout Plain Layout
|
|
|
|
|
|
\backslash
|
|
xyz{28}
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
So the optional argument is not optional any more after export, but explicit.
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
|
|
\backslash
|
|
def style
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
Last but not least, as in the old implementation you can use
|
|
\family typewriter
|
|
|
|
\backslash
|
|
def
|
|
\family default
|
|
macros, i.e.
|
|
\SpecialChar TeX
|
|
style definitions.
|
|
They don't support optional arguments.
|
|
They don't support
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
patterns
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
of the shape
|
|
\family typewriter
|
|
|
|
\backslash
|
|
def
|
|
\backslash
|
|
term #1+#2{#1+#2}
|
|
\family default
|
|
where you can use it as in
|
|
\family typewriter
|
|
|
|
\backslash
|
|
term 43+12
|
|
\family default
|
|
.
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
Redefinition
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
On export \SpecialChar LyX
|
|
will correctly use
|
|
\family typewriter
|
|
|
|
\backslash
|
|
newcommand
|
|
\family default
|
|
and
|
|
\family typewriter
|
|
|
|
\backslash
|
|
renewcommand
|
|
\family default
|
|
if needed.
|
|
This is not visible in the \SpecialChar LyX
|
|
file format though.
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
How it looks to the user
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
Creation
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
Macro definitions look more or less the same as in the old implementation.
|
|
I.e.
|
|
there is a macro definition inset showing the macro like
|
|
\family typewriter
|
|
|
|
\backslash
|
|
foo{#1}:={a#1b}
|
|
\family default
|
|
.
|
|
You can create i
|
|
\family typewriter
|
|
t
|
|
\family default
|
|
via the
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
math-macro foo 4
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
to create a macro
|
|
\family typewriter
|
|
|
|
\backslash
|
|
foo
|
|
\family default
|
|
with 4 parameters.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
A second way to create them is to write down the \SpecialChar LaTeX
|
|
definition like
|
|
\family typewriter
|
|
|
|
\backslash
|
|
newcommand
|
|
\backslash
|
|
foo{abc}
|
|
\family default
|
|
as plain text.
|
|
Select it and press Ctrl-m.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The last way, which is new with the new implementation, is to use the Insert/Mat
|
|
h/Macro menu item.
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
Modification
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The are the following actions defined:
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
\begin_inset Tabular
|
|
<lyxtabular version="3" rows="12" columns="2">
|
|
<features tabularvalignment="middle">
|
|
<column alignment="center" valignment="top">
|
|
<column alignment="center" valignment="top">
|
|
<row>
|
|
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
Action
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
Menu
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
</row>
|
|
<row>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
math-macro-unfold
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
View/Unfold Math Macro
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
</row>
|
|
<row>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
math-macro-fold
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
View/Fold Math Macro
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
</row>
|
|
<row>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
math-macro-add-param
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
Edit/Math/Macro/Append Parameter
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
</row>
|
|
<row>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
math-macro-remove-param
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
Edit/Math/Macro/Remove Last Parameter
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
</row>
|
|
<row>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
math-macro-append-greedy-param
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
Edit/Math/Macro/Append Parameter Eating From the Right
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
</row>
|
|
<row>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
math-macro-make-optional
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
Edit/Math/Macro/Make First Non-Optional into Optional Parameter
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
</row>
|
|
<row>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
math-macro-remove-greedy-param
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
Edit/Math/Macro/Remove Last Parameter Spitting Out To The Right
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
</row>
|
|
<row>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
math-macro-make-nonoptional
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
Edit/Math/Macro/Make Last Optional into Non-Optional Parameter
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
</row>
|
|
<row>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
math-macro-add-optional-param
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
Edit/Math/Macro/Insert Optional Parameter
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
</row>
|
|
<row>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
math-macro-remove-optional-param
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
Edit/Math/Macro/Remove Optional Parameter
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
</row>
|
|
<row>
|
|
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
math-macro-add-greedy-optional-param
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
|
|
\begin_inset Text
|
|
|
|
\begin_layout Plain Layout
|
|
Edit/Math/Macro/Append Optional Parameter Eating From the Right
|
|
\end_layout
|
|
|
|
\end_inset
|
|
</cell>
|
|
</row>
|
|
</lyxtabular>
|
|
|
|
\end_inset
|
|
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
Greedy vs.
|
|
Non-Greedy
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
As described above the key idea is that macros and eat up and spit out parameter
|
|
s, depending on their arity.
|
|
This makes them very dynamic and powerful, but at the same time adds some
|
|
complexity which must be understood by the user to effectively use the
|
|
macros.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
Hence if the arity is increased (i.e.
|
|
another parameter is added to a macro) there are two ways to do that: if
|
|
this is done greedily the macro tries to eat up another inset from the
|
|
right.
|
|
This is the natural way if you import a document and then start to define
|
|
a macros with \SpecialChar LyX
|
|
's math macros.
|
|
Then you want that the macros take the (existing) parameters from the right.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The second case is the non-greedy use case.
|
|
E.g.
|
|
you want to change a macro to take another parameter because you just found
|
|
out that your notation needs another index.
|
|
Then you want to insert this non-greedily.
|
|
All macro instances in your text should get another parameter without touching
|
|
the surroundings.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The greedy variants of the actions have the word
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
greedy
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
in their name.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
Some of the actions also take a parameter to define the position to act
|
|
on in the parameter list.
|
|
E.g.
|
|
you can write
|
|
\family typewriter
|
|
math-macro-add-param 2
|
|
\family default
|
|
in the mini-buffer to add a parameter at position 2.
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
Folding/Unfolding
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
Sometimes it is desirable to switch to the \SpecialChar TeX
|
|
code of a macro instance, i.e.
|
|
without any substitution using the macro definition.
|
|
This can be done with the fold/unfold actions.
|
|
You can use the
|
|
\family typewriter
|
|
Ctrl-+
|
|
\family default
|
|
and
|
|
\family typewriter
|
|
Ctrl--
|
|
\family default
|
|
shortcuts for that.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
If you nest macro instances these actions will unfold from inside to the
|
|
outside and the same for folding.
|
|
This is supposed to replace the old list display when entering a macro.
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
Toolbar
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
Currently there is no toolbar for math macros.
|
|
Because the menu hierarchy is very deep a toolbar would make the life a
|
|
lot easier.
|
|
It shouldn't be hard to implement that.
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
More natural macro definition editing
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
Instead of the described actions it would desirable to add another more
|
|
natural way to edit macros.
|
|
The vision is that the user can put the cursor everywhere inside of the
|
|
macro definition inset which shows (already now!) the definition in the
|
|
way
|
|
\family typewriter
|
|
|
|
\backslash
|
|
name{#1}{#2}:={definition}
|
|
\family default
|
|
.
|
|
The user should be able to use the backspace and the
|
|
\family typewriter
|
|
{
|
|
\family default
|
|
key to remove and add parameters when the cursor is in the parameter definition
|
|
part.
|
|
For a non-greedy macro-append one could put a small (+) button or a hungry
|
|
packman
|
|
\family typewriter
|
|
(<
|
|
\family default
|
|
behind the
|
|
\family typewriter
|
|
{#2}
|
|
\family default
|
|
in front of the definition.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
For implementing this one has to customize the
|
|
\family typewriter
|
|
MathInsetNest
|
|
\family default
|
|
a lot to handle the key presses correctly, because it's probably not directly
|
|
doable with
|
|
\family typewriter
|
|
MathInsetNest
|
|
\family default
|
|
in a simple way with its children insets.
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
Keyboard navigation
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
You can jump from
|
|
\family typewriter
|
|
#n
|
|
\family default
|
|
to
|
|
\family typewriter
|
|
#n+1
|
|
\family default
|
|
with the cursor key and conversely backwards.
|
|
This navigation is not visual.
|
|
I.e.
|
|
the user can define macros like
|
|
\family typewriter
|
|
|
|
\backslash
|
|
foo{#1}{#2}:={#2+#1}
|
|
\family default
|
|
.
|
|
Then the cursor jumps first to the right and then to the left where the
|
|
#1 is.
|
|
This can be confusing.
|
|
One could think about a visual movement mode by taking the position of
|
|
the macro argument insets into account to find the next inset for the cursor
|
|
keys.
|
|
This should be doable.
|
|
\end_layout
|
|
|
|
\end_body
|
|
\end_document
|