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.
See https://d-bl.github.io/GroundForge/
src/scala/main/*
is translated to : docs/js/GroundForge-opt.js
docs/js/*.js
src/test/Demo4Java.java
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.
You are welcome to help us to make GroundForge a better place for bobbin lace makers and designers.
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:
propose change
.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
.
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:
patch
branch mentioned by your pull request.https://github.com/YOUR_ACCOUNT/REPO_NAME/settings/pages
:https://YOUR_ACCOUNT.github.io/REPO_NAME
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...
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.
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.
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.
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.
Currently, we have a mix of UK and US spelling.
tiles.md
file. See the workflow.src/main/scala/
into docs/js/GroundForge-opt.js
:/docs/js
.
Depending in your OS use the one liner in toJS.sh
or toJS.bat
the latter is not battle proven.docs/*.html
pagesShould 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
:
Try
as exceptions terminate the JavaScript.
The tests might succeed with maven, but the JavaScript breaks.
Prevent exceptions like illegal arguments and indexes and return a Failure
for safe execution with JavaScript.LinkProps
and NodeProps
as a map.
Caused by the initial proof of concept starting with plain JavaScript by modifying D3js examples.
So far no success in phasing out this heritage.
However, these maps are hidden from the world outside these two classes as much as possible.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
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.
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
:
.jar
from the last release
or a self-built one.pom.xml
For a maven/scala-sdk-2.12 environment:
maven clean install
in the unzipped directorypom.xml
of your own project
<dependency>
<groupId>io.github.d-bl</groupId>
<artifactId>GroundForge</artifactId>
<version>0.x-SNAPSHOT</version>
</dependency>