@4u6u57/dotfiles/bin/repo-iconify/README.md

August Valera's preferences for Linux

# repo-iconify

A simple shell script that overlays text over an image, for use in creating unique
logos for your VCS repositories.

## Example

The easiest way to describe what this does is to show an example. This is the logo for this repository.

![logo](./logo.png)

It was generated with the following configuration, stored within a `.repo-iconify` file in the current directory.

```bash
InputFile=~/.face
Color=white
Background="#EF6C00"
Text=ICON
Direction=east
Suffix=" "
Offset=+0-70
```

This file can be summarized as follows:

- The base image (input file) is my Linux profile picture, found in `~/.face`
- Text color is set to white
- Background color is set to a hex value, which is a shade of orange
- The actual text contents is the word "ICON"
- Direction (location of text) is set to east (the right of the image)
- After `$Text`, the suffix (a single space) is added for spacing
- Offset is set to horizontal: 0px, vertical -70px. This has the effect of shifting the text up 70 pixels

## Full Specification

Generate an icon by running `repo-iconify` in the current directory. To get a good looking one, you will want to specify preferences in a `.repo-iconify` configuration file. On runtime, `repo-iconify` traverses through the directory tree, and applies all configurations found within, prioritizing ones lower down (closer to the current directory).

### Options

The following is a list of options than can be specified in a `.repo-iconify` file.

- `InputFile` Path to image source
- `Color` Color of text
- `Background` Color of background
- `Outline` Color of text outline
- `Text` Text string, required nonempty
- `Prefix` Prefix to text
- `Suffix` Suffix to text
- `Point` Text size, in pts
- `Stroke` Outline weight, in pts (acts as text weight if outline color is same as text, as default)
- `Direction` Text position, one of `{north, south, east, west, northeast, ...}`
- `Offset` Offset from direction, horizontal then vertical concatenated. Example: `-10+20` means left 10 pixels, down 20 pixels
- `OutputFile` Path of image output, with file extension (proper file will be created, depending on extension given)

As a `.repo-iconify` file is simply a script that is executed, these options can be complex and reference each other, as well as other macros provided, like so:

```bash
Direction=east
Offset=+0-$((Height / 4))
```

The ```$(( ... ))``` operator is the Bash arithmetic operator, and thus we are shifting the text up 1/4th of the height of the full image, centering it on the north-northeast line.

### Macros

The previous point brings up the subject of macros, which are procedurally generated variables you can use in your configuration files. These are:

- `Root=true` Setting `Root` to `true` in a configuration sets the current directory as pthe root of the configuration tree, and prevents further traversal up the directory tree in search of higher configuration files
- `GenerateImageData` Placing this line in a configuration file, provided that `InputFile` has already been defined in that file or in a higher file, and provided that that file exists, generates the following macros for your disposal:
    - `Height` Height of the image, in px
    - `Width` Width of the image, in px
    - `MinDim` Minimum dimension, the minimum of `Height` and `Width`
- `FullText` This variable should not be declared in most cases, as it is generated by the program as the concatenation of `Prefix`, `Text`, and `Suffix`. However, if it is overwritten in a config, then `Prefix`, `Text`, and `Suffix` are ignored.

## Defaults

In lieu of any modifications within a `.repo-iconify`, these are the default settings given. Note that this will not work, as `Text` is set empty, and thus the program will error out.

```bash
InputFile=~/.face
Color=white
Background=black
Outline=$Color
Text=""
Direction=east
Offset=+0+0
OutputFile=logo.png
Point=$((MinDim * 7 / 10 / 4))
Stroke=$((Point / 20))
FullText="$Prefix$Text$Suffix"
```

The `Point` field is set as the minimum dimension of image, multiplied by 0.7 (which is the approximate point/pixels ratio, 7.5 pt font being 10 px high), and then divided by 4, to make a quarter of the minimum dimension (which, if the minimum dimension is height, is equivalent to the quarter the height of the image).

The `Stroke` is set to 1/20th of the `Point`, which is slightly bold.

## Command Line Arguments

Although, with the default configuration, `repo-iconify` will not process (as `$Text` is not specified), you do not need to create a `.repo-iconify` configuration file yourself to use this utility. An easier way is to specify command line arguments on runtime to `repo-iconify`, and the program will append (or replace) these options in the local (current directory) `.repo-iconify` config and then execute them with these changes reflected. For example, the icon displayed at the top of this README could have been accomplished with running:

```bash
repo-iconify Color=white Background="EF6C00" Text=ICON Suffix=" " Offset=+0-70
```