path: root/Master/texmf-dist/source/latex/gridset/gridset.dtx

% \CheckSum{416}
% \iffalse meta-comment
%
% gridset.dtx
%
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3
%% of this license or (at your option) any later version.
%% The latest version of this license is in
%% http://www.latex-project.org/lppl.txt
%% and version 1.3 or later is part of all distributions of LaTeX
%% version 2003/12/01 or later.
%%
%% This work has the LPPL maintenance status "maintained".
%%
%% The author of the initial version of these work was
%% Markus Kohm <komascript@gmx.info>
%%
%% This work consists of the files gridset.dtx and README.
%%
%% Important Recommendation:
%%   The LPPL requires that distributions of the Work contain all the files of
%%   the Work (see ``Important Recommendations'' at lppl.txt).
%%
%
%<*dtx>
\def\FmtName{LaTeX2e}
\ifx\FmtName\fmtname
  % Give me the package or the documentation
  \ifnum \catcode`\@=12\relax
    % Give me the documentation
    \ProvidesFile{gridset.dtx}
%</dtx>
%<*dtx|tex|package|example>
%<package>\ProvidesPackage{gridset}
%<tex>\ProvidesFile{gridset.tex}
%<example>\ProvidesFile{gridsetexample.tex}
                 [2008/11/12 v0.1 grid - aka in-register - setting]
%</dtx|tex|package|example>
%<*dtx|tex>
    \documentclass{ltxdoc}
    \begin{document}
    \RecordChanges
%<*!tex>
    \GetFileInfo{gridset.dtx}
%</!tex>
%<tex>    \GetFileInfo{gridset.tex}
    \DocInput{gridset.dtx}
%<tex>\end{document}
%</dtx|tex>
%<*dtx>
    \expandafter\expandafter\expandafter\enddocument
  \fi
\else
  % Make the package
  \def\batchfile{gridset.dtx}
  \let\batchendinput\endinput
%</dtx>
%<*ins>
%<ins>\def\batchfile{gridset.ins}
  \input docstrip.tex

  \ifToplevel{%
    \let\ifalpha\iffalse
  }
  \keepsilent
  \askforoverwritefalse
  \usedir{tex/latex/gridset}
  \preamble
Copyright (c) Markus Kohm 2008

IMPORTANT NOTE:

This is a generated file and you are not allowed to distribute it
without the source ot the work.  See below about more informations
about the files the work consists of.

\endpreamble

  \generate{%
    \file{gridset.tex}{\from{gridset.dtx}{tex}}%
    \file{gridset.ins}{\from{gridset.dtx}{ins}}%
    \file{gridsetx.sty}{\from{gridset.dtx}{package}}%
    \file{gridsetexample.tex}{\from{gridset.dtx}{example}}%
  }

  \ifToplevel{%
    \Msg{*********************************************************************}
    \Msg{*}
    \Msg{* gridset}
    \Msg{* =======}
    \Msg{*}
    \ifalpha% ALPHA
      \Msg{* THIS IS AN ALPHA VERSION!}
      \Msg{* DON'T USE IT ONLY TEST IT!}
      \Msg{*}
    \fi
    \Msg{* To finish the installation run}
    \Msg{* \space\space latex gridset.dtx}
    \Msg{* or}
    \Msg{* \space\space pdflatex gridset.dtx}
    \Msg{* and then copy}
    \Msg{* \space\space gridset.sty to .../tex/latex/gridset/}
    \Msg{* \space\space gridset.dvi or gridset.pdf to .../doc/latex/gridset/}
    \Msg{* \space\space gridset.dtx and README to .../source/latex/gridset/}
    \Msg{* where .../ is your local TDS tree.}
    \Msg{* On some systems you'll get the local TDS tree using:}
    \Msg{* \space\space kpsewhich -var-value=TEXMFLOCAL}
    \Msg{*}
    \Msg{*********************************************************************}
%<*!ins>
    \csname fi\endcsname\csname fi\endcsname\endinput
%</!ins>
  }

%</ins>
%<*dtx>
\fi
\csname batchendinput\endcsname
%</dtx>
% \fi ^^A meta-comment
%
% \title{Semi-Manual Grid Setting Using \textsf{gridset}\iftrue^^A ALPHA
%   \footnote{This is an alpha version! Don't use it! Only test it! There's no
%     support and everything may change!}\fi
% }
% \author{Markus Kohm}
% \date{\filedate~\fileversion}
% \maketitle
% \begin{abstract}
%   Grid setting\,---\,also known as strict in-register setting\,---\,is
%   something, that should be done for a lot of documents but is not easy
%   using \LaTeX{}.  Package \textsf{gridset} helps to get the information
%   needed for grid setting.  It does not implement auto grid setting, but
%   there is a command \cs{vskipnextgrid}, that moves to the next grid
%   position.  This may be enough under some circumstances.  In other
%   circumstances it may fail.  So \textsf{gridset} is only one more step for
%   grid setting not a complete solution.
% \end{abstract}
% \tableofcontents
% \section{User Manual}
%
% \DescribeMacro{\gridinterval}%
% This macro contains a number without unit!  The number is the distance
% between two grid lines in unit `scale points' (sp).  You may set it so
% another value using, e.g.
% \begin{flushleft}
%  |\newlength{\|\meta{name of your length}|}|\\
%  |\setlength{\|\meta{name of your length}|}{|\meta{new length value}|}|\\
%  |\newcounter{\|\meta{name of your counter}|}|\\
%  |\setcounter{\|\meta{name of your counter}|}{\|\meta{name of your
%        length}|}|\\
%  |\edef\gridinterval{\|\meta{name of your length}|}|\\
% \end{flushleft}
%
% \DescribeMacro{\gridbase}%
% This macro contains an integer number, that represents the y-coordinate of
% the upper start of the grid.  If you want to change it, just save a position
% and \cs{edef} the \cs{gridbase} to the y-pos of that position.
%
% Most time you don't need to change \cs{gridinterval} and \cs{gridposition},
% because they are initialized to a base line grid at start of first page.
% Because of this, it doesn't matter, that changing them is not really user
% friendly.
%
% \DescribeMacro{\savepos}%
% \cs{savepos}\marg{unique name} saves informations about the current position
% to the \texttt{aux}-file.  These informations are read at next \LaTeX{} run
% and may be used (see \cs{the\dots} commands below) then. The \meta{unique
% name} has to be a position name, that is unique for all saved position
% informations of the current document.
%
% \DescribeMacro{\vskipnextgrid}
% This command moves to the next grid position.  To achieve this, a position
% information is saved at this and used at next \LaTeX{} run.  The used name
% of the position information is \texttt{vb!\meta{number of
% skip}}. \meta{number of skip} is the number of the current
% \cs{vskipnextgrid} usage.  Counter \texttt{gridcnt} is used to number the
% usage of \cs{vskipnextgrid}.
%
% \DescribeMacro{\thegridinfo}
% \cs{thegridinfo}\marg{name} outputs
% \begin{itemize}
% \item arabic page number of the named position,
% \item grid base, that was valid saving the information of the named
%   position,
% \item grid interval, that was valid saving the information of the named
%   position,
% \item x-coordinate of the named position,
% \item y-coordinate of the named position.
% \end{itemize}
% The coordinates and intervals are numbers without units.  The unit is `scale
% points' (sp).
%
% \DescribeMacro{\theposinfo}
% \cs{theposinfo}\marg{name} outputs
% \begin{itemize}
% \item y-coordinate of the named position,
% \item grid line number (first is 0) of the next grid position,
% \item offset of the next grid position from grid base,
% \item distance to the next grid position.
% \end{itemize}
% The coordinates, offsets and distances are numbers without units.  The unit
% is `scale points' (sp).
%
% \DescribeMacro{\theypos}
% \cs{theypos}\marg{name} outputs the y-coordinate of the named position.
%
%
% \StopEventually{\PrintIndex\PrintChanges}
%
% \section{Implementation}
%
% \iffalse meta-comment
%<*package>
% \fi ^^A meta-comment
%    \begin{macrocode}
%<package>\ProvidesPackage{gridset}[\fileversion\space (package)]
%    \end{macrocode}
%
% \begin{macro}{\gridbase}
% \begin{macro}{\gridinterval}
%   These contain the grid information.  \cs{gridbase} is a integer number
%   representing the absolute y coordinate of the upper end of the
%   grid relative to the same reference point \cs{pdfsavepos}
%   uses.  \cs{gridinterval} is a integer number representing the distance of
%   two grid lines.  The unit is `scaled point' (sp) both time.
%    \begin{macrocode}
\newcommand*{\gridbase}{}
\newcommand*{\gridinterval}{}
%    \end{macrocode}
%   \cs{gridbase} and \cs{gridinterval} need to be initialized at the start of
%   the first page (fixme: shouldn't this be done at the start of every
%   page?).  We use this occasion to also initialize \cs{pdfpageheight} and
%   \cs{pdfpagewidth} if this hasn't been done already.
%    \begin{macrocode}
\AtBeginDocument{%
  \ifdim\pdfpageheight=\z@
    \pdfpageheight=\pageheight
  \fi
  \ifdim\pdfpagewidth=\z@
    \pdfpagewidth=\pagewidth
  \fi
  \begingroup
    \@tempdima=\dimexpr \pdfpageheight - \topmargin - 1in 
                      - \headheight - \headsep 
                      - \topskip \relax
    \@tempcnta=\@tempdima
    \xdef\gridbase{\the\@tempcnta}%
    \@tempcnta=\baselineskip
    \xdef\gridinterval{\the\@tempcnta}%
  \endgroup
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\savepos}
%   Save current position on the page to the \texttt{aux}-file.  The argument
%   is a unique name for the position.  The saved informations are:
%   \begin{itemize}
%   \item the name of the position,
%   \item the arabic page number of the page with the position,
%   \item the grid base, that was valid for this position,
%   \item the grid interval, that was valid for this position,
%   \item the x-coordinate of the absolute position,
%   \item the y-coordinate of the absolute position.
%   \end{itemize}
%    \begin{macrocode}
\newcommand*{\savepos}[1]{%
  \begingroup
    \pdfsavepos
    \protected@write\@auxout{}{%
      \protect\newpos{#1}{\the\count\z@}{\gridbase}{\gridinterval}{%
        \noexpand\number\pdflastxpos
      }{%
        \noexpand\number\pdflastypos
      }%
    }%
  \endgroup
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\newpos}
%   This is the command, that has been written to the \texttt{aux}-file.
%   Reading the \texttt{aux}-file it defines several position dependant macros
%   to store the position information.  Reading the \texttt{aux}-file while
%   \cs{begin{document}} a double definition test is done.  Reading the
%   \texttt{aux}-file while \cs{end{document}} a test is done, if the position
%   has been changed and notes the user about needed additional \LaTeX{} runs.
%   (fixme: shouldn't the test be done with the x- and the y-coordinate
%   instead of the vskip only?)
%   The defined macros are:
%   \begin{description}
%   \item[\cs{pos@\meta{position name}@page}] the arabic page number of the
%     position
%   \item[\cs{pos@\meta{position name}@base}] the valid grid base while
%     saving the position
%   \item[\cs{pos@\meta{position name}@interval}] the valid grid interval
%     while saving the position
%   \item[\cs{pos@\meta{position name}@x}] the x-coordinate of the position
%   \item[\cs{pos@\meta{position name}@y}] the y-coordinate of the postion
%   \item[\cs{pos@\meta{position name}@line}] the number of the next grid line
%     for the position (first grid line has number 0)
%   \item[\cs{pos@\meta{position name}@offset}] distance of the next grid line
%     from the grid base
%   \item[\cs{pos@\meta{position name}@vskip}] distance to the next grid line
%     for the position
%   \end{description}
%   All values are integers. The unit to all values is `scaled points'
%   (sp). See \cs{pdfsavepos} at the pdf\TeX{} user manual for more
%   information.
%    \begin{macrocode}
\newcommand*{\newpos}[6]{%
  \grid@unique@test{#1}{#2}%
  \expandafter\global\@namedef{pos@#1@page}{#2}%
  \expandafter\global\@namedef{pos@#1@base}{#3}%
  \expandafter\global\@namedef{pos@#1@interval}{#4}%
  \expandafter\global\@namedef{pos@#1@x}{#5}%
  \expandafter\global\@namedef{pos@#1@y}{#6}%
  \begingroup
    \@tempcnta=\numexpr \@nameuse{pos@#1@base} - \@nameuse{pos@#1@y}\relax
    \@tempcnta=\numexpr \@tempcnta + \@nameuse{pos@#1@interval} - 1\relax
    \divide\@tempcnta by\@nameuse{pos@#1@interval}\relax
    \expandafter\xdef\csname pos@#1@line\endcsname{\the\@tempcnta}%
    \@tempcnta=\numexpr \@tempcnta * \@nameuse{pos@#1@interval}\relax
    \expandafter\xdef\csname pos@#1@offset\endcsname{\the\@tempcnta}%
    \@tempcnta=\numexpr \@nameuse{pos@#1@y} 
                      - ( \@nameuse{pos@#1@base} - \@tempcnta )\relax
    \expandafter\let\expandafter\@tempa\csname pos@#1@vskip\endcsname%
    \expandafter\xdef\csname pos@#1@vskip\endcsname{\the\@tempcnta}%
    \expandafter\ifx\csname pos@#1@vskip\endcsname\@tempa\else
      \grid@ReRunMessage
    \fi
  \endgroup
}
%    \end{macrocode}
% \begin{macro}{\grid@unique@test}
%   A very simple test to warn if a position name isn't unique.
%    \begin{macrocode}
\newcommand*{\grid@unique@test}[2]{%
  \expandafter\ifx\csname pos@#1@page\endcsname\relax\else
    \PackageError{gridset}{position `#1' is not unique.\@gobble}{%
      You have used the position name `#1' you are using on page
      `#2'\MessageBreak
      already on page `\csname pos@#1@page\endcsname'.\MessageBreak
      You should stop processing, remove the aux-files and correct the
      names.\MessageBreak
      If you'd continue, this will result in grid position
      failures,\MessageBreak
      that won't be reported!}%
  \fi
}
\AtBeginDocument{%
  \global\let\grid@unique@test\@gobble
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\grid@ReRunMessage}
%   The change test will be done for each \cs{newpos} but one user information
%   at the end of the document should be enough.  So we use a message macro,
%   that destroys itself after first usage.
%    \begin{macrocode}
\newcommand*\grid@ReRunMessage{}
\AtBeginDocument{%
  \renewcommand*\grid@ReRunMessage{%
    \PackageWarningNoLine{gridset}{Grid position labels may have
      changed.\MessageBreak
      Rerun to get grid positions right}%
    \global\let\grid@ReRunMessage\relax
  }%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\vskipnextgrid}
% \begin{macro}{gridcnt}
%   Move to next grid position.  The counter \texttt{gridcnt} is used to give
%   every move to position a unique position name.  The names are
%   `\texttt{vp!\meta{number of the move to position}}'.  You may use this to
%   get informations e.g. about the last move to position.
%    \begin{macrocode}
\newcounter{gridcnt}
\newcommand*{\vskipnextgrid}{%
  \begingroup
    \stepcounter{gridcnt}\edef\@tempa{vp!\thegridcnt}%
    \ifvmode
%    \end{macrocode}
%   \cs{pdfsavepos} in vertical mode is a problem, because the base line
%   alignment will be done at least at paragraph breaking.  Because of this,
%   we have to leave the vertical mode and do it then.  But remark: If you
%   change the base line skip e.g. changing the font size, the next line would
%   not be grid aligned!
%    \begin{macrocode}
      \leavevmode\savepos{\@tempa}%
      \expandafter\ifx\csname pos@\@tempa @vskip\endcsname\relax
      \else
        \expandafter\ifnum \csname pos@\@tempa @vskip\endcsname =\z@\else
          \PackageInfo{gridset}{%
            vmode \string\vskip\csname pos@\@tempa @vskip\endcsname sp%
          }%
          \vskip -\parskip\vskip -\baselineskip
          \expandafter\vskip\csname pos@\@tempa @vskip\endcsname sp\relax
        \fi
      \fi
    \else
%    \end{macrocode}
%   \cs{pdfsavepos} in horizontal mode is a problem too, because we have to
%   enter the vertical mode to do vertical skips. Because of this, the remark
%   is  the same like the vertical mode remark.
%    \begin{macrocode}
      \parskip=\z@
      \savepos{vp!\thegridcnt}%
      \expandafter\ifx\csname pos@\@tempa @vskip\endcsname\relax
      \else
        \expandafter\ifnum \csname pos@\@tempa @vskip\endcsname =\z@\else
         \PackageInfo{gridset}{%
            hmode \string\vskip\csname pos@\@tempa @vskip\endcsname sp%
          }%
          \vskip -\baselineskip
          \expandafter\vskip\csname pos@\@tempa @vskip\endcsname sp\relax
          \if@twoside
            \expandafter\ifodd\csname pos@\@tempa @page\endcsname\relax
              \leavevmode\hskip \dimexpr - 1in - \oddsidemargin - \parindent
                              + \csname pos@\@tempa @x\endcsname sp\relax
            \else
              \leavevmode\hskip \dimexpr - 1in - \evensidemargin - \parindent
                              + \csname pos@\@tempa @x\endcsname sp\relax
            \fi
          \else
            \leavevmode\hskip \dimexpr - 1in - \oddsidemargin - \parindent 
                            + \csname pos@\@tempa @x\endcsname sp\relax
          \fi
        \fi
      \fi
    \fi
  \endgroup
}
%    \end{macrocode}
%   (fixme: A better solution would be to first move and then set the
%   position.  But that solution needs some more tests and maybe some more
%   ideas, because after moving the position is on grid and so the saved x-pos
%   would be on grid.)
% \end{macro}
% \end{macro}
%
% \begin{macro}{\thegridinfo}
% \begin{macro}{\theposinfo}
% \begin{macro}{\theypos}
% Some informations about the grid (valid for a position) or the position.
%    \begin{macrocode}
\newcommand*{\thegridinfo}[1]{%
  page=\@nameuse{pos@#1@page},
  base=\@nameuse{pos@#1@base},
  interval=\@nameuse{pos@#1@interval},
  x=\@nameuse{pos@#1@x},
  y=\@nameuse{pos@#1@y}%
}
\newcommand*{\theposinfo}[1]{%
  y=\@nameuse{pos@#1@y},
  gridline=\@nameuse{pos@#1@line},
  gridoffset=\@nameuse{pos@#1@offset},
  movedown=\@nameuse{pos@#1@vskip}%
}
\newcommand*{\theypos}[1]{\@nameuse{pos@#1@y}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \iffalse meta-comment
%<*FALSE>
\csname endinput\endcsname
%</FALSE>
%</package>
% \fi ^^A meta-comment
%
% \section{Example}
%
% You may try the following example document.  You have to do several \LaTeX{}
% runs until no new rerun warning occurs.
% \iffalse meta-comment
%<*example>
% \fi ^^A meta-comment
%    \begin{macrocode}
\documentclass[a4paper,12pt]{article}
\usepackage{gridset}
\usepackage{blindtext}
\raggedbottom

\pagestyle{myheadings}

\begin{document}
\markright{gridbase=\gridbase, gridinterval=\gridinterval\ without move down}%
\newcounter{Zeile}%
\makeatletter
\@whilenum \value{Zeile}<40\do {%
  \stepcounter{Zeile}%
  \theZeile. Zeile:
  \savepos{\thepage.\theZeile}\thegridinfo{\thepage.\theZeile}\par
}%
\makeatother
\clearpage
\setcounter{Zeile}{0}
\makeatletter
\@whilenum \value{Zeile}<20\do {%
  \stepcounter{Zeile}%
  \theZeile. Zeile:
  \savepos{\thepage.\theZeile}\theposinfo{\thepage.\theZeile}\par 
}%
\makeatother
\clearpage
\parskip=.5\baselineskip
\setcounter{Zeile}{0}
\makeatletter
\@whilenum \value{Zeile}<20\do {%
  \stepcounter{Zeile}%
  \theZeile. Zeile:
  \savepos{\thepage.\theZeile}\theposinfo{\thepage.\theZeile}\par 
}%
\makeatother
\clearpage
\markright{gridbase=\gridbase, gridinterval=\gridinterval\ with real move down
at vmode}%
\parskip=.5\baselineskip
\setcounter{Zeile}{0}
\makeatletter
\@whilenum \value{Zeile}<25\do {%
  \stepcounter{Zeile}%
  \vskipnextgrid\theZeile. Zeile: \theposinfo{vp!\thegridcnt}\par
}%
\makeatother
\clearpage
\markright{gridbase=\gridbase, gridinterval=\gridinterval\ with real move down
at hmode}%
\parskip=.5\baselineskip
\setcounter{Zeile}{0}
\makeatletter
\@whilenum \value{Zeile}<25\do {%
  \stepcounter{Zeile}%
  \theZeile. Zeile: \vskipnextgrid\theposinfo{vp!\thegridcnt}\par
}%
\makeatother
\clearpage
\parskip=0pt
\blindtext
\begin{itemize}
\item Test
\item Test
\end{itemize}
\vskipnextgrid\theposinfo{vp!\thegridcnt}\blindtext

\end{document}
%    \end{macrocode}
% \iffalse meta-comment
%</example>
% \fi ^^A meta-comment
%
% \Finale
%
\endinput
%
% end of `gridset.dtx'
%
% \iffalse meta-comment
%%% Local Variables:
%%% mode: docTeX
%%% TeX-master: t
%%% End:
% \fi ^^A meta-comment