% tagsnip sample document
% Author: Rostislav Brož
% Semester project, 2026

% tagsnip needs a Python backend in order to work. 
% Before compiling the document, it has to be installed:

\iffalse
pip install tagsnip
\fi

% To compile the document, the following sequence of commands should be run. 
% Without it, citations in the document will probably not be displayed correctly.

\iffalse
lualatex --shell-escape docs/docs.tex
bibtex main
lualatex --shell-escape docs/docs.tex
lualatex --shell-escape docs/docs.tex
\fi

\documentclass{article}

\usepackage[a4paper,margin=2cm]{geometry}
\usepackage[english]{babel}
\usepackage{natbib}
\usepackage[hidelinks]{hyperref}

\usepackage{tagsnip}

\begin{document}

\hypersetup{pageanchor=false}
\begin{titlepage}
    \centering

    {\Large Czech Technical University in Prague\par}
    {\Large Faculty of Information Technology\par}

    \vspace{3cm}

    {\Huge\bfseries tagsnip\par}

    \vspace{0.5cm}

    {\Large Package Documentation\par}

    \vfill

    \begin{tabular}{rl}
        Author: & Rostislav Brož \\
        Year: & 2026 \\
    \end{tabular}

    \vspace{2cm}
\end{titlepage}

\hypersetup{pageanchor=true}
\clearpage
\pagenumbering{arabic}

\section*{tagsnip}

\textit{tagsnip} is a La\TeX{} package for including tagged code snippets from local files or remote URLs. 
It extracts marked sections of code and typesets them in a consistent style, 
supporting reproducible and maintainable documentation.

\subsection*{Installation}

For parsing source files, \textit{tagsnip} uses a Python package of the same name, 
which is published in the PyPI software repository \citep{pypi}. 
In order for \textit{tagsnip} to work, 
the backend has to be installed using the following command.

\IncludeCode[firstnumber=1]{docs/example2.py}{comm0}{cpp}{}

\subsection*{Usage}

\textit{tagsnip} defines the command \textbackslash{}IncludeCode, which is used as follows:

\IncludeCode[firstnumber=1]{docs/example2.py}{comm1}{cpp}{}

The optional argument \textit{options} allows the user to override code formatting settings. 
In the command below, the options \textit{firstnumber}, \textit{fontsize}, and \textit{style} were used. 
They set line numbering to start from number 1, the font size to \nobreak\textit{\textbackslash{}scriptsize}, 
and the syntax highlighting style to \textit{monokai}. 
The options must exist in the Minted package \citep{minted} and must be separated by commas. 
It is also important to mention that, without changing the \textit{firstnumber} option, 
\textit{tagsnip} numbers lines according to their original numbering in the source file.

\IncludeCode[firstnumber=1]{docs/example2.py}{comm2}{cpp}{}

The mandatory argument \textit{source} defines the source from which the code snippet should be taken. 
The argument can be either a path to a local file or a link to a web page. 
\textit{tagsnip} can distinguish these possibilities automatically. 
The mandatory argument \textit{tag} specifies a unique keyword that identifies one code snippet. 
The tag must be separated by exactly one space and must follow the phrases \textit{tagsnip-start} and \textit{tagsnip-end}, 
which delimit the snippet (see Snippet~1).

\IncludeCode{docs/example.py}{demo}{Python}{Snippet 1: Example of tag usage.}

With the mandatory argument \textit{language}, the user selects the programming language 
whose syntax highlighting style should be used for the snippet. 
The last argument is the caption, which may be empty. 
However, the braces must still be written even for an empty caption.

\subsubsection*{Local snippet}

To demonstrate how the \textbackslash{}IncludeCode command works for local files, 
we use the file \textit{example.py} from Snippet~1. In this file, the function \textit{main()} 
is enclosed by the tag \textit{tag1}. The command for displaying the function code in the document 
would therefore look as follows:

\IncludeCode[firstnumber=1]{docs/example2.py}{comm3}{cpp}{}

This command produces Snippet 2:

\IncludeCode{docs/example.py}{tag1}{Python}{Snippet 2: Snippet delimited by the tag \textit{tag1} from Snippet 1.}

\newpage

\subsubsection*{Snippet from a remote URL}

The home repository of \textit{tagsnip} on GitHub also contains the file \textit{example2.py}, 
which includes a function for extracting a snippet. 
Part of this function is enclosed by the tag \textit{tag2}. 
We display it using the following command:

\IncludeCode[firstnumber=1]{docs/example2.py}{comm4}{cpp}{}

The result of this command is Snippet 3:

\IncludeCode[]{https://raw.githubusercontent.com/brozrost/tagsnip/main/docs/example2.py}{tag2}{Python}{Snippet 3: Code snippet from a remote URL.}

\subsection*{Architecture}

\textit{tagsnip} consists of two main parts: a La\TeX{} frontend package and an external backend utility written in Python. 
The frontend defines the command \textbackslash{}IncludeCode and handles the typesetting of the resulting snippets 
using the Minted package. The backend is responsible for accessing source files, finding marked sections, 
and extracting them into temporary files. During document compilation, the frontend uses shell escape 
to run the backend utility, passes it the path to the source file and the name of the tag, 
and then inserts the generated temporary file into the document.

\subsection*{Backend}

The Python package \textit{tagsnip} is a simple command-line interface that accepts a source file, 
a tag name, and a path to an output file. The interface loads the source file, 
finds the corresponding pair of \textit{tagsnip-start} and \textit{tagsnip-end} markers, 
and then extracts the text between them.

The package also checks error states. An error state means, for example, a non-existent source file, 
a missing tag, or multiple occurrences of the same tag in the source file. If an error is detected, 
the backend raises an exception, which interrupts document compilation and prints the corresponding error message. 
For working with local files, the package uses the \textit{pathlib} module; for finding tags, it uses the \textit{re} module; 
and for loading remote files over HTTP, it uses the \textit{requests} library.

\subsection*{Limitations}

\begin{itemize}
    \item \textit{tagsnip} requires the LuaLa\TeX{} compiler.
    
    \item During document compilation, 
    shell escape must be enabled using the \textit{--shell-escape} option.

    \item The Python backend must be installed and available in the system PATH 
    under the command \textit{tagsnip}.

    \item The package depends on the Minted package.

    \item Remote source files must be available over HTTP(S) and in the format of 
    a readable text file.
\end{itemize}

\bibliographystyle{unsrt}
\bibliography{docs/citations.bib}

\end{document}