1 #LyX 2.2 created this file. For more info see http://www.lyx.org/
7 \use_default_options false
8 \maintain_unincluded_children false
10 \language_package default
13 \font_roman "default" "default"
14 \font_sans "default" "default"
15 \font_typewriter "default" "default"
16 \font_math "auto" "auto"
17 \font_default_family default
18 \use_non_tex_fonts false
21 \font_sf_scale 100 100
22 \font_tt_scale 100 100
24 \default_output_format default
26 \bibtex_command default
27 \index_command default
28 \paperfontsize default
33 \use_package amsmath 1
34 \use_package amssymb 1
37 \use_package mathdots 0
38 \use_package mathtools 1
40 \use_package stackrel 1
41 \use_package stmaryrd 1
42 \use_package undertilde 1
44 \cite_engine_type default
48 \paperorientation portrait
58 \paragraph_separation indent
59 \paragraph_indentation default
60 \quotes_language english
63 \paperpagestyle default
64 \tracking_changes false
74 Dynamic Macros for \SpecialChar LyX
80 \begin_inset Newline newline
87 \begin_layout Plain Layout
101 \begin_layout Section
105 \begin_layout Standard
107 has the concept of math macros for quite some time.
109 1.4 or 1.5 you can create one in your document by calling the
113 command in the mini buffer.
114 Visually this results in something equivalent to a \SpecialChar TeX
116 \begin_inset listings
120 \begin_layout Plain Layout
136 \begin_layout Standard
137 After \SpecialChar LyX
138 processed this, the command is available in math environments in
140 But internally there is nothing more than
145 The position inside the document does not matter.
146 The command is available even in front of the definition.
147 But even worse, this global macro table is global for all opened documents.
148 If two buffers use the same macro name with different definitions, you
150 The behaviour is undefined.
151 If you are lucky \SpecialChar LyX
153 Nothing must be said about redefining a macro later in the document: the
154 behaviour of \SpecialChar LyX
155 will not be what you expect.
158 \begin_layout Standard
160 1.4 and 1.5 do not show the support for this kind of macro very prominently.
161 In fact it is described in the
162 \begin_inset Quotes eld
166 \begin_inset Quotes erd
170 But there is no menu item to create macros.
171 Next to the mentioned method with the mini buffer you can use the
172 \begin_inset Quotes eld
176 \begin_inset Quotes erd
179 short cut to convert a raw
181 newcommand into a \SpecialChar LyX
183 Hence the role of macro is more of a power user tool for users who know
187 \begin_layout Section
188 A wish list for a new macro implementation
191 \begin_layout Standard
192 In the following usecases are shown which can be wished to be supported
193 if macros are reimplemented.
194 Most of them are not possible in the old implementation, or at least very
199 \begin_layout Enumerate
204 with a known arity ("arity" = number of arguments).
205 Use instances later on in the document.
208 \begin_layout Enumerate
213 a macro to use the same macro name with different definitions in different
214 areas of the document.
217 \begin_layout Enumerate
224 in the preamble (i.e.
225 by importing tex code) or
229 as a \SpecialChar LyX
230 macro in another way, and then define the command as a native \SpecialChar LyX
233 All the uses of the old command should then turn into instances of the
239 \begin_layout Enumerate
244 a macro and also adapt all the instance of the macro in the document.
247 \begin_layout Enumerate
252 of a macro (normally probably increase it), maybe with a default value
253 used in instances of the macro (possibly empty).
256 \begin_layout Enumerate
264 \begin_layout Enumerate
265 Insertion of a macro via the
269 like "Insert->MathMacro".
272 \begin_layout Enumerate
280 \begin_layout Enumerate
283 \begin_inset CommandInset label
285 name "subsec:listedit"
291 Editing of a macro instance as a
295 of #1: __, #2: __, i.e.
300 s when the cursor goes inside.
303 \begin_layout Enumerate
308 (the macro definition will be read-only, only the arguments as holes are
312 \begin_layout Enumerate
320 \begin_inset CommandInset ref
322 reference "subsec:listedit"
328 for certain macros, not only globally.
331 \begin_layout Enumerate
334 macros inside of macros
339 \begin_layout Enumerate
340 Using macros with the
344 , but different definitions in different open documents or parts of the
348 \begin_layout Enumerate
349 Using macros from the
356 \begin_layout Enumerate
357 Using the same argument, e.g.
362 ) more than once in the definition, like
371 \begin_layout Enumerate
387 \begin_layout Enumerate
392 substitution (or call-by-name text substitution) like
400 , which is applicable like
413 \begin_layout Enumerate
427 \begin_layout Standard
428 The old implementation supports the following:
449 Though support of master documents is more or less an coincidence by the
453 \begin_layout Standard
454 The implementation described later (short: the new implementation) supports
510 \begin_layout Standard
521 macros inside of macros
536 The last 3 should be doable without much work, maybe also
543 \begin_layout Subsection
544 Main deficiencies of the old system
547 \begin_layout Standard
548 The main problem of the old implementation is that it is not dynamic at
550 A macro is resolved (i.e.
551 the lookup in the global table takes place) when the internal object is
557 document or when typing
564 If no macro definition of the right name exists at this time, an ERT is
569 \begin_layout Standard
570 Moreover there is no position awareness of the definition, only during loading
571 of a document there is something like that because macro definitions are
572 put into the global table at the point in the document where it appears.
576 \begin_layout Section
580 \begin_layout Standard
581 The goal of a new macro approach must be to support as many use cases subsection
582 1.2 as possible, or at least make an implementation possible of the remaining
584 Moreover a proper implementation better brings most of \SpecialChar TeX
586 command into \SpecialChar LyX
590 \begin_layout Standard
591 In a few words the new approach could be described as follow:
594 \begin_layout Itemize
595 A macro is a dynamic inset which can
596 \begin_inset Quotes eld
600 \begin_inset Quotes erd
604 \begin_inset Quotes eld
608 \begin_inset Quotes erd
611 insets which follow the macro, depending on the success to resolve it and
612 the arity of the macro definition at the position in the document.
615 \begin_layout Itemize
616 Macros are resolved again every time it is redrawn on screen if the macro
617 definition changed which is valid at the position.
620 \begin_layout Standard
622 \begin_inset Quotes eld
626 \begin_inset Quotes erd
630 \begin_inset Quotes eld
634 \begin_inset Quotes erd
637 process is the key idea.
638 Imagine a macro definition
646 which is valid when a macro
652 appears in the context
659 When the macro is drawn the definition is checked and the arity is compared
661 \begin_inset Quotes eld
665 \begin_inset Quotes erd
669 At the beginning the latter will be zero.
676 is 2, the macro inset will eat up 2 insets (the
684 ), hence internally the macro
690 is changed to arity 2 and
699 The visual representation of macro is that of the definition with the arguments
700 replaced by the eaten insets.
701 So eventually you will see
708 \begin_layout Standard
709 When you change the macro definition at the position into a unary macro,
719 , the macro inset will spit out the second eaten inset, here the
724 Hence you will eventually see
731 \begin_layout Standard
732 This process is done automatically, transparent to the user and in a fast
733 way every time the macro is rendered and the definition has changed.
736 \begin_layout Standard
737 If you look at the produced \SpecialChar TeX
744 you will notice that it didn't change during all this eating and spitting.
745 This is what you expect from a macro in \SpecialChar TeX
747 There the whole sense of command (i.e.
748 macros) is that you keep the same \SpecialChar TeX
749 code, independently from the macro definitio
751 This approach carries this over to the \SpecialChar LyX
755 \begin_layout Subsection
759 \begin_layout Subsubsection
763 \begin_layout Standard
764 When a MathData object is drawn, more precisely when the metrics are computed,
765 all math macros in the
769 are processed in the way described in the previous section.
770 If the arity of definition of a macro is changed the spitting/eating process
772 This is implemented in
774 MathData::updateMacros
776 , in a quite straight forward way.
780 \begin_layout Standard
781 Some complexity comes into the game by the necessary updating of the current
783 If the user unfolds a macro the arity practically changes to zero, hence
784 the arguments are spit out.
785 If the cursor was inside an argument before, it should be in the same argument
787 The same should be the case for folding.
790 \begin_layout Standard
791 The metrics calculation is, by its typing, a const method, i.e.
792 it shouldn't change the
797 The macro updating though does changes of course.
798 Technically this is true, semantically (taking the produced \SpecialChar TeX
800 it is not because nothing changes by eating/spitting or folding/unfolding
801 with the later output.
802 To still allow these changes in
811 This is somewhat ugly and a cleaner solution should be found.
812 Maybe one day the drawing and metrics will merge, then it would make sense
820 \begin_layout Subsubsection
824 \begin_layout Standard
829 know which macro definitions are known at its position in the buffer? During
834 is passed around as an element of the
839 This context can be asked to resolve a macro name.
842 \begin_layout Standard
843 To make this possible it has to know about a position in the buffer.
844 In fact it knows about the paragraph in the buffer, and in addition it
846 \begin_inset Quotes eld
850 \begin_inset Quotes erd
858 The latter is used to also resolve macros correctly which are defined in
859 the paragraph where the macro appears.
860 The inset loop in the
862 TextMetrics::redoParagraph
864 creates and updates the
868 and the local macros in the expected way.
872 \begin_layout Standard
873 All the other macros are resolved by the
877 by asking the buffer directly.
882 , as written above, knows the paragraph it belongs to.
883 It passes this information to the buffer (via
885 Buffer::hasMacro(docstring name, Paragraph par)
887 ) and the buffer then uses the
889 par.macrocontextPosition()
891 information to lookup the defined macros at the position in the map
893 Buffer::pimpl->macros
896 This maps macro names and positions to the macro definitions.
897 which are defined at the position or before.
900 \begin_layout Standard
901 The missing bit is how the buffer creates this map.
902 This is done in the same way as in the old macro implementation, namely
903 by the Buffer::updateMacros method which iterates over the top-level inset
907 BufferView::processUpdateFlags
910 This sounds slow, but it turned out that it is not noticable in fact.
912 1.5 the same is done as well already.
913 Maybe some optimisation could help though, but was not investigated.
916 \begin_layout Standard
917 To support master documents there will a last lookup (if the previous lookup
918 were not successful) by asking the master buffer.
921 \begin_layout Subsection
925 \begin_layout Standard
926 The file format concerning macros in the old macro implementation is not
928 As described above there is a big difference between the visual semantics
929 (what the user sees inside \SpecialChar LyX
930 1.5) and the latex semantics (what \SpecialChar LaTeX
932 out of the document) are not the same.
935 \begin_layout Standard
936 The new approach changes this for most documents (if the user does not do
937 any dirty tricks at least) to be the same.
938 So from the file format point of view there probably should not be any
939 conversion needed to a new file format.
942 \begin_layout Standard
943 One exception of this comes from the support for optional arguments in the
945 Those were not available in the old format.
948 \begin_layout Subsubsection
952 \begin_layout Standard
953 Macro definitions are stored in the following way:
954 \begin_inset listings
958 \begin_layout Plain Layout
962 begin_inset FormulaMacro
965 \begin_layout Plain Layout
982 \begin_layout Plain Layout
994 \begin_layout Standard
995 The resulting \SpecialChar LaTeX
997 \begin_inset listings
1001 \begin_layout Plain Layout
1023 \begin_layout Subsubsection
1024 One Optional Argument
1027 \begin_layout Standard
1028 With one optional argument the \SpecialChar LyX
1029 code looks like this:
1030 \begin_inset listings
1034 \begin_layout Plain Layout
1038 begin_inset FormulaMacro
1041 \begin_layout Plain Layout
1058 \begin_layout Plain Layout
1067 and the \SpecialChar LaTeX
1068 code again is the same:
1069 \begin_inset listings
1073 \begin_layout Plain Layout
1095 \begin_layout Subsubsection
1096 Multi Optional Argument Macro
1099 \begin_layout Standard
1100 More than one optional argument is not supported by \SpecialChar LaTeX
1102 There are several solutions to allow them by defining some custom
1108 , but this is not standardized.
1109 It might make sense for \SpecialChar LyX
1110 to also support those when importing, but this
1112 Instead the new implementation will create valid standard \SpecialChar LaTeX
1114 what the user sees on screen in \SpecialChar LyX
1116 \begin_inset listings
1120 \begin_layout Plain Layout
1124 begin_inset FormulaMacro
1127 \begin_layout Plain Layout
1146 \begin_layout Plain Layout
1155 with the \SpecialChar LaTeX
1157 \begin_inset listings
1161 \begin_layout Plain Layout
1182 When the user creates an instance of
1184 xyz without substituting the optional argument, e.g.
1186 \begin_inset listings
1190 \begin_layout Plain Layout
1200 will create the following \SpecialChar LaTeX
1201 code when exporting to \SpecialChar LaTeX
1203 \begin_inset listings
1207 \begin_layout Plain Layout
1216 So the optional argument is not optional any more after export, but explicit.
1219 \begin_layout Subsubsection
1225 \begin_layout Standard
1226 Last but not least, as in the old implementation you can use
1235 They don't support optional arguments.
1237 \begin_inset Quotes eld
1241 \begin_inset Quotes erd
1252 where you can use it as in
1261 \begin_layout Subsubsection
1265 \begin_layout Standard
1266 On export \SpecialChar LyX
1280 This is not visible in the \SpecialChar LyX
1284 \begin_layout Subsection
1285 How it looks to the user
1288 \begin_layout Subsubsection
1292 \begin_layout Standard
1293 Macro definitions look more or less the same as in the old implementation.
1295 there is a macro definition inset showing the macro like
1307 \begin_inset Quotes eld
1311 \begin_inset Quotes erd
1323 \begin_layout Standard
1324 A second way to create them is to write down the \SpecialChar LaTeX
1334 Select it and press Ctrl-m.
1337 \begin_layout Standard
1338 The last way, which is new with the new implementation, is to use the Insert/Mat
1342 \begin_layout Subsubsection
1346 \begin_layout Standard
1347 The are the following actions defined:
1350 \begin_layout Standard
1351 \begin_inset Tabular
1352 <lyxtabular version="3" rows="12" columns="2">
1353 <features tabularvalignment="middle">
1354 <column alignment="center" valignment="top">
1355 <column alignment="center" valignment="top">
1357 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1360 \begin_layout Plain Layout
1366 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
1369 \begin_layout Plain Layout
1377 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1380 \begin_layout Plain Layout
1386 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1389 \begin_layout Plain Layout
1390 View/Unfold Math Macro
1397 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1400 \begin_layout Plain Layout
1406 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1409 \begin_layout Plain Layout
1410 View/Fold Math Macro
1417 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1420 \begin_layout Plain Layout
1421 math-macro-add-param
1426 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1429 \begin_layout Plain Layout
1430 Edit/Math/Macro/Append Parameter
1437 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1440 \begin_layout Plain Layout
1441 math-macro-remove-param
1446 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1449 \begin_layout Plain Layout
1450 Edit/Math/Macro/Remove Last Parameter
1457 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1460 \begin_layout Plain Layout
1461 math-macro-append-greedy-param
1466 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1469 \begin_layout Plain Layout
1470 Edit/Math/Macro/Append Parameter Eating From the Right
1477 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1480 \begin_layout Plain Layout
1481 math-macro-make-optional
1486 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1489 \begin_layout Plain Layout
1490 Edit/Math/Macro/Make First Non-Optional into Optional Parameter
1497 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1500 \begin_layout Plain Layout
1501 math-macro-remove-greedy-param
1506 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1509 \begin_layout Plain Layout
1510 Edit/Math/Macro/Remove Last Parameter Spitting Out To The Right
1517 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1520 \begin_layout Plain Layout
1521 math-macro-make-nonoptional
1526 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1529 \begin_layout Plain Layout
1530 Edit/Math/Macro/Make Last Optional into Non-Optional Parameter
1537 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1540 \begin_layout Plain Layout
1541 math-macro-add-optional-param
1546 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1549 \begin_layout Plain Layout
1550 Edit/Math/Macro/Insert Optional Parameter
1557 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1560 \begin_layout Plain Layout
1561 math-macro-remove-optional-param
1566 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1569 \begin_layout Plain Layout
1570 Edit/Math/Macro/Remove Optional Parameter
1577 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1580 \begin_layout Plain Layout
1581 math-macro-add-greedy-optional-param
1586 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
1589 \begin_layout Plain Layout
1590 Edit/Math/Macro/Append Optional Parameter Eating From the Right
1603 \begin_layout Subsubsection
1608 \begin_layout Standard
1609 As described above the key idea is that macros and eat up and spit out parameter
1610 s, depending on their arity.
1611 This makes them very dynamic and powerful, but at the same time adds some
1612 complexity which must be understood by the user to effectively use the
1616 \begin_layout Standard
1617 Hence if the arity is increased (i.e.
1618 another parameter is added to a macro) there are two ways to do that: if
1619 this is done greedily the macro tries to eat up another inset from the
1621 This is the natural way if you import a document and then start to define
1622 a macros with \SpecialChar LyX
1624 Then you want that the macros take the (existing) parameters from the right.
1627 \begin_layout Standard
1628 The second case is the non-greedy use case.
1630 you want to change a macro to take another parameter because you just found
1631 out that your notation needs another index.
1632 Then you want to insert this non-greedily.
1633 All macro instances in your text should get another parameter without touching
1637 \begin_layout Standard
1638 The greedy variants of the actions have the word
1639 \begin_inset Quotes eld
1643 \begin_inset Quotes erd
1649 \begin_layout Standard
1650 Some of the actions also take a parameter to define the position to act
1651 on in the parameter list.
1655 math-macro-add-param 2
1657 in the mini-buffer to add a parameter at position 2.
1660 \begin_layout Subsubsection
1664 \begin_layout Standard
1665 Sometimes it is desirable to switch to the \SpecialChar TeX
1666 code of a macro instance, i.e.
1667 without any substitution using the macro definition.
1668 This can be done with the fold/unfold actions.
1680 \begin_layout Standard
1681 If you nest macro instances these actions will unfold from inside to the
1682 outside and the same for folding.
1683 This is supposed to replace the old list display when entering a macro.
1686 \begin_layout Subsubsection
1690 \begin_layout Standard
1691 Currently there is no toolbar for math macros.
1692 Because the menu hierarchy is very deep a toolbar would make the life a
1694 It shouldn't be hard to implement that.
1697 \begin_layout Subsubsection
1698 More natural macro definition editing
1701 \begin_layout Standard
1702 Instead of the described actions it would desirable to add another more
1703 natural way to edit macros.
1704 The vision is that the user can put the cursor everywhere inside of the
1705 macro definition inset which shows (already now!) the definition in the
1710 name{#1}{#2}:={definition}
1713 The user should be able to use the backspace and the
1717 key to remove and add parameters when the cursor is in the parameter definition
1719 For a non-greedy macro-append one could put a small (+) button or a hungry
1728 in front of the definition.
1731 \begin_layout Standard
1732 For implementing this one has to customize the
1736 a lot to handle the key presses correctly, because it's probably not directly
1741 in a simple way with its children insets.
1744 \begin_layout Subsubsection
1748 \begin_layout Standard
1757 with the cursor key and conversely backwards.
1758 This navigation is not visual.
1760 the user can define macros like
1764 foo{#1}{#2}:={#2+#1}
1767 Then the cursor jumps first to the right and then to the left where the
1769 This can be confusing.
1770 One could think about a visual movement mode by taking the position of
1771 the macro argument insets into account to find the next inset for the cursor
1773 This should be doable.