new latex package canoniclayout (23jan11)

git-svn-id: svn://tug.org/texlive/trunk@21155 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 452 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/canoniclayout/canoniclayout.dtx b/Master/texmf-dist/source/latex/canoniclayout/canoniclayout.dtx
new file mode 100644
index 00000000000..cff4dc127dd
--- /dev/null
+++ b/Master/texmf-dist/source/latex/canoniclayout/canoniclayout.dtx
@@ -0,0 +1,452 @@
+% \iffalse
+%<*internal>
+\begingroup
+\input docstrip.tex
+\keepsilent
+\preamble
+  ______________________________________________________
+  The canoniclayout package for LaTeX
+  Copyright (C) 2010 Claudio Beccari 
+  All rights reserved
+
+  License information appended
+
+\endpreamble
+\postamble
+Copyright 2010 Claudio Beccari
+
+Distributable under the LaTeX Project Public License,
+version 1.3c or higher (your choice). The latest version of
+this license is at: http://www.latex-project.org/lppl.txt
+
+This work is "author-maintained"
+
+This work consists of this file canoniclayout.dtx, a README file
+and the derived files canoniclayout.sty and canoniclayout.pdf.
+
+\endpostamble
+\askforoverwritefalse
+%
+\generate{\file{canoniclayout.sty}{\from{canoniclayout.dtx}{package}}}
+%
+\def\tmpa{plain}
+\ifx\tmpa\fmtname\endgroup\expandafter\bye\fi
+\endgroup
+%</internal>
+% \fi
+%
+% \iffalse
+%<*driver>
+\ProvidesFile{canoniclayout.dtx}
+%</driver>
+%<package>\NeedsTeXFormat{LaTeX2e}[2009/01/01]
+%<package>\ProvidesPackage{canoniclayout}%
+%<*package>
+   [2010/12/04 v.0.2 Canonic layout circumscribed to a circle]
+%</package>
+%<*driver>
+\documentclass{ltxdoc}
+\paperwidth=220mm\paperheight=280mm
+\pdfpagewidth=\paperwidth \pdfpageheight=\paperheight
+\usepackage[latin1]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{lmodern}
+\usepackage{textcomp}
+\usepackage{multicol}
+\usepackage{amsmath,array,booktabs}
+\usepackage{pict2e}[2009/06/01]%
+\usepackage{color}
+\hfuzz 10pt
+%\makeatletter
+\newcommand*\class[1]{\textsf{#1}}
+\newcommand*\pack[1]{\textsf{#1}}
+\newcommand*\prog[1]{\textsl{#1}}
+\newcommand*\file[1]{\texttt{#1}}
+\definecolor{grigio}{gray}{.75}
+\makeatletter
+\def\ps@title{\ps@plain
+\def\@oddhead{\dimen256=\dimexpr\headheight+\topmargin+1in-\paperheight\relax
+\dimen258=\dimexpr\oddsidemargin+1in\relax
+\begin{picture}(0,0)(\strip@pt\dimen258,-\strip@pt\dimen256)
+\put(0,0){\unitlength=\dimexpr\paperwidth/220\relax % rounded expression
+\let\ul\unitlength
+\put(0,0){\framebox(220,280){}}
+\color{red}
+\put(20.742,33.6){\makebox(0,0)[bl]{\color{grigio}\rule{172.86\ul}{220\ul}}}
+\put(110,143.6){\circle{220}}
+	\Line(0,280)(220,0)}
+\end{picture}}
+\let\@evenhead\@oddhead}
+\allowdisplaybreaks
+\begin{document}
+\GetFileInfo{canoniclayout.dtx}
+\title{Package \pack{canoniclayout}\thanks{Version number \fileversion; last
+ revision \filedate.}}
+\author{Claudio Beccari\thanks{e-mail: \texttt{claudio dot beccari at gmail dot com}}}
+ \maketitle\thispagestyle{title}
+ \DocInput{canoniclayout.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{115}
+% \begin{abstract}
+%	This package is a small extension to the memoir class that allows to determine the page 
+%	parameters for a canonical layout where the text block is placed onto the page in such a
+%   way 	as: $(a)$ its diagonal coincides with the page relevant diagonal, and $(b)$ the
+%   circle inscribed within the text block is also tangent to the page sides. The text
+%   block width to height ratio is kept equal to the page ratio, as well as  the inner to
+%   outer and the top to bottom margin ratios.
+%
+%   The canonical layout determined by this package is laid down on this very page; of
+%   course the actual text block does not fit the text block grid, because this
+%   documentation is typeset by means of the \texttt{ltxdoc} document clssa, that uses
+%   different layout paramenters. At the same time the classical layout, conceived fot two
+%   sided printing, gets properly compared with a standard (one sided printing) \LaTeX\ 
+%   layout.\footnote{Actually the \texttt{ltxdoc} class default paper size is the letter
+%   paper; here we rounded a little bit the letter paper dimensions to integer millimeter
+%   values of 220\,mm $\times$ 280\,mm. See the discussion about the convenience od such
+%   layout when the main font size is considered.}
+% \end{abstract}
+%
+% \begin{multicols}{2}
+% \tableofcontents
+% \end{multicols}
+%
+% \section{Introduction}
+% As any user of the \class{memoir} class knows well, this class allows to customize the
+% page layout virtually without any limitation; such limitations are connected mainly with
+% the user inconsistent data that miss to specify necessary information or give unnecessary
+% and contrasting information.
+% 
+% Many packages exist in order to specify a named layout; this package \pack{canoniclayout}
+% is another one that computes the page parameters  to determine the horizontal and vertical
+% dimensions of the margins and the text block. All other details shall be specified by the
+% user, for example the dimensions of the stock paper, the trimming widths, and therefore
+% the position of the page onto the stock paper, and so on.
+% This package deals only with the trimmed page, not with the page and stock paper
+% relationship.
+%
+% \begin{figure}
+% \makebox[\textwidth]{\makebox[1.1\textwidth][r]{%
+% \unitlength=0.0015\textwidth
+% \let\ul\unitlength
+%	\begin{picture}(184,320)(0,-20)
+%	\put(0,0){\framebox(184,297){}}
+%	\put(27,70){\makebox(0,0)[bl]{\color{grigio}\rule{113\ul}{184\ul}}}
+%	\put(92,-20){\makebox(0,0)[t]{Golden number canonical layout}}
+%	\color{red}
+%	\put(92,162){\circle{184}}
+%	\linethickness{.2pt}
+%	\multiput(0,297)(1.98918918919,-3.21081081082){93}{\line(184,-297){1}}
+%	\end{picture}%
+% \hfill
+%	\unitlength0.0015\textwidth
+%	\let\ul\unitlength
+%		\begin{picture}(210,330)(0,-20)
+%		\put(0,0){\framebox(210,297){}}
+%		\put(25,51){\makebox(0,0)[bl]{\color{grigio}\rule{149\ul}{210\ul}}}
+%		\put(105,-35){\makebox(0,0)[b]{ISO canonical layout}}
+%		\color{red}
+%		\put(105,156){\circle{210}}
+%		\multiput(0,297)(2.27027027027,-3.21081081082){93}{\line(210,-297){1}}
+%		\end{picture}%
+% \hfill
+%   \unitlength0.001591\textwidth
+%   \let\ul=\unitlength
+%   \begin{picture}(220,330)(0,-20)
+%   		\put(0,0){\framebox(220,280){}}
+%   		\put(20.742,33.6){\makebox(0,0)[bl]{\color{grigio}\rule{172.86\ul}{220\ul}}}
+%   		\put(110,-35){\makebox(0,0)[b]{Letter paper canonical layout}}
+%   		\color{red}
+%   		\put(110,143.6){\circle{220}}
+%		\multiput(0,280)(2.37837837838,-3.02702702703){93}{\line(220,-280){1}}
+%   \end{picture}
+% }}%
+% \caption{A right page with the relevant diagonal, the text block and the canonical circle.
+% In this figure the important information is the page proportions, not the scale; matter of
+% fact the letter paper is 17.6 mm shorter than the A4 paper, but the drawings to the same
+% height emphasize the relative proportions of the various page parts.}
+% \label{fig:canoniclayout}
+% \end{figure}
+%
+% Figure~\ref{fig:canoniclayout} depicts the situation described above; the gray rectangle
+% represents the type block; the dotted page diagonal, as it can be seen, passes through
+% the diagonal vertices of the type block; at the same time the circle is tangent to both
+% the type block and the page contour.
+%
+% It must also be noticed, in the sketch on the left, that the page rectangle is a golden
+% one; therefore also the type block is a golden rectangle; the inner to the outer margin
+% ratio is the golden section value so as this same ratio exists between the top and the
+% bottom margin. This canonical layout implies that the type block height is equal to the
+% page width.
+% Therefore this canonical layout is not suited when the page width is small compared
+% to the page height: with the golden section\footnote{Here we denote $\phi=1,618\dots$
+% with the name of \emph{golden number}, and its reciprocal $\varphi=0,618\dots$ with the
+% name of \emph{golden section}.} this ratio is 0.618, with the ISO paper shape, in the
+% sketch on the center, this ratio is 0,707, and so on.
+% But it is equally unsuitable with squarish pages, such as the scketch on the right where
+% the page proportions conform with the USA letter paper size: the type block leaves little
+% space for the margins, as it is evident from the properties of the canonical circle, which
+% is tangent to the page lateral sides and to the type block horizontal sides; to the limit
+% in a square page the type block is so large that there is no room for the margins.
+%
+% \section{The mathematics of the canonical layout}
+% If one plays a little with the drawing of figure~\ref{fig:canoniclayout} and applies what
+% has been described in the Introduction, may easily derive the following formulas:
+%\begin{align}
+%&\text{Page shape ratio:}&		x&=b/h			\label{equ:1}\\
+%&\text{Inner margin:}&			I&=bx(1-x)/(1+x)	\\
+%&\text{External margin:}&		E&=b(1-x)/(1+x)	\\
+%&\text{Top margin:}&			T&=hx(1-x)/(1+x)	\\
+%&\text{Bottom margin:}&			B&=h(1-x)/(1+x)	\\
+%&\text{Text width:}&			W&=xb			\\
+%&\text{Text height:}&			H&=b				\\
+%&\text{Circle center abscissa:}&C_x&=0.5b		\\
+%&\text{Circle center ordinate:}&C_y&=h(1-x)/(1+x)+b/2\\
+%&\text{Circle radius:}&			R&=0.5b			\label{equ:10}
+%\end{align}
+% whose results are summarized in table~\ref{tab:canoniclayout} for three common values of
+% the shape factor and for the letter paper shape ratio.
+%
+%\begin{table}[!b]\centering\let~\enspace
+%\hrule
+%\caption{Canonical layout ratios referred to the the base (or width, $b$) of the trimmed
+% page and its height ($h$).}\label{tab:canoniclayout}
+%\bigskip
+%\begin{tabular}{l@{\qquad}*4{>{$}c<{$}}}
+%\toprule
+%						&\multicolumn4c{Canon}			\\
+%\multicolumn1c{Quantity}& \phi:1	& 3:2	& \sqrt2:1	& 11:8.5\\
+%\midrule
+% Page shape ratio 		&0,618~		&0,666~	&0,707~		&0,773~	\\
+% Inner margin 			&0,146b		&0,133b	&0,121b		&0,099b \\
+% External margin 		&0,236b		&0,200b	&0,172b		&0,128b	\\
+% Top margin 			&0,146h		&0,133h	&0,121h		&0,099h \\
+% Bottom margin 			&0,236h		&0,200h	&0,172h		&0,128h	\\
+% Text width  			&  0,618b	&0,666b	&0,707b		&0,773b	\\
+% Text height 			& b			& b		& 	b		&b		\\
+% Circle center abscissa	& b/2		& b/2	& b/2		&b/2		\\
+% Circle center ordinate	& 0,545h		&0,533h	&0,526h		&0,515h	\\
+% Circle radius 			& b/2		& b/2	& b/2		&b/2		\\
+%\bottomrule
+%\end{tabular}
+%\end{table}
+%
+% Actually the formulas~\ref{equ:1}--\ref{equ:10}, and their numerical evaluations reported
+% in table~\ref{tab:canoniclayout}, are just for general information. The actual
+% computations are performed by this package, by means of the \class{memoir} built-in
+% facilities. But it can be easily seen that as the trimmed page becomes more squarish, the
+% page size ratio tends to one, ad the margins become smaller and smaller. Therefore it
+% seems that thsi layout is most suited for intermediate page ratios, such as the ISO one
+% or the common European book size of 170\,mm $\times$ 240\,mm with a ratio of 0,708.
+%
+% \section{Usage}
+% This package is invoked as usual with:
+%\begin{verbatim}
+%   \usepackahe{canoniclayout}
+%\end{verbatim}
+% No options are necessary; but it is necessary to invoke the package only after the page
+% dimensions are known, be they specified by an option passed to the class, such as, for
+% example, \texttt{a4paper}, or by means of a \texttt{page}$size$ specification, for example
+% \texttt{pagebv} for calling the ISO B5 size.
+% 
+% At any convenient moment after calling this package, the trimming margins with respect to
+% the stock paper may be computed and the layout rechecked and fixed for consistency.
+%
+% \section{Font normal size}
+% At the same time if this page layout is chosen, the font normal size should be selected on
+% the actual text block width; it is possible that the golden ratio type block, on a golden
+% rectangle paper obtained by trimming  an ISO A4 stock paper, might be suitable with a 10pt
+% normal font size (exactly 66 characters per line with 10pt Latin Modern fonts), while a full
+% ISO A4 paper yields a type block that might be more suited for a 12pt normal font size (86
+% characters with 10pt Latin Modern fonts). The computations might be left to the
+% \class{memoir} class commands, but it's better the user is aware of this particular point.
+% For his/her sake this package provides the command |\currentfontletters| (to be used
+% only after |\begin{document}|, because specific font packages might be loaded after the page
+% layout has been computed; in any case the command is ``text producing'', therefore it can't
+% be used while in the preamble!) that types out a sentence such as ``The number of characters
+% in one text line with the current font is $nn$'', where the $nn$ is the actual number
+% printed out. If such number is much larger than the ideal Bringhurst range of $66\pm5$, it's
+% wiser to chose a larger normal font size. 
+% In any case the alternative command |\charactersperpage| types out the same information,
+% the number of lines and the estimated number of characters per page. These commands are
+% supposed to be useful while setting up the complete preliminary parameters for the page
+% layout. 
+%
+% Just to have a comparison, table~\ref{tab:sizes} displays the number of characters in one
+% line of text for several fonts and for page sizes A4 and A5.
+%
+%\begin{table}
+%\caption{Text line lengths measured in average number
+% of characters in different fonts}\label{tab:sizes}
+% \bigskip
+% 
+% \centering
+% \let\b\bfseries \let\i\itshape\tabcolsep=5pt
+% \makebox[\textwidth]{\small\begin{tabular}{l*9c}
+% \toprule
+% Font collection	& \multicolumn3c{A4 paper size}
+%                                        & \multicolumn3c{A5 paper size}
+%																&\multicolumn3c{B5 paper size}\\
+% 				& 10\,pt	& 11\,pt	& 12\,pt	& 10\,pt	& 11\,pt	& 12\,pt	& 10\,pt	& 11\,pt	& 12\,pt	\\
+% \midrule
+% Times eXtended	&	\i92	&	\i84	&	\i77	&	\b64	&	59	&	\i54	&	\i77	&	\b70	&	\b64	\\
+% Latin Modern	&	\i86	&	\i79	&	73	&	60	&	\i55	&	\i51	&	72	&	\b66	&	\b61	\\
+% Kepler Project	&	\i83	&	76	&	\b69	&	58	&	\i53	&	\i48	&	\b69	&	\b63	&	58	\\
+% Palatino eXtended&	\i82	&	75	&	\b69	&	58	&	\i53	&	\i48	&	\b69	&	\b63	&	57	\\
+% \bottomrule
+% \end{tabular}}
+%\end{table}
+%
+% It can be seen that the bold measures satisfy the Bringhurst rule with a number of
+% characters in the range $66\pm5$;  the  measures typeset in medium series type are out of 
+% the optimal Bringhurst range, but may be considered acceptable; the measures typeset in
+% italics  are completely out of the interval $66\pm10$ and should not be considered
+% acceptable. This means that the large A4 paper size may be best used with intrinsically
+% large fonts such as the Palatino eXtended (package \pack{pxfonts}) and the Kepler Project
+% (package  \pack{kpfonts}). With the smaller A5 paper size with 10\,pt size fonts the best
+% ones are the Times eXtended (package \pack{txfonts}), but substantially all the examined
+% fonts are acceptable, while with 12\,pt fonts none are acceptable.
+%
+% With an intermediate sized paper, such as a B5 ISO size, all the considered fonts are
+% acceptable inside or just outside the optimal Bringhurst interval.
+%
+% Many books are trimmed to a size close the B5 paper size, therefore the page layout
+% produced with this package is most useful with medium and smaller sizes (at least with
+% ISO sizes).
+
+% \section{Conclusion}
+% I don't think this package should set also the header and footer distances, for example,
+% or should set any specification for the page ``decorations'', such as underlined headers,
+% or overlined footers, or the size, font family, series and shape of the header and footer
+% contents. These specifications are of course important, but have nothing to do with the
+% relationship between the paper size, the page size and the type block size. 
+%
+% As a final remark it's worth noting that a single pass of \prog{pdflatex} on this
+% \texttt{canoniclayout.dtx} file
+% produces at the same time both the \file{canoniclayout.sty} package file and the
+% documentation \file{canoniclayout.pdf} file. After running \prog{pdflatex} move
+% \file{canoniclayout.sty} to a \file{tex/latex/canoniclayout/} folder and
+% \file{canoniclayout.pdf} to a \file{doc/latex\discretionary{}{/}{/}canoniclayout/} one;
+% if such folders don't exist, create them on your personal \TeX\ tree. After moving these
+% files remember to refresh the file name data base.
+%
+%
+% \StopEventually{} 
+%
+% \section{Documented code}
+% The package preliminaries are already in place. We are going to make some computations in
+% order to determine the page shape factor $x$; to this end we exploit the dimensional
+% computing capabilities of $\varepsilon$-\TeX, that are already embedded in the most recent
+% implementations of the program \prog{pdftex}; in fact it must be remarked that these
+% facilities are being embedded into the \prog{pdftex} typesetting engine since the \TeX~Live
+% distribution of the year 2005. If these facilities are not available, either
+% because the \TeX\ distribution is a little too old, or because the real \prog{tex}
+% typesetting engine, not \prog{pdftex}, is being used, then, this entire package contents is
+% skipped and nothing is done, except issuing a suitable warning.
+%    \begin{macrocode}
+%<*package>
+\expandafter\ifx\csname eTeXversion\endcsname\relax
+	\PackageWarning{canoniclayout}{%
+	The typesetting engine is not suited\Messagebreak
+	for working in extended mode.\Messagebreak}
+	This package is being skipped}
+	\expandafter\endinput
+\fi
+\ifnum\eTeXversion>\z@\else
+	\PackageWarning{canoniclayout}{%
+	The typesetting engine is not working in extended mode.\MessageBreak
+	This package is being skipped}
+	\expandaftter\endinput
+\fi
+%    \end{macrocode}
+% Now we can determine the page shape factor and we save it into the control sequence
+% |\CLshape|. The trick of multiplying by |p@|, a length of 1\,pt, is a simple trick for
+% reducing the shape ratio to a length whose numerical value is exactly the ratio we are
+% interested in. By stripping the `pt' part from this dimension value we remain with the
+% real number we want to keep in memory. Of course we need also the reciprocal value so
+% that we have to perform this calculation two times with different factors.
+% This ``strange'' way of computing real ratios derives from the ability of the
+% $\varepsilon$-\TeX\ engine to scale lengths with a higher computational precision than
+% ``normal'' \TeX\ can do with the standard dimension and integer operations. In facts
+% all the computational operations are performed in the CPU registers and the intermediate
+% first result of the multiplication is kept into a double length register, so that no bits
+% are rounded or truncated; the division operation is performed then with a double length
+% numerator and a single length denominator, so that, again, almost no information is lost
+% at the inevitable end of the division algorithm with a non vanishing remainder.
+%    \begin{macrocode}
+\dimen@=\dimexpr \p@ * \paperwidth / \paperheight\relax
+\edef\CLshape{\strip@pt\dimen@}
+\dimen@=\dimexpr \p@ * \p@ / \dimen@\relax
+\edef\CLinvshape{\strip@pt\dimen@}
+%    \end{macrocode}
+% We then assign the text height, thanks to the fact that the canonical layout has the
+% block height just long as the page width, due to the circle property mentioned in the
+% Introduction; in any case the formulas~\ref{equ:1}--\ref{equ:10} and
+% table~\ref{tab:canoniclayout} confirm this property for any shape.
+%    \begin{macrocode}
+\textheight=\paperwidth
+%    \end{macrocode}
+%
+% This done, we can use the internal \class{memoir} commands to determine the other layout
+% dimensions.
+%    \begin{macrocode}
+\settypeblocksize{\textheight}{*}{\CLshape}
+\setlrmargins{*}{*}{\CLinvshape}
+\setulmargins{*}{*}{\CLinvshape}
+\setmarginnotes{7pt}{\dimexpr \foremargin-3\marginparsep}{\onelineskip}
+
+%    \end{macrocode}
+%
+% We now use the |\checkandfixthelayout| so that it prints the page parameters to the
+% \file{.log} file.
+%    \begin{macrocode}
+\checkandfixthelayout
+%    \end{macrocode}
+% Just for testing the number of character in a line the following macros are provided.
+% A couple of scratch dimension registers will be used |dimen@| and |\abcwidth|; |\abcwidth|
+% will hold the current lowercase alphabet length, and |\dimen@| will hold several values
+% in succession. The scratch counter |\count254| will receive the final result to be
+% printed out. $\varepsilon$-\TeX\ arithmetics will be used throughout, but we know this
+% is possible, since we already tested it at the very beginning.
+%
+% Another service macro for the user's sake is |\charactersperpage|; this macro typesets the
+% number of characters per line, the numbers of lines per page, and eventually their product,
+% a good estimate of the number of characters per page. Many test editors have facilities for
+% counting a ``compuscript'' number o words and characters; with this further information the
+% user may easily estimate the number of pages of his/her document; of course s/he must make
+% a certain allowance for the front and back matter pages, so that s/he can evaluate the total
+% amount of signatures of the whole typeset document; of course, by typesetting it with
+% \prog{(pdf)latex} s/he knows exactly the number of pages of the final document, but the
+% typographer wants to know a good estimate before the source \TeX\ files are finished.
+%    \begin{macrocode}
+\newlength\abc@width
+\newcommand*\currentfontletters{%
+\settowidth\abc@width{abcdefghijklmnopqrstuvwxyz}\dimen0=26\p@
+\dimen0=\dimexpr \textwidth * \dimen0 / \abc@width \relax
+\count254=\numexpr \dimen0 / \p@ \relax
+\par The number of characters in one text line with the current font is
+    \the\count254.\par}
+    
+\newcommand*\charactersperpage{%
+\settowidth\abc@width{abcdefghijklmnopqrstuvwxyz}\dimen0=26\p@
+\dimen0=\dimexpr \textwidth * \dimen0 / \abc@width \relax
+\count254=\numexpr \dimen0 / \p@ \relax
+\count252=\numexpr \textheight / \onelineskip \relax
+\count250=\numexpr \count252 * \count254\relax
+\quote The number of characters in one text line with the current
+    font is \the\count254;
+    this text block contains \the\count252\ lines;
+    a rough estimate of the number of characters per page is
+    \the\count250.\par
+    This can be used to evaluate the total number of pages of
+    a document.
+\endquote}
+
+%</package>
+%    \end{macrocode}
+% \Finale
+% \endinput
+%
+