%% regulatory-preamble.tex
%% Copyright 2024 E. Nijenhuis
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
% http://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status ‘maintained’.
%
% The Current Maintainer of this work is E. Nijenhuis.
%
% This work consists of the files listed in the meta-comment of
% regulatory-struct.dtx.
% \widthof, in the two conjunction tables of the reference section. It used to arrive
% through xifthen, which regulatory-struct loaded and which pulls calc in; that package
% is gone from the bundle because nothing in it used a command of xifthen that plain
% ifthen does not have. The manual does use one, so the manual asks for it.
\usepackage{calc}
% The index of \DescribeMacro, \DescribeEnv and the macro environments of the
% implementation. ltxdoc.cfg of the packaging tree only arranges this for a manual
% that does not load hyperref itself, and this one does -- through the package it
% documents -- so it is arranged here.
%
% \PageIndex rather than \CodelineIndex, and that is not a preference: every module
% resets CodelineNo, so a code line number would name nine different lines at once.
% What is done below is \PageIndex without its \makeindex, since imakeidx wants the
% index declared with its own options: gind.ist is what reads back the separators
% doc.sty writes into the idx file.
%
% \DisableCrossrefs, because the alternative is an index of every control sequence
% on every line of the implementation. What is indexed is where something is
% described and where it is defined, which is what a reader of this manual is
% looking one up for.
% makeindex is run by doc/Makefile between the runs, the way bib2gls is, rather than
% by a package that shells out: this build already has a step for a program between
% two runs, and one that answers for its own output is one less thing to explain.
\PageIndex
\DisableCrossrefs
% Why the drivers pass hyperindex=false to hyperref: that option makes hyperref wrap
% every index entry in \hyperpage, and doc.sty has already put |usage or |main there.
% Two encapsulators is one too many -- makeindex rejects the line with ``Extra `|' at
% position ...'' and writes an empty index without the build failing. Measured: 150
% entries in and none out. It has to be passed before hyperref is loaded, which this
% manual does not do itself -- the package it documents does -- so it is passed in
% front of \documentclass rather than here. The page numbers of the index are
% therefore not links, which is what is given up for having an index at all.
% \DescribeMacro is given a whole signature in this manual -- \foo\\\marg{x} -- so
% that the margin note shows one. \SpecialMacroIndex applies \string to the first
% token of what it gets and passes the rest through, so the signature ends up in the
% index key, which makeindex then cannot sort either. The margin note keeps the
% signature; the index is given the part in front of the first line break.
% An index entry is a macro name set with \verb, which is one unbreakable box, and
% the longest names of this bundle -- \markdownRendererFencedDivAttributeContextBegin
% is forty-six characters -- are wider than a column of a two-column index. Measured
% before this: they ran straight across the gutter into the next column.
%
% So \verb is given a version of its own inside the index, and only there: it reads
% the same characters with the same catcodes and offers a break between them. Not
% between just any two, which would put a line end after a backslash: before a capital
% and before an at sign, which are where the parts of these names begin. The first two
% characters are emitted before the loop starts, so `\Aref' and `\ProvidesRegulatory-
% Language' keep their backslash.
\makeatletter
\def\reg@idx@endmark{}
\def\reg@idx@verb{%
    \begingroup
        \let\do\@makeother \dospecials
        \verbatim@font \@noligs
        \@ifstar\reg@idx@verb@delim\reg@idx@verb@delim}
% Gobbles the opening delimiter, then reads to the closing one.
\def\reg@idx@verb@delim#1{\reg@idx@verb@body}
\def\reg@idx@verb@body#1+{%
    \reg@idx@verb@two#1\reg@idx@endmark\reg@idx@endmark\endgroup}
\def\reg@idx@verb@two#1#2{#1#2\reg@idx@verb@loop}
\def\reg@idx@verb@loop#1{%
    \ifx#1\reg@idx@endmark
    \else
        \reg@idx@verb@break{#1}%
        #1%
        \expandafter\reg@idx@verb@loop
    \fi}
% \uccode of an uppercase letter is itself; of a lowercase letter its capital; of
% anything else zero. So this one test picks out the capitals, and the at sign is
% named beside it.
% Penalty 700 rather than 0, because \pfill offers a break of its own between the two
% runs of dots at 500: a name that fits on the line but leaves no room for its page
% number should break there and not in the middle of itself.
\def\reg@idx@verb@break#1{%
    \ifnum\uccode`#1=`#1\relax\penalty700 \else
        \ifnum`#1=`\@ \penalty700 \fi
    \fi}
% And a smaller hanging indent than doc.sty's 30pt, which is a sixth of a column of
% this index: the continuation line of a broken name is where the room is needed.
\g@addto@macro\IndexParms{%
    \let\verb\reg@idx@verb
    \def\@idxitem{\par\hangindent 12pt}}
\def\reg@indexhead#1#2\\#3\relax{\@nameuse{Special#1Index}{#2}}
\def\@doc@describe#1#2{%
    \ifdoc@noprint\else
      \marginpar{\raggedleft
                 \strut
                 \doc@providetarget
                 \@nameuse{PrintDescribe#1}{#2}}%
    \fi
    \ifdoc@noindex\else
      \reg@indexhead{#1}#2\\\relax
    \fi
  \@esphack
  \endgroup
  \ignorespaces}
\makeatother
\usepackage{listings}
% The Markdown syntax extension is Lua, not TeX, so it is not documented with
% docstrip but from its own comments, as a listing with prose in between.
\usepackage{comment2tex}
\ctxuselistings
\usepackage{adjustbox}
\usepackage{tikz}
\usetikzlibrary{arrows.meta}

\usepackage{fontspec}
\usepackage{textcomp}

\def\projecturl{https://github.com/Xerdi/regulatory}

\definecolor{greycolor}{HTML}{BFBFBF}
\definecolor{primary}{HTML}{174A67}
\definecolor{darkcolor}{HTML}{091D28}
\definecolor{greencolor}{HTML}{176734}
\colorlet{artlabel}{primary}
\colorlet{green}{greencolor}

% The pictures of the test section share their shapes, so that a box means the same
% thing in every one of them: a rounded box is a document that becomes a PDF file, a
% dashed one a file it reads, a grey one a program that runs between two LaTeX runs,
% a sharp-cornered one something written out literally -- keys in a document, an
% object in the PDF file -- and a doubled one an assertion of the suite that reads
% the result back.
% Two colours the prose does not use. A warning is a state a document can be in
% and not a defect of the manual, and a step that did not happen is drawn in grey
% -- but grey as text, not as a rule: greycolor is a hairline colour and reads at
% about two to one against white, which is not enough to be read at scriptsize.
\definecolor{warncolor}{HTML}{8C3A2E}
\definecolor{fadedcolor}{HTML}{707070}
\tikzset{
    diagram/.style = {
        every node/.style = {font=\small},
        doc/.style   = {draw, rounded corners, minimum height=8mm, minimum width=25mm,
                        align=center, font=\small\ttfamily},
        data/.style  = {draw, dashed, minimum height=7mm, align=center,
                        font=\small\ttfamily},
        prog/.style  = {draw, fill=greycolor!40, minimum height=7mm, align=center,
                        font=\small\ttfamily},
        obj/.style   = {draw, minimum height=7mm, align=left, font=\small\ttfamily},
        check/.style = {draw, double, minimum height=7mm, align=center,
                        font=\small\ttfamily},
        bare/.style  = {align=center, font=\small\ttfamily},
        rel/.style   = {-{Stealth[length=2mm]}, semithick},
        gone/.style  = {-{Stealth[length=2mm]}, semithick, densely dotted, fadedcolor},
        faded/.style = {text=fadedcolor},
        lbl/.style   = {font=\scriptsize\sffamily, fill=white, inner sep=1.5pt,
                        align=center},
        note/.style  = {font=\scriptsize\sffamily, align=left},
        warn/.style  = {font=\scriptsize\sffamily, align=left, text=warncolor},
        ok/.style    = {font=\scriptsize\sffamily, align=left, text=greencolor}
    }
}

\lstdefinestyle{tex}{%
    language=[LaTeX]TeX,
    keywordsprefix={\\},
    alsoletter={\\},
    morekeywords={article,para,textfill,masterdocument,refdocument,loadglsdefs,printdefs,setmiddleconjunction,setlastconjunction,setrangeconjunction,setconjunction,markdownInput,glssetwidest,describe,newdefinition,autocitedefs}
}

\lstdefinestyle{bash}{%
    language=bash,
    morekeywords={pdflatex,lualatex,latexmk,makeglossaries,bib2gls}
}

% A Markdown source of this bundle holds no TeX any more, so the language is no
% longer derived from it: what is worth marking is where a label is written and
% where one is read.
% MoreSelectCharTable, and \makeatletter for it, because of `)'. With
% breaklines on -- which the \lstset below turns on -- listings rebinds that
% character in its own SelectCharTable hook, to offer a break after a closing
% parenthesis. That hook runs after the one which installs the delimiters of a
% language, so the rebinding wins and `)' stops ending a delimiter: from the
% first (#label) onwards the whole listing keeps the colour of that delimiter,
% including the ones after it, which never open again. Measured on listings
% 1.11b, with `]' as the end delimiter as the control: that one closes.
% MoreSelectCharTable is run after the hook, so putting the delimiters back
% there is what undoes it. The break after `)' is what is given up for it.
\makeatletter
\@ifundefined{lst@DefDelims}{%
    \PackageError{regulatory-doc}{Listings no longer defines
        \string\lst@DefDelims}{%
        The Markdown listings put their delimiters back with it, since
        breaklines\MessageBreak takes the closing parenthesis away from them.
        Without it a listing comes out\MessageBreak in one colour from its
        first link onwards.}%
}{}
\lstdefinelanguage{Markdown}{%
    sensitive=true,
    moredelim=[s][\bfseries\color{blue}]{\{\#}{\}},
    moredelim=[s][\color{purple}]{<\#}{>},
    moredelim=[s][\color{purple}]{(\#}{)},
    MoreSelectCharTable=\lst@DefDelims,
}
\makeatother

\lstdefinestyle{md}{%
    language=Markdown
}

\lstdefinelanguage{BibTeX}{%
    keywords={%
        article,book,collectedbook,conference,electronic,entry,ieeetranbstctl,%
        inbook,incollectedbook,incollection,injournal,inproceedings,%
        manual,mastersthesis,misc,patent,periodical,phdthesis,preamble,%
        proceedings,standard,string,techreport,unpublished%
    },
    keywordsprefix={@},
    comment=[l][\itshape]{@comment},
    sensitive=false,
}

\lstdefinestyle{bib}{%
    language=BibTeX,
    morestring=[s][\bfseries\ttfamily\color{purple}]{\ \ \ \ }{\ },
    morecomment=[n][\bfseries\ttfamily\color{green}]{\ \{}{\}},
}

\lstset{
    title=\lstname,
    basicstyle=\ttfamily,
    numberstyle=\ttfamily,
    numbersep=5pt,
    rulecolor=\color{greycolor},
    stringstyle=\color{pink},
    keywordstyle=\color{primary},
    commentstyle=\itshape\color{darkcolor},
    breaklines=true,
    captionpos=b,
    tabsize=4,
    showtabs=true
}

% A doc element for the package options, so that the index answers for them as well.
% They stand in a labeling list rather than beside a margin note, so the entries are
% asked for with [noprint]: the same mechanism that indexes a macro, without the note.
\NewDocElement[macrolike = false ,
               idxtype   = option ,
               idxgroup  = options ,
               printtype = \textnormal{(option)}
              ]{Option}{docoption}

\newcommand\package{\texttt}
\newcommand\file{\texttt}
\newcommand\option{\texttt}

% Reads test/conformance.tex, which test/conformance.sh generates and which is
% kept in the repository: veraPDF is not available everywhere this manual is
% built, so the verdicts travel with the sources.
\newcommand\conformanceversion{?}
\newcommand\conformanceimage{?}
% A digest carries no break points of its own and does not fit a line, so this
% offers one after every character. The argument is expanded first, otherwise the
% loop sees one macro instead of the characters it stands for.
\newcommand\anywherebreakend{}
\def\anywherebreakloop#1{%
    \ifx#1\anywherebreakend\else#1\allowbreak\expandafter\anywherebreakloop\fi}
\newcommand\anywherebreak[1]{\anywherebreakloop#1\anywherebreakend}
\newcommand\conformanceimagetext{%
    \expandafter\anywherebreak\expandafter{\conformanceimage}}

% \ignorespaces, because this macro typesets nothing while its line in the
% generated file still ends in a newline, and that space would otherwise open
% the first cell of the table.
\newcommand\conformancevalidator[2]{%
    \gdef\conformanceversion{#1}\gdef\conformanceimage{#2}\ignorespaces}
\newcommand\conformancerow[6]{%
    \texttt{#1} & \texttt{#2} & \texttt{#3} & \texttt{#4} & \texttt{#5}%
    \ifthenelse{\equal{#6}{}}{}{ \footnotesize(#6)} \\}

% Points at the resulting PDF of an example, which is attached to this manual.
% Its argument is the label of the artifact the example was declared with, and it
% falls back to plain text whenever the PDF isn't there.
\newcommand\exampleresult[1]{%
    \par\noindent
    \translation{The result of this example is}{Het resultaat van dit voorbeeld is}
    \documentattachment{#1}{\file{\artifactfilename{#1}}}.\par}

% The release the manual belongs to, taken from the package it documents rather than
% stated here or read out of the repository. \ProvidesPackage in regulatory-struct.dtx
% is the one place the bundle names its version, and \GetFileInfo hands back what the
% loaded regulatory.sty declared, so a manual can no longer carry a release the files
% beside it do not. It used to come from gitinfo-lua, which describes the checkout:
% between two tags that is the previous tag plus a commit count, so the manual of a
% release built before its tag existed said 0.0.4-48-g<hash>.
\GetFileInfo{regulatory.sty}
% \filedate is LaTeX's YYYY/MM/DD. Every other date in this bundle is written the way
% a `valid' field is, so this one is too.
\def\isodate#1/#2/#3\relax{#1-#2-#3}
\edef\packagedate{\expandafter\isodate\filedate\relax}
\let\packageversion\fileversion

%\def\cmd{\lstinline[style=tex]}
\def\cmditem#1{\item[\ttfamily\textbackslash{}#1]}

\newcommand\Vtextvisiblespace[1][.3em]{%
  \mbox{\kern.06em\vrule height.3ex}%
  \vbox{\hrule width#1}%
  \hbox{\vrule height.3ex}}

% Package zref-clever loads its language files lazily, which would otherwise
% happen inside a \DocInput region, where the percent sign is ignored and the
% comments of those files end up being parsed as keys. Touching every language
% of this manual schedules them at the start of the document instead, while the
% percent sign still is a comment character.
\zcsetup{lang=english}
\zcsetup{lang=dutch}
\zcsetup{lang=current}