diff options
author | Norbert Preining <norbert@preining.info> | 2023-01-03 03:01:37 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2023-01-03 03:01:37 +0000 |
commit | 660cf44d2a0aee74bd6e69615fedfc57c966a260 (patch) | |
tree | 3e62bc2b2f8208c4abcad9423ee2efa266fa8c7b /macros/latex/contrib/xput | |
parent | 4841af990664e40ab2f20099d8b39dabacf5ad0f (diff) |
CTAN sync 202301030301
Diffstat (limited to 'macros/latex/contrib/xput')
-rw-r--r-- | macros/latex/contrib/xput/README.md | 109 | ||||
-rw-r--r-- | macros/latex/contrib/xput/doc/example-book.tex | 2 | ||||
-rw-r--r-- | macros/latex/contrib/xput/doc/example-grid.tex | 4 | ||||
-rw-r--r-- | macros/latex/contrib/xput/doc/example-template.tex | 4 | ||||
-rw-r--r-- | macros/latex/contrib/xput/doc/example-text.tex | 2 | ||||
-rw-r--r-- | macros/latex/contrib/xput/doc/xputmanual-layout-guides.pdf | bin | 6452 -> 6493 bytes | |||
-rw-r--r-- | macros/latex/contrib/xput/doc/xputmanual-layout-guides.tex | 1 | ||||
-rw-r--r-- | macros/latex/contrib/xput/doc/xputmanual.pdf | bin | 77006 -> 77041 bytes | |||
-rw-r--r-- | macros/latex/contrib/xput/doc/xputmanual.tex | 2 | ||||
-rwxr-xr-x | macros/latex/contrib/xput/scripts/xput | 31 | ||||
-rwxr-xr-x | macros/latex/contrib/xput/scripts/xputserver | 83 | ||||
-rw-r--r-- | macros/latex/contrib/xput/tex/xput.cls | 15 |
12 files changed, 195 insertions, 58 deletions
diff --git a/macros/latex/contrib/xput/README.md b/macros/latex/contrib/xput/README.md index 8843656c15..6471ea4556 100644 --- a/macros/latex/contrib/xput/README.md +++ b/macros/latex/contrib/xput/README.md @@ -1,46 +1,99 @@ -# Xput +## What is Xput -__Declarative Desktop Publishing with LaTeX__ +Xput is a LaTeX class to create graphic rich, layouted, perfectly typeset, and print ready PDFs just from a text file. It provides simple macros to put content on a page declaratively. Generic templates, automatic grid layout, and a simple and consistent user interface help you to create layouts with ease. -The Xput LaTeX class provides a collection of macros that wrap the macro put to offer a more desktop-publishing-like experience for creating graphic rich documents like photo books. -With Xput you can create single- and double-sided documents, create pages with margins, safety margins and bleed, use templates, align text and graphics in a grid, wrap text across multiple pages and use before pages. -Generic templates, automatic grid layout and a simple and consistent user interface make it easier than ever to create graphic rich documents with LaTeX. -Under the hood Xput uses the TikZ and tcolorbox packages, ImageMagick and Inkscape. +The integration of Inkscape allows your to create beautiful box shadows. Text shadows and SVG filters are ideas for future releases. -Xput is distributed under the [LaTeX Project Public License](https://www.latex-project.org/lppl/lppl-1-3c/) version 1.3c or later. +The integration of ImageMagick allows you to configure the PDF export to create web, print or preview versions of your document. Parallelized image optimization, caching and a draft mode enable fast PDF creation and a responsive workflow, even for large documents with lots of photos and graphics. -To submit bug reports and feature requests go to the official repository on [GitHub](https://github.com/friedemannbartels/xput/issues). +Xput also integrates the TikZ and tcolorbox LaTeX packages. -## Installation +## Quick Start -In general, you should use the package manager shipped with your TeX distribution to install Xput. Alternatively you can copy the contents of [xput-1.0.1.tds.zip](https://github.com/friedemannbartels/xput/releases/download/1.0.1/xput-1.0.1.tds.zip) to your local TeX directory tree. +### Generic Templates -### Command Line Tools +Generic templates are the easiest way to put content on a page. The template name describes the layout. You can arrange [l]andscape, [p]ortrait, [s]quare, [w]ide, [g]olden ratio, g[o]lden upright ratio or [f]lexible placeholders in rows [-]. A valid template name for example is `sg-ff`. Notice you cannot combine flexible with fixed aspect ratio placeholders within a row. -For image optimization, shadow creation and preflight perform these installation steps: +```latex +\template{sg}{ + \text{Hello Xput} + \graphic{IMG1234} +} +``` -- Add the directory `tex/latex/xput/scripts` in your local TeX file tree to your `$PATH`. -- Add `xputserver` to the list of `shell_escape_commands` in your `texmf.cnf`. -- Install ImageMagick 7.0 or newer and Inkscape 1.0 or newer. +### Custom Templates and the Grid -The setup is tested with the engines `xelatex`, `pdflatex` and `lualatex` and the shells `zsh`, `bash` and `dash`. +You can use the grid to layout content on a page. The grid has rows with cells. You can set width relations between cells and height relations between rows. You can give cells a explicit aspect ratio by adding a `!`. -## Known Issues +```latex +\newtemplate{my template}{ + \grid{ + {[2]{2!}{3!}} + {[2]{1}} + } + \placeholder{0 0 1 1} +} +``` -### LuaLaTeX +You can set margin and gutter for a single grid or on document or page level. -Setting the page width and height as document option or in the preamble does not work with LuaLaTeX. You need to set the page width and height after `begin{document}`. -Multi-threaded batch processing of images does not work with LuaLaTeX too. +### Graphics -### LuaLaTeX and pdfLaTeX +Adding a graphic to a page is simple. You can scale, position and sharpen a graphic. -LuaLaTeX and pdfLaTeX only work with restricted shell access. When running with unrestricted shell access (`--shell-escape`), image optimization, shadow creation and preflight do not work. +```latex +\page{ + \graphic[ + scale=1.2, + hpos=0.3, + unsharp=3x1 + ]{filename} +} +``` -## Development +### Borders and Shadows + +You can add borders and box shadows to graphics and text frames. + +```latex +\newborder{my border}{ + width=2mm, + color=magenta, + radius=5mm +} +\newshadow{my shadow}{ + size=5, + color=magenta, + opacity=1 +} + +\page{ + \graphic[ + shadow=my shadow, + border=my border, + border radius=10mm + ]{filename} +} +``` + +Have a look at the [examples](https://github.com/friedemannbartels/xput/tree/main/doc) and start playing with these. + +For a complete reference have a look at the [manual](https://github.com/friedemannbartels/xput/raw/main/doc/xputmanual.pdf). + +## Installation + +In general, you should use the package manager shipped with your TeX distribution to install Xput. Alternatively you can copy the contents of [xput.tds.zip](https://github.com/friedemannbartels/xput/releases/download/v1.0.2/xput.tds.zip) to your local TeX directory tree. + +### Command Line Tools + +For image optimization, shadow creation and preflight perform these installation steps: -Run visual regression tests with the following command: +- Add the directory _tex/latex/xput/scripts_ in your local TeX file tree to your `$PATH`. + +- Add `xputserver` to the list of `shell_escape_commands` in your top level _texmf.cnf_. Find your _texmf.cnf_ with the command `kpsewhich texmf.cnf`. + +- Install ImageMagick 7.0 or newer and Inkscape 1.0 or newer. + +## Development - cd test - xput test - -The tests are not included in the [CTAN](https://www.ctan.org/pkg/xput) package. You find the tests on [GitHub](https://github.com/friedemannbartels/xput/tree/main/test). +Run visual regression tests inside the _tests_ directory with the command `xput test` diff --git a/macros/latex/contrib/xput/doc/example-book.tex b/macros/latex/contrib/xput/doc/example-book.tex index f770532e69..d318eba582 100644 --- a/macros/latex/contrib/xput/doc/example-book.tex +++ b/macros/latex/contrib/xput/doc/example-book.tex @@ -98,7 +98,7 @@ \lipsum[1][1-7] } } - + \newgraphic{koepi wide}{vpos=0.43, file=koepi} \page[double, page graphic=koepi wide, before page=, color=white]{ \rightpage{ diff --git a/macros/latex/contrib/xput/doc/example-grid.tex b/macros/latex/contrib/xput/doc/example-grid.tex index 1a5c707dac..a1c341cd66 100644 --- a/macros/latex/contrib/xput/doc/example-grid.tex +++ b/macros/latex/contrib/xput/doc/example-grid.tex @@ -112,7 +112,7 @@ A grid with a fixed height relation between rows. } } - + \page[gutter=10mm]{ \setgrid[ width=0.5\width, @@ -132,7 +132,7 @@ {{1}} } } - + \page{ \setgrid[width=\height]{ {{1}{1}} diff --git a/macros/latex/contrib/xput/doc/example-template.tex b/macros/latex/contrib/xput/doc/example-template.tex index a70acfd481..eb0b773601 100644 --- a/macros/latex/contrib/xput/doc/example-template.tex +++ b/macros/latex/contrib/xput/doc/example-template.tex @@ -26,7 +26,7 @@ This is a generic template. } } - + \newtemplate{my template}{ \setgrid[height=\height-20mm]{ {[1]{1!}{1}} @@ -36,7 +36,7 @@ \placeholder{1 0 2 1} \placeholder{0 1 2 2} } - + \template[outer margin=10mm]{my template}{ \text{ This is a custom template. diff --git a/macros/latex/contrib/xput/doc/example-text.tex b/macros/latex/contrib/xput/doc/example-text.tex index 421532418e..9be397a042 100644 --- a/macros/latex/contrib/xput/doc/example-text.tex +++ b/macros/latex/contrib/xput/doc/example-text.tex @@ -33,7 +33,7 @@ } \usetext[lorem] } - + \page{ \usetext[lorem] \tcbset{ diff --git a/macros/latex/contrib/xput/doc/xputmanual-layout-guides.pdf b/macros/latex/contrib/xput/doc/xputmanual-layout-guides.pdf Binary files differindex ec1763bf5d..0ec732a859 100644 --- a/macros/latex/contrib/xput/doc/xputmanual-layout-guides.pdf +++ b/macros/latex/contrib/xput/doc/xputmanual-layout-guides.pdf diff --git a/macros/latex/contrib/xput/doc/xputmanual-layout-guides.tex b/macros/latex/contrib/xput/doc/xputmanual-layout-guides.tex index 1e53fb0bf7..023858736a 100644 --- a/macros/latex/contrib/xput/doc/xputmanual-layout-guides.tex +++ b/macros/latex/contrib/xput/doc/xputmanual-layout-guides.tex @@ -18,6 +18,7 @@ gutter=5mm, page width=20cm, page height=20cm, + safety margin=2mm, draft, safezone, grid, diff --git a/macros/latex/contrib/xput/doc/xputmanual.pdf b/macros/latex/contrib/xput/doc/xputmanual.pdf Binary files differindex 7ce8804b7a..ccb1e39f44 100644 --- a/macros/latex/contrib/xput/doc/xputmanual.pdf +++ b/macros/latex/contrib/xput/doc/xputmanual.pdf diff --git a/macros/latex/contrib/xput/doc/xputmanual.tex b/macros/latex/contrib/xput/doc/xputmanual.tex index fbfc3805c5..ff75b4eecf 100644 --- a/macros/latex/contrib/xput/doc/xputmanual.tex +++ b/macros/latex/contrib/xput/doc/xputmanual.tex @@ -18,7 +18,7 @@ \usepackage{tikz} \OnlyDescription \hypersetup{pdfborder={0 0 0}} -\def\Xputversion{1.0.1} +\def\Xputversion{1.0.2} \begin{document} diff --git a/macros/latex/contrib/xput/scripts/xput b/macros/latex/contrib/xput/scripts/xput index 3727bb3dc1..57203c7a5d 100755 --- a/macros/latex/contrib/xput/scripts/xput +++ b/macros/latex/contrib/xput/scripts/xput @@ -13,6 +13,8 @@ # LaTeX version 2008/05/04 or later. # +version=1.0.2 + OK="$( tput setaf 2 )•$( tput sgr0 )" FAILED="$( tput setaf 1 )$( tput bold )x$( tput sgr0 )" NEW="$( tput setaf 3 )$( tput bold )+$( tput sgr0 )" @@ -380,27 +382,33 @@ perf() { usage() { cat <<HELP_USAGE -usage: $(basename $0) test [-cs] [-e engine] [-d density] pattern - or: $(basename $0) approve [-e engine] pattern - or: $(basename $0) compare [-d density] files - or: $(basename $0) perf [-cs] [-e engine] file +usage: xput test [-cs] [-e ENGINE] [-d DENSITY] [PATTERN] + xput approve [-e ENGINE] [PATTERN] + xput compare [-d DENSITY] FILE FILE + xput perf [-cs] [-e ENGINE] FILE + xput --help + xput --version -c clear cache -s enable shell escape - -d density set density in ppi (default 72) - -e engine set latex engine (default xelatex) + -d DENSITY density in ppi (default 72) + -e ENGINE latex engine (default xelatex) - Running \`$(basename $0) test\` creates pdf files for all tex files matching the + Running \`xput test\` creates pdf files for all tex files matching the pattern and performs a visual regression test. If no pattern is specified, all files in the current directory are tested except for files whose names begin with an underscore. - Running \`$(basename $0) approve\` replaces the reference files with the test files. + Running \`xput approve\` replaces the reference files with the test files. - Running \`$(basename $0) compare\` creates a visual diff for two pdf files. + Running \`xput compare\` creates a visual diff for two pdf files. - Running \`$(basename $0) perf\` measures the time for creating a pdf file from the + Running \`xput perf\` measures the time for creating a pdf file from the given tex file. + + Running \`xput --help\` returns this man page. + + Running \`xput --version\` returns the Xput version. HELP_USAGE } @@ -504,6 +512,9 @@ perf) perf $clear $shell $engine $1 ;; +--version) + echo Xput $version + ;; *) usage esac diff --git a/macros/latex/contrib/xput/scripts/xputserver b/macros/latex/contrib/xput/scripts/xputserver index 924bfe0da0..8e2baac919 100755 --- a/macros/latex/contrib/xput/scripts/xputserver +++ b/macros/latex/contrib/xput/scripts/xputserver @@ -13,6 +13,8 @@ # LaTeX version 2008/05/04 or later. # +version=1.0.2 + _convert() { turbo=$1 filename=$2 @@ -229,18 +231,27 @@ import() { } startturbo() { - file=$1 + file="$(echo $1 | sed -e 's/\.pdflatex$//g')" if [ -f $file.tex ]; then tmpdir=$( mktemp -d 2>/dev/null )/xputturbo$( date "+%Y%m%d%H%M%S" )$RANDOM mkdir $tmpdir cp $file.tex $tmpdir/xputturbobatchoptimizexyz.tex - engine=$(echo $(ps -p $PPID -o command | sed -e 's/[A-Z]//g'| sed -e 's/ .*//g' | tr -d '\n')) + command=$(echo $(ps -p $PPID -o command )) + engine=$(echo $command | sed -e 's/^[A-Z ]*//g' | sed -e 's/ .*//g' | tr -d '\n') + + case "$command" in + *-shell-escape*) + shellescape="--shell-escape" + ;; + esac + if [ "$engine" = "xelatex" ]; then nopdf="-no-pdf" fi - $engine -interaction=batchmode $nopdf --output-directory $tmpdir $tmpdir/xputturbobatchoptimizexyz.tex > /dev/null + + $engine $shellescape -interaction=batchmode $nopdf --output-directory $tmpdir $tmpdir/xputturbobatchoptimizexyz.tex > /dev/null rm -rf $tmpdir fi @@ -285,11 +296,73 @@ batchoptimize() { done } +usage() { + cat <<HELP_USAGE +This script is intended for internal use of the Xput LaTeX class. + +usage: xputserver getwidth % FILE + xputserver optimize % FILE % FILENAME % EXTENSION % ORIGINALWIDTH % ORIGINALHEIGHT % CROPLEFT % CROPRIGHT % CROPTOP % CROPBOTTOM % DENSITY % WIDTH % HEIGHT % DOWNSAMPLETHRESHOLD % UNSHARP % QUALITY + xputserver makeshadow % FILENAME % STANDARDDEVIATION % OPACITY % COLOR % WIDTH % HEIGHT % FRAMEWIDTH % FRAMEHEIGHT % MARGIN % BORDERRADIUS + xputserver start [% import % [GRAPHICSPATH]] [% turbo % JOBNAME] + xputserver batchoptimize % BATCHLIST + xputserver --help + xputserver --version + + FILE filename with extension (eg. IMG1234.JPEG) + FILENAME filename without extension (eg. IMG1234) + EXTENSION optimized file extension (.jpg|.png) + DENSITY density in ppi (eg. 72) + DOWNSAMPLETHRESHOLD downsample threshold (integer >= 100) + UNSHARP unsharp filter (eg. 2x1) + QUALITY quality (integer > 0, <= 100) + STANDARDDEVIATION standard deviation (decimal > 0.0) + OPACITY opacity (decimal >= 0.0, <= 1.0) + COLOR color string (eg. pink) + GRAPHICSPATH list of directories (eg. {images/}{tmp/}) + JOBNAME LaTeX filename without extension (eg. my-document) + BATCHLIST a flat list of batch items where each batch item is + a flat list of the 15 parameters required by the + command \`xputserver optimize\` + + All other parameters are length dimensions. + The command \`xputserver optimize\` expects integer values in the LaTeX + unit sp (eg. 65536). + The command \`xputserver makeshadow\` expects decimal values in a SVG + compatible unit (eg. 420.0pt). + + Running \`xputserver getwidth\` returns the width in pixels for the given + image file. + + Running \`xputserver optimize\` creates a cropped, rezised, sharpend and + compressed image and stores it in the cache directory. + + Running \`xputserver makeshadow\` creates a shadow image and stores it in + the cache directory. + + Running \`xputserver start\` with the import parameter triggers the image + import (see xputmanual.pdf chapter "Image Optimization"). + Running the command with the parameter turbo, where the jobname is the + filename of the Xput document, processes the document in a special batch + mode, that creates a batch list and calls the command + \`xputserver batchoptimize\`. + + Running \`xputserver batchoptimize\` optimizes multiple images in parallel. + + Running \`xputserver --help\` returns this man page. + + Running \`xputserver --version\` returns the Xput version. +HELP_USAGE +} + +if [ "$1" = --version ]; then + echo Xput Server $version + exit +fi + input=$( echo "$@" | sed -e 's/\\//g' | sed -e 's/ %/%/g' | sed -e 's/% /%/g' ) IFS="%" set -- $input IFS=" " -shift case "$1" in getwidth) @@ -334,5 +407,5 @@ batchoptimize) echo ok ;; *) - echo 🤖 Hi, I serve the Xput LaTeX class. + usage esac diff --git a/macros/latex/contrib/xput/tex/xput.cls b/macros/latex/contrib/xput/tex/xput.cls index 6da33ee25d..a7fdd1c2bf 100644 --- a/macros/latex/contrib/xput/tex/xput.cls +++ b/macros/latex/contrib/xput/tex/xput.cls @@ -13,8 +13,8 @@ %% \NeedsTeXFormat{LaTeX2e}[2020/10/01] -\ProvidesClass{xput}[2022/12/19 declarative desktop publishing] -\def\Xputversion{1.0.1} +\ProvidesClass{xput}[2023/01/02 declarative desktop publishing] +\def\Xputversion{1.0.2} % packages \RequirePackage{pgfopts} @@ -3596,9 +3596,8 @@ \def\xput@err@noimportdir{errornoimportdir} \def\xput@err@magicknotinstalled{errormagicknotinstalled} \def\xput@err@inkscapenotinstalled{errorinkscapenotinstalled} -\def\preventunrestrictedshellexecution{";-)" \%} \newcommand\xput@getppi[1]{ - \immediate\openin\xput@scriptresult={|xputserver \preventunrestrictedshellexecution getwidth\% "#1"} + \immediate\openin\xput@scriptresult={|xputserver getwidth\% "#1"} \ifeof\xput@scriptresult \xput@errmsg@shellaccessforbidden{Ppi not calculated} \else @@ -3621,7 +3620,7 @@ \immediate\closein\xput@scriptresult } \newcommand\xput@optimizegraphic[2]{ - \immediate\openin\xput@scriptresult={|xputserver \preventunrestrictedshellexecution optimize\% "#1#2" \% "\xput@filename" \%\xput@optimizedext\%\the\numexpr\xput@originalgraphicwidth\%\the\numexpr\xput@originalgraphicheight\%\the\numexpr\xput@cropleft\%\the\numexpr\xput@cropright\%\the\numexpr\xput@croptop\%\the\numexpr\xput@cropbottom\%\the\numexpr\xput@density\%\the\numexpr\width\%\the\numexpr\height\%\xput@downsamplethreshold\%\xput@graphicoptionunsharp\%\xput@quality} + \immediate\openin\xput@scriptresult={|xputserver optimize\% "#1#2" \% "\xput@filename" \%\xput@optimizedext\%\the\numexpr\xput@originalgraphicwidth\%\the\numexpr\xput@originalgraphicheight\%\the\numexpr\xput@cropleft\%\the\numexpr\xput@cropright\%\the\numexpr\xput@croptop\%\the\numexpr\xput@cropbottom\%\the\numexpr\xput@density\%\the\numexpr\width\%\the\numexpr\height\%\xput@downsamplethreshold\%\xput@graphicoptionunsharp\%\xput@quality} \ifeof\xput@scriptresult \xput@errmsg@shellaccessforbidden{File not optimized} \else @@ -3639,7 +3638,7 @@ \immediate\closein\xput@scriptresult } \newcommand\xput@makeshadow[1]{ - \immediate\openin\xput@scriptresult={|xputserver \preventunrestrictedshellexecution makeshadow\%#1\%\xput@defaultshadowsize\%\xput@defaultshadowopacity\%\xput@defaultshadowcolor\%\the\xput@frameshadowwidth\%\the\xput@frameshadowheight\%\the\xput@frameshadowframewidth\%\the\xput@frameshadowframeheight\%\the\xput@frameshadowborder\%\the\xput@frameshadowradius} + \immediate\openin\xput@scriptresult={|xputserver makeshadow\%#1\%\xput@defaultshadowsize\%\xput@defaultshadowopacity\%\xput@defaultshadowcolor\%\the\xput@frameshadowwidth\%\the\xput@frameshadowheight\%\the\xput@frameshadowframewidth\%\the\xput@frameshadowframeheight\%\the\xput@frameshadowborder\%\the\xput@frameshadowradius} \ifeof\xput@scriptresult \edef\xput@processresult{\xput@err@shellaccessforbidden} \xput@errmsg@shellaccessforbidden{Shadow not created} @@ -3659,7 +3658,7 @@ \immediate\closein\xput@scriptresult } \def\xput@start{ - \immediate\openin\xput@scriptresult={|xputserver \preventunrestrictedshellexecution start\ifxput@import\%import\% "\ifdefined\Ginput@path\Ginput@path\fi" \fi\ifxput@isturbomode\%turbo\% "\jobname" \fi} + \immediate\openin\xput@scriptresult={|xputserver start\ifxput@import\%import\% "\ifdefined\Ginput@path\Ginput@path\fi" \fi\ifxput@isturbomode\%turbo\% "\jobname" \fi} \ifeof\xput@scriptresult \ifxput@import \xput@errmsg@shellaccessforbidden{Import not working} @@ -3689,7 +3688,7 @@ \global\edef\xput@batchlist{\xput@batchlist\% "#1#2" \% "\xput@filename" \%\xput@optimizedext\%\the\numexpr\xput@originalgraphicwidth\%\the\numexpr\xput@originalgraphicheight\%\the\numexpr\xput@cropleft\%\the\numexpr\xput@cropright\%\the\numexpr\xput@croptop\%\the\numexpr\xput@cropbottom\%\the\numexpr\xput@density\%\the\numexpr\width\%\the\numexpr\height\%\xput@downsamplethreshold\%\xput@graphicoptionunsharp\%\xput@quality} } \newcommand\xput@batchoptimize{ - \immediate\openin\xput@scriptresult={|xputserver \preventunrestrictedshellexecution batchoptimize\xput@batchlist} + \immediate\openin\xput@scriptresult={|xputserver batchoptimize\xput@batchlist} \ifeof\xput@scriptresult \else \endlinechar=-1 |