[NTG-pdftex] [ pdftex-Patches-603 ] Patch ColorStackTransformMatrix

noreply at sarovar.org noreply at sarovar.org
Tue Oct 17 15:08:27 CEST 2006


Patches item #603, was opened at 2006-09-07 10:35
You can respond by visiting: 
http://sarovar.org/tracker/?func=detail&atid=495&aid=603&group_id=106

Category: Primitives
Group: v1.40.0
Status: Open
>Resolution: Accepted
Priority: 8
Submitted By: Heiko Oberdiek (oberdiek)
Assigned to: Martin Schröder (oneiros)
Summary: Patch ColorStackTransformMatrix

Initial Comment:
Subject: Patch ColorStackTransformMatrix
Date: 2006/09/07
Author: Heiko Oberdiek

The patch is based on pdftex-1.40.0-beta-20060906

It tries to solve two FAQ problems:
* missing color stack
* wrong annotation rectangles (links, anchors)
  if the material was scaled or rotated.

Files:
  ColorStackTransformMatrix.patch
    The patch, apply it in src/texk/web2c/pdftexdir:
    patch <ColorStackTransformMatrix.patch
  pdftex.def
    A modified version that uses the patch if the
    new primitives are found.

A short test file:

\documentclass{article}
\usepackage{color}
\usepackage{pdflscape}
\usepackage{hyperref}
\begin{document}
\tableofcontents
\section{Hello World}
\label{sec:hello}
\textcolor{blue}{Blue\newpage Blue}
\begin{landscape}
See \autoref{sec:hello}.
\end{landscape}
\end{document}

Without the patch:
* Text on first page before "Blue" is blue instead of
black.
* Text on second page is black instead of blue.
* The link frame on page three is misplaced.
With the patch and modified pdftex.def these things are
fixed.

New commands
  % color stack
    * \pdfcolorstackinit
    * \pdfcolorstack
  % matrix transformations
    * \pdfsetmatrix
    * \pdfsave
    * \pdfrestore

Syntax:

  %% expandable commands:
  \pdfcolorstackinit [page] [direct] <general text>

  %% general commands:
  \pdfcolorstack <stack number> <stack action> <general
text>
  \pdfsetmatrix
  \pdfsave
  \pdfrestore

  <stack action> ::= set | push | pop | current
Description for color stack:

  This color stack implementation allows several
  independent stacks (upto 32686):
  * Stacks can be used for other properties than color,
    especially other graphics state parameters.
  * Several "text flows across pages" can be supported
    by color stacks.
    Example: footnotes.

  \pdfcolorstackinit [page] [direct] {<initial value>}
    A stack is initialized by \pdfcolorstackinit. It
    expands to the number of the new stack. The common
    case, the traditinal color stack is already
    initialized as first stack:
      \pdfcolorstackinit page direct {0 g 0 G}
    The keyword "page" means, that this stack is page
    based. At the start of the new page, the current
    stack value is automatically set:
      \textcolor{blue}{A\newpage B}
    The second page with "B" will start with blue
    setting.
    The keyword "direct" has the same meaning as
    "direct" for \pdfliteral.
    If the stack value is set, it is done by an
    equivalent of
      \pdfliteral direct {...}.
    The mandatory argument is the initial value on the
    stack. It should be the default at page start for
    the property, see PDF documentation.

  \pdfcolorstack <stack number> push {<new color>}
    pushes the current value on the stack and sets the
    <new color>.
  \pdfcolorstack <stack number> pop
    pops and sets the current stack value.
  \pdfcolorstack <stack number> current   
    sets the current stack value without changing the
    stack. This is useful for stacks that are
    initialized without keyword "page".
    Thus the page start setting can be set manually.
  \pdfcolorstack <stack number> set {<new color>}   
    The current value is set to <new color>.

  Example (changed pdftex.def):

  \chardef\GPT at colorstack=0 %
  \def\set at color{%
    \pdfcolorstack\GPT at colorstack push{\current at color}%
    \aftergroup\reset at color
  }%
  \def\reset at color{%
    \pdfcolorstack\GPT at colorstack pop\relax
  }%

  If someone wants to add color stack support for
  footnotes, the principle would be:
    \edef\stackfootnote{\pdfcolorstackinit direct{0 g 0
G}}%
    % Then at begin of the footnote area on the page:
    \pdfcolorstack\stackfoonote current\relax
    % During footnote processing the footnote stack is
used:
    \let\GPT at colorstack\stackfoonote

Description for matrix transformations:

  Currently matrix changes are done and hidden inside
  \pdfliteral nodes; pdfTeX doesn't parse its contents
  and does not know the new settings of the transform
  matrix. Thus the patch adds new primitives to save
  pdfTeX from parsing \pdfliteral contents and to
  notify pdfTeX about matrix changes to use them in
  calculating link and anchor positions.

  \pdfsetmatrix{<a> <b> <c> <d>}
    is the equivalent to
    \pdfliteral{<a> <b> <c> <d> 0 0 cm}
  \pdfsave
    is the equivalent to \pdfliteral{q}
  \pdfrestore
    is the equivalent to \pdfliteral{Q}

  Some remarks:
  * TeX already supports translations, thus the matrix
    is limited to four values for scaling and rotating.
  * There are some restrictions about \pdfsave and
    \pdfrestore:
    * They must be properly nested.
    * A pair must start and end in the same group at
      the same level.
    * A pair must start and end at the same position.
    Happily these restrictions are satisfied by the
    graphics package.

  Example (changed pdftex.def):
    \def\Grot at start{%
      \pdfsave
      \pdfsetmatrix{%
        \Grot at cos\space\Grot at sin\space
        \if-\Grot at sin\else-\Grot at sin\fi\space\Grot at cos
      }%
      \wd\z@\z@
    }%
    \def\Grot at end{\pdfrestore}
    \def\Gscale at start{%
      \pdfsave
      \pdfsetmatrix{%
        \Gscale at x\space0 0 \Gscale at y
      }%
    }%  

Have fun
  Heiko <oberdiek at uni-freiburg.de>


----------------------------------------------------------------------

>Comment By: Martin Schröder (oneiros)
Date: 2006-10-17 15:08

Message:
Logged In: YES 
user_id=421

I still get the warning in utils.c :-{

Can you update the pdfTeX manual on this?

----------------------------------------------------------------------

Comment By: Heiko Oberdiek (oberdiek)
Date: 2006-09-12 16:38

Message:
Logged In: YES 
user_id=1276

| Two questions come to mind:
| - how does this patch interact with existing documents,

The design principle is that the patch does not have an
effect if the new primitives are not used (modulo bugs).

| i.e.
| what must be changed when using this patch? Obviously the
| use of \pdfliteral must be checked. Anything else?

LaTeX's color/graphics: pdftex.def that support the
new primitives.

| - does this collide with pdftex's use of the cm? The only
| use of the transformation matrix by pdftex I could find
| concerns magnifications, so that's most likely not a 
| problem.

I had played a little with magnification, but not too
intensively.

| Btw: gcc with -Wall -std=c99 gives this warning:
| ../../../../src/texk/web2c/pdftexdir/utils.c: In function
| ‘newcolorstack’:
| ../../../../src/texk/web2c/pdftexdir/utils.c:1366: 
| warning:
| operation on ‘colstacks’ may be undefined

Assignments to colstacks are controlled by colstack_size,
thus the warnung can be gnored. To avoid the warning
replace
  static colstack_type *colstacks;
by
  static colstack_type *colstacks = NULL;

Yours sincerely
  Heiko <oberdiek at uni-freiburg.de>

----------------------------------------------------------------------

Comment By: Martin Schröder (oneiros)
Date: 2006-09-12 16:06

Message:
Logged In: YES 
user_id=421

Heiko,
thank you very much for your patch. 

Two questions come to mind:
- how does this patch interact with existing documents, i.e.
what must be changed when using this patch? Obviously the
use of \pdfliteral must be checked. Anything else?
- does this collide with pdftex's use of the cm? The only
use of the transformation matrix by pdftex I could find
concerns magnifications, so that's most likely not a problem.

Btw: gcc with -Wall -std=c99 gives this warning:
../../../../src/texk/web2c/pdftexdir/utils.c: In function
‘newcolorstack’:
../../../../src/texk/web2c/pdftexdir/utils.c:1366: warning:
operation on ‘colstacks’ may be undefined

----------------------------------------------------------------------

You can respond by visiting: 
http://sarovar.org/tracker/?func=detail&atid=495&aid=603&group_id=106


More information about the ntg-pdftex mailing list