summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/fillpages/fillpages-documentation.tex
blob: 943a48acfe018837c97960d27ce2c9f7f1d9c200 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                   %
%      Made by Gabriel Ruprecht     %
%                                   %
% This work is published under the  %
% LaTeX project public license 1.3  %
%                                   %
%       Package version 1.0.0       %
%            2025-01-07             %
%                                   %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\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.0.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 dividable 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}

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

\setFillPage{2}{
ABC

DEF
}

\setFillPage{3}{
123

456
}


\begin{document}

\lipsum

\clearpage
\insertFillPages
\insertFillPages

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

\clearpage
\insertFillPages

\lipsum

\end{document}
\end{lstlisting}

\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#. Previous to every \verb+\inserFillPages+ there should be a \verb+\clearpage+. Otherwise the page count will be miscalculated and might toggle.

\noindent\verb&\pagesDividableBy{number}[offset]&\\ This defines the number the page number must be dividable 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 dividable by 5 with an offset of 3. There is no limitation. The result will always be the minimal number of inserted pages. Dividable by 4, offset 1 has the same result as dividable 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 .

\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 dividable 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 dividable 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
\end{tabular}


\end{document}

\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}