From adac22a945bfa784fdfbb471fcf0dd3d78305bdd Mon Sep 17 00:00:00 2001 From: Erik Demaine Date: Tue, 18 Oct 2022 17:19:56 -0400 Subject: [PATCH] Maketile documentation (#99) --- README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) diff --git a/README.md b/README.md index 1620bb6..755b863 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,10 @@ see [more examples below](#examples). - [`` Processing](#image-processing) - [Converting SVG to PDF/PNG](#converting-svg-to-pdfpng) - [LaTeX Text](#latex-text) +- [Maketiles](#maketiles) + - [Maketile.args](#maketileargs) + - [Maketile.coffee/js](#maketilecoffeejs) + - [Directories](#directories) - [API](#api) - [Examples](#examples) - [Video/board games](#videoboard-games) @@ -737,6 +741,89 @@ via one of the following options (any one will do): instead of `\import{filename.svg_tex}`. * `\graphicspath{{path/to/file/}}` (note extra braces and trailing slash). +## Maketiles + +SVG Tiler has a simple `Makefile`-like build system for keeping track of the +`svgtiler` command-line arguments needed to build your tiled figures. +These `Maketile`s generally get run whenever you run `svgtiler` without +any filename arguments (e.g. just running `svgtiler` without any arguments). +(If you ever want to skip the `Maketile` behavior, just provide mapping +and drawing filename arguments like you normally would.) +Several examples of `Maketile`s are in the [examples](examples) directory. + +### Maketile.args + +At the simplest level, you can put the command-line arguments to `svgtiler` +into a file called `Maketile.args` (or `maketile.args`), and running +`svgtiler` without any filename arguments will automatically append those +arguments to the command line. Thus the `.args` file could specify the +mappings and drawings to render, and you can still add extra options like +`--pdf` or `--force` to the actual command line as needed. +The `.args` file gets parsed similar to the `bash` shell, +so you can write one-line comments with `#`, +you can use glob expressions like `**/*.asc`, +and you put quotes around filenames with spaces or other special characters. +You can also write the arguments over multiple lines +(with no need to end lines with `\`). + +### Maketile.coffee/.js + +The more sophisticated system is to write a `Maketile.coffee` or +`Maketile.js` file. This system offers the entire CoffeeScript or +JavaScript programming language to express complex build rules. +In particular, you can write multiple different build rules by +`export`ing different named functions. The `default` export is the rule +that gets run when `svgtiler` has no filename arguments; you can run +another exported rule `foo` by running `svgtiler foo` from the command line +(provided `foo` is not an actual filename). + +Build rules can run the equivalent of an `svgtiler` command line by calling +the `svgtiler` function, e.g., `svgtiler('mapping.coffee *.asc')`. +String arguments are parsed just like `.args` files: whitespace separates +arguments, `#` indicates comments, glob patterns get expanded, and quotes +get processed. +Array arguments are treated as already parsed argument lists, so +the previous example is equivalent to `svgtiler(['mapping.coffee', '*.asc'])` +(where the glob pattern still gets processed, but whitespace in filenames +would not). +Instead of strings, you can also directly pass in `Mapping` or `Drawing` or +`Style` objects (as arguments or as part of an array argument). +An easy way to create such objects is to call `svgtiler.require()`, +which processes any given filename (without any processing of its filename). +For example, `svgtiler.require('filename with spaces and *s.asc')` transforms +an ASCII file into a `Drawing` object. + +There are also tools for manually working with glob patterns: +`svgtiler.glob(pattern)` returns an array of filenames that match a pattern, +and `svgtiler.match(filename, pattern)` checks whether a filename +matches a pattern. +These helpers use [node-glob](https://github.com/isaacs/node-glob) and +[minimatch](https://github.com/isaacs/minimatch) respectively, so follow their +[glob notation](https://github.com/isaacs/node-glob#glob-primer). +Thus you can write your own `for` loops and e.g. +`switch` depending on what additional pattern(s) the filenames match. +For example, `svgtiler('mapping.coffee *.asc')` can be rewritten as +`svgtiler.glob('*.asc').forEach((asc) => +svgtiler('mapping.coffee', svgtiler.require(asc))`. + +No calls to `svgtiler()` or other side effects should be at the top level +of the `Maketile`. Instead, put these build steps inside an `export default` +function or a named `export`ed function. + +### Directories + +It usually makes sense to put `Maketile`s in the directory where your +figures are getting built, but sometimes that's not the directory you're +working in. For example, SVG Tiler figures may be in a `figures` +subdirectory or your paper's main directory. In this case, you can trigger +the `Maketile` within the `figures` directory by running `svgtiler figures`. +You can use this shorthand also when defining `Maketile`s, +to recurse into subdirectories. +For example, [examples/Maketile.coffee](examples/Maketile.coffee) +loops over all the subdirectories within `examples` and runs their `Maketile`s. +You can thus trigger building all examples in this repository by typing +`svgtiler examples` at the root directory of a checkout. + ## API SVG Tiler provides an API for rendering SVG directly from your JavaScript code.