Skip to content

Commit

Permalink
Add Section 1.1
Browse files Browse the repository at this point in the history
  • Loading branch information
Witiko committed Jun 7, 2024
1 parent c3df3d2 commit 07dc6d0
Show file tree
Hide file tree
Showing 3 changed files with 240 additions and 6 deletions.
55 changes: 55 additions & 0 deletions examples/landing-page.cls
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
\int_compare:nNnTF
{ \seq_count:N \g_istqb_third_parties_seq }
=
{ 1 }
{
% A single third-party organization
\istqbprovidedbysingularname{}~
\seq_get_left:NN
\g_istqb_third_parties_seq
\l_tmpa_tl
\tl_use:N
\l_tmpa_tl
}
{
% Several third-party organizations
\istqbprovidedbypluralname \par \vfill
\exp_last_unbraced:NNo
\seq_use:Nnnn
\g_istqb_third_parties_seq
{
{ \g_istqb_list_delimiter_two }
{ \g_istqb_list_delimiter_many }
{ \g_istqb_list_delimiter_last }
}
}
\par \vspace { 0.3in } \vfill \vfill
% Display logos of third-party organizations
\seq_clear:N \l_tmpa_seq
\seq_map_inline:Nn
\g_istqb_third_parties_seq
{
\prop_get:NnNT
\g_istqb_third_party_logos_prop
{ #1 }
\l_tmpa_tl
{
\tl_set:Nn
\l_tmpb_tl
{
\includegraphics
[ align = c, width = 2in,
height = 0.4in ]
}
\tl_put_right:Nx
\l_tmpb_tl
{ { \l_tmpa_tl } }
\seq_put_right:NV
\l_tmpa_seq
\l_tmpb_tl
}
}
\seq_use:Nn
\l_tmpa_seq
{ \qquad }
\par
122 changes: 122 additions & 0 deletions examples/landing-page.sty
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
\keys_define:nn% \linelabel{keys:istqb/metadata:begin} %
{ istqb / metadata }
{
organization .tl_gset:N =
\g_istqb_organization_tl,
schema .tl_gset:N = \g_istqb_schema_tl,
level .tl_gset:N = \g_istqb_level_tl,
title .tl_gset:N = \g_istqb_title_tl,
prefix .tl_gset:N = \g_istqb_prefix_tl,
code .tl_gset:N = \g_istqb_code_tl,
type .tl_gset:N = \g_istqb_type_tl,
version .tl_gset:N = \g_istqb_version_tl,
language .tl_gset:N =
\g_istqb_language_tl,
compatibility .tl_gset:N =
\g_istqb_compatibility_tl,
}% \linelabel{keys:istqb/metadata:end} %

\markdownSetupSnippet% \linelabel{snippet:metadata:begin} %
{ metadata }
{
jekyllData,
expectJekyllData,
renderers = {
jekyllData(String|Number) = {
\keys_set:nn
{ istqb / metadata }
{ { #1 } = { #2 } }
},
jekyllDataSequenceBegin = {
\str_case:nn
{ #1 }
{
{ provided-by } {
% A third-party organization
\markdownSetup {% \linelabel{pattern:first:begin} %
code = \group_begin:,
renderers = {
jekyllDataSequenceEnd =
},
snippet = istqb / common
/ metadata / provided-by,
renderers = {
jekyllDataSequenceEnd +=
\group_end:
},
}% \linelabel{pattern:first:end} %
}
}
},
jekyllDataEnd = {
\istqb_load_language:V
\g_istqb_language_tl
},
},
}% \linelabel{snippet:metadata:end} %
\seq_new:N \g_istqb_third_parties_seq% \linelabel{snippet:metadata/provided-by:begin} %
\markdownSetupSnippet
{ metadata / provided-by }
{
renderers = {
jekyllData(String|Number) = {
% Short-hand definition
\seq_gput_right:Nn
\g_istqb_third_parties_seq
{ #2 }
},
jekyllDataMappingBegin = {
% Verbose definition
\markdownSetup {% \linelabel{pattern:second:begin} %
code = \group_begin:,
renderers = {
jekyllDataMappingEnd =
},
snippet = istqb / common
/ metadata / provided-by
/ verbose,
renderers = {
jekyllDataMappingEnd +=
\group_end:
},
}% \linelabel{pattern:second:end} %
},
},
}% \linelabel{snippet:metadata/provided-by:end} %

\tl_new:N \l_istqb_third_party_name_tl% \linelabel{keys:istqb/metadata/provided-by:begin} %
\tl_new:N \l_istqb_third_party_logo_tl
\keys_define:nn
{ istqb / metadata / provided-by }
{
name .tl_set:N =
\l_istqb_third_party_name_tl,
logo .tl_set:N =
\l_istqb_third_party_logo_tl,
}% \linelabel{keys:istqb/metadata/provided-by:end} %

\prop_new:N \g_istqb_third_party_logos_prop% \linelabel{snippet:metadata/provided-by/verbose:begin} %
\markdownSetupSnippet
{ metadata / provided-by / verbose }
{
renderers = {
jekyllData(String|Number) = {
\keys_set:nn
{ istqb / metadata / provided-by }
{ { #1 } = { #2 } }
},
jekyllDataMappingEnd = {
\seq_gput_right:NV
\g_istqb_third_parties_seq
\l_istqb_third_party_name_tl
\tl_if_empty:VF
\l_istqb_third_party_logo_tl
{
\prop_gput:NVV
\g_istqb_third_party_logos_prop
\l_istqb_third_party_name_tl
\l_istqb_third_party_logo_tl
}
},
}
}% \linelabel{snippet:metadata/provided-by/verbose:end} %
69 changes: 63 additions & 6 deletions tb140starynovotny-markdown.ltx
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,27 @@
\usepackage[hidelinks,pdfa]{hyperref}
\usepackage{hologo}
\usepackage{minted}
\AtBeginEnvironment{minted}{\let\textit\textsl}
\setminted{breaklines}
\usemintedstyle{bw}
\newmintedfile[showimplementation]{tex}{
fontsize=\small,
linenos,
xleftmargin=0.5\parindent,
escapeinside=\%\%,
}
\let\oldshowimplementation\showimplementation
\def\showimplementation#1{%
\begingroup
\def\linelabel##1{%
\phantomsection
\label{\detokenize{line:##1}}%
}%
\let\textit\textsl
\let\bfseries\relax
\oldshowimplementation{#1}%
\endgroup
}
\def\verb{\mintinline{text}}
\usepackage{tikz}
\usetikzlibrary{positioning}
\def\url{\tbsurl}
Expand Down Expand Up @@ -51,7 +70,7 @@ In July 2023, I began working with the International Software Testing Qualificat
\begin{figure*}
\centering
\includegraphics[width=\linewidth]{images/class-diagram}
\caption{A class diagram of the six Markdown themes that I developed for the International Software Testing Qualifications Board (\acro{ISTQB}). The snippets \texttt{language}, \texttt{metadata}, \texttt{questions}, \texttt{answer-key}, and \texttt{answers} specify the public interface of the themes. The arrows specify inheritance. For example, the theme \texttt{istqb/sample-exam/answers} loads both themes \texttt{istqb/common} and \texttt{istqb/sample-exam} and implements all five snippets.}
\caption{A class diagram of the six Markdown themes that I developed for the International Software Testing Qualifications Board (\acro{ISTQB}). The snippets \texttt{language}, \texttt{metadata}, \texttt{questions}, \texttt{answer-key}, and \texttt{answers} specify the public interface of the themes and arrows specify inheritance.}
\label{fig:class-diagram}
\end{figure*}

Expand Down Expand Up @@ -84,29 +103,67 @@ The themes define snippets \texttt{metadata}, \texttt{language}, and \texttt{que

\subsection{Document metadata}
Here is an example \acro{ISTQB} Syllabus document that loads document metadata from a \acro{YAML} file named \texttt{metadata.yml} and typesets a landing page:

\inputminted{latex}{examples/landing-page.tex}

\phantomsection
\label{listing:landing-page.tex}%

\noindent
Here is the \acro{YAML} file \texttt{metadata.yml}:
Here is an example of the \acro{YAML} file \texttt{metadata.yml}:
\inputminted{yaml}{examples/metadata.yml}

Typesetting the example \acro{ISTQB} Syllabus document produces the following output:
\smallskip

\begingroup
\centering
\setlength{\fboxsep}{0pt}
\fbox{\includegraphics[width=.625\linewidth, trim={15mm 30mm 15mm 40mm}, clip]{examples/landing-page}}
\setlength{\fboxsep}{0pt}%
\fbox{\includegraphics[width=.775\linewidth, trim={15mm 30mm 15mm 40mm}, clip]{examples/landing-page}}%
\par
\endgroup

The snippet \texttt{metadata} processes \acro{YAML} content. It is defined in the theme \texttt{istqb/common} as follows:

\showimplementation{examples/landing-page.sty}

On lines \ref{line:keys:istqb/metadata:begin}--\ref{line:keys:istqb/metadata:end}, we define an expl3 key--value \texttt{istqb/metadata} that stores the values of unstructured metadata fields in global expl3 variables.

On lines \ref{line:snippet:metadata:begin}--\ref{line:snippet:metadata:end}, we define a snippet \texttt{metadata}, which processes \acro{YAML} content as follows:
\begin{enumerate}
\item Pass unstructured metadata fields to the key--value \texttt{istqb/metadata}.
\item Pass the metadata field \texttt{provided-by} to a snippet \texttt{metadata/provided-by}.
\end{enumerate}
After processing the \acro{YAML} content, the snippet loads language definitions, which we will discuss in more detail in the following section.

On lines \ref{line:snippet:metadata/provided-by:begin}--\ref{line:snippet:metadata/provided-by:end}, we define the snippet \texttt{metadata\discretionary{/}{}{/}provided-by}, which processes the metadata field of the same name as follows:
\begin{enumerate}
\item Store short-hand third-party definitions, such as \mintinline{yaml}"- Hungarian testing board" from the example \acro{YAML} file, in an expl3 sequence variable \verb"\g_istqb_third_parties_seq".
\item Pass verbose third-party definitions, such as the following one from the example \acro{YAML} file, to a snippet \texttt{metadata/provided-by/verbose}:
\begin{minted}{yaml}
- name: Czech and Slovak Quality Board
logo: casqb-logo-vertical
\end{minted}
\end{enumerate}

Notice the design pattern on lines \ref{line:pattern:first:begin}--\ref{line:pattern:first:end} and \ref{line:pattern:second:begin}--\ref{line:pattern:second:end} that applies a snippet to a part of the \acro{YAML} content. First, \verb"code = \group_begin:" opens a \TeX{} group. Then, \verb"renderers = {" \meta{element}\verb"End = }" locally empties the renderer command that is placed to the output stream at the end of the current \acro{YAML} \meta{element}. Next, \verb"snippet =" \meta{snippet} locally applies the definitions from \meta{snippet}. Finally, \verb"renderers = {" \meta{element}\verb"End += \group_end: }" closes the \TeX{} group at the end of the current \acro{YAML} \meta{element}.

On lines \ref{line:keys:istqb/metadata/provided-by:begin}--\ref{line:keys:istqb/metadata/provided-by:end}, we define an expl3 key--value \textls[-12]{\texttt{istqb/metadata/provided-by}} that stores the names and logos from verbose third-party definitions in local expl3 variables.

On lines \ref{line:snippet:metadata/provided-by/verbose:begin}--\ref{line:snippet:metadata/provided-by/verbose:end}, we define snippet \texttt{metadata\discretionary{/}{}{/}provided-by/verbose}, which passes names and logos from verbose third-party definitions to the key--value \texttt{istqb/metadata/provided-by}. After processing a single definition, the name is stored in the variable \verb"\g_istqb_third_parties_seq". If the filename of a logo is also specified, it is stored in an expl3 dict variable \verb"\g_istqb_third_party_logos_prop".

\subsection{Language definitions}
\subsection{Question definitions}

\section{Typesetting Markdown content}
\label{sec:markdown}
\subsection{Landing page}
% [@istqb2024example, Section 1.1]
The command \verb"\istqblandingpage" in the example \acro{ISTQB} Syllabus document on page~\pageref{listing:landing-page.tex} typesets the landing page shown on the same page. Since the majority of the implementation involves text formatting and is not particularly noteworthy, we will concentrate on the bottom part of the landing page that lists the names and logos of third-party organizations:

\showimplementation{examples/landing-page.cls}

% TODO: Discuss the implementation.

\subsection{Learning objectives}
% [@istqb2024example, Section 1.2]
\subsection{Superscripts and subscripts}
Expand Down

0 comments on commit 07dc6d0

Please sign in to comment.