diff options
Diffstat (limited to 'macros/latex/contrib/xput/README.md')
-rw-r--r-- | macros/latex/contrib/xput/README.md | 109 |
1 files changed, 81 insertions, 28 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` |