%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                   %
%      Made by Gabriel Ruprecht     %
%                                   %
% This work is published under the  %
% LaTeX project public license 1.3  %
%                                   %
%       Package version 1.1.0       %
%            2025-01-21             %
%                                   %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentclass[11pt,a4paper]{scrartcl}
\usepackage[utf8]{inputenc}
\usepackage[english]{babel}
\usepackage{graphicx}
\usepackage{listings}
\lstset
{ %Formatting for code in appendix
    language=TeX,
    numbers=left,
    stepnumber=1,
    showstringspaces=false,
    tabsize=1,
    breaklines=true,
    breakatwhitespace=false,
    basicstyle=\ttfamily}


\usepackage{xcolor}
\usepackage{hyperref}
\usepackage{parskip}

\makeatletter
%\def\FillPages{\makebox{\vspace*{50pt} \includegraphics[height=\f@size pt]{./GFM-FP-Logo}} }
\def\FillPagesTiny{\includegraphics[height=\f@size pt]{./GFM-FP-LogoTiny}\hspace*{-3pt}}
\def\FillPagesS{\hspace*{3pt}\includegraphics[height=\f@size pt]{./GFM-FP-LogoS}\hspace*{3pt}}
\makeatother
\title{Fill\FillPagesS Pages\FillPagesS Package\vskip 9pt\relax}
\subtitle{Version 1.1.0}
\author{Gabriel Ruprecht}


\begin{document}
\maketitle
\section{Introduction}
\subsection{About}
The \textsf{Fill\FillPagesS Pages\FillPagesS Package} can be used, if you create a book, booklet or similar. In these cases you often print something, where your page count must be divisible by 4, 8 or 16. This package fills your document with the needed pages. By default, they are blank, but they may also have a pre-defined content. If you use this package, you have to compile at least two times. The first run counts the pages and inserting positions. This information is then used in the second run, to calculate the number of pages to be inserted. 

\subsection{License}
This package is subject to the LaTeX Project Public License 1.3. You may do whatever you want with.  If you change the package and redistribute it, please keep the credits.

\section{Example document}
The fastest way to see, how it works, is copying this document and play around a little bit:

\begin{lstlisting}[numbers=none]
\documentclass{report}
\usepackage[utf8]{inputenc}
\usepackage[latin,english]{babel}
\usepackage{lipsum}

\usepackage{fillpages}

\pagesDivisibleBy{4}
%\pagesDivisibleBy{4}[2] % with optional offset

\setFillPage{2}{
ABC

DEF
}

\setFillPage{3}{
123

456
}

\setDefaultFillPage{
Nothing
}


\begin{document}

\lipsum

\insertFillPages
\insertFillPages

\lipsum
\lipsum
\pagenumbering{Roman}
\lipsum
\lipsum

\insertFillPages

\lipsum

\end{document}
\end{lstlisting}

\newpage
\section{Commands}
You have to define the number which the total page number should be devideable by. Then you define the insertion points for the fill-pages. You can define content for any of these pages. After that, you have to run the document at least two times for a proper result. In the first run, the insertion points are counted and the regular page number is collected. On the second run, the pages are inserted.\bigskip

\noindent\verb&\insertFillPages&\\ This command must be placed at the points, where insertion is allowed (insertion points). This can be done at multiple points. The total number of pages to be inserted is divided by the number of insertion points. If there are three insertion points and five pages will be inserted, the insertion will be \verb#1 1 2#. Inside each \verb+\inserFillPages+ a \verb+\clearpage+ is executed at the beginning. Therefore all pending floats will be shipped out. \verb+\inserFillPages+ equals a \verb+\clearpage+, even if there are no fill-pages inserted.

\noindent\verb&\pagesDivisibleBy{number}[offset]&\\ This defines the number the page number must be divisible by (default~=~4). If \verb+number+ is 4 and page count is 13, 3 pages will be inserted~(4*4=16; 13+3=16). If \verb+number+ is~4 and \verb+offset+ is 2, the same example will lead to 1 inserted page (3*4=12; 12+2=14; 13+1=14). You can make the page numbers also divisible by 5 with an offset of 3. There is no limitation. The result will always be the minimal number of inserted pages. Divisible by 4, offset 1 has the same result as divisible by 4, offset 5.

\noindent\verb&\setFillPage{pagenumber}{content}&\\
This creates a custom page, which will be used, if needed. By default all inserted pages are white, but if they shouldn't be white, you can define a content. I.e.
\begin{lstlisting}[numbers=none]
    \setFillPage{3}{This is the insert page three}
\end{lstlisting}\vskip -8pt\relax
will create a page with the text ''This is the insert page three''. If only 2 pages are needed, it won't be used. If more than 2 are used, it will be. You can define as many fill-pages as you want, but only the required amount will appear in your document. The command is defined as long, which means, you are allowed to use paragraphs inside. It behaves almost like any other page in \LaTeX .

\noindent\verb&\setDefaultFillPage{content}&\\
This command works exactly like \verb&\setFillPage&, but takes only one argument. It sets the appearance of all other fill-pages. This makes it possible to set headers and footers, the page style or even a default text.

\section{What the package uses}
The package relies solely on standard \LaTeX -core functions.

\section{How it works}
The principle is really straight forward. The difficulty was to implement it bug free and robust (especially the idempotency).

\begin{enumerate}
\item First run: 
\begin{enumerate}
\item Count all places, where pages can be inserted.
\end{enumerate}
\item Second run: 
\begin{enumerate}
\item Calculate the number of total pages without the fill-pages, that were inserted.
\item Do a modulo division on this page count by target divisor (offset must be considered). It is actually not a modulo operation, but this is the principle behind it. Page count is 15, must be divisible by 4 (offset 0), 15\%4=3 $\rightarrow$ 1 page too less.
\item This number of pages to be inserted is distributed across all insertion points.\\Example 1: 3 insertion points and 3 pages, each gets one page.\\Example 2: 3 insertion points and 4 pages, first two get one page, third one gets two pages. This is done by the total limit. At the first point total limit is 1.33 $\rightarrow$ 1 inserted. At the second point, limit is 2.66, 1 already inserted $\rightarrow$ insert 1. At the third insertion point the total limit is 4, 2 already inserted  $\rightarrow$  insert 2.
\end{enumerate}
\end{enumerate}

\section{References and interferences}
To avoid any interference with other packages, I listed the most probable causes for interference.

The package uses the \verb+\AtBeginDocument+ and \verb+\AtEndDocument+ document hook. If there is some issue with them, it won't work. I experienced some weird behaviour in koma classes with a beta-version of this package, which I couldn't explain. Therefore, it is mentioned here.

The package writes the following lines to the aux-file:\begin{lstlisting}[breaklines, numbers=none]
    \global\GFM@FiPa@numberOfFillPagePositions=<Number of fill-page positions>}

    \global\GFM@FiPa@numberOfInsertedPages=<Page count of fill-pages>}
\end{lstlisting}\vskip -8pt\relax
\noindent Make sure, that they don't interfere with anything of other packages or with any of your counters. Due to the naming this shouldn't happen at all.


\section{Known problems}
\subsection{Page number toggles}
If you have i.e. 10 pages and define divisible by 4, it should be 12 pages, which makes 2 fill-pages. If the page number toggles between 11 and 13 every two runs, there are two possible reasons:
\begin{enumerate}
\item You didn't put a clearpage before the \verb+\insertFillPages+
\item You defined a custom fill-page which is bigger than one page and will result in two fill-pages, though one should be inserted
\end{enumerate}


\section{Bug reports}
Nothing to say here. You can post any bug reports on bitbucket, if you find some:
\begin{quote}
\url{https://bitbucket.org/maestro-glanz/fillpages/src/main/}
\end{quote}
If you don't have a bitbucket account and don't want to create one, you can post an email to \mbox{text\color{white}.\color{black}\hspace*{-7.5pt} inkerer.1904$@$gmail.com} and hope, that I read it within 3 month. Note:~Copying the mail address will fail. This is for spam precautions. You have to type it off your screen. This is a good memory exercise to keep your mind vital a flexible.

\section{Revision history}
\noindent
\begin{tabular}{l l}
2017/11/01:& version 0.1.0\\
2025/01/07:& version 1.0.0\\
2025/01/10:& version 1.0.1\\
2025/01/21:& version 1.1.0
\end{tabular}


\end{document}

\section{Version 1.1.0}
\long\def\setDefaultFillPage#1{%
    \def\GFM@FP@defaultFillPage{%
        #1%
    }%
}

\section{Before upload}
Is the license in 
- the sty- and tex-files?
- readme?

Is the author name in 
- the sty- and tex-files?
- readme?

Is the version number in 
- the docu text?
- the sty- and tex-files (+provides package param)?
- readme?
  
Is the correct revision date in 
- the docu text?
- the sty- and tex-files?
- readme?

Is the repo link in
- the docu text?
- the sty- and tex-files? -> no
- readme? -> no





\chapter{fillpages}