Customization: correct some color names.

[lyx.git] / development / mathmacros / architecture.lyx

#LyX 1.5.2 created this file. For more info see http://www.lyx.org/
\lyxformat 276
\begin_document
\begin_header
\textclass article
\language english
\inputencoding auto
\font_roman default
\font_sans default
\font_typewriter default
\font_default_family default
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100
\graphics default
\paperfontsize default
\papersize default
\use_geometry false
\use_amsmath 1
\use_esint 1
\cite_engine basic
\use_bibtopic false
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\author "" 
\author "" 
\end_header

\begin_body

\begin_layout Title
Dynamic Macros for LyX
\end_layout

\begin_layout Author
Stefan Schimanski 
\newline

\begin_inset LatexCommand url
target "sts@1stein.org"

\end_inset


\end_layout

\begin_layout Date
21.10.2007
\end_layout

\begin_layout Section
The old system
\end_layout

\begin_layout Standard
LyX has the concept of math macros for quite some time.
 In 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 TeX macro: 
\begin_inset listings
inline false
status open

\begin_layout Standard


\backslash
newcommand{
\backslash
foo}{
\backslash
frac{1}{2}}
\end_layout

\end_inset


\end_layout

\begin_layout Standard
After 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 LyX will not crash.
 Nothing must be said about redefining a macro later in the document: the
 behaviour of LyX will not be what you expect.
\end_layout

\begin_layout Standard
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 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 implemention, 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 LyX macro in another way, and then define the command as a native
 LyX math macro later.
 All the uses of the old command should then turn into instances of the
 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 (normaly 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 LatexCommand label
name "sub: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 LatexCommand ref
reference "sub: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 substition) 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 accesible
\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 TeX's power of math
 command into 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 everytime 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 everytime the macro is rendered and the definition has changed.
\end_layout

\begin_layout Standard
If you look at the produced 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 TeX.
 There the whole sense of command (i.e.
 macros) is that you keep the same TeX code, independently from the macro
 definition.
 This approach carries this over to the 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 TeX code as
 semantics) it is not because nothing changes by eating/spitting or folding/unfo
lding 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 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 successfull) 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 LyX 1.5) and the latex semantics (what 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 Standard


\backslash
begin_inset FormulaMacro
\end_layout

\begin_layout Standard


\backslash
newcommand{
\backslash
abc}[1]{
\backslash
sin
\backslash
left(
\backslash
frac{-3}{#1}
\backslash
right)} 
\end_layout

\begin_layout Standard


\backslash
end_inset
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The resulting LaTeX code is as expected:
\begin_inset listings
inline false
status open

\begin_layout Standard

 
\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 LyX code looks like this:
\begin_inset listings
inline false
status open

\begin_layout Standard


\backslash
begin_inset FormulaMacro
\end_layout

\begin_layout Standard


\backslash
newcommand{
\backslash
abc}[1][42]{
\backslash
sin
\backslash
left(
\backslash
frac{-3}{#1}
\backslash
right)}
\end_layout

\begin_layout Standard


\backslash
end_inset
\end_layout

\end_inset

 and the LaTeX code again is the same:
\begin_inset listings
inline false
status open

\begin_layout Standard


\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 LaTeX.
 There are several solutions to allow them by defining some custom 
\family typewriter

\backslash
newcommand
\family default
, but this is not standarized.
 It might make sense for LyX to also support those when importing, but this
 is not implemented.
 Instead the new implementation will create valid standard LaTeX code by
 outputting what the user sees on screen in LyX:
\begin_inset listings
inline false
status open

\begin_layout Standard


\backslash
begin_inset FormulaMacro
\end_layout

\begin_layout Standard


\backslash
newcommand{
\backslash
xyz}[2][42][28]{
\backslash
sqrt{#1}+
\backslash
ln
\backslash
left(
\backslash
frac{#2}{82}
\backslash
right)} 
\end_layout

\begin_layout Standard


\backslash
end_inset
\end_layout

\end_inset

 with the LaTeX code:
\begin_inset listings
inline false
status open

\begin_layout Standard


\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 Standard


\backslash
xyz
\end_layout

\end_inset

 LyX will create the following LaTeX code when exporting to LaTeX:
\begin_inset listings
inline false
status open

\begin_layout Standard


\backslash
xyz{28}
\end_layout

\end_inset

So the optional argument is not optional anymore 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.
 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 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 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 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>
<column alignment="center" valignment="top" leftline="true" width="0">
<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Action
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Menu
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
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 Standard
View/Unfold Math Macro
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
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 Standard
View/Fold Math Macro
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
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 Standard
Edit/Math/Macro/Append Parameter
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
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 Standard
Edit/Math/Macro/Remove Last Parameter
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
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 Standard
Edit/Math/Macro/Append Parameter Eating From the Right
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
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 Standard
Edit/Math/Macro/Make First Non-Optional into Optional Parameter
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
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 Standard
Edit/Math/Macro/Remove Last Parameter Spitting Out To The Right
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
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 Standard
Edit/Math/Macro/Make Last Optional into Non-Optional Parameter
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
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 Standard
Edit/Math/Macro/Insert Optional Parameter
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
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 Standard
Edit/Math/Macro/Remove Optional Parameter
\end_layout

\end_inset
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
math-macro-add-greedy-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 Standard
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 LyX's math macros.
 Then you want that the macros take the (existing) paramenters 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 surrouindings.
\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 paramenter 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 desireable to switch to the 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 keypresses 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