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

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

This file contains macro definitions that are common to all languages,
i.e., all macro definitions that do not contain translatable text
(namely text visible in the output).

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
@set txiindexbackslashignore


@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`.

@macro bs
\\
@end macro


@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 `texi2html` 1.82 doesn't support the newer `@indentedblock`,
@c `@smallindentedblock`, and `@raggedright` environments.  It would be
@c tempting to use `@quotation` and `@smallquotation` as a replacement
@c for the former two; however, due to a bug we get terrible vertical
@c formatting if `@multitable` environments are put inside of quotation
@c environments.

@ifnothtml

@macro indentedBlock
@indentedblock
@end macro

@macro endIndentedBlock
@end indentedblock
@end macro

@end ifnothtml

@ifhtml

@macro indentedBlock
@end macro

@macro endIndentedBlock
@end macro

@end ifhtml


@ifnothtml

@macro smallIndentedBlock
@smallindentedblock
@end macro

@macro endSmallIndentedBlock
@end smallindentedblock
@end macro

@end ifnothtml

@ifhtml

@macro smallIndentedBlock
@end macro

@macro endSmallIndentedBlock
@end macro

@end ifhtml


@iftex

@macro raggedRight
@raggedright
@end macro

@macro endRaggedRight
@end raggedright
@end macro

@end iftex

@ifnottex

@macro raggedRight
@end macro

@macro endRaggedRight
@end macro

@end ifnottex


@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.4 is heuristic.
\global\let\imageold = \image
\gdef\image#1{%
  \ifhmode
    \raisebox{-.4\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

@ifclear snippets-sections
@macro lydoctitle {TEXT}
@subsubsubheading{\TEXT\}
@end macro
@end ifclear


@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. However,
@c the command is not supported by texi2html-1.82

@ifnothtml

@xrefautomaticsectiontitle on

@end ifnothtml

@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.
%
% Not 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}%
  %
  % Make link in pdf output.
  \ifpdf
    % For pdfTeX and LuaTeX.
    {\indexnofonts
     \makevalueexpandable
     \turnoffactive
     \setpdfdestname{#1}%
     \leavevmode
     \startlink attr{/Border [0 0 0]} goto name{\pdfmkpgn{\pdfdestname}}%
    }%
    \setcolor{\linkcolor}%
  \else
    \ifx\XeTeXrevision\thisisundefined
    \else
      % For XeTeX.
      {\indexnofonts
       \makevalueexpandable
       \turnoffactive
       \setpdfdestname{#1}%
       \leavevmode
       \special{pdf:bann << /Border [0 0 0] /Type /Annot /Subtype /Link /A
         << /S /GoTo /D (\pdfdestname) >> >>}%
      }%
      \setcolor{\linkcolor}%
    \fi
  \fi
  %
  {%
    % Have to otherify everything special to allow `\csname` to
    % include `_` in the xref name, etc.
    \indexnofonts
    \turnoffactive
    \def\value##1{##1}%
    \expandafter\global\expandafter\let\expandafter\Xthisreftitle
      \csname XR#1-title\endcsname
  }%
  %
  % Start reference with node name.
  \code{\printedrefname}\space
  % Output page reference.
  \turnoffactive (\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', `@cindex', and `@vindex'
@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'.

@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\
@kindex @sortas{\TEXT\@indexB{}}\TEXT\
@c
@end macro

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

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

@end iftex

@ifnottex

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

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

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

@end ifnottex

@c XXX Currently we are forced to use ancient version 1.82 of texi2html
@c     (from 2005); we thus have to provide a macro for `@sortas',
@c     which was introduced in texinfo version 6.1 (in 2016).

@ifhtml
@macro sortas {TEXT}
@end macro
@end ifhtml


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

@c ugh, cannot set/define global variable 'translationof' in any way :-(

@iftex

@macro translationof{TEXT}
@end macro

@end iftex

@ifinfo

@macro translationof{TEXT}
@set translationof \TEXT\
@end macro

@end ifinfo

@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 docSize{before,target,after}
@html
\before\<!-- file-size:, href="../\target\"-->\after\
@end html
@end macro
@end ifclear
@ifset bigpage
@macro docSize{before,target,after}
@html
\before\<!-- file-size:, href="\target\"-->\after\
@end html
@end macro
@end ifset
@end ifhtml
@ifnothtml
@macro docSize{before,target,after}
\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/website/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


@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`.
\global\font\texttt = lmttr scaled \mainmagstep
\global\font\deftt = lmttr scaled \magstep1
\global\font\smalltt = lmttr scaled 900
\global\font\smallertt = lmttr scaled 800
\global\font\seventt = lmttr scaled 700
\global\font\titlett = lmttb scaled \magstep4
\global\font\chaptt = lmttb scaled \magstep3
\global\font\sectt = lmttb scaled \magstep2
\global\font\ssectt = lmttb scaled 1315
\global\font\reducedtt = lmttr

\global\font\textttsl = lmttro scaled \mainmagstep
\global\font\defttsl = lmttro scaled \magstep1
\global\font\smallttsl = lmttro scaled 900
\global\font\smallerttsl = lmttro scaled 800
\global\font\seventtsl = lmttro scaled 700
\global\font\titlettsl = lmttbo scaled \magstep4
\global\font\chapttsl = lmttbo scaled \magstep3
\global\font\secttsl = lmttbo scaled \magstep2
\global\font\ssecttsl = lmttbo scaled 1315
\global\font\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.
\global\font\textttbx = lmttb scaled \mainmagstep
\global\font\textttbxsl = lmttbo scaled \mainmagstep

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

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

% Internal font switches for `@tb` and `@tbsl`.
\gdef\dotb#1{{%
  \textttbx
  \plainfrenchspacing
  #1}%
  \null}

\gdef\dotbsl#1{{%
  \textttbxsl
  \plainfrenchspacing
  #1}%
  \null}

@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}
\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}
\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
