diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c6ffd26 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,82 @@ +# Contributing to Illuscape + +Thank you for helping make Inkscape more accessible to Illustrator migrants. + +## How to add a keyboard shortcut + +1. Open `config/keys/illustrator-cc.xml` and/or `config/keys/illustrator-cs6.xml` +2. Add a `` element: + ```xml + + ``` + Valid modifiers: `Primary` (Ctrl/Cmd), `Shift`, `Alt`. Omit `modifiers=""` for bare keys. +3. Find Inkscape action names via `inkscape --action-list` on your system +4. Update the shortcut table in `README.md` +5. Update the shortcut comparison table in the spec if the shortcut differs between CC and CS6 + +## How to add a color palette + +1. Create `config/palettes/YourPalette.gpl` following GPL format: + ``` + GIMP Palette + Name: Your Palette Name + Columns: 8 + # + 255 0 0 Red + ... + ``` +2. Add the filename to `uninstall.sh`'s `remove_files()` function so it gets cleaned up +3. The palette will be installed automatically by `install.sh` (it copies all `*.gpl` files) + +## How to add a document template + +1. Create an SVG at `config/templates/YourTemplate.svg` +2. Include a `sodipodi:namedview` element with appropriate canvas settings +3. Add the filename to `uninstall.sh`'s `remove_files()` function +4. The template will be installed automatically by `install.sh` (copies all `*.svg` files) + +## How to add a preference + +Preferences live in `config/preferences-patch.xml`. The XML merge algorithm (in +`scripts/merge_prefs.py`) does an upsert: it walks the patch tree, matches nodes +by their `id` attribute, and sets only the attributes present in the patch. It +never deletes nodes or attributes. + +To add a new preference: +1. Find the relevant node in Inkscape's `preferences.xml` on a running install +2. Add the node/attribute to `config/preferences-patch.xml` with the correct `id` values +3. Write a test in `tests/test_merge_prefs.py` that verifies the attribute is set +4. Run `conda run -n cf python3 -m pytest tests/test_merge_prefs.py -v` to verify + +## Running tests + +```bash +# Python unit tests (merge algorithm) +conda run -n cf python3 -m pytest tests/test_merge_prefs.py -v + +# Integration tests (requires bats-core) +bats tests/test_install.bats + +# Validate all config files +conda run -n cf python3 -c " +from xml.etree import ElementTree as ET +from pathlib import Path +for f in [*Path('config/keys').glob('*.xml'), *Path('config/templates').glob('*.svg'), + *Path('config/symbols').glob('*.svg'), Path('config/preferences-patch.xml')]: + ET.parse(f) + print(f'OK {f}') +" +``` + +## Commit format + +``` +feat: add +fix: correct +test: add test for +docs: update
+``` + +## License + +By contributing, you agree that your contributions are released under the MIT license. diff --git a/README.md b/README.md index c62601a..11b3033 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,26 @@ Illuscape patches Inkscape's config to match Illustrator's keyboard shortcuts, workspace layout, scroll/zoom behavior, color palettes, and document templates — without modifying Inkscape itself. +## What it does + +| Feature | Detail | +|---------|--------| +| Keyboard shortcuts | Adobe Illustrator CC or CS6 presets — your choice at install | +| Scroll/zoom | Mouse wheel pans (not zooms); Ctrl+wheel zooms — matching Illustrator | +| Canvas | White background, cyan guides, rubber-band selection (touching, not enclosed) | +| Node handles | Square handles, rotation handles hidden until needed | +| Palettes | Illustrator Defaults, Grays, and Earth Tones swatches | +| Templates | Letter, A4, Web 1920x1080, Web 1280x720, Print CMYK Letter, Print CMYK A4 | +| Symbols | Common symbol library (arrows, checkmark, star, cross) | +| Recent files | 20 (matching Illustrator; Inkscape default is 4) | +| Single-window mode | On by default | + +## Requirements + +- Inkscape 1.2 or later +- Python 3.8+ +- Bash 4+ + ## Install ```bash @@ -14,7 +34,21 @@ cd illuscape ./install.sh ``` -Follow the prompt to select your Illustrator era (CC or CS6), then open Inkscape. +Follow the prompt to choose your Illustrator era (CC or CS6), then open Inkscape. + +### Non-interactive (for scripts / MenagerieOS) + +```bash +./install.sh --preset=cc --yes +# or +./install.sh --preset=cs6 --yes +``` + +### Supported Inkscape installs + +- Native (apt, pacman, etc.) +- Flatpak (`org.inkscape.Inkscape`) +- Snap ## Uninstall @@ -22,8 +56,46 @@ Follow the prompt to select your Illustrator era (CC or CS6), then open Inkscape ./uninstall.sh ``` -Your original Inkscape config is restored from backup. +Your original Inkscape config is restored from the backup created at install time. + +## Tool mapping from Illustrator to Inkscape + +| Illustrator tool | Key | Inkscape equivalent | +|-----------------|-----|---------------------| +| Selection | V | Selection tool | +| Direct Selection | A | Node tool | +| Pen | P | Pen tool | +| Pencil | N | Pencil tool | +| Paintbrush | B | Calligraphy tool | +| Type | T | Text tool | +| Rectangle | M | Rectangle tool | +| Ellipse | L | Ellipse tool | +| Rotate | R | Transform > Rotate | +| Scale | S | Transform > Scale | +| Reflect | O | Transform > Flip | +| Gradient | G | Gradient tool | +| **Mesh** | **U** | **Mesh Gradient tool (direct equivalent)** | +| Eyedropper | I | Dropper tool | +| Zoom | Z | Zoom tool | +| Hand | H / Space | Pan (Space held) | +| Scissors | C | Scissors tool | +| Eraser | Shift+E | Eraser tool | +| Blob Brush | Shift+B | Spray tool (paint mode) | +| Symbol Sprayer | Shift+S | Spray tool (clone mode) | +| Live Paint | K | Paint Bucket tool | + +## Planned extensions (post-v1) + +- Artboards panel +- Character Styles +- Recolor Artwork +- Object Styles +- Export for Screens (1x/2x/3x batch) + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md). ## License -MIT +MIT — see [LICENSE](LICENSE).