defines.tex

\newcommand*{\isPDF}{1}
\newcommand*{\isWIP}{1}


% ░█▀▀█ ▒█▀▀█ ▒█▀▀▀█ ▒█░▒█ ▀▀█▀▀ 
% ▒█▄▄█ ▒█▀▀▄ ▒█░░▒█ ▒█░▒█ ░▒█░░ 
% ▒█░▒█ ▒█▄▄█ ▒█▄▄▄█ ░▀▄▄▀ ░▒█░░

% general document info for simpler reuse
\newcommand{\AuthorName}{Toma\v{z}}
\newcommand{\AuthorNameSurname}{\AuthorName ~Kragelj}
\newcommand{\BookTitleMain}{ZX Spectrum Next}
\newcommand{\BookTitleSub}{Assembly Developer Guide}
\newcommand{\BookTitle}{\BookTitleMain~\BookTitleSub}
\newcommand{\BookKeywords}{zx,next,spectrum,retro,documentation,manual,guide,assembly,language,programming}


% ▒█▀▀█ ▒█▀▀▀ ▒█░░▒█ ▀█▀ ▒█▀▀▀█ ▀█▀ ▒█▀▀▀█ ▒█▄░▒█ ▒█▀▀▀█ 
% ▒█▄▄▀ ▒█▀▀▀ ░▒█▒█░ ▒█░ ░▀▀▀▄▄ ▒█░ ▒█░░▒█ ▒█▒█▒█ ░▀▀▀▄▄ 
% ▒█░▒█ ▒█▄▄▄ ░░▀▄▀░ ▄█▄ ▒█▄▄▄█ ▄█▄ ▒█▄▄▄█ ▒█░░▀█ ▒█▄▄▄█

\newcommand{\LatestYear}{2022}
\newcommand{\LatestMonthName}{July}
\newcommand{\LatestMonth}{07}
\newcommand{\LatestDay}{15}

% revision name is nicely structured variant with named month
\newcommand{\LatestRevisionName}{\LatestDay~\LatestMonthName~\LatestYear}

% revision date is "reverse domain" type that can be easily sorted in various computer lists; also suitable for git tags
\newcommand{\LatestRevisionDate}{\LatestYear-\LatestMonth-\LatestDay}

% older revisions
\newcommand{\RevisionTwoDate}{2021-11-11}
\newcommand{\RevisionTwoName}{11 November 2021}

\newcommand{\RevisionOneDate}{2021-07-16}
\newcommand{\RevisionOneName}{16 July 2021}


% ▒█▀▀▀ ▒█░░░ ▒█▀▀▀ ▒█▀▄▀█ ▒█▀▀▀ ▒█▄░▒█ ▀▀█▀▀ ▒█▀▀▀█ 
% ▒█▀▀▀ ▒█░░░ ▒█▀▀▀ ▒█▒█▒█ ▒█▀▀▀ ▒█▒█▒█ ░▒█░░ ░▀▀▀▄▄ 
% ▒█▄▄▄ ▒█▄▄█ ▒█▄▄▄ ▒█░░▒█ ▒█▄▄▄ ▒█░░▀█ ░▒█░░ ▒█▄▄▄█

% creates an email (obfuscated for PDF variant), Discord or Twitter user text
\newcommand{\email}[3]{\ifdefined\isPDF{\tt #1 AT #2 DOT #3}\else{\tt #1@#2.#3}\fi}
\newcommand{\discord}[1]{{\tt @#1}}
\newcommand{\twitter}[1]{{\tt @#1}}

% sets given font size for just "selected" text
\newcommand{\FontSize}[2]{\fontsize{#1}{#1}\selectfont #2}

% creates minitoc without any headers; parameters:
% - (optional) #1 boolean; if star present, no styling will be applied after TOC, otherwise default styling will be applied (which is the default)
% - (optional) #1 boolean; if present, chapter TOC is generated, otherwise not (default will create TOC)
\NewDocumentCommand{\ChapterTOC}{ o o }{
	\pagestyle{nosectionmarker}

	% if #2 is present (aka not "[]"), render TOC.
	\IfValueF{#2}{
		\etocsettocstyle{}{}	% no title
		\localtableofcontents
	}
	\thispagestyle{plain}	% simple TOC pages without headers
	
	% if #1 is present (aka not "[]"), set page style to clean
	\IfValueF{#1}{\pagestyle{clean}}
}

% we can use this for pages that are intentionally left blank
\newcommand{\IntentionallyEmpty}{
	\mbox{}
	\vfill
	\begin{center}
	This page intentionally left empty
	\end{center}
	\vfill
	\mbox{}
}

% renders "work in progress" text using current font and size.
\newcommand{\WorkInProgress}{\ifdefined\isWIP\color{red}\textbf{WORK IN PROGRESS}\fi}

% renders "work in progress" sign for use on "full screen" pages; uses \Huge font by default, but that can be changed with optional parameter
\newcommand{\WorkInProgressFullScreen}[1][\normalsize]{
	\ifdefined\isWIP
		#1
		\begin{center}
			\WorkInProgress
		\end{center}
	\fi
}

\newenvironment{changemargin}[2]{%
	\begin{list}{}{%
		\setlength{\topsep}{0pt}%
		\setlength{\leftmargin}{#1}%
		\setlength{\rightmargin}{#2}%
		\setlength{\listparindent}{\parindent}%
		\setlength{\itemindent}{\parindent}%
		\setlength{\parsep}{\parskip}%
	}%
\item[]}{\end{list}}


% ▒█▀▀█ ▒█▀▀▀█ ▒█░░░ ▒█▀▀▀█ ▒█░▒█ ▒█▀▀█ ▒█▀▀▀█ 
% ▒█░░░ ▒█░░▒█ ▒█░░░ ▒█░░▒█ ▒█░▒█ ▒█▄▄▀ ░▀▀▀▄▄ 
% ▒█▄▄█ ▒█▄▄▄█ ▒█▄▄█ ▒█▄▄▄█ ░▀▄▄▀ ▒█░▒█ ▒█▄▄▄█

\definecolor{PrintableLightGray}{rgb}{0.85, 0.85, 0.85}
\definecolor{PrintableLightMidGray}{rgb}{0.7675, 0.7675, 0.7675}
\definecolor{PrintableMidGray}{rgb}{0.675, 0.675, 0.675}
\definecolor{PrintableDarkGray}{rgb}{0.5, 0.5, 0.5}


% ▒█▀▀▀█ ▒█░▒█ ▒█▀▀▀█ ▒█▀▀█ ▀▀█▀▀ ▒█░▒█ ░█▀▀█ ▒█▄░▒█ ▒█▀▀▄ ▒█▀▀▀█ 
% ░▀▀▀▄▄ ▒█▀▀█ ▒█░░▒█ ▒█▄▄▀ ░▒█░░ ▒█▀▀█ ▒█▄▄█ ▒█▒█▒█ ▒█░▒█ ░▀▀▀▄▄ 
% ▒█▄▄▄█ ▒█░▒█ ▒█▄▄▄█ ▒█░▒█ ░▒█░░ ▒█░▒█ ▒█░▒█ ▒█░░▀█ ▒█▄▄▀ ▒█▄▄▄█

% less tall slash
\newcommand\scslash{\stretchrel*{$/$}{\textsc{e}}}

% couple shorthands that can be used throughout the document
\newcommand{\Deg}{\textsuperscript{o}}
\newcommand{\ddd}{\makebox[1em][c]{.\hfil.\hfil.}}
\newcommand{\See}[1]{\textsuperscript{#1}}
\newcommand{\UNDOC}{\textnormal{\textsuperscript{**}}}
\newcommand{\ZXN}{\textnormal{\textsuperscript{ZX}}}
\newcommand{\ZXNS}{\tiny\textnormal{\textsuperscript{ZX}}}
\newcommand{\High}{\textsubscript{h}}
\newcommand{\Low}{\textsubscript{l}}

% instruction flags definitions - for unified formatting
\newcommand{\FS}{$\updownarrow$} % standard effect
\newcommand{\FN}{-}				% no effect
\newcommand{\FU}{?}				% unknown effect
\newcommand{\FX}{$\bullet$}		% special case
\newcommand{\FPV}{VF}			% PV=Overflow
\newcommand{\FPP}{PF}			% PV=Parity

% flags with expected formatting
\newcommand{\FlagSF}{\textbf{SF}}
\newcommand{\FlagZF}{\textbf{ZF}}
\newcommand{\FlagHF}{\textbf{HF}}
\newcommand{\FlagPV}{\textbf{PV}}
\newcommand{\FlagNF}{\textbf{NF}}
\newcommand{\FlagCF}{\textbf{CF}}

% cross reference with section and page number
\newcommand{\XRef}[1]{\ref{#1}, page \pageref{#1}}

% generic renderer for any chip pin label (uses line above); this is used for all concrete chip labels internally.
\newcommand{\NoLinkChipPinLabel}[1]{$\mathtt{\overline{#1}}$}
% renders the given Z80 chip pin label with link to Z80 chip diagram. Needless to say - only use for links to Z80 chip pins!
\newcommand{\ZilogPinLabel}[1]{\hyperref[z80_pin_descriptions]{\NoLinkChipPinLabel{#1}}}
% renders the given DMA chip pin label with link to DMA chip diagram (once we actually have it)
\newcommand{\DMAPinLabel}[1]{\NoLinkChipPinLabel{#1}}

% other commonly used definitions
\newcommand{\MemAddr}[1]{{\tt \$#1}}


% ▒█▀▀█ ▒█▀▀▀█ ▒█▀▄▀█ ▒█▀▄▀█ ▒█▀▀▀█ ▒█▄░▒█ 　 ▒█▀▀▄ ▒█▀▀█ ░█▀▀█ ▒█░░▒█ ░█▀▀█ ▒█▀▀█ ▒█░░░ ▒█▀▀▀ ▒█▀▀▀█ 
% ▒█░░░ ▒█░░▒█ ▒█▒█▒█ ▒█▒█▒█ ▒█░░▒█ ▒█▒█▒█ 　 ▒█░▒█ ▒█▄▄▀ ▒█▄▄█ ▒█▒█▒█ ▒█▄▄█ ▒█▀▀▄ ▒█░░░ ▒█▀▀▀ ░▀▀▀▄▄ 
% ▒█▄▄█ ▒█▄▄▄█ ▒█░░▒█ ▒█░░▒█ ▒█▄▄▄█ ▒█░░▀█ 　 ▒█▄▄▀ ▒█░▒█ ▒█░▒█ ▒█▄▀▄█ ▒█░▒█ ▒█▄▄█ ▒█▄▄█ ▒█▄▄▄ ▒█▄▄▄█

% horizontal arrows of arbitrary size (lehgth specified through parameter)
\newcommand{\RArrow}[1]{\parbox{#1}{\tikz{
	\draw[->,line width=0.5pt](0,0)--(#1,0);
}}}
\newcommand{\LArrow}[1]{\parbox{#1}{\tikz{
	\draw[<-,line width=0.5pt](0,0)--(#1,0);
}}}

% horizontal arrows with vertical line on the arrow side; parameters:
% - mandatory horizontal line width
% - optional any additional horizontal line styles (dotted, dashed etc)
% - optional vertical line height (divided by 2), default 0.1
% - optional arrow scale, default 1
% - optional line width, default 0.5pt
\NewDocumentCommand{\RArrowLine}{ m O{} O{0.1} O{1.6} O{0.5pt} }{\parbox{#1}{\tikz{
	\draw[-{>[scale=#4,length=#4,width=#4]},line width=#5,#2](0,0)--(#1,0);
	\draw[line width=#5](#1,-#3)--(#1,#3);
}}}
\NewDocumentCommand{\LArrowLine}{ m O{} O{0.1} O{1.6} O{0.5pt} }{\parbox{#1}{\tikz{
	\draw[line width=#5](0,-#3)--(0,#3);
	\draw[-{>[scale=#4,length=#4,width=#4]},line width=#5,#2](#1,0)--(0,0);
}}}


% ▒█▀▀█ ▒█░▒█ ▒█▀▀▀█ ▀▀█▀▀ ▒█▀▀▀█ ▒█▀▄▀█ ▀█▀ ▒█▀▀▀█ ░█▀▀█ ▀▀█▀▀ ▀█▀ ▒█▀▀▀█ ▒█▄░▒█ ▒█▀▀▀█ 
% ▒█░░░ ▒█░▒█ ░▀▀▀▄▄ ░▒█░░ ▒█░░▒█ ▒█▒█▒█ ▒█░ ░▄▄▄▀▀ ▒█▄▄█ ░▒█░░ ▒█░ ▒█░░▒█ ▒█▒█▒█ ░▀▀▀▄▄ 
% ▒█▄▄█ ░▀▄▄▀ ▒█▄▄▄█ ░▒█░░ ▒█▄▄▄█ ▒█░░▒█ ▄█▄ ▒█▄▄▄█ ▒█░▒█ ░▒█░░ ▄█▄ ▒█▄▄▄█ ▒█░░▀█ ▒█▄▄▄█

% define the style for lstlisting
\lstdefinestyle{CodeStyle}{
	basicstyle=\ttfamily\small,
	commentstyle=\color{PrintableDarkGray},
	columns=flexible,
	tabsize=4,
	numbers=left,
	numberstyle=\ttfamily\tiny,
	numbersep=1.8em,
	morecomment=[l]{;},
	moredelim=[is][\rmfamily\itshape]{|}{|},	% any text within |...| will be roman/italic
	literate={&}{\$}1							% replace `&` with `$` (to avoid syntax higlight issues)
			{Band}{\&~}1						% replace `Band` with `&` (to allow bitwise and output without & being consumed for $ from previous rule)
			{Bor}{|~}1							% replace `Bor' with `|` (to allow bitwise or output without | being consumed for roman/italic from moredelim rule above)
}

% define default settings for all tcolorbox instances
\tcbset{
	arc=4pt,			% radius for rounded corners
	boxrule=0pt,		% no frame around the box
	boxsep=1.3ex,		% add some spacing between frame and content
	left=0ex,			% left side should be flush with content
	right=0ex,			% right side should be flush with content
	top=-1.5ex,			% less spacing between frame and start of content
	bottom=-1.5ex,		% less spacing between end of content and frame
	pad at break=1pt,	% leave some small spacing between content and frame when page break occurs
	before skip=2ex,
	after skip=3ex,
	colback=PrintableLightGray,
	colframe=PrintableLightGray,
	enhanced,			% only use rounded corners on top and bottom part, not between page breaks
	breakable,			% allow breaking tcolorbox to multiple pages
	listing only,		% only show listing
	listing options={style=CodeStyle},
}