d-bl / GroundForge

Bobbin Lace Diagrams : threads from pairs
https://d-bl.github.io/GroundForge/
GNU General Public License v3.0
12 stars 7 forks source link
bobbin-lace d3js svg

Build Status

A toolbox to design bobbin lace grounds with matching sets of pair/thread diagrams.

The table of contents icon in the top left corner of this document gets you to a specific section quickly.

Short intros

for end users (bobbin lace makers and designers):

See https://d-bl.github.io/GroundForge/

for developers:

licenses

The help pages and examples have a CC-BY license. The code has a GPL-v3 license.

Diagrams created by you and saved as link and/or images are owned by you and/or the original authors in cases you adapted or embedded a definition by someone else.

Note that individual diagram definitions may or may not meet the threshold of originality. A stitch may be traditional yet take creativity to define with GroundForge, as shown by the discussion that started with this message. Others may be new but not take much "sweat of the brow".

You are responsible for publishing your work under a license of your choosing and tracking your use of derivative works. Downloaded diagrams don't come with properties expressing origin, author or license, you will have to add that information yourself with your favourite editor.

Contribute to documentation

You are welcome to help us to make GroundForge a better place for bobbin lace makers and designers.

Get started

You can start humble with fixing typos and grammer or rewrite sections once you figured out what confused you at first. Note that you will work on a personal copy, once notified, a moderator can merge your proposal in the official version.

Github elaborates the following procedure (and more) to propose changes to the help pages and catalogues. A shortcut into this procedure starts near the bottom of the sidebar on the published pages:

Please don't be shy, any little improvement is good enough and welcome. Forget perfection, even disputable suggestions may inspire something better. Also note that little quickly made changes hardly need coordination, so go ahead, drops can build a river.

Note for moderators:
When you have write rights for a repository, the green button to save your changes will show commit changes and the change will be effective immediately. To first discuss you changes through a pull request, check the radio button to Create a new branch, the big green button then changes to propose changes.

Preview more complex changes

The preview by the editor is not always exactly what-you-see-is-what-you-get. There might be some broken images, broken links or illegible content. Publishing your personal repositories helps to check whether everything renders and links properly.

The help pages and catalogues are spread among several repositories in the pseudo-organisation d-bl (Diagrams for Bobbin Lace):

create forks for all projects: links to sidebars: identical sidebars
please keep these up-to-date
GroundForge X X
GroundForge-help X X
gw-lace-to-gf X
tesselace-to-gf X
MAE-gf X

Pages may have their own internal table of content. Please keep them up-to-date too.

To preview a rendered version of the pages:

Multiple updates in a single pull request

The github workflow works best an app but that might be a big learning curve. So here an introduction to a workaround.

Each time you edit a page via its 'propose changes' link, a patch branch is created in your personal fork of the repository. Until a pull request is merged (you'll get notified of the fact), you can continue making updates to a patch branch. You can find your branches with https://github.com/YOUR_ACCOUNT/REPO_NAME/branches. Select the desired branch and with the go to file button, you will arrive at https://github.com/YOUR_ACCOUNT/REPO_NAME/find/YOUR_PATCH. Type fragments of the file name you have been changing or want to change too and continue editing.

Accidentally created multiple patches intended for a single pull request?
Go to https://github.com/YOUR_ACCOUNT/REPO_NAME/compare select which branches you want to become one, create a pull request and merge it yourself.
Read more...

Conventions

licenses

The license in the sidebar should apply to all content on all pages that use the sidebar. In case of exceptions use "Some rights reserved", linking to an explanation of the general rule. Exceptions should be placed as close to the relevant artifacts as possible, preferably with Creative Commons icons.

metadata

A mark-down pages start with a metadata section, something like

---
layout: default
title: XYZ
---

Browsers show XYZ as tab title. Keep it short and catchy. Other lines might have a more technical purpose. Don't touch them, unless you know what you are doing.

links

Thumbnails in catalogues are the biggest target and should point to the pattern definition. If available, use a sample of real lace, otherwise the thread diagram.

Use root relative links for references between the repositories. Thus following links keeps you in your personal set of repositories when verifying your changes beyond the editor preview.

scalable prickings

Images might be intended to download for further processing. Vector based images (such as SVG) are scalable and hence suit that purpose better than pixel based images. SVG images can be altered by 3rd party applications like Inkscape, Affinity Designer, Adobe Illustrator and CorelDraw.
Knipling can export PDF. When you just want a section of some design, save a (temporary) copy of the pattern, delete the rest, then export the PDF. Import into Inkscape (for example) to save as SVG.

language

Currently, we have a mix of UK and US spelling.

Functional contribution

Requirements

Work flow

Should you want to test changes for the tiles page, you can try a local build with Jekyll, this requires some hoops to jump through. Alternatively, you can configure your online project to publish your topic branch

at https://github.com/YOUR_ACCOUNT/GroundForge/settings/pages:

screen snippet

Code conventions

Tests

Use mvn clean test to run unit tests. As some tests read pattern links from help files using java-io, the test fail with SBT. Maven is much faster but uses JVM while the JS used by SBT is the actual target environment. Some classes under src/test are suffixed with Demos rather than Spec these runnable objects create SVG documents in a target/test directory for a visual check.

The tiles page requires Jekyll compilation or deploy on github, For a quicker visual test cycle of the diagrams you can make use of docs.html or the pages located in docs/API.

For manual tests with other browsers and devices than your own, you can sign-up (for free, since this project is open source) at
BrowserStack

Use as JavaScript Library

The demo's mentioned above use the scala code as a JavaScript library as explained under short intro for developers. Other mash ups and more user-friendly applications could be wrapped around the library.

Use as JVM library

A JVM library allows server-side or batch processing.

The Demo4Java.java between the test classes is a simple plain java main class example that generates diagrams. This example uses the code in src/main as a Java library.

In a plain JVM environment, you'll need at least on your classpath:

For a maven/scala-sdk-2.12 environment: