@c Defined macros for Texinfo source documents.
@c Copyright 2017-2025 The Software Samurai
@c 15-Sep-2025

@c (Software Sam web address)
@macro SAMADDRESS
www.SoftwareSam.us
@end macro

@c Tech Note: In texi2any version 5, there is a serious bug in the parser 
@c related to the '@heading' group of instructions when those headings are 
@c inside and indentation block.
@c In texi2any version 6, the parser automatically and INAPPROPRIATELY 
@c promotes or demotes the '@heading' group of instructions to match the 
@c actual section level. We seriously disagree with this design decision; 
@c and assert that "headings" have no relation whatever to "sections."
@c To avoid these issues, we define our own @heading, @subheading and 
@c @subsubheading commands. Note that for HTML output, the referenced CSS 
@c classes should be defined, which they are in our implementation. If they 
@c were not, then the browser's defaults would be used.
@macro Heading{x,y}
@ifnothtml
@sp 1
@t{\x\}@*
@t{\y\}@*
@end ifnothtml
@ifhtml
@html
<h3 class="heading">\x\</h3>
@end html
@end ifhtml
@end macro

@macro Subheading{x,y}
@ifnothtml
@sp 1
@t{\x\}@*
@t{\y\}@*
@end ifnothtml
@ifhtml
@html
<h4 class="subheading">\x\</h4>
@end html
@end ifhtml
@end macro

@macro Subsubheading{x,y}
@ifnothtml
@sp 1
@t{\x\}@*
@t{\y\}@*
@end ifnothtml
@ifhtml
@html
<h4 class="subsubheading">\x\</h4>
@end html
@end ifhtml
@end macro

@c Additional heading-style definitions.
@c - Note that the info-reader document displays all of these in the same format.
@c   The "y" parameter may be any single-width character; however, recommended
@c   characters are '▔' (Unicode U+2594) or '─' (Unicode U+2500).
@c - Note also that for maximum flexibility in formatting the info-reader 
@c   document, this macro DOES NOT enforce a linefeed before display of heading.
@c   For this reason, be sure to provide a newline (@*) or leave an empty line 
@c   before the macro invocation. Spacing within the HTML document is 
@c   automatically handled by the specified class definition.
@macro H5heading{x,y}
@ifnothtml
@t{\x\}@*
@t{\y\}@*
@end ifnothtml
@ifhtml
@html
<p class="h5heading">\x\</p>
@end html
@end ifhtml
@end macro

@macro H6heading{x,y}
@ifnothtml
@t{\x\}@*
@t{\y\}@*
@end ifnothtml
@ifhtml
@html
<p class="h6heading">\x\</p>
@end html
@end ifhtml
@end macro

@macro H7heading{x,y}
@ifnothtml
@t{\x\}@*
@t{\y\}@*
@end ifnothtml
@ifhtml
@html
<p class="h7heading">\x\</p>
@end html
@end ifhtml
@end macro

@macro H8heading{x,y}
@ifnothtml
@t{\x\}@*
@t{\y\}@*
@end ifnothtml
@ifhtml
@html
<p class="h8heading">\x\</p>
@end html
@end ifhtml
@end macro

@c Page Dividers
@macro hr90
@ifnothtml
@verb{|     _____________________________________________________________________|}
@sp 1
@end ifnothtml
@ifhtml
@html
<hr>
@end html
@end ifhtml
@sp 1
@end macro

@macro hr90w
@ifnothtml
@sp 1
@verb{|     █████████████████████████████████████████████████████████████████████|}
@sp 2
@end ifnothtml
@ifhtml
@html
<br><hr style="height:14px; border-radius:7px; color:silver; background:silver;"><br>
@end html
@end ifhtml
@end macro

@macro hr40
@ifnothtml
@center @t{────────────────────}
@end ifnothtml
@ifhtml
@html
<div style="width:40%; margin:0 auto"><hr></div><br>
@end html
@end ifhtml
@end macro

@macro hr40d
@ifnothtml
@center @t{─ ─ ─ ─ ─ ─ ─ ─ ─ ─}
@end ifnothtml
@ifhtml
@html
<div style="width:40%; margin:0 auto; font-family:monospace">──  ──  ──  ──  ──  ──  ──  ──  ──  ──  ──  ──  ──  ──</div><br>
@end html
@end ifhtml
@end macro

@macro hr20
@ifnothtml
@center @t{──────────}
@end ifnothtml
@ifhtml
@html
<div style="width:20%; margin:0 auto"><hr></div><br>
@end html
@end ifhtml
@end macro

@macro hr20d
@ifnothtml
@center @t{─ ─ ─ ─ ─ }
@end ifnothtml
@ifhtml
@html
<div style="width:20%; margin:0 auto; font-family:monospace">──  ──  ──  ──  ──  ──  ──</div><br>
@end html
@end ifhtml
@end macro

@macro Cartouche{x}
@ifnothtml
@example
┌──────────────────────────────────────────────────────
 \x\
└──────────────────────────────────────────────────────
@end example
@end ifnothtml
@ifhtml
@cartouche
\x\
@end cartouche
@end ifhtml
@end macro

@c Custom Cartouche macro for HTML output only.
@c Argument 'x' is the text to be displayed.
@c The text begins with a 4-character token which specifies 
@c the formatting parameters:
@c =ai=  auto (preformatted) text, inherited font size (this is the default format)
@c =as=  auto (preformatted) text, smaller   font size
@c =al=  auto (preformatted) text, larger    font size
@c =fi=  flowing text,             inherited font size
@c =fs=  flowing text,             smaller   font size
@c =fl=  flowing text,             larger    font size
@c Example: @CartHtml{=as=Hello World, how are you?}
@c Example using 'embedTOKEN' macro: @CartHtml{@embedTOKEN{as}Hello World, how are you?}
@macro CartHtml{x}
@ifhtml
@cartouche
\x\
@end cartouche
@end ifhtml
@end macro

@c Macro for inserting an embedded token into the Texinfo source for 
@c generating HTML markup for: a) Multitables, b) enumerated lists, 
@c                             c) CartHtml,    d) others?
@macro embedTOKEN{x}
@ifhtml
=\x\=
@end ifhtml

@end macro

@c Convenient spacing between items in an itemized or enumerated list
@macro spi
@ifhtml
@sp 1
@end ifhtml
@ifnothtml
@sp 2
@end ifnothtml
@end macro

@c This macro explicitly calls out a non-breaking sequence. This means that if 
@c it would extend beyond the margin, the entire sequence will be wrapped to 
@c the next line.
@c The Texinfo @w{} command does the same thing, but does not create a container, 
@c and does not call out a class, but simply replaces all whitespace characters 
@c in the sequence with the HTML &nbsp; element.
@c NOTE: If this macro is not placed at the beginning of the source line, it will
@c       cause makeinfo to generate a warning; but will still work as designed.
@macro W{x}
@ifnothtml
@w{\x\}
@end ifnothtml
@ifhtml
@html
<span class="nowrap">\x\</span>
<!--<span class="rewrap"></span>-->
@end html
@end ifhtml
@end macro

@c These macros reference CSS style classes for each of the generic font types.
@c (Note that @sansserif is a built-in Texinfo command.)
@macro serif{x}
@ifnothtml
@r{\x\}
@end ifnothtml
@ifhtml
@html
<span class="serif">
@end html
\x\
@html
</span>
@end html
@end ifhtml

@end macro

@macro monospace{x}
@ifnothtml
@t{\x\}
@end ifnothtml
@ifhtml
@html
<span class="monospace">
@end html
\x\
@html
</span>
@end html
@end ifhtml

@end macro

@macro cursive{x}
@ifnothtml
@r{\x\}
@end ifnothtml
@ifhtml
@html
<span class="cursive">
@end html
\x\
@html
</span>
@end html
@end ifhtml

@end macro

@macro fantasy{x}
@ifnothtml
@r{\x\}
@end ifnothtml
@ifhtml
@html
<span class="fantasy">
@end html
\x\
@html
</span>
@end html
@end ifhtml

@end macro

@c ****************************************************
@c ** Miscellaneous text decoration macros:          **
@c ** uline    : underline                           **
@c ** oline    : overline                            **
@c ** tline    : strikethough                        **
@c ** smalltext: font size smaller                   **
@c ** smallboldtext: font size smaller               **
@c ** largetext: font size larger                    **
@c ** redtext  : font color = red, font size inherit **
@c ** Sredtext : font color = red, font size smaller **
@c ** Lredtext : font color = red, font size larger  **
@c ****************************************************
@macro uline{x}
@ifnothtml
_\x\_
@end ifnothtml
@ifhtml
@html
<span class="uline">\x\</span>
@end html
@end ifhtml
 
@end macro

@macro oline{x}
@ifnothtml
\x\
@end ifnothtml
@ifhtml
@html
<span class="oline">\x\</span>
@end html
@end ifhtml
 
@end macro

@macro tline{x}
@ifnothtml
\x\
@end ifnothtml
@ifhtml
@html
<span class="tline">\x\</span>
@end html
@end ifhtml
 
@end macro

@macro smalltext{x}
@ifnothtml
\x\
@end ifnothtml
@ifhtml
@html
<span class="smalltext">\x\</span>
@end html
@end ifhtml
 
@end macro

@macro smallboldtext{x}
@ifnothtml
\x\
@end ifnothtml
@ifhtml
@html
<span class="smallboldtext">\x\</span>
@end html
@end ifhtml
 
@end macro

@macro largetext{x}
@ifnothtml
\x\
@end ifnothtml
@ifhtml
@html
<span class="largetext">\x\</span>
@end html
@end ifhtml
 
@end macro

@macro redtext{x}
@ifnothtml
\x\
@end ifnothtml
@ifhtml
@html
<span class="redtext">\x\</span>
@end html
@end ifhtml
 
@end macro

@macro Sredtext{x}
@ifnothtml
\x\
@end ifnothtml
@ifhtml
@html
<span class="smallredtext">\x\</span>
@end html
@end ifhtml
 
@end macro

@macro Lredtext{x}
@ifnothtml
\x\
@end ifnothtml
@ifhtml
@html
<span class="largeredtext">\x\</span>
@end html
@end ifhtml
 
@end macro


@c ******************************************************************
@c ** Macros for '@itemize' bulleted lists.                        **
@c ** These correspond to the bullets used in HTML <ul> lists.     **
@c ** See the corresponding CSS style classes in infodoc-style.css **
@c ** ul.disc-small, ul.disc-medium, etc.                          **
@c ******************************************************************

@c Small Disc     U+2022  &#x2022;
@macro SDISC
•
@end macro
@c Medium Disc    U+25CF  &#x25CF;
@macro MDISC
●
@end macro
@c Large Disc     U+23FA  &#x23FA;
@macro LDISC
⏺
@end macro

@c Small Circle   U+25E6  &#x25E6;
@macro SCIRCLE
◦
@end macro
@c Medium Circle (candidate)  U+25CB  $#x25CB '○'
@c Medium Circle  U+26AC  $#x26AC
@macro MCIRCLE
⚬
@end macro
@c Large Circle   U+25EF  $#x25EF
@macro LCIRCLE
◯
@end macro

@c Small Square   U+25AB  ('▫' substitute for 'square' style element)
@c We don't know the Unicode codepoint for the square bullet character.
@c We define a dummy value in this macro. 
@c The dummy has an adequate appearance in the info document.
@macro SSQUARE
▫
@end macro
@c Medium Square  U+25AA HTML: blacksquare;
@macro MSQUARE
▪
@end macro
@c Large Square   U+25FB  '◻'  (Alternate Large Square   U+25A0  '■')
@macro LSQUARE
◻
@end macro

@c Small Pointer  U+2023  $#x2023
@macro SPOINTER
‣
@end macro
@c Medium Pointer  U+25B8 HTML: blacktriangleright;
@macro MPOINTER
▸
@end macro
@c Large Pointer   U+25B7  '▷'  (Alternate Large Pointer U+25B6 '▶')
@macro LPOINTER
▷
@end macro

@c Small Diamond  U+2666  $#x2666
@macro SDIAMOND
♦
@end macro
@c Medium Diamond U+25C6
@macro MDIAMOND
◆
@end macro
@c Large Diamond  U+25C7  '◇'  (Alternate Large Diamond  U+2BC1  '⯁')
@macro LDIAMOND
◇
@end macro

@c Special macro for itemized (unordered) lists, which removes the 
@c complex makeinfo-generated tag, and replaces it with a plain "<ul>" tag.
@macro CIRCLESLASH
⊘
@end macro

@c Itemized (unordered) Lists: Display using smaller font.
@macro SmallItemize{BULL,ITEM}
@itemize \BULL\
@item 
@ifhtml
=s=
@end ifhtml
\ITEM\
@end macro
@c Itemized (unordered) Lists: Display using larger font.
@macro LargeItemize{BULL,ITEM}
@itemize \BULL\
@item 
@ifhtml
=l=
@end ifhtml
\ITEM\
@end macro
@c Enumerated (ordered) Lists: Display using smaller font.
@macro SmallEnumerate{ETYPE,ITEM}
@enumerate \ETYPE\
@item 
@ifhtml
=...s.=
@end ifhtml
\ITEM\
@end macro
@c Enumerated (ordered) Lists: Display using larger font.
@macro LargeEnumerate{ETYPE,ITEM}
@enumerate \ETYPE\
@item 
@ifhtml
=...l.=
@end ifhtml
\ITEM\
@end macro


@c *** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - *** 
@c *** Legacy bullet characters - Deprecated, do not use with new documents. ***
@c HTML 'disc' (⏺)     == U+23FA
@macro BDISC
⏺
@end macro
@c TEXI 'circle' (⚬)   == U+26AC (looks good in console, but too small in HTML)
@macro BCIRCLE
⚬
@end macro
@c HTML 'circle' (⚪)   == U+26AA (looks bad in console, but good in HTML)
@c @macro HCIRCLE
@c ⚪
@c @end macro
@c HTML 'square' (▪)   == U+25AA
@macro BSQUARE
▪
@end macro
@c U+2666 'diamond' (♦) (see SDIAMOND, above)
@macro BDIAMOND
♦
@end macro


@c *** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ***
@c *** Miscellaneous character definitions.                                  ***
@c *** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ***
@c U+2014 - In Texinfo, '---'.  In HTML, &#x2014; or &mdash;
@macro EMDASH
—
@end macro
@c U+2013 - In HTML, &#x2013; or &ndash;
@macro NDASH
–
@end macro
@c U+2212 - In Texinfo, @minus{}, Unicode 'minus'
@macro UMINUS
−
@end macro
@c U+2018 (html: &lsquo;) left-single-quote
@macro LSQ
‘
@end macro
@c U+2019 (html: &rsquo;) right-single-quote
@macro RSQ
’
@end macro
@c U+201C (html: &ldquo;) left-double-quote
@macro LDQ
“
@end macro
@c U+201D (html: &rdquo;) right-double-quote
@macro RDQ
”
@end macro
@c U+2660 (html: &spades;)
@macro SPADESUIT
♠
@end macro
@c U+2663 (html: &clubs;)
@macro CLUBSUIT
♣
@end macro
@c U+2665 (html: &hearts;)
@macro HEARTSUIT
♥
@end macro
@c U+2666 (html: &diams;)
@macro DIAMONDSUIT
♦
@end macro
@c '▬' U+25AC, '▶' U+25B6 (For 'info' doc, try U+2501 '━' instead of U+25AC)
@macro RARROW
▬▶
@end macro
@c '◀' U+25C0, '▬' U+25AC
@macro LARROW
◀▬
@end macro


@c **********************************************************
@c Macros for "larger" and "smaller" data blocks            *
@c which are not supported by makeinfo.                     *
@c "Small" blocks are written with a 10% smaller font size. *
@c "Large" blocks are written with a 10% larger font size.  *
@c **********************************************************
@macro largeindentedblock{x}
@smallindentedblock
@ifhtml
=l=
@end ifhtml
\x\
@end smallindentedblock
@end macro

@macro largequotation{x}
@smallquotation
@ifhtml
=l=
@end ifhtml
\x\
@end smallquotation
@end macro

@macro Author{x}
@ifnothtml
@*@t{@ @ @ @ @ @ @ @ @EMDASH{} \x\}
@end ifnothtml
@ifhtml
@html
<br><span class="quote-author">&mdash;&nbsp;\x\</span>
@end html
@end ifhtml
@end macro

@macro largeformat{x}
@smallformat
@ifhtml
=l=
@end ifhtml
\x\
@end smallformat
@end macro

@macro largedisplay{x}
@smalldisplay
@ifhtml
=l=
@end ifhtml
\x\
@end smalldisplay
@end macro

@macro largeexample{x}
@smallexample
@ifhtml
=l=
@end ifhtml
\x\
@end smallexample
@end macro

@macro largelisp{x}
@smalllisp
@ifhtml
=l=
@end ifhtml
\x\
@end smalllisp
@end macro

@macro smallverbatim{x}
@ifnothtml
@verbatim
\x\
@end verbatim
@end ifnothtml
@ifhtml
@verbatim
=s=\x\
@end verbatim
@end ifhtml
@end macro

@macro largeverbatim{x}
@ifnothtml
@verbatim
\x\
@end verbatim
@end ifnothtml
@ifhtml
@verbatim
=l=\x\
@end verbatim
@end ifhtml
@end macro

