@c -*- coding: utf-8; mode: texinfo; -*-

@ignore
****************************
MACRO DEFINITIONS GUIDELINES
****************************

This file contains macro definitions that are common to all languages.
It holds all macro definitions that either do not contain translatable
text (i.e., text visible in the output) or intentionally stay
untranslated.

Macro definitions that contain translatable text belong to file
`macros.itexi`.
@end ignore

@c Don't replace quotes with directed quotes.
@set txicodequoteundirected
@set txicodequotebacktick

@c For sorting, ignore backslashes in indices.
@set txiindexbackslashignore

@c Make `@var` in typewriter environments use slanted typewriter.
@set txicodevaristt

@c Don't break words at `-` and `_` within `@code`, and activate
@c 'microtype'.
@c
@c Both commands must be in an `iftex` block because microtype is
@c new in Texinfo 7.0 (we have it texinfo.tex) and neither of the
@c two has an effect outside of PDF documentation anyhow.
@iftex
@allowcodebreaks false
@microtype on
@end iftex


@include en/cyrillic.itexi


@c   ***** Displaying text *****

@c We need this for `@warning`: Due to a bug in `texi2html`, ordinary
@c backslashes disappear if used in commands like `@code`.

@ifnottex
@macro bs
\\
@end macro
@end ifnottex

@iftex
@tex
\global\let\bs = \backslashchar
@end tex
@end iftex


@ifnotinfo

@macro notation{TEXT}
@var{\TEXT\}
@end macro

@end ifnotinfo

@ifinfo

@macro notation{TEXT}
\TEXT\
@end macro

@end ifinfo


@macro smallspace
@sp 1
@end macro


@c This macro stays untranslated because it is only used in untranslated
@c manuals.

@ifhtml

@macro advanced{TEXT}
@html
<div class="advanced">
@end html
@strong{Advanced note:} \TEXT\
@c keep the space for proper nesting of </p>

@html
</div>
@end html
@end macro

@end ifhtml

@ifnothtml

@macro advanced{TEXT}
@quotation
@b{Advanced note:} \TEXT\
@end quotation
@end macro

@end ifnothtml


@c   ***** Displaying images *****

@iftex
@tex
% We want inline images vertically centered (more or less).
% Non-inline images are not affected (due to the `\ifhmode`
% conditional).

% This command is a simplified version of the corresponding LaTeX
% macro.
%
% Don't remove the spaces after the digit 0; they are needed to
% end the scanning of a number.
\gdef\raisebox#1#2{%
  \setbox0 = \hbox{#2}%
  \def\width{\wd0 }%
  \def\height{\ht0 }%
  \dimen0 = #1\relax
  \raise\dimen0 \box0 }

% Factor -0.2 is heuristic.
\global\let\imageold = \image
\gdef\image#1{%
  \ifhmode
    \raisebox{-.2\height}{\imageold{#1}}%
  \else
    \imageold{#1}%
  \fi}
@end tex
@end iftex


@c   ***** Displaying images not generated by lilypond-book *****

@c Current installation setup of Info docs requires that all images are
@c expected to be found in the `lilypond/` subdirectory.  `lilypond-book`
@c already generates proper @image commands for images of music; these
@c macro definitions do the same for other images.
@c
@c We use the file name as the `alt` attribute.

@ifnotinfo

@macro sourceimage{FILENAME,WIDTH,HEIGHT}
@image{pictures/\FILENAME\,\WIDTH\,\HEIGHT\,\FILENAME\}
@end macro

@end ifnotinfo

@ifinfo

@macro sourceimage{FILENAME,WIDTH,HEIGHT}
@image{lilypond/pictures/\FILENAME\,\WIDTH\,\HEIGHT\,\FILENAME\}
@end macro

@end ifinfo


@c   ***** Headers *****

@c For use as the Level 5 header
@macro subsubsubheading {TEXT}
@subsubheading @i{\TEXT\}
@end macro

@macro lydoctitle {TEXT}
@subsubheading @i{\TEXT\}
@end macro


@c   ***** References *****

@c References look better if section names (which can use `@code`
@c and the like) are used instead of plain-text node names.

@xrefautomaticsectiontitle on


@c We introduce an additional cross-reference command `@iref`
@c specifically tailored for the PDF version of the Internals
@c Reference, making
@c
@c   @iref{foo}
@c
@c print
@c
@c   foo (page Y).

@iftex

@tex
% All special argument handling has been removed since the `@iref`
% calls are auto-generated for the Internals Reference and thus always
% well-defined.
%
% See the implementation of `\xrefX` in `texinfo.tex` for more comments
% and explanations.
%
% Note that we bypass `@xrefautomaticsectiontitle on` to get proper
% formatting of references to `@anchor`.
%
% This code needs `texinfo.tex` version 2021-02-20.11 or newer.

\gdef\iref{\irefXX}
\gdef\irefXX#1{\def\irefXXarg{#1}\futurelet\tokenafteriref\irefXXX}
\gdef\irefXXX{\expandafter\irefX\expandafter[\irefXXarg]}

\gdef\irefX[#1]{\begingroup
  \unsepspaces
  \def\printedrefname{\ignorespaces #1}%
  \startxreflink{#1}{}%
  \getrefx{#1-title}\Xthisreftitle
  %
  % Start reference with node name.
  \code{\printedrefname}%
  % Output page reference.
  \turnoffactive \space (\putwordpage\tie\refx{#1-pg})%
  %
  % Add a `,` if `@iref` is followed by a space.
  \if\space\noexpand\tokenafteriref ,%
  \else\ifx\	\tokenafteriref ,%  @TAB
  \else\ifx\*\tokenafteriref ,%     @*
  \else\ifx\ \tokenafteriref ,%     @SPACE
  \else\ifx\
            \tokenafteriref ,%      @NL
  \else\ifx\tie\tokenafteriref ,%   @tie
  \fi\fi\fi\fi\fi\fi
  \endlink
\endgroup}
@end tex

@end iftex

@ifnottex

@c Let `@xrefautomaticsectiontitle on` take care of improved
@c formatting.

@macro iref {TEXT}
@ref{\TEXT\}
@end macro

@end ifnottex


@c   ***** Indexing *****

@c Don't remove the `@c` within the macro definition!  See section 19.3,
@c 'Macro Details and Caveats', in the Texinfo info file for explanation.

@iftex

@c In TeX output mode we unify `@findex` and `@cindex`
@c entries in the concept index; this is done with the `@syncodeindex`
@c lines in macro `@lilyTitlePage`.  We also set
@c `txiindexbackslashignore` so that '\foo' gets sorted as 'foo'.
@c However, the latter directive has the side effect that '\foo' and
@c 'foo' are treated as equal by the index sorting program.  We don't
@c want that: It is important for us that entries for both '\foo' and
@c 'foo' appear in the unified index.
@c
@c For this reason, we make macro `@funindex` use `@sortas` to set a
@c special sorting key, and we redefine Texinfo's internal macro
@c `\indexwritesortas` to swallow backslashes.  We also modify
@c `@cindex` to insert another sorting key to ensure that '\foo'
@c immediately comes after 'foo', followed by entries like 'foo bar'.
@c
@c While the above works well for most cases, there is still a problem
@c if we have `@funindex foo` and `@funindex \foo` at the same time.
@c This can't be handled in an automated way, so we introduce two
@c macros `@funindexpre` and `@funindexpost`.  In particular,
@c
@c * `@funindexpre foo` gets sorted before `@funindex \foo`.
@c * `@funindexpost \foo` gets sorted after `@funindex foo`.
@c
@c `@cpindex` is the internal version of `@cindex`.
@c
@c Another special case is indexing '\\'; you have to write
@c
@c   @funindex @sortas{@bs{}@bs{}} \\

@tex
{
\catcode`\-=13
\gdef\indexwritesortas{%
  \begingroup
  \indexnonalnumreappear
  \backslashdisappear
  \indexwritesortasxxx}
}

% `@macro` doesn't allow redefinition of existing commands.
\global\let\cindex\relax

% For index sorting we need two characters with charcode values less
% than that of the space character.  Note that this only works if TeX
% is called with option `-8bit` so that real 8-bit characters are
% emitted to the auxiliary index files.
{
\catcode`\^^A=11 % 0x01
\catcode`\^^B=11 % 0x02
\catcode`\^^C=11 % 0x03
\catcode`\^^D=11 % 0x04
\xdef\indexA{^^A}
\xdef\indexB{^^B}
\xdef\indexC{^^C}
\xdef\indexD{^^D}
}
@end tex

@macro cindex {TEXT}
@cpindex @sortas{\TEXT\@indexA{}}\TEXT\
@c
@end macro

@macro funindexpre {TEXT}
@findex @sortas{\TEXT\@indexB{}}\TEXT\
@c
@end macro

@macro funindex {TEXT}
@findex @sortas{\TEXT\@indexC{}}\TEXT\
@c
@end macro

@macro funindexpost {TEXT}
@findex @sortas{\TEXT\@indexD{}}\TEXT\
@c
@end macro

@end iftex

@ifnottex

@macro funindexpre {TEXT}
@findex \TEXT\
@c
@end macro

@macro funindex {TEXT}
@findex \TEXT\
@c
@end macro

@macro funindexpost {TEXT}
@findex \TEXT\
@c
@end macro

@end ifnottex


@c   ***** Macros specific to translated docs *****

@ifhtml

@ifset bigpage
@macro untranslated
@end macro
@end ifset

@ifclear bigpage
@macro untranslated
UNTRANSLATED NODE: IGNORE ME
@end macro
@end ifclear

@end ifhtml

@ifnothtml

@macro untranslated
@end macro

@end ifnothtml


@c   ***** Macros specific to the web site *****

@ifset web

@c make link to bugfixes for news-old.itexi
@c use underscores for version: @bugfixes{2_13_13,}
@c use specifier arg when listing multiple versions
@c (see September 20, 2007 post for an example)
@macro bugfixes{version,specifier}
@uref{https://code.google.com/p/lilypond/issues/list?can=1&q=fixed_\version\&colspec=ID+Type+Status+Priority+Milestone+Owner+Summary,Bugfixes
\specifier\}
@end macro

@macro divId {ID}
@html
<div id="\ID\">
@end html
@end macro

@macro divClass {CLASS}
@html
<div class="\CLASS\">
@end html
@end macro

@macro divEnd
@c keep the space for proper nesting of </p>

@html
</div>
@end html
@end macro

@ifhtml
@ifclear bigpage
@macro docDownload{before,target,after}
@c Empty comment to enforce that the html environment starts at the
@c beginning of a line.
@html
<em>\before\<!-- file-size:, href="../\target\"-->\after\</em>
@end html
@end macro
@end ifclear
@ifset bigpage
@macro docDownload{before,target,after}
@c Empty comment to enforce that the html environment starts at the
@c beginning of a line.
@html
<em>\before\<!-- file-size:, href="\target\"-->\after\</em>
@end html
@end macro
@end ifset
@end ifhtml
@ifnothtml
@macro docDownload{before,target,after}
@emph{\before\\after\}
@end macro
@end ifnothtml

@ifclear web_version
@ifclear bigpage
@macro docLink{name,target,webLink}
@uref{../\target\, \name\}
@end macro
@end ifclear
@ifset bigpage
@macro docLink{name,target,webLink}
@uref{\target\, \name\}
@end macro
@end ifset
@end ifclear
@ifset web_version
@macro docLink{name,target,webLink}
\webLink\
@end macro
@end ifset

@macro miscLink{MISC-FILE,MISC-TEXT}
@uref{https://lilypond.org/misc/\MISC-FILE\,\MISC-TEXT\}
@end macro

@macro spanClass {CLASS}
@html
<span class="\CLASS\">
@end html
@end macro

@macro spanEnd
@c keep the space for proper nesting of </p>

@html
</span>
@end html
@end macro


@c not strictly necessary, but it makes things easier for updating news
@macro newsItem
@html
<div class="news-item">
@end html
@end macro

@macro newsEnd
@c keep the space for proper nesting of </p>

@html
</div>
@end html
@end macro


@macro imageClickable{IMAGE-FILE, EXT, MORE-TEXT, CLICK-FILE, CLICK-EXT, POSITION}
@html
<div class="float-\POSITION\">
  <a class="clickable" href="pictures/\CLICK-FILE\.\CLICK-EXT\">
    <img src="pictures/\IMAGE-FILE\.\EXT\" alt="\IMAGE-FILE\">
  </a>
  <p style="text-align: center">
    \MORE-TEXT\
  </p>
</div>
@end html
@iftex
@image{pictures/\IMAGE-FILE\,,,\IMAGE-FILE\}
@end iftex
@ifinfo
@image{lilypond/pictures/\IMAGE-FILE\,,,\IMAGE-FILE\}
@end ifinfo
@end macro

@macro imageFloat{IMAGE-FILE, EXT, POSITION}
@html
<img class="float-\POSITION\" src="pictures/\IMAGE-FILE\.\EXT\" alt="\IMAGE-FILE\">
@end html
@iftex
@image{pictures/\IMAGE-FILE\,,,\IMAGE-FILE\,\EXT\}
@end iftex
@ifinfo
@image{lilypond/pictures/\IMAGE-FILE\,,,\EXT\}
@end ifinfo
@end macro

@macro imageId{ID, IMAGE-FILE, EXT, ALT}
@html
<div id="\ID\">
  <img src="pictures/\IMAGE-FILE\.\EXT\" alt="\ALT\">
</div>
@end html
@iftex
@image{pictures/\IMAGE-FILE\,,,\ALT\}
@end iftex
@ifinfo
@image{lilypond/pictures/\IMAGE-FILE\,,,\ALT\}
@end ifinfo
@end macro

@end ifset

@macro staticFile{RELLINK, DESC}
@uref{https://lilypond.gitlab.io/static-files/\RELLINK\, \DESC\}
@end macro


@c   ***** Macros and fonts for displaying LilyPond code snippets *****

@tex

% Override CM typewriter.  For Pygments support we need bold and bold
% slanted typewriter, which is not available in the Computer Modern font
% family used by Texinfo.  Instead, we use the font family 'LMMonoLt10' that
% comes with the 'Latin Modern' package, which is a light version of 'cmtt',
% and which provides all necessary shapes.
%
% We do even more than just overriding: We correctly use bold shapes for
% typewriter in section titles.  Note that Texinfo is already partially
% prepared to do so via the `\ttbshape` macro; however, it doesn't provide
% `\ttbslshape`.
\def\makefont#1#2{%
  \global\font#1 = #2
  \global\hyphenchar#1 = -1
}

\makefont{\texttt}{lmttr scaled \mainmagstep}
\makefont{\deftt}{lmttr scaled \magstep1}
\makefont{\smalltt}{lmttr scaled 900}
\makefont{\smallertt}{lmttr scaled 800}
\makefont{\seventt}{lmttr scaled 700}
\makefont{\titlett}{lmttb scaled \magstep4}
\makefont{\chaptt}{lmttb scaled \magstep3}
\makefont{\sectt}{lmttb scaled \magstep2}
\makefont{\ssectt}{lmttb scaled 1315}
\makefont{\reducedtt}{lmttr}

\makefont{\textttsl}{lmttro scaled \mainmagstep}
\makefont{\defttsl}{lmttro scaled \magstep1}
\makefont{\smallttsl}{lmttro scaled 900}
\makefont{\smallerttsl}{lmttro scaled 800}
\makefont{\seventtsl}{lmttro scaled 700}
\makefont{\titlettsl}{lmttbo scaled \magstep4}
\makefont{\chapttsl}{lmttbo scaled \magstep3}
\makefont{\secttsl}{lmttbo scaled \magstep2}
\makefont{\ssecttsl}{lmttbo scaled 1315}
\makefont{\reducedttsl}{lmttro}

% Activate font changes.  To avoid redefinitions of Texinfo macros, we use
% `\aftergroup` to call `\assignfonts{text}` to do this job (right now we
% are in a `@tex` group).
\gdef\callassignfonts{\assignfonts{text}}
\aftergroup\callassignfonts

% Bold and bold italic typewriter are only needed by Pygments in the
% `@format` environment; no need to set up sectioning fonts or other
% sizes.
\makefont{\textttbx}{lmttb scaled \mainmagstep}
\makefont{\textttbxsl}{lmttbo scaled \mainmagstep}

% Register additional CMaps.
\csname cmapOT1TT\endcsname{\textttbx}
\csname cmapOT1TT\endcsname{\textttbxsl}

\ifx\luatexversion\thisisundefined
\else
  \protected\def\pdfmapfile{\pdfextension mapfile }
\fi

% Load font map file.
\pdfmapfile{+lmtt.map}

% Use normal characters for typewriter bold and typewriter bold italic, not
% active ones (which would always select non-bold, upright typewriter).
\gdef\normalcatcodes{%
  \catcode`\"=\other
  \catcode`\$=\other
  \catcode`\<=\other
  \catcode`\>=\other
  \catcode`\\=\other
  \catcode`\^=\other
  \catcode`\_=\other
  \catcode`\|=\other
  \catcode`\~=\other
  \catcode`\+=\other
}

% Internal font switches for `@tb` and `@tbsl`.  We have to do this in two
% steps, resetting the character category codes before the argument `#1` is
% read.
\gdef\dotb{%
  \begingroup
  \normalcatcodes
  \dotbx}
\gdef\dotbx#1{%
  \textttbx
  \plainfrenchspacing
  #1%
  \endgroup
  \null}

\gdef\dotbsl{%
  \begingroup
  \normalcatcodes
  \dotbslx}
\gdef\dotbslx#1{%
  \textttbxsl
  \plainfrenchspacing
  #1%
  \endgroup
  \null}

% The macros `\stripPT` and `\slantshift` have been adapted from `plain.tex`.

% Strip off 'pt' from a font dimension returned by the `\the` command so
% that its value can be used as a dimension-less scaling factor.
\global\let\oldbb = \\
{\catcode`p=12 %
 \catcode`t=12 %
 \gdef\\#1pt{#1}}
\global\let\stripPT = \\
\global\let\\ = \oldbb

% Insert a kern scaled by the slant of the font.
\gdef\slantshift#1{%
  \dimen1 = #1\relax
  \kern \expandafter\stripPT\the\fontdimen1\font \dimen1}

% Latin Modern's typewriter tilde character has a different vertical
% position in comparison to Computer Modern – being a modern font, this
% glyph is not intended to be used as an accent character by TeX.  As a
% result, TeX's `\accent` command fails: it causes an overlap of the base
% glyph with the tilde.  We thus redefine the `@~` macro, shifting the tilde
% glyph both vertically and horizontally (the latter mainly to provide a
% proper offset for slanted base glyphs) if a typewriter font is detected.
\gdef\~#1{{%
  \ifusingtt
    {\leavevmode
     \setbox0 = \hbox{#1}%
     \dimen0 = \ht0 %
     \advance\dimen0 \string-.35ex%
     {\rlap{\slantshift{\dimen0}\raise \dimen0 \hbox{\char "7E}}#1}}%
    {\accent "7E #1}%
}}

@end tex


@c Since stuff like `@t{@b{...}}` doesn't work in Texinfo, provide `@tb` as
@c a command to access bold typewriter.

@iftex
@macro tb {arg}
@dotb{\arg\}
@end macro
@end iftex

@ifnottex
@macro tb {arg}
@t{\arg\}
@end macro
@end ifnottex


@c Provide another command `@tbsl` to access bold slanted typewriter.

@iftex
@macro tbsl {arg}
@dotbsl{\arg\}
@end macro
@end iftex

@ifnottex
@macro tbsl {arg}
@t{\arg\}
@end macro
@end ifnottex


@c Finally, we need a new environment `pygments`: Internally, `@format` is
@c used instead of `@example`, but this doesn't activate straight single
@c quotes and backquotes in PDF output.

@iftex
@macro pygments
@format
@setcodequotes
@end macro
@end iftex

@ifnottex
@macro pygments
@format
@end macro
@end ifnottex

@macro endPygments
@end format
@end macro


@c   ***** LuaTeX enhancement for `@code` *****

@c See file `code.lua` for details.
@tex
\ifx\luatexversion\thisisundefined
\else
  % Register `code_hyphenate` as a filter, to be applied before normal
  % hyphenation.
  \directlua{
    dofile(kpse.find_file("code.lua"))
    callback.register("hyphenate",
      function(head, tail)
        code_hyphenate(head)
        lang.hyphenate(head)
      end) }

  % Save the original internal function that handles the argument of
  % `@code`.
  \global\let\texicodex \codex

  % Set and unset node attribute key 200 (which is an arbitrarily
  % chosen value), enabling `code_hyphenate` to identify nodes that
  % belong to `@code`.  We use `\xdef` to avoid issues with '-',
  % which is defined differently outside of this group.
  \xdef\setattribute{%
    \attribute 200 = 1 }
  \xdef\unsetattribute{%
    \attribute 200 = -"7FFFFFFF }

  % To 'escape' the current group we use `\aftergroup` to unset the
  % LuaTeX attribute.
  \gdef\codex#1{%
    \setattribute
    \aftergroup\unsetattribute
    \texicodex{#1}}
\fi
@end tex
