summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/xput/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/xput/README.md')
-rw-r--r--macros/latex/contrib/xput/README.md109
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`