diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/asyfig/asyfig.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/asyfig/asyfig.tex | 466 |
1 files changed, 466 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/asyfig/asyfig.tex b/Master/texmf-dist/doc/latex/asyfig/asyfig.tex new file mode 100644 index 00000000000..f18c8eda5e5 --- /dev/null +++ b/Master/texmf-dist/doc/latex/asyfig/asyfig.tex @@ -0,0 +1,466 @@ +\RequirePackage{filecontents} +\begin{filecontents*}{README.txt} +__________________ +The ASYFIG package + +This package provides an alternative to the asymptote package for including Asymptote graphics in a LaTeX document. In this package, all Asymptote figures are defined separately from the source in their own individual ".asy" files. This package uses Asymptote's inline mode so that labels in the graphics are produced by the main typesetting run; this ensures consistent font and size selection of text within the graphics. In addition, each individual ".asy" graphic can be very quickly processed individually to facilitate easy maintenance and editing of the graphics. + +____________ +INSTALLATION + +Run `latex` on asyfig.tex to produce the files + asyfig.ins, asyfig.sty, asyalign.sty, asyprocess.sty, and README.txt, +as well as to compile the PDF documentation. + +Execute `tex pstool.ins` to produce the files above +except pstool.ins (and the PDF file, obviously). + +___________ +MAINTENANCE + +Please report bugs or request features: + <http://github.com/wspr/asyfig/issues> + +Developmental and historical versions: + <http://github.com/wspr/asyfig> + +Current release version: + <http://ctan.tug.org/pkg/asyfig> + +______________ +Will Robertson +Copyright 2008-2009 +\end{filecontents*} +%%%%%%%%%1%%%%%%%%%2%%%%%%%%%3%%%%%%%%%4%%%%%%%%%5 + +\begin{filecontents}{asyfig.sty} +\ProvidesPackage{asyfig}[2009/06/23 v0.1a + Commands for using asymptote figures] + +% This package is the main user interface for inserting external |asy| figures +% into the document. + +\RequirePackage{% + asyalign,color,ifmtarg,ifpdf,ifplatform,import, + graphicx,pdftexcmds,suffix,xkeyval} + +% Better conditionals than |\newif| provides: +\def\@True{11} +\def\@False{01} +\def\asy@If#1{\if#1\relax\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi} + +\let\asy@always\@False +\let\asy@never\@False +\let\asy@process\@False + +% Package options: +\define@choicekey*{asyfig.sty}{process}[\@tempa\@tempb]{all,none,auto}{% + \ifcase\@tempb\relax + \let\asy@always\@True + \or + \let\asy@never\@True + \or + \fi +} +\ExecuteOptions{process=auto} + +\ProcessOptionsX + +% \subsection{Auxiliary macros} + +\def\asy@splitpath#1/#2/{% +% Recursive macro that is used like\\ +% \qquad |\asy@splitpath abc/def/ghi.asy/\@nil/|\\ +% It defines |\asy@filename| $\to$ |ghi.asy| and |\asy@path| $\to$ |abc/def/| + \ifx\@nil#2\relax +% If input is \<anything>|/\@nil/| then we've reached the end: + \def\asy@filename{#1}% + \else +% Otherwise we're in the middle of the slash-separated list; +% build up |\asy@path|, and iterate: + \edef\asy@path{\asy@path#1/}% + \def\@tempa{\asy@splitpath#2/}% + \expandafter\@tempa + \fi +} + +\newcommand\asypath[1]{\def\asy@pathprefix{#1}} +\asypath{} + +\def\asy@asyfile{\asy@pathprefix\asy@path\asy@filename.asy} +\def\asy@texfile{\asy@pathprefix\asy@path\asy@filename\string_.tex} + +\def\asy@cmdsep{\ifwindows \string& \else; \fi} + +% \subsection{The main macro} + +\newcommand\asyfig[1]{% + \let\asy@path\@empty + \asy@splitpath #1/\@nil/% + \IfFileExists{\asy@asyfile}{% + \asy@If\asy@process{}{% + \asy@If\asy@always{% + \let\asy@process\@True + }{% + \IfFileExists{\asy@texfile}{% + \asy@If\asy@never{}{% + % compare file dates to see if we want to reprocess: + \ifnum\pdf@strcmp{\pdf@filemoddate{\asy@texfile}} + {\pdf@filemoddate{\asy@asyfile}} < \z@ + \let\asy@process\@True + \fi + }% + }{% if the .tex file doesn't exist, either + % give an error or process the .asy file: + \asy@If\asy@never{% + \PackageError{asyfig}{% + ^^J\space\space\space\space + "\asy@pathprefix\asy@path\asy@filename.asy" requires processing% + }{% + The generated file that is required to insert the asy graphic, + ^^J\space\space\space\space + "\asy@pathprefix\asy@path\asy@filename\string_.tex"^^J% + does not exist. + Please process the asy figure manually or de-activate the^^J% + [process=none] package option. + }% + }{% + \let\asy@process\@True + } + }% + }}% + \asy@If\asy@process{% + \edef\@tempa{\asy@pathprefix\asy@path}% + \pdf@system{% + echo "^^J====== ASY PROCESS =====^^J" + \asy@cmdsep + \ifx\@tempa\@empty\else + cd \@tempa + \asy@cmdsep + \fi + \ifpdf pdf\fi latex + -shell-escape + -interaction=batchmode + -jobname=\asy@filename-comp + \unexpanded{% + "\RequirePackage{asyprocess}\ProcessAsy + \documentclass{article} + \begin{document}\ShowAsy + \end{document}" + }% + \asy@cmdsep + echo "^^J==== ASY END PROCESS ===^^J" + }% + }{}% + \import{\asy@pathprefix\asy@path}{\asy@filename\string_.tex}% + }{% + \PackageWarning{asyfig}{% + ^^J\space\space + "\asy@pathprefix\asy@path\asy@filename.asy" not found.^^J% + This warning occurred% + }% + }% + \let\asy@process\@False +} + +% The starred version of \cmd\asyfig\ processes the graphic always: +\WithSuffix\newcommand\asyfig*[1]{% + \begingroup + \let\asy@process\@True + \csname\NoSuffixName\asyfig\endcsname{#1}% + \endgroup +} + +\end{filecontents} +%%%%%%%%%1%%%%%%%%%2%%%%%%%%%3%%%%%%%%%4%%%%%%%%%5 + + + + +\begin{filecontents}{asyalign.sty} +\ProvidesPackage{asyalign} + +% This package provides code for placing Asymptote labels inline in \LaTeX\ documents. It is adapted from code that is usually included within Aymptote's \<filename>|_.pre| file, which provides a \LaTeX\ preamble for |asy| processing; this preamble is skipped with the \pkg{asyfig} package since all figures inherit the preamble from that of the main document. + +\RequirePackage{ifpdf} + +\newbox\ASYbox +\newdimen\ASYdimen + +\def\ASYbase#1#2{% + \setbox\ASYbox=\hbox{#1}% + \ASYdimen=\ht\ASYbox + \setbox\ASYbox=\hbox{#2}% + \lower\ASYdimen\box\ASYbox} + +\ifpdf + \def\ASYalign(#1,#2)(#3,#4)#5#6{% + \leavevmode + \setbox\ASYbox=\hbox{#6}% + \setbox\ASYbox\hbox{% + \kern#3\wd\ASYbox + \raise#4\dimexpr\ht\ASYbox+\dp\ASYbox\relax\box\ASYbox}% + \put(#1,#2){% + \special{pdf:q #5 0 0 cm}% + \wd\ASYbox\z@\dp\ASYbox\z@\ht\ASYbox\z@ + \box\ASYbox + \special{pdf:Q}% + }} + \let\ASYraw\@firstofone + +\else + \def\ASYalign(#1,#2)(#3,#4)#5#6{% + \leavevmode + \setbox\ASYbox=\hbox{#6}% + \setbox\ASYbox\hbox{% + \kern#3\wd\ASYbox + \raise#4\dimexpr\ht\ASYbox+\dp\ASYbox\relax\box\ASYbox}% + \put(#1,#2){% + \special{% + ps:gsave currentpoint currentpoint translate + [#5 0 0] concat neg exch neg exch translate}% + \box\ASYbox + \special{ps:currentpoint grestore moveto}% + }} + \def\ASYraw#1{% + currentpoint currentpoint translate matrix currentmatrix + 100 12 div -100 12 div scale + #1 + setmatrix neg exch neg exch translate} +\fi + +\end{filecontents} +%%%%%%%%%1%%%%%%%%%2%%%%%%%%%3%%%%%%%%%4%%%%%%%%%5 + +\begin{filecontents}{asyprocess.sty} +\ProvidesPackage{asyprocess} +\nofiles + +\RequirePackage{ifmtarg,ifpdf,catchfile,ifplatform,color,graphicx} +\RequirePackage[active,tightpage]{preview} + +\def\@par@macro{\par} + +\def\asy@status{asyprocess-statusfile.txt} + +\edef\@tempa{\detokenize{-comp}} +\@temptokena{\def\asy@strip@comp#1} +\expandafter\the\expandafter\@temptokena\@tempa#2\@nil{% + \@ifmtarg{#2}{% + \errorstopmode + \PackageError{asyprocess}{% + The \string\jobname\space of this compilation must end with `-comp'% + }{% + You must set the \cmd\jobname\ with the equivalent of^^J\space\space + pdflatex -jobname=XYZ-comp ...% + } + }{}% + \edef\asy@compname{#1}} +\expandafter\expandafter\expandafter + \asy@strip@comp\expandafter\jobname\@tempa\@nil + +\newcommand\ProcessAsy{% + \immediate\write18{% + asy -wait -inlinetex -tex \ifpdf pdf\fi latex + \asy@compname\space 2> \asy@status}% + \CatchFileDef{\@tempb}{\asy@status}{}% + \immediate\write18{\ifwindows del \else rm \fi \asy@status} + \ifx\@tempb\@par@macro + \expandafter\@gobble + \else + \g@addto@macro\@tempb{^^J^^J% + ------------ ASY ERROR ------------^^J% + -----------------------------------}% + \expandafter\@firstofone + \fi{% + \errorstopmode + \typeout{% + -----------------------------------^^J% + ------------ ASY ERROR ------------^^J} + \typeout{\expandafter\strip@prefix\meaning\@tempb} + \batchmode + \end{document}}} + +\newcommand\ShowAsy{% + \begin{preview} + \input{\asy@compname_} + \end{preview}} + +\AtBeginDocument{\InputIfFileExists{\asy@compname_.pre}{}{}} + +\end{filecontents} + + +\begin{filecontents*}{test-asyfig.tex} + +%% uncomment this to enable non-PDF mode: +%\pdfoutput=0 +%% (rememer to delete asyfig_.tex if it's previously been generated for PDF mode) + +\documentclass[12pt,twocolumn]{article} +\usepackage[sc]{mathpazo} +\usepackage{asyfig} +\begin{document} +A boxed graphic:\\ +\fbox{\sffamily\asyfig{frf}}\par +Note the font in the graphic follows +the current font of the document. +\end{document} + +\end{filecontents*} + +\begin{filecontents*}{frf.asy} +unitsize(10mm); +draw( (0,0){right}..{up}(3,2){down}.. + {down}(4,-2){up}..{right}(7,0) ); +draw( "Resonance" , align=E, (3,2) ); +draw( "Anti-resonance" , align=W, (4,-2) ); +\end{filecontents*} + + + + +% Conditionally compile the documentation & generate the .ins file: +\providecommand\asyfigCompile{Y} +\makeatletter +\if\asyfigCompile N + \expandafter\@@end +\fi + + + + +\begin{filecontents*}{asyfig.ins} +%&latex +\def\asyfigCompile{N} +\input asyfig.tex +\csname@@end\endcsname +\end{filecontents*} + + + + +\makeatletter +\documentclass{article} + +\usepackage[it,medium]{titlesec} + +\usepackage{bigfoot,xcolor} +\usepackage[colorlinks,linktocpage]{hyperref} + +\usepackage{gmdoc} +\usepackage{gmverb} +\dekclubs +\stanzaskip=\bigskipamount +\CodeSpacesGrey + +\usepackage{tocloft,varwidth} +\setcounter{tocdepth}{1} +\def\tocwidthA{0.45} +\def\tocwidthB{0.45} +\def\cftpartfont{\scshape} +\def\cftsecfont{\small} +\cftbeforesecskip=0pt +\def\cftpartleader{} +\def\cftpartafterpnum{\cftparfillskip} +\def\cftsecleader{} +\def\cftsecafterpnum{\cftparfillskip} + +\let\pkg\textsf +\def\pkgopt#1{\texttt{[#1]}} + +\def\PDF{\textsc{pdf}} +\def\PS{\textsc{ps}} +\def\DVI{\textsc{dvi}} +\def\EPS{\textsc{eps}} + +\usepackage{amsmath,listings} +\lstset{basicstyle=\ttfamily,columns=fullflexible} + +\usepackage{asyfig} +\usepackage[T1]{fontenc} +\usepackage{microtype} +\usepackage{lmodern} +\usepackage[sc,osf]{mathpazo} +\linespread{1.1} +\frenchspacing + +\GetFileInfo{asyfig.sty} +\begin{document} +{\addtocontents{toc}{\protect\begin{varwidth}[t]{\tocwidthA\linewidth}}} + +\title{The \pkg{asyfig} packages} +\author{% + \normalsize Will Robertson\footnote{\texttt{wspr81@gmail.com}}} +\date{\fileversion\qquad\filedate} + +\maketitle + +\begin{abstract} +This suite of packages provides an alternate method of including stand-alone Aymptote figures within \LaTeX\ documents via the \cmd\asyfig\ command. +\end{abstract} + +\tableofcontents + +\part{User documentation} + +\section{Introduction} +Asymptote (or |asy|) is a vector graphics programming language inspired by MetaPost but based around an extended C-like language and full support for 3\textsc{d} bezier curves. Asymptote uses an auxiliary \LaTeX\ process to typeset its labels, and figures can be either generated as stand-alone graphics or in an `inline' form in which labels get placed by the main typesetting process as the figure is inserted into a document. + +Support for |asy| in a \LaTeX\ document is provided by the \pkg{asymptote} package, which defines the |\begin{asy}| environment in which |asy| figures may be directly typed. In this case, the source file contains the complete specification for the text and graphics in the document. However, for large documents it can be quite inconvenient to maintain |asy| graphics that are inline with the document source, because the whole document requires two compilations before any changes in the graphic can be visualised. + +This package, \pkg{asyfig}, provides an alternative, whereby all |asy| figures are defined \emph{separately} from the source in their own individual |.asy| files. \pkg{asyfig} uses Asymptote's inline mode so that labels in the graphics are produced by the main typesetting run; this ensures consistent font and size selection of text within the graphics. In addition, each individual |.asy| graphic can be very quickly processed individually to facilitate easy maintenance and editing of the graphics. + +\section{Getting started} + +Load the \pkg{asyfig} package like any other. I'll discuss the workflow of the package with an illustrative example. + +\paragraph{An \texttt{asy} graphic} +First we need an example Asymptote graphic. This package is distributed with one such, |frf.asy|: +\lstinputlisting{frf.asy} +Material within |texpreamble| is \emph{not} used in the final typesetting of the labels; it is purely for the `proof' graphic that is produced before the graphic is integrated within the main document. + +\paragraph{Inserting the graphic} +After processing (see the next step), this graphic can be included in the document with the \cmd\asyfig\arg{graphic name} command. In the case of the example, this would be |\asyfig{frf}|. It does \emph{not} take any option arguments like a regular graphic to affect the scaling or rotation of the graphic (cf.~\cmd\includegraphics); you are expected to produce the figure in the correct size and orientation within Asymptote. + +If all of your |.asy| files take a common path prefix (such as |./figures/asy/|), this can be defined with the \cmd\asypath\marg{path} command. For example, instead of writing |\asyfig{asy/frf}| one can write |\asypath{asy/}| somewhere in the document (usually the preamble) and then later |\asyfig{frf}|. + +\paragraph{Processing the graphic} +But before the graphic can be placed into the document it must be processed. If the \texttt{asy} graphic has not been processed, or if the \texttt{asy} file is \emph{newer} than its processed graphic, then this package will attempt to do the processing automatically. To turn off this automatic processing, load the package with the \texttt{[process=none]} package option. Alternatively, to re-process \emph{all} \texttt{asy} graphics, use \texttt{[process=none]} instead. + +The primary feature of this package is that figures may be processed independently of the main document in order to be able to rapidly iterate changes to the graphic. This processing is performed by the \pkg{asyprocess} package in an auxiliary \LaTeX\ execution. Here is a basic shell script that I use to do this: +\begin{lstlisting} +#!/bin/sh +pdflatex -shell-escape -interaction=batchmode -jobname=$1-comp + "\RequirePackage{asyprocess}\ProcessAsy + \documentclass{article}\begin{document}\ShowAsy\end{document}" +\end{lstlisting} +Simply change |pdflatex| to |latex| to have \EPS\ graphics produced by Asymptote. Note that it is \emph{mandatory} to use the |-comp| suffix for the jobname. + +By saving the script above into (say) |asyprocess| and making it executable, an individual \texttt{asy} graphic can be processed by running (following from the running example) `|asyprocess frf|'. + +\section{Package information} +The most recent publicly released version of \pkg{asyfig} is available from \textsc{ctan}:\\ +\centerline{\url{http://tug.ctan.org/pkg/asyfig/}}\\ +Historical and developmental versions are available at GitHub:\\ \centerline{\url{http://github.com/wspr/asyfig/}}\\ +While general feedback at \url{wspr81@gmail.com} is welcomed, specific bugs should be reported through the issue tracker at GitHub: \url{http://github.com/wspr/asyfig/issues}. + +This package is freely modifiable and distributable under the terms and conditions of the \LaTeX\ Project Public Licence, version 1.3c or greater (your choice). The latest version of this license is available at: \url{http://www.latex-project.org/lppl.txt}. This work is maintained by \textsc{Will Robertson}. + +{\addtocontents{toc}{\protect\end{varwidth}\protect\hfill}} +{\addtocontents{toc}{\protect\begin{varwidth}[t]{\protect\tocwidthB\protect\linewidth}}} +\clearpage +\parindent=0pt + +\part{Implementation} +\section{The asyfig package} +\DocInput{asyfig.sty} + +\section{The asyalign package} +\DocInput{asyalign.sty} + +\section{The asyprocess package} +\DocInput{asyprocess.sty} + +{\addtocontents{toc}{\protect\end{varwidth}}} +\end{document} |