release: 0.3.1

.gitattributes

@@ -0,0 +1,3 @@
+release/completions/* linguist-detectable=false
+release/man/* linguist-detectable=false
+test-assets/* linguist-detectable=false

.github/workflows/ci.yaml

@@ -0,0 +1,62 @@
+name: Build
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+defaults:
+  run:
+    shell: bash
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  all:
+    name: All
+
+    strategy:
+      matrix:
+        target:
+        - x86_64-unknown-linux-gnu
+        - x86_64-apple-darwin
+        include:
+        - target: x86_64-unknown-linux-gnu
+          os:     ubuntu-latest
+        - target: x86_64-apple-darwin
+          os:     macos-latest
+
+    runs-on: ${{matrix.os}}
+
+    env:
+      RUSTFLAGS: "-D warnings"
+
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions-rs/toolchain@v1
+      with:
+        toolchain: stable
+        target: ${{ matrix.target }}
+        profile: minimal
+        override: true
+        components: clippy
+
+    - name: Info
+      run: |
+        rustup --version
+        cargo --version
+        cargo clippy --version
+
+    - name: Build
+      run: |
+        cargo build --release --target ${{ matrix.target }}
+
+    - name: Clippy
+      run: |
+        cargo clippy --release --all-features --target ${{ matrix.target }}
+
+    - name: Tests
+      run: |
+        cargo test --release --all-features --target ${{ matrix.target }}

CREDITS.md

@@ -1,7 +1,7 @@
 # Project Dependencies
     Package:   yesvgmap
-    Version:   0.3.0
-    Generated: 2022-01-28 21:59:03 UTC
+    Version:   0.3.1
+    Generated: 2022-01-29 03:51:52 UTC
 
 | Package | Version | Author(s) | License |
 | ---- | ---- | ---- | ---- |
@@ -23,8 +23,8 @@
 | [hermit-abi](https://github.com/hermitcore/libhermit-rs) | 0.1.19 | Stefan Lankes | Apache-2.0 or MIT |
 | [instant](https://github.com/sebcrozet/instant) | 0.1.12 | [sebcrozet](mailto:[email protected]) | BSD-3-Clause |
 | [lazy_static](https://github.com/rust-lang-nursery/lazy-static.rs) | 1.4.0 | [Marvin Löbel](mailto:[email protected]) | Apache-2.0 or MIT |
-| [libc](https://github.com/rust-lang/libc) | 0.2.115 | The Rust Project Developers | Apache-2.0 or MIT |
-| [lock_api](https://github.com/Amanieu/parking_lot) | 0.4.5 | [Amanieu d'Antras](mailto:[email protected]) | Apache-2.0 or MIT |
+| [libc](https://github.com/rust-lang/libc) | 0.2.116 | The Rust Project Developers | Apache-2.0 or MIT |
+| [lock_api](https://github.com/Amanieu/parking_lot) | 0.4.6 | [Amanieu d'Antras](mailto:[email protected]) | Apache-2.0 or MIT |
 | [memoffset](https://github.com/Gilnaa/memoffset) | 0.6.5 | [Gilad Naaman](mailto:[email protected]) | MIT |
 | [num-traits](https://github.com/rust-num/num-traits) | 0.2.14 | The Rust Project Developers | Apache-2.0 or MIT |
 | [num_cpus](https://github.com/seanmonstar/num_cpus) | 1.13.1 | [Sean McArthur](mailto:[email protected]) | Apache-2.0 or MIT |

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "yesvgmap"
-version = "0.3.0"
+version = "0.3.1"
 license = "WTFPL"
 authors = ["Josh Stoik <[email protected]>"]
 edition = "2021"
@@ -31,54 +31,54 @@ credits-dir = "./"
 [[package.metadata.bashman.switches]]
 short = "-h"
 long = "--help"
-description = "Print help information."
+description = "Print help information and exit."
 
 [[package.metadata.bashman.switches]]
 long = "--hidden"
-description = "Hide with the 'hidden' attribute. Overrides --offscreen if both are set."
+description = "Hide the map using the 'hidden' HTML attribute. This takes priority over --offscreen when both are present."
 
 [[package.metadata.bashman.switches]]
 long = "--offscreen"
-description = "Hide by placing the element offscreen with inline styles."
+description = "Hide the map using inline styles to position it offscreen."
 
 [[package.metadata.bashman.switches]]
 short = "-V"
 long = "--version"
-description = "Print application version."
+description = "Print version information and exit."
 
 [[package.metadata.bashman.options]]
 short = "-l"
 long = "--list"
 label = "<FILE>"
-description = "Read file paths from this text file."
+description = "Read (absolute) file and/or directory paths from this text file, one entry per line."
 path = true
 
 [[package.metadata.bashman.options]]
 long = "--map-class"
-description = "A class attribute value to assign to the map itself. [default: ]"
+description = "Add this class to the generated SVG map. [default: ]"
 label = "<CLASS>"
 
 [[package.metadata.bashman.options]]
 long = "--map-id"
-description = "An ID attribute value to assign to the map itself. [default: ]"
+description = "Add this ID to the generated SVG map. [default: ]"
 label = "<ID>"
 
 [[package.metadata.bashman.options]]
 short = "-o"
 long = "--output"
-description = "A file path to save the generated map to. If not specified, the map will print to STDOUT."
+description = "Save the generated map to this location. If omitted, the map will print to STDOUT instead."
 label = "<FILE>"
 path = true
 
 [[package.metadata.bashman.options]]
 short = "-p"
 long = "--prefix"
-description = "Symbols will be assigned the ID 'prefix-basename'. [default: icon]"
+description = "Set a custom prefix for the IDs of each entry in the map. (IDs look like PREFIX-STEM, where STEM is the alphanumeric portion of the source file name, e.g. 'i-close'.) [default: i]"
 label = "<PREFIX>"
 
 [[package.metadata.bashman.arguments]]
-label = "<SVG(s)…>"
-description = "Any number of files and directories to crawl and crunch."
+label = "<PATH(s)…>"
+description = "One or more file and/or directory paths to crunch and/or (resursively) crawl. Only files with the extension .svg will ultimately be included."
 
 [dependencies]
 argyle = "0.5.*"

README.md

@@ -0,0 +1,131 @@
+# Yesvgmap
+
+[![Build Status](https://github.com/Blobfolio/yesvgmap/workflows/Build/badge.svg)](https://github.com/Blobfolio/yesvgmap/actions)
+[![Dependency Status](https://deps.rs/repo/github/blobfolio/yesvgmap/status.svg)](https://deps.rs/repo/github/blobfolio/yesvgmap)
+
+
+
+Yesvgmap is a fast, lightweight CLI app for x86-64 Linux machines that compiles SVG sprite maps from one or more standalone SVG files.
+
+
+
+## Features and Non-Features
+
+Yesvgmap will:
+
+* Normalize the XML output;
+* Strip comments, instructions, and declarations from the sources;
+* Reconstruct missing `viewBox` attributes using `width`/`height` (if present);
+* Help suppress browser display using the `hidden` attribute or inline positioning styles;
+
+If you find an icon isn't working correctly after being jammed into a map, take a look at its source code to make sure it has a `viewBox` beginning `0 0` and ending with two positive decimals, e.g. `0 0 123 456`. If it doesn't, you'll need to edit the original image to give it a canvas size matching the content, and/or recenter the layers to avoid janky offsets.
+
+Yesvgmap will _not_ heavily compress the output. The normalization and comment-stripping passes help, but for real shrinkage, you should run your source images through something like [svgo](https://github.com/svg/svgo) first.
+
+Yesvgmap does employ a lot of general sanity checks, but is not a spec-complete SVG validator. If your sources are weird/broken, the map might have some weirdness too.
+
+
+
+## Usage
+
+```bash
+yesvgmap [FLAGS] [OPTIONS] <PATH(S)>
+
+# Pass as many paths as you like...
+yesvgmap -o map.svg icon1.svg icon2.svg icon3.svg
+
+# Or if it is easier to load them from a tex file...
+yesvgmap -o map.svg -l list.txt
+```
+
+| Short | Long | Value | Description | Default |
+| ----- | ---- | ----- | ----------- | ------- |
+| -h | --help | | Print help information and exit. | |
+| | --hidden | | Hide the map using the "hidden" HTML attribute. | |
+| -l | --list | *path* | Read (absolute) file and/or directory paths from this text file, one entry per line. | |
+| | --map-class | *string* | Add this class to the generated SVG map. | |
+| | --map-id | *string* | Add this ID to the generated SVG map. | |
+| | --offscreen | | Hide the map using inline styles to position it offscreen. | |
+| -o | --output | *path* | Save the generated map to this location. If omitted, the map will print to STDOUT instead. | |
+| -p | --prefix | *string* | Set a custom prefix for the IDs of each entry in the map. (IDs look like `PREFIX-STEM`, where "STEM" is the alphanumeric portion of the source file name.) | `"i"` |
+| -V | --version | | Print version information and exit. | |
+
+
+
+## Installation
+
+Debian and Ubuntu users can just grab the pre-built `.deb` package from the [latest release](https://github.com/Blobfolio/yesvgmap/releases/latest).
+
+This application is written in [Rust](https://www.rust-lang.org/) and can alternatively be built from source using [Cargo](https://github.com/rust-lang/cargo):
+
+```bash
+# Clone the source.
+git clone https://github.com/Blobfolio/yesvgmap.git
+
+# Go to it.
+cd yesvgmap
+
+# Build as usual. Specify additional flags as desired.
+cargo build \
+    --bin yesvgmap \
+    --release
+```
+
+(This should work under other 64-bit Unix environments too, like MacOS.)
+
+
+
+## FAQ
+
+### What Are SVG Sprite Maps?
+
+An SVG sprite map is a non-displayable SVG comprising one or more displayable SVGs, each accessible via a unique ID.
+
+Rather than inlining a full SVG like…
+
+```html
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512.001 512.001"><path fill="currentColor" d="M512.001 84.853L427.148 0 256.001 171.147 84.853 0 0 84.853 171.148 256 0 427.148l84.853 84.853 171.148-171.147 171.147 171.147 84.853-84.853L340.853 256z"/></svg>
+```
+
+…each time you need a simple `X` icon to appear in your document, you can inline the SVG map _once_, and then link to the (single) `X` icon over and over again like…
+
+```html
+<svg><use xlink:href="#i-close"></use></svg>
+```
+
+Depending on the amount of repetition and the size of the images, SVG sprite maps can substantially reduce the size of the HTML payload, and improve/speed up GZIP/Brotli compression.
+
+But that said, be careful not to go overboard. Sprite maps should only include images that are actually referenced on the page. If you build a map with thousands of unused icons, that's only creating more bloat for yourself. ;)
+
+
+
+### When Not to Use a Sprite Map?
+
+Generally speaking, directly inlining an SVG makes more sense than using a sprite map if:
+* The image only appears once;
+* You need to be able to manipulate its `<path>`s at runtime for e.g. animation;
+* It has no `viewBox` or requires canvas overflow for proper display;
+
+
+
+## License
+
+See also: [CREDITS.md](CREDITS.md)
+
+Copyright © 2022 [Blobfolio, LLC](https://blobfolio.com) &lt;[email protected]&gt;
+
+This work is free. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2.
+
+    DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+    Version 2, December 2004
+
+    Copyright (C) 2004 Sam Hocevar <[email protected]>
+
+    Everyone is permitted to copy and distribute verbatim or modified
+    copies of this license document, and changing it is allowed as long
+    as the name is changed.
+
+    DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+    0. You just DO WHAT THE FUCK YOU WANT TO.

release/man/yesvgmap.1

@@ -1,40 +1,40 @@
-.TH "YESVGMAP" "1" "January 2022" "Yesvgmap v0.3.0" "User Commands"
+.TH "YESVGMAP" "1" "January 2022" "Yesvgmap v0.3.1" "User Commands"
 .SH NAME
-Yesvgmap \- Manual page for yesvgmap v0.3.0.
+Yesvgmap \- Manual page for yesvgmap v0.3.1.
 .SH DESCRIPTION
 Yesvgmap is a CLI tool for building SVG sprite maps from individual SVG images.
 .SS USAGE:
 .TP
-yesvgmap [FLAGS] [OPTIONS] <SVG(s)…>
+yesvgmap [FLAGS] [OPTIONS] <PATH(s)…>
 .SS FLAGS:
 .TP
 \fB\-h\fR, \fB\-\-help\fR
-Print help information.
+Print help information and exit.
 .TP
 \fB\-\-hidden\fR
-Hide with the 'hidden' attribute. Overrides \-\-offscreen if both are set.
+Hide the map using the 'hidden' HTML attribute. This takes priority over \-\-offscreen when both are present.
 .TP
 \fB\-\-offscreen\fR
-Hide by placing the element offscreen with inline styles.
+Hide the map using inline styles to position it offscreen.
 .TP
 \fB\-V\fR, \fB\-\-version\fR
-Print application version.
+Print version information and exit.
 .SS OPTIONS:
 .TP
 \fB\-l\fR, \fB\-\-list\fR <FILE>
-Read file paths from this text file.
+Read (absolute) file and/or directory paths from this text file, one entry per line.
 .TP
 \fB\-\-map\-class\fR <CLASS>
-A class attribute value to assign to the map itself. [default: ]
+Add this class to the generated SVG map. [default: ]
 .TP
 \fB\-\-map\-id\fR <ID>
-An ID attribute value to assign to the map itself. [default: ]
+Add this ID to the generated SVG map. [default: ]
 .TP
 \fB\-o\fR, \fB\-\-output\fR <FILE>
-A file path to save the generated map to. If not specified, the map will print to STDOUT.
+Save the generated map to this location. If omitted, the map will print to STDOUT instead.
 .TP
 \fB\-p\fR, \fB\-\-prefix\fR <PREFIX>
-Symbols will be assigned the ID 'prefix\-basename'. [default: icon]
-.SS <SVG(S)…>:
+Set a custom prefix for the IDs of each entry in the map. (IDs look like PREFIX\-STEM, where STEM is the alphanumeric portion of the source file name, e.g. 'i\-close'.) [default: i]
+.SS <PATH(S)…>:
 .TP
-Any number of files and directories to crawl and crunch.
+One or more file and/or directory paths to crunch and/or (resursively) crawl. Only files with the extension .svg will ultimately be included.

src/main.rs

@@ -169,25 +169,33 @@ USAGE:
     yesvgmap [FLAGS] [OPTIONS] <PATH(S)>
 
 FLAGS:
-    -h, --help                  Prints help information.
-        --hidden                Hide with the "hidden" attribute. Overrides
-                                --offscreen if both are set.
-        --offscreen             Hide by placing the element offscreen with inline
-                                styles.
-    -V, --version               Prints version information.
+    -h, --help                  Print help information and exit.
+        --hidden                Hide the map using the "hidden" HTML attribute.
+                                This takes priority over --offscreen when both
+                                are present.
+        --offscreen             Hide the map using inline styles to position it
+                                offscreen.
+    -V, --version               Print version information and exit.
 
 OPTIONS:
-    -l, --list <FILE>           Read file paths from this list.
-        --map-class <CLASS>     A class attribute value to assign to the map
-                                itself. [default: ]
-        --map-id <ID>           An ID attribute value to assign to the map
-                                itself. [default: ]
-    -o, --output <PATH>         A file path to save the generated map to. If
-                                not specified, the map will print to STDOUT.
+    -l, --list <FILE>           Read (absolute) file and/or directory paths
+                                from this text file, one entry per line.
+        --map-class <CLASS>     Add this class to the generated SVG map.
+                                [default: ]
+        --map-id <ID>           Add this ID to the generated SVG map.
+                                [default: ]
+    -o, --output <PATH>         Save the generated map to this location. If
+                                omitted, the map will print to STDOUT instead.
+    -p, --prefix <STRING>       Set a custom prefix for the IDs of each entry
+                                in the map. (IDs look like PREFIX-STEM, where
+                                STEM is the alphanumeric portion of the source
+                                file name, e.g. "i-close".) [default: i]
 
 ARGS:
-    <PATH(S)>...                One or more files or directories to crunch and
-                                crawl.
+    <PATH(S)>...                One or more file and/or directory paths to
+                                crunch and/or (resursively) crawl. Only files
+                                with the extension .svg will ultimately be
+                                included.
 "#
 	));
 }