Debian Codegraph @

texmf-dist/source/latex/adjmulticol/adjmulticol.dtx

raw
1 % \iffalse
2 %
3 %% Copyright 2022, Boris Veytsman <[email protected]>
4 %% This work may be distributed and/or modified under the
5 %% conditions of the LaTeX Project Public License, either
6 %% version 1.3 of this license or (at your option) any
7 %% later version.
8 %% The latest version of the license is in
9 %% http://www.latex-project.org/lppl.txt
10 %% and version 1.3 or later is part of all distributions of
11 %% LaTeX version 2003/06/01 or later.
12 %%
13 %% This work has the LPPL maintenance status `maintained'.
14 %%
15 %% The Current Maintainer of this work is Boris Veytsman
16 %%
17 %% This work consists of the file adjmulticol.dtx and the
18 %% derived file adjmulticol.sty,
19 %%
20 %%
21 %% Since this package is based on the multicol package,
22 %% Copyright 1989-2005 Frank Mittelbach, the following additional
23 %% condition is added to the licensing terms. The term ``multicol''
24 %% here should be interpreted as ``multicol and/or adjmulticol''
25 %% package, as appropriate.
26 %%
27 %% In addition to the terms of LPPL any distributed version
28 %% (unchanged or modified) of multicol has to keep the statement
29 %% about the moral obligation for using multicol. In case of major
30 %% changes where this would not be appropriate the author of the
31 %% changed version should contact the copyright holder.
32 %%
33 %%
34 %% Moral obligation for using multicol:
35 %% ------------------------------------
36 %%
37 %% Users of multicol who wish to include or use multicol or a modified
38 %% version in a proprietary and commercially market product are asked
39 %% under certain conditions (see below) for the payment of a license
40 %% fee. The size of this fee is to be determined, in each instance,
41 %% by the commercial user, depending on his/her judgment of the value of
42 %% multicol for his/her product.
43 %%
44 %%
45 %% The conditions for this are as follows:
46 %%
47 %% The producer of a proprietary and commercially market product
48 %% that involves typesetting using multicol is asked to determine
49 %% the value of a license fee for using multicol if
50 %%
51 %% - the product is a document and the producer has decided to
52 %% include multicol to typeset (parts of) the document or has
53 %% directed the author of the document to include multicol (for
54 %% example, by providing a class file to be used by the author)
55 %%
56 %% - the product is a LaTeX class or package that includes multicol
57 %%
58 %%
59 %% There is no moral obligation in case
60 %%
61 %% - the product is a document but producer has not directed
62 %% the author to include multicol (in that case the moral obligation
63 %% lies with the author of the document)
64 %%
65 %% - the product does not involve typesetting, e.g., consists, for
66 %% example, of distributing multicol and its documentation.
67 %%
68 %% - the product is not proprietary, i.e., is made available as free
69 %% software itself (which doesn't prohibit its commercial marketing)
70 %%
71 %% - multicol is used for non-commercial purposes
72 %%
73 %%
74 %% Determinating a license fee might result in a license fee of zero
75 %% (i.e., no payment) in case a producer has determined that the use
76 %% of multicol has no enhancing effect on the product. This is a
77 %% plausible scenario, i.e., in the above two cases the producer is
78 %% only asked to evaluate the value of multicol for the product
79 %% not for the payment of a license fee per se (which might or might
80 %% not follow from this evaluation).
81 %%
82 %% The license fee, if any, can be payed either to the LaTeX3 fund
83 %% (see ltx3info.txt in the base LaTeX distribution) or to the author of
84 %% the program who can be contacted at
85 %%
86 %% [email protected]
87 %%
88 %<*gobble>
89 % \fi
90 % \CheckSum{0}
91 %
92 %
93 %% \CharacterTable
94 %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
95 %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
96 %% Digits \0\1\2\3\4\5\6\7\8\9
97 %% Exclamation \! Double quote \" Hash (number) \#
98 %% Dollar \$ Percent \% Ampersand \&
99 %% Acute accent \' Left paren \( Right paren \)
100 %% Asterisk \* Plus \+ Comma \,
101 %% Minus \- Point \. Solidus \/
102 %% Colon \: Semicolon \; Less than \<
103 %% Equals \= Greater than \> Question mark \?
104 %% Commercial at \@ Left bracket \[ Backslash \\
105 %% Right bracket \] Circumflex \^ Underscore \_
106 %% Grave accent \` Left brace \{ Vertical bar \|
107 %% Right brace \} Tilde \~}
108 %
109 %\iffalse
110 % \begin{macrocode}
111 \documentclass{ltxdoc}
112 \usepackage[breaklinks,colorlinks,linkcolor=black,citecolor=black,
113 pagecolor=black,urlcolor=black]{hyperref}
114 \usepackage{breakurl,adjmulticol}
115 \PageIndex
116 \CodelineIndex
117 \RecordChanges
118 \EnableCrossrefs
119 \begin{document}
120 \DocInput{adjmulticol.dtx}
121 \end{document}
122 % \end{macrocode}
123 %</gobble>
124 % \fi
125 % \MakeShortVerb{|}
126 % \GetFileInfo{adjmulticol.sty}
127 %
128 % \title{Adjusting Margins for Multicolumn and Unicolumn
129 % Output\thanks{\copyright Boris Veytsman, 2022} \thanks{Note: This
130 % package is released under terms which affect its use in commercial
131 % applications. Please see the details at the top of the source file}}
132 % \author{Boris Veytsman}
133 % \date{\filedate, \fileversion}
134 % \maketitle
135 %
136 % \begin{abstract}
137 % This package provides an extension of the \textsf{multicol}
138 % package~\cite{Mittelbach06:Multicol} with the option to change the
139 % margins for multicolumn and unicolumn layout. The package understands the
140 % difference between the even and odd margins for two side printing.
141 % \end{abstract}
142 %
143 % \tableofcontents
144 %
145 % \clearpage
146 %
147 %\section{Introduction}
148 %\label{sec:intro}
149 %
150 %
151 % One of the common requests from the book designers is the
152 % possibility to change the margins of the text in the midddle of the
153 % page. The standard \LaTeX{} |list| environment does exactly this.
154 % Thus it is not surprising that many packages creatively use this
155 % tool to change the layout. An example is the \textsf{changepage}
156 % package~\cite{Wilson09:Changepage}. Unfortunately this approach has
157 % a seriour drawback: a list sets the margins globally. If the
158 % material is split between the pages, the margins on the first page
159 % are repeated on all the subsequent pages. While this is fine for
160 % one-side printing, it leads to a catastrophe for the two-sided
161 % one, as can be seen from the following example (provided by Ivo
162 % Welch):
163 % \begin{verbatim}
164 % \documentclass{book}
165 % \usepackage{lipsum,multicol}
166 % \evensidemargin=1.5in
167 % \oddsidemargin=-3em
168 % \textwidth=5in
169 %
170 % \newenvironment{chmargin}[2]{%
171 % \begin{list}{}{\topsep0pt\partopsep0pt\itemsep0pt\parsep\parskip%
172 % \listparindent\parindent\itemindent\parindent
173 % \leftmargin#1\rightmargin#2\relax}\item}%
174 % {\end{list}}
175 %
176 % \begin{document}
177 %
178 % \chapter{Show}
179 % \section{Normal}
180 % \marginpar{I need a lot of outer margin space in the normal text.}
181 % \lipsum[1-10]
182 % \begin{chmargin}{0pt}{-160pt}
183 % \section{End of Chapter Meterial}
184 % \textbf{Now I want to use the outer margin because I need width.}
185 % \lipsum[11-16]
186 % \fbox{\textbf{\Large Darn---it extends into the inner spine margin now.}}
187 % \lipsum[17-40]
188 % \end{chmargin}
189 %
190 % \end{document}
191 % \end{verbatim}
192 %
193 %
194 % To remedy this problem, we need a completely different approach: we
195 % need to change the output routine. This is done in this package.
196 %
197 % Since the text with the special layout is often typeset in the
198 % multicolumn mode, we load the \textsf{multicol}
199 % package~\cite{Mittelbach06:Multicol} and patch it to provide two
200 % changes:
201 % \begin{enumerate}
202 % \item Margins changes, persistent over the pages.
203 % \item The possibility of an one-column ``multicolumn'' layout. Of
204 % course, this layout does not make sense in the context of the
205 % original \textsf{multicol} package, but is useful when the
206 % margins are changed.
207 % \end{enumerate}
208 %
209 % Note that since this package uses the \textsf{multicol} package, it
210 % inherits its special moral obligation for the commercial users.
211 % Please see the source file for the details.
212 %
213 % This file was commissioned for by Prof.~Ivo Welch,
214 % \url{http://www.ivo-welch.info/}. He also provided sample files
215 % and patiently tested it.
216 %
217 %\section{User Interface}
218 %\label{sec:interface}
219 %
220 % The installation of the class follows the usual
221 % practice~\cite{TeXFAQ} for \LaTeX{} packages:
222 % \begin{enumerate}
223 % \item Run \textsf{latex} on |adjmulticol.ins|. This will produce the file
224 % |adjmulticol.sty|.
225 % \item Put the file |adjmulticol.sty| to
226 % the place where \LaTeX{} can find them (see
227 % \cite{TeXFAQ} or the documentation for your \TeX{}
228 % system).\label{item:install}
229 % \item Update the database of file names. Again, see \cite{TeXFAQ}
230 % or the documentation for your \TeX{} system for the system-specific
231 % details.\label{item:update}
232 % \item The file |adjmulticol.pdf| provides the documentation for the
233 % package (this is the file you are probably reading now).
234 % \end{enumerate}
235 % As an alternative to items~\ref{item:install} and~\ref{item:update}
236 % you can just put the files in the working directory where your
237 % |.tex| file is.
238 %
239 %
240 %
241 % To use this package, add to the preamble of your document
242 % the line |\usepackage{adjmulticol}|.
243 %
244 % The package provides two new environments for adjusted multicolumn
245 % layout.
246 %
247 % \DescribeEnv{adjmulticols}
248 % The environment |adjmulticols| is similar to the environment
249 % |multicols|, but it has three mandatory arguments instead of one:
250 % \begin{quote}
251 % |\begin{adjmulticols}|\marg{number}\marg{inner margin}\marg{outer
252 % margin}\\
253 % \meta{text}\\
254 % |\end{adjmulticols}|
255 % \end{quote}
256 % For example,
257 % \begin{verbatim}
258 % \begin{adjmulticols}{2}{12pt}{-1in}
259 % Text Text Text
260 % \end{adjmulticols}
261 % \end{verbatim}
262 % Here \meta{number} is the number of columns. Unlike |multicols|,
263 % |adjmulticols| environment allows this number to be 1.
264 %
265 % The \meta{inner margin} and \meta{outer margin} are calculated from
266 % the current text area margins, so negative values mean the extension
267 % of the text area. In one-sided printing \meta{inner margin} is the
268 % left margin, and \meta{outer margin} is the right margin. You
269 % probably would not want to use this package for one-sided printing,
270 % since in this case \textsf{changepage}
271 % package~\cite{Wilson09:Changepage} works fine. In two-sided
272 % printing \meta{inner margin} is the margin on the spine side of the
273 % page, and \meta{outer margin} is the margin on the other side.
274 %
275 % You can use the optional arguments of the |multicols| environment.
276 % Note that the argument of the first optional argument, the header text
277 % spread over all columns, is typeset with the \emph{normal} margins.
278 % If you want to change margins for the header too, you may want to
279 % use one-column |adjmulticols| environment instead.
280 %
281 % \DescribeEnv{adjmulticols*}
282 % The starred version of the environment, |adjmulticols*| is similar
283 % to the |multicols*| environment: it does not balance the columns on
284 % the last page.
285 %
286 %
287 %
288 %\StopEventually{\clearpage
289 % \bibliography{adjmulticol}
290 % \bibliographystyle{unsrt}}
291 %
292 % \clearpage
293 %
294 % \section{Implementation}
295 % \label{sec:implementation}
296 %
297 %
298 %\subsection{Declarations}
299 %\label{sec:decl}
300 %
301 % We start with declaration, who we are:
302 %
303 %
304 % \begin{macrocode}
305 %<style>\NeedsTeXFormat{LaTeX2e}
306 %<*gobble>
307 \ProvidesFile{adjmulticol.dtx}
308 %</gobble>
309 %<style>\ProvidesPackage{adjmulticol}
310 %<*style>
311 [2022/05/15 v1.5 Adjusted margins for multicolumn layout]
312 % \end{macrocode}
313 %
314 %
315 %\subsection{Options}
316 %\label{sec:options}
317 %
318 % All options are sent to |multicols|:
319 % \begin{macrocode}
320 \DeclareOption*{\PassOptionsToPackage{\CurrentOption}{multicol}}
321 \ProcessOptions\relax
322 % \end{macrocode}
323 %
324 %
325 %\subsection{Loading Packages}
326 %\label{sec:loading}
327 %
328 % We use |multicol| to get all the code from it:
329 % \begin{macrocode}
330 \RequirePackage{multicol}
331 % \end{macrocode}
332 %
333 %
334 %\subsection{Registers}
335 %\label{sec:registers}
336 %
337 % \begin{macro}{\adjmc@inner}
338 % Inner margin delta: left on odd pages, right on even pages for
339 % two-sided typesetting, and left for one-sided typesetting.
340 % \begin{macrocode}
341 \newdimen\adjmc@inner
342 % \end{macrocode}
343 % \end{macro}
344 % \begin{macro}{\adjmc@outer}
345 % Outer margin delta: right on odd pages, left on even pages, and
346 % right for two-sided typesetting
347 % \begin{macrocode}
348 \newdimen\adjmc@outer
349 % \end{macrocode}
350 % \end{macro}
351 %
352 %
353 % \begin{macro}{\adjmc@saved@leftmargin}
354 % We save the value of |\multicol@leftmargin| between the calls in
355 % the register |\adjmc@savedleftmargin|:
356 % \begin{macrocode}
357 \newdimen\adjmc@saved@leftmargin
358 % \end{macrocode}
359 %
360 % \end{macro}
361 %
362 %\subsection{Starting Environment}
363 %\label{sec:start}
364 %
365 % \begin{macro}{\adjmulticols}
366 % \changes{v1.3}{2022/03/27}{Do not try to balance one-column version}
367 % \changes{v1.4}{2022/04/17}{Change the balancing of one-column}
368 % We have three mandatory arguments instead of one for |multicols|:
369 % the number of columns, the left margin delta and the right margin
370 % delta:
371 % \begin{macrocode}
372 \def\adjmulticols#1#2#3{\col@number#1\relax
373 \def\@tempa{#2}%
374 \ifx\@tempa\@empty\adjmc@inner\z@\else\adjmc@inner#2\fi
375 \def\@tempa{#3}%
376 \ifx\@tempa\@empty\adjmc@outer\z@\else\adjmc@outer#3\fi
377 % \end{macrocode}
378 % The standard |multicols| have the minimum of two columns. We, of
379 % course, want to consider one column layout too:
380 % \begin{macrocode}
381 \ifnum\col@number<\@ne
382 \PackageWarning{adjmulticol}%
383 {Using `\number\col@number'
384 columns doesn't seem a good idea.^^J
385 I therefore use one columns instead}%
386 \col@number\@ne\fi
387 \ifnum\col@number>10
388 \PackageError{adjmulticol}%
389 {Too many columns}%
390 {Current implementation doesn't
391 support more than 10 columns.%
392 \MessageBreak
393 I therefore use 10 columns instead}%
394 \col@number10 \fi
395 \ifnum\col@number=\@ne\relax
396 \let\balance@columns\adjmc@process@ne@column
397 \fi
398 % \end{macrocode}
399 %
400 %
401 % As in the standard package we redefine the footnote making command:
402 % \begin{macrocode}
403 \ifx\@footnotetext\mult@footnotetext\else
404 \let\orig@footnotetext\@footnotetext
405 \let\@footnotetext\mult@footnotetext
406 \fi
407 % \end{macrocode}
408 % And look for the optional arguments
409 % \begin{macrocode}
410 \@ifnextchar[\adjmult@cols{\adjmult@cols[]}}
411 % \end{macrocode}
412 % \end{macro}
413 %
414 % \begin{macro}{\adjmult@cols}
415 % Looking for the second optional argument. Note that we use
416 % |\premulticols| for the default:
417 % \begin{macrocode}
418 \def\adjmult@cols[#1]{\@ifnextchar[%
419 {\adjmult@@cols{#1}}%
420 {\adjmult@@cols{#1}[\premulticols]}}
421 % \end{macrocode}
422 % \end{macro}
423 %
424 % \begin{macro}{\adjmult@@cols}
425 % And now we are gathered all arguments:
426 % \begin{macrocode}
427 \def\adjmult@@cols#1[#2]{%
428 % \end{macrocode}
429 % The macro |\prepare@multicols| uses the current value of
430 % |\linewidth|. We do not change his, but rather change |\linewidth|:
431 % \begin{macrocode}
432 \advance\linewidth by -\adjmc@inner\relax
433 \advance\linewidth by -\adjmc@outer\relax
434 % \end{macrocode}
435 % Then we redefine the output routines:
436 % \begin{macrocode}
437 \let\page@sofar=\adjmc@page@sofar
438 % \end{macrocode}
439 % and start the standard multicols:
440 % \begin{macrocode}
441 \mult@@cols#1[#2]}
442 % \end{macrocode}
443 % \end{macro}
444 %
445 %
446 %
447 % \begin{macro}{\set@mult@vsize}
448 % \changes{v1.1}{2013/01/20}{Redefined macro}
449 % The formula for |\vsize| in multicols seem to work only for
450 % column number above 2. Here we add special case of 1.
451 % \begin{macrocode}
452 \def\set@mult@vsize#1{%
453 \vsize\@colroom
454 \@tempdima\baselineskip
455 \advance\@tempdima-\topskip
456 \advance\vsize\@tempdima
457 \vsize\col@number\vsize
458 \advance\vsize-\@tempdima
459 \ifnum\col@number>1\relax
460 \advance\vsize\col@number\baselineskip
461 \else
462 \advance\vsize-2\baselineskip
463 \fi
464 #1\advance\vsize
465 \c@collectmore\baselineskip}
466 % \end{macrocode}
467 % \end{macro}
468 %
469 %\subsection{Ending Environment}
470 %\label{sec:end}
471 %
472 % \begin{macro}{\endadjmulticols}
473 % \changes{v1.2}{2020/03/06}{Redefined macro}
474 % \changes{v1.3}{2022/03/27}{Added \cs{vfill} for one-column environment}
475 % Here we use the standard environment end. Note that it uses
476 % |\@checkend|, so we need to redefine it to fool the
477 % check. We need to do it globally to work inside a box too.
478 % \begin{macrocode}
479 \def\endadjmulticols{%
480 \global\let\@ADJMC@checkend\@checkend
481 \gdef\@checkend##1{}%
482 \ifnum\col@number=\@ne\relax\vfill\fi
483 \endmulticols
484 \global\let\@checkend\@ADJMC@checkend}
485 % \end{macrocode}
486 % \end{macro}
487 %
488 %
489 %
490 %\subsection{Output Routines}
491 %\label{sec:output}
492 %
493 % \begin{macro}{\adjmc@page@sofar@orig}
494 % First, we save the original declaration of |\page@sofar|:
495 % \begin{macrocode}
496 \let\adjmc@page@sofar@orig=\page@sofar
497 % \end{macrocode}
498 %
499 % \end{macro}
500 %
501 %
502 % \begin{macro}{\adjmc@page@sofar}
503 % \changes{v1.4}{2022/04/17}{No longer copying boxes for one column
504 % version}
505 % We redefine |\page@sofar| to change the margins and allow for
506 % one-column output:
507 % \begin{macrocode}
508 \def\adjmc@page@sofar{%
509 % \end{macrocode}
510 % We redefine |\multicol@leftmargin| to introduce the shift of the
511 % box. We save the old code in |\adjmc@saved@leftmargin|
512 % \begin{macrocode}
513 \adjmc@saved@leftmargin=\multicol@leftmargin
514 \if@twoside
515 \ifodd\c@page
516 \advance\multicol@leftmargin by \adjmc@inner\relax
517 \else
518 \advance \multicol@leftmargin by \adjmc@outer\relax
519 \fi
520 \else
521 \advance \multicol@leftmargin by \adjmc@inner\relax
522 \fi
523 % \end{macrocode}
524 % Then we invoke the original |\page@sofar| and restore the margin:
525 % \begin{macrocode}
526 \adjmc@page@sofar@orig
527 \multicol@leftmargin=\adjmc@saved@leftmargin}
528 % \end{macrocode}
529 %
530 % \end{macro}
531 %
532 % \begin{macro}{\adjmc@process@ne@column}
533 % \changes{v1.4}{2022/04/17}{Added macro}
534 % \changes{v1.5}{2022/05/15}{Added \cs{vfill}}
535 % If we have one column, we do not need to balance it. Mostly stolen
536 % from |multicol.sty|
537 % \begin{macrocode}
538 \def\adjmc@process@ne@column{%
539 \setbox\mult@firstbox\vbox{\unvbox\mult@box\vfill}}
540 % \end{macrocode}
541 %
542 %
543 % \end{macro}
544 %
545 %\subsection{Not Balancing Columns}
546 %\label{sec:not_balance}
547 %
548 % The starred versions do not balance the columns.
549 %
550 % \begin{macro}{\adjmulticols*}
551 % \changes{v1.4}{2022/04/17}{Special code for one column version}
552 % This follows the code of the \textsf{multicols} package with the
553 % special check for one column:
554 % \begin{macrocode}
555 \newenvironment{adjmulticols*}{%
556 \ifinner
557 \PackageWarning{multicol}%
558 {multicols* inside a box does
559 not make sense.\MessageBreak
560 Going to balance anyway}%
561 \else
562 \ifnum\col@number=\@ne\relax
563 \let\balance@columns\adjmc@process@ne@column
564 \else
565 \let\balance@columns@out\multi@column@out
566 \fi
567 \fi
568 \adjmulticols}{%
569 \vfill
570 \endadjmulticols}
571 % \end{macrocode}
572 %
573 % \end{macro}
574 %
575 %
576 %\subsection{Ending the Style}
577 %\label{sec:end}
578 %
579 %
580 %
581 % \begin{macrocode}
582 %</style>
583 % \end{macrocode}
584 %\Finale
585 %\clearpage
586 %
587 %\PrintChanges
588 %\clearpage
589 %\PrintIndex
590 %
591 \endinput