summaryrefslogtreecommitdiff
path: root/macros/lollipop/doc/manual/comm.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/lollipop/doc/manual/comm.tex')
-rw-r--r--macros/lollipop/doc/manual/comm.tex642
1 files changed, 0 insertions, 642 deletions
diff --git a/macros/lollipop/doc/manual/comm.tex b/macros/lollipop/doc/manual/comm.tex
deleted file mode 100644
index 2876acf959..0000000000
--- a/macros/lollipop/doc/manual/comm.tex
+++ /dev/null
@@ -1,642 +0,0 @@
-% comm.tex copyright 1992 Victor Eijkhout
-% copyright 2014--2016 Vafa Khalighi
-%
-%
-% This program is free software: you can redistribute it and/or modify
-% it under the terms of the GNU General Public License as published by
-% the Free Software Foundation, either version 3 of the License, or
-% (at your option) any later version.
-%
-% This program is distributed in the hope that it will be useful,
-% but WITHOUT ANY WARRANTY; without even the implied warranty of
-% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-% GNU General Public License for more details.
-%
-% You should have received a copy of the GNU General Public License
-% along with this program. If not, see <http://www.gnu.org/licenses/>.
-%
-%
-\Chapter Commands
-
-\Section[sec:counters] Counters
-
-Counters can be declared explicitly by the user, but more often they
-are defined automatically in some generic construct:
-
-The \cs{Foo} defined by
-\Ver>\DefineBar:Foo ...
- counter:i ...
- Stop<Rev
-
-will have a counter that counts in roman lowercase, and which is
-accessible as \refcs{FooCounter}. Everytime \cs{Foo} is used, this
-counter is increased by one.
-
-The use of the \opt{counter} option is described
-in~\ref[sec:opt:counter].
-Here are the commands for explicit manipulation of counters.
-
-\SubSection[sec:counter:repr] Allocation and representation
-
-A counter is created by for instance
-\Ver>\NewCounter:Things<Rev
-This will create control sequence \cs{ThingsCounter} that will print
-the value of the counter.
-The counter will usually be printed as an Arabic numeral, but other
-counter representations can be specified by
-\refcs{CounterRepresentation}. Here are their codes: \Description
-\item 1
-numeric
-\item a
-lowercase character
-\item A
-uppercase character
-\item i
-lowercase roman
-\item I
-lowercase roman
-\>
-for instance
-\Ver>\CounterRepresentation:Things=i<Rev
-will cause \cs{ThingsCounter} to print a lowercase Roman numeral.
-
-However, a call such as
-\Ver>\CounterRepresentation:Theorem=Lemma<Rev
-will make the \cs{TheoremCounter} a synonym of an earlier created
-\cs{LemmaCounter}
-
-\SubSection Counter manipulation
-
-The following commands can be used to manipulate counters, both when
-they are created by hand using \refcs{NewCounter} and when they were
-generated automatically in some generic construct:
-
-With \refcs{StartCounter} reset the counter to one:
- \Ver>\StartCounter:things<Rev
-
-With \refcs{StepCounter} increase the counter by one:
- \Ver>\StepCounter:things<Rev
-
-With \refcs{BackStepCounter} decrease the counter by one:
- \Ver>\BackStepCounter:things<Rev
-
-With \refcs{SetCounter} set the counter to some specified value:
- \Ver>\SetCounter:things=5<Rev
-
-With \refcs{AddToCounter} increase the counter by some
-specified value:
- \Ver>\AddToCounter:things=7<Rev
-
-The last two commands accept names of numerical parameters, for
-instance the value of a counter:
- \Ver>\NewCounter:Favourite
-\AddToCounter:things=FavouriteValue<Rev
-More about this `value' thing in the next section.
-
-\SubSection What do you get when you define a counter?
-
-After you define a counter as \Ver>\NewCounter:MyThings<Rev there are
-two commands that it is important to distinguish between. First of
-all, \cs{MyThingsCounter} gives the {\it printed\/} value of the
-counter. This is the command that you will use mostly. It uses
-whatever representation you have specified for the counter, or plain
-Arabic numerals if haven't specified anything.
-
-Secondly, \cs{MyThingsValue} gives the value of the counter. You can
-not use this command on its own: you will get a `number expected'
-error.
-
-\SubSection Counter hierarchies
-
-Often counters are related to each other. For instance, when a new
-section begins, the subsection counter has to be reset. The same may
-be true for equation counters. In Lollipop such a relation is
-indicated by a call to \refcs{GoverningCounter}, for instance
-
-\Ver>\GoverningCounter:SubSection=Section<Rev
-
-All of the counter manipulation commands applied to a governing
-counter will cause all governed counters to be reset. Such a reset
-also occurs if the counter was created in some generic construct.
-
-For examples, see section~\ref[sec:head:examples].
-
-\SubSection Referencing counters
-
-All counters that are declared as part of a generic construct, or
-explicitly through \refcs{NewCounter} automatically become the current
-reference when they are altered. Thus \ver>\label[bar]> will make
-\ver>\ref[bar]> refer to the value of the counter most recently
-changed. The way the counter is referenced can be altered by the
-\opt{label} option in generic constructs; see
-section~\ref[sec:opt:label].
-
-For generic constructs with a counter no explicit \refcs{label} commands
-need to be given; such commands take an optional argument with the
-label key:
-\Ver>\Section[sec:examples] Examples<Rev
-
-\SubSection Adaptive counters
-
-It may happen that you want to compute a value during one run of
-\TeX, and use it in the next. An example is the fact that this manual
-states the total number of pages on the title page. For this you can
-use \refcs{AdaptiveCounter}
- \Ver>\AdaptiveCounter:LastPage<Rev
-which is like \cs{NewCounter}, except that the value of this counter
-gets written to the \file{.aux} file.
-
-There are two ways of setting an adaptive counter: you can simply use
-it in some construct (for instance through a counter synonym;
-section~ref[sec:counter:repr]), or you can set it explicitly, for
-instance as
- \Ver>\SetCounter:LastPage=PageValue<Rev
-See how this manual does it.
-
-\SubSection Examples of counter usage
-
-Items start at the value of one, so if a starting value of zero is
-necessary, the following will work
-\Ver>
-\Enumerate \SetCounter:item=-1
-\item ...<Rev
-
-
-\Section[sec:font] Font selection
-
-In \Lollipop, choosing a font is done through three parameters:
-\Description\item Typeface
-A collection of related styles and sizes. The typeface is set by the
-command \refcs{Typeface}.
-\item Style
-Italic, bold, roman, typewriter. You know. The style is set by the
-command \refcs{Style}.
-\item PointSize
-The size of a font in typographical points ($72.27$ per inch).
-The pointsize is set by the command \refcs{PointSize}.
-\>
-
-The most common change of font is a change in style. Therefore,
-issuing a command such as \Ver>\Style:bold<Rev immediately changes
-the font to the bold of the current typeface in the current pointsize.
-
-However, issuing a command such as \Ver>\Typeface:GoudyOldStyle<Rev
-or \Ver>\PointSize:28<Rev will not change the font, since such
-changes are usually accompanied by a change in style. In case that an
-immediate switch is necessary, the command
-\refcs{SetFont} can be given.
-This evaluates the current value of the typeface, style, and
-pointsize commands, and sets the font accordingly.
-
-A number of typeface names have been predefined in \Lollipop,
-however, in order to print them your printer (software) must have them
-available.
-
-\Example
-\SerifFace \PointSize:12
-\Style:roman This \Style:italic sentence \PointSize:10 has
-\SetFont way \SansFace \Style:roman too \SetFont many
-\PointSize:12 \SetFont font \Style:bold changes.
-\ExampleStop
-
-(The commands \cs{SerifFace} and \cs{SansFace} are defined in
-the master file of this manual, and serve to make this manual
-formattable on any system.)
-
-\SubSection Relative size changes
-
-Apart from setting the pointsize explicitly, it is also possibly to
-make size changes relative to the current size. For instance,
-\refcs{PointSizeLarger} and \refcs{PointSizeSmaller} with an optional
-argument indicating the size of the change can be used. These
-commands are not cumulative.
-
-\Example
-\SerifFace
-\PointSize:9 \SetFont Every once in a while,\SaveFont
-\PointSizeLarger[2] shouting \PointSizeLarger helps.
-\PointSizeSmaller[2]But most of the times it doesn't.
-\RestoreFont Unfortunately.
-\ExampleStop
-
-Similar to the changes in mathematics mode to script and scriptscript
-size, the same relative changes are available in text mode through
-the control sequences \refcs{script} and \refcs{scriptscript}.
-The control
-sequence \refcs{normal} can be used to restore the default size.
-
-Here is one application of such relative changes:
-\Ver>
-L\kern -.3em\raise .35ex\hbox {\script A}\kern -.1em\TeX<Rev
-which gives definition of the \LaTeX\ logo that is independent
-of typeface, size and style.
-
-The relative sizes of script and scriptscript fonts are by default at
-$70\%$ and $50\%$, but they can be set explicitly by
-\Ver>\PointSizeScriptSizes:10=10,7,5<Rev
-This also gives the possibility to have the \cs{normal} size to be
-different from the surrounding pointsize.
-
-\SubSection Typeface definition
-
-Defining a typeface means telling \Lollipop\ how the external font
-name, that is, the name of the \n{tfm} file, is to be constructed from
-the internal parameters. The command \refcs{DefineTypeface} takes four
-parameters and an optional fifth. The parameters are in sequence
-\Enumerate\item The internal name of the typeface: the name that is
-given to the \cs{Typeface} command.
-\item The root of the external file name. It is assumed that all
-font names of different styles and sizes are constructed by appending
-characters to this base.
-\item Suffixes corresponding to the styles that are available.
-\item Suffixes corresponding to the sizes that are available.
-\>
-
-Here is the definition of the Computer Modern typeface:
-
-\Ver>
-\DefineTypeface{ComputerModern}{cm}
- {roman:r; slant:sl; italic:ti; mitalic:mi; bold:bx; typewriter:tt;
- default:r;}
- {<6:5; <7:6; <8:7; <9:8; <10:9; <11:10;
- <12:10 \scaled\magstephalf;
- <14:10 \scaled\magstep1; <16:10 \scaled\magstep2;
- <20:10 \scaled\magstep3; >19:10 \scaled\magstep4;
- default:10;}<Rev
-
-Actually, not all combinations of styles and sizes are available.
-That's where the optional argument comes in. This argument can be
-used to specify with \TeX\ conditionals exceptional style/size
-combinations. Here some trickery is needed: internally the size is
-stored in \cs{Fsize}, and in order to use this parameter we need to
-make the at-sign a letter temporarily.
-
-\Ver>\makeatletter
-\DefineTypeface{Compu ...
- ...
- default:10;}
- [\ifStyle:italic \ifnum\Fsize<7 ti7\fi\fi
- \ifStyle:typewriter \ifnum\Fsize<8 tt8\fi\fi]<Rev
-
-You may have noticed that this scheme is not all-powerful. Thus
-I~found it easier to move all Computer Modern sans serif fonts into a
-new typeface: \n{ComputerSans}.
-
-For other typefaces specifying the size suffix may be much easier
-than for Computer Modern. For instance, here is the definition of the
-PostScript Helvetica typeface.
-
-\Ver>\makeatletter
-\DefineTypeface{psHelvetica}{helv}
- {roman:; italic:i; mitalic:i; bold:b; default:;}
- {default: at \Fsize pt;}
-\makeatother<Rev
-
-
-\SubSection Math fonts
-
-Switching styles in math mode should be possible:
-$${\Style:bold x\Style:roman y}z$$
-
-\SubSection Other font matters
-
-The combination \refcs{SaveFont} with a subsequent
-\refcs{RestoreFont} can
-be used to save and restore the current font.
-
-An abbreviation for a font can be defined by
-\Ver>\DefineFont:name=face,size,style<Rev
-This has the same effect as
-\Ver>\def\name{\TypeFace:face \PointSize:size \Style:style }<Rev
-but it takes considerable less processing inside \TeX.
-
-Even if you don't use Computer Modern as your main typeface, the
-typewriter style is not bad, so a control sequence
-\Ver>
-\def\tt{\Typeface:ComputerModern \Style:typewriter }<Rev
-has been given that makes \refcs{tt} always refer to the
-\n{cmtt} fonts. You're at liberty to change this, of course.
-
-\Section Baselineskip
-
-Corresponding to a font size usually the baseline skip has to change.
-By default a fixed ratio of~$1.2$ for this is taken, for instance
-using a 12~point baseline skip for 10~point fonts. Changing the ratio
-can be done by
-\Ver>\BaselineSkipPointSizeRatio:1.3<Rev
-
-If only for some specific size the baseline skip has to deviate from
-the default ratio, then this can be set by
-\Ver>\SetPointSizeBaselineSkip:9=12<Rev
-
-\Section[sec:indent:control] Indentation Control
-
-\SubSection To indent or not to indent
-
-In most documents there is a general rule that all paragraphs indent
-unless a certain condition, or that they do not indent unless certain
-special conditions hold. For \Lollipop\ documents this is determined
-by the command \refcs{AlwaysIndent}, with values \n{yes}/\n{no}.
-
-To override this default setting a command \refcs{Indent}
-(with values \n{yes}/\n{no}) exists, but that is mostly useful as an
-option in generic constructs, and even there it will not be used much.
-See section~\ref[sec:opt:indent] for options relating to indentation.
-
-Important: never set \cs{parindent} to zero. Preventing indentation
-globally should be done through \ver>\AlwaysIndent:no>.
-
-\SubSection[sec:basic-indent] Basic indent
-
-There is a quantity \refcs{basicindent} that is used on the first
-indentation level (see the next section for an explanation of these
-levels). At the start of a document it is set to the then current
-value of \cs{parindent}. You can override that by
-\refcs{BasicIndentIsSet}: give
-\Ver>\BasicIndentIsSet:no<Rev before the \cs{Start} command.
-
-This way, setting \cs{parindent} in the style definition controls the
-indentation in the whole document.
-
-\SubSection Indentation levels; indentation size
-
-When \Lollipop\ decides that text should be indented, it refers to a
-list of indentations for the exact amount. This list contains
-indentation amounts for each `level' of indentation: initially the
-level is one, and if you nest constructs that indent (for instance
-using a list inside a list) the level goes up one step per nested
-construct.
-
-By
-default the indentation on different levels is a fraction of the
-\cs{basicindent}. Thus you can regulate the indentation on
-all levels simultaneously by resetting the \cs{basicindent}.
-
-\Example
-\Distance:basicindent=15pt
-\DefineList:TestList item:left itemCounter item:stop Stop
-\TestList\item Level one \TestList\item Level two
-\TestList\item Level three\>]
-\Distance:basicindent=25pt
-\TestList\item Level one \TestList\item Level two
-\TestList\item Level three\>]
-\ExampleStop
-
-The amount of
-indentation on a certain level can be set explicitly with
-\refcs{LevelIndent}.
-
-\Example
-\Distance:basicindent=15pt
-\LevelIndent:2=20pt
-\DefineList:TestList item:left itemCounter item:stop Stop
-\TestList\item Level one \TestList\item Level two
-\TestList\item Level three\>]
-\ExampleStop
-
-In fact, sometimes you may want to know the name of the indentation
-on a certain level. This is a control sequence such as
-\refcs{levelindentii} for the second level. You get the idea.
-
-\SubSection Manipulating the indentation level
-
-Every once in a while it can be useful to move to a next indentation
-level, or to return to a previous level. For this
-the two commands \refcs{PushIndentLevel} and \refcs{PopIndentLevel} are
-available. One application is for `interrupted lists':
-
-\Example
-\Itemize\item One
-{\par\PopIndentLevel Interrupted text!\par}
-\item Two\>
-\ExampleStop
-
-See chapter~\ref[chap:external-files] for examples of the use of
-\cs{PushIndentLevel}
-
-\Section Margins
-
-By default, \Lollipop\ tries to keep straight margins. You can change
-its mind about that by \refcs{FlushRight} and \refcs{FlushLeft}
-which are tests:
-\Ver>\FlushRight:no \FlushLeft:no<Rev
-If the margins are not flush, the stretchable white space used
-is \refcs{rightmarginstretch} and \refcs{leftmarginstretch},
-which can be set by \cs{Distance}.
-
-You have to set the amount of stretch {\it before} specifying that
-the margins will not be flush. The \cs{FlushRight/Left} commands take
-the current value whenever they are called.
-
-\Section White Space
-
-White space can be indicated by \refcs{hwhite} and \refcs{vwhite}.
-They are often useful in style definitions. Use:
-\Ver>\vwhite:15pt<Rev
-or \Ver>\hwhite:{15pt minus 3pt}<Rev
-for stretch and shrink. The command \refcs{white} is independent
-of the mode, and it expands to \cs{hwhite} or \cs{vwhite}
-depending on the prevailing mode of \TeX.
-
-The command \refcs{fillup} is mostly useful in style definitions:
-it tries to fill up as much white space as is possible.
-For instance
-\Ver> line:start litteral:foo fillup litteral:bar line:stop<Rev
-will push \n{foo} and \n{bar} as far apart as is possibly
-within the margins.
-
-\ImpNote
-All three control sequences \cs{white}, \cs{hwhite}, \cs{vwhite}
-have internal equivalents, for instance
-\Ver>\def\white:#1 {\@white{#1}}<Rev
-\ImpNoteStop
-
-\Section[sec:com:distance] Distances
-
-The command \refcs{Distance} can be used
-to declare a name for a certain
-distance, or in more correct \TeX nical lingo, for a certain piece of
-glue. For instance, declaring that
- \Ver>\Distance:oneline=15pt<Rev
-means that you can specify in some constructs
-\Ver>\DefineFoo:Bar whitebefore:oneline whiteafter:oneline<Rev
-If you change your mind later about the value of \n{oneline} you only
-need to change one line in the style definition.
-
-Since the second parameter of \cs{Distance} is bounded by a space (or
-the line end, whatever comes first), you can specify stretchable
-distances by enclosing \n{plus} and \n{minus} parts in braces:
-\Ver>\Distance:oneline={15pt plus 2pt minus 3pt}<Rev
-
-The effect of \cs{Distance} is global. Let me know if you don't
-like it.
-
-\SubSection Distance synonyms
-
-Another use of \cs{Distance} is to define one distance as a synonym
-of another. This may come in handy if you use some basic distance,
-such as \n{oneline} for several purposes. Example: if you specify
-\Ver>\Distance:whitebefore=oneline<Rev
-than the whitespace before a construct will be taken to be
-\n{oneline} if you don't use the \opt{whitebefore} option explicitly.
-
-\SubSection[sec:adapt-distance] Adaptive distances
-
-Suppose you want to declare a section heading as
- \Ver>\DefineHeading:Section ...
- block:start [...] fillupto:widelabel title<Rev
-where \cs{widelabel} is the width of the widest label that
-occurs in your document. This requires just a tad of \TeX\
-programming. Just copy the details from the example below, which is
-the definition of \cs{Section} in this manual.
-
-By declaring something a \refcs{AdaptiveDistance} instead of just
-\cs{Distance} its value gets written to the \file{.aux} file at the
-end of the run, and restored in the next run. The second argument is
-simply the default value, in case you don't have an auxiliary file
-yet.
-
-\Ver>\AdaptiveDistance:WidestLabel=15pt
-\def\MeasureLabel{\ifdim\BlockWidth>\WidestLabel
- \global\WidestLabel\BlockWidth\fi}
-\DefineHeading:Section
- whitebefore:{20pt plus 2pt} whiteafter:14pt
- line:start PointSize:14 Style:italic
- block:start block:start ChapterCounter . SectionCounter
- Spaces:1 block:stop MeasureLabel
- fillupto:WidestLabel
- title line:stop
- external:contents title external:stop
- label:start ChapterCounter . SectionCounter label:stop
- Stop<Rev
-
-Note how two nested blocks are used: the first is to measure the
-label, and the width is written to the adaptive distance by means of
-a small macro; the second block is to fill out the white space.
-
-If you want the paragraph indentation to depend on this adaptive
-width, you can give
- \Ver>\StartCommand{\Distance:parindent=WidestLabel }<Rev
-to set \cs{parindent} at the start of the document.
-See section~\ref[sec:doc-start-stop] and~\ref[sec:basic-indent].
-
-\Section[sec:InputFile] Input Files
-
-Parts of a document can be loaded by
-\Ver>\InputFile:parta
-\InputFile:partb<Rev
-et cetera. A~document part loaded by \refcs{InputFile} always starts
-on a new page. In section~\ref[sec:ref-local] it was already
-explained how local references for such files can be created.
-
-Perhaps most importantly, loading files this way provides a form of
-error checking; \Lollipop\ checks at the end of such a file whether all
-used constructs are balanced properly.
-
-
-\Section[sec:tests] Tests
-
-Users can define tests:
-\Ver>\DefineTest:SomethingTheMatter<Rev
-which are set like any other test:
-\Ver>\SomethingTheMatter:yes<Rev
-or \Ver>\SomethingTheMatter:no<Rev
-
-Tests can be used as \Ver>\ifSomethingTheMatter ... \else ... \fi<Rev
-Like any other conditional, test can be used inside constructs.
-\Ver>\DefineFoo:Bar [...]
- ifSomethingTheMatter [...] fi
- [...] Stop<Rev
-
-\Section Goodies
-
-\SubSection List commands
-
-Lollipop does a lot of list processing internally, and a few
-of the commands have been made available to the user.
-
-\Description\item \refcs{NewList}
-creates a list, and sets it to empty:
- \Ver>\NewList:mylist<Rev
- \item \refcs{EmptyList}
-just empty a list.
- \item \refcs{TheList}
-inserts the list. This will typeset the contents of it.
- \Ver>\TheList:mylist<Rev
- \item \refcs{AppendToList}
-adds data to a list. \Ver>\AppendToList:mylist={my data}<Rev
-The data are terminated by a space or line end, hence the braces.
-\>
-
-\SubSection Programming Tools
-
-A few commands are useful for the Lollipop style designer who wants
-to write more sophisticated macros (see for instance the address book
-macros in the last chapter).
-
-\Description\item \refcs{UndefinedCS}
-is a test on control sequences.
- \Ver>\if\UndefinedCS{testcs} ... \else ... \fi<Rev
- \item \refcs{EqualString}
-tests equality of strings.
- \Ver>\if\EqualString{one}{two} ... \else ... \fi<Rev
- \item \refcs{EqualStringX}
-tests equality of strings, using only expansion.
- \Ver>\if\EqualStringX{one}{two} ... \else ... \fi<Rev
- \item \refcs{StringBefore}
-tests lexicographic ordering of strings. The string are not supposed
-to contain characters with char codes~0, 127,~255.
- \Ver>\if\StringBefore{one}{two} ... \else ... \fi<Rev
- \item \refcs{NextChar}
-chooses between two actions, based on the next character.
- \Ver>\if\NextChar[{\macro}{\macro[default]} ...<Rev
- \item \refcs{IsEmptyList}
-can test whether an argument is empty.
- \Ver>\if\IsEmptyList{#1} ...<Rev
-is true for calls such as \ver>\macro{}>.
- \item\refcs{loop}
-can be used for repeated execution of statements. (Users of plaing
-\TeX\ may recognize this macro; it is slightly extended here
-to include the \cs{else} case.) It is
-used as:
- \Ver>\loop ... \if ... \repeat<Rev
-of \Ver>\loop ... \if ... \else ... \repeat<Rev
-
-
- \>
-
-\SubSection[sec:everypar] \cs{everypar}
-
-The \TeX\ primitive \cs{everypar} should not be used any more.
-Instead use the command \refcs{EveryParagraph} as if you are setting
-a token list:
- \Ver>\EveryParagraph{ ... }<Rev
-
-\SubSection[sec:everymath] \cs{everymath}
-
-The \TeX\ primitive \cs{everymath} should not be used any more.
-Instead use the command \refcs{EveryMath} as if you are setting
-a token list:
- \Ver>\EveryMath{ ... }<Rev
-
-\SubSection[sec:everydisplay] \cs{everydisplay}
-
-The \TeX\ primitive \cs{everydisplay} should not be used any more.
-Instead use the command \refcs{EveryDisplay} as if you are setting
-a token list:
- \Ver>\EveryDisplay{ ... }<Rev
-
-\SubSection Allocation
-
-The commands \refcs{SaveAlloc} and subsequent \refcs{RestoreAlloc} save and
-reset the internal \TeX\ allocation counters.
-
-\endinput
-
-% 2014/04/13 Added some notes about \EveryMath, and
-% \EveryDisplay. Also the wrong spelling of `note' changed
-% to `not' in `sec:everypar'.
-% 2014/04/11 Changed \n{tty} style to \n{typewriter} style
-% 92/11/18 Adaptive distances explained
-% 92/11/20 Adaptive counters explained
-% 93/05/13 changes in font macros