Add basic readme to explain installation and usage

thundernixon commented 5 years ago

Thanks to @benkiel and @frankrolf for introducing and explaining this tool on a Twitter thread.

I felt a little uncertain coming into this repo, so I put together a very basic guide, partially based on the README of https://github.com/googlefonts/gftools.

The basic description of the tool is quoted from Ben. Examples of formatting are observations from running the tool on a (very new) UFO of my own.

Thoughts:

If it's useful to add more examples of what formatting is applied, I'm happy to do so (I'm also happy for this to be expanded upon by others, of course).
If it would be beneficial to link to a guide on virtual environments, I can also add that.

Question:

Is there a good way to integrate this into a workflow? For instance, is there some way to configure git to run formatting when files are staged, or a good way to watch UFO files for changes, to then format? If so, that might be really useful to add to this README.

Thanks for a useful tool! Hope my small addition is helpful.

benkiel commented 5 years ago

This looks good, it may also be nice to add a note about hooking the Normalizer to a git hook. Do you have a pre-commit hook script @frankrolf that could be contributed to this? If not, I could throw one together.

frankrolf commented 5 years ago

I think it would be good to merge this for now. I have not used git hooks, I am curious how they’d be useful in this case. I used to just normalize before committing, and now use RoboFont’s setDefault("shouldNormalizeOnSave", True), which comes with a few drawbacks (such as popup windows).

thundernixon commented 5 years ago

RoboFont’s setDefault("shouldNormalizeOnSave", True), which comes with a few drawbacks (such as popup windows).

I wasn’t aware that RoboFont had a built-in (?) option. Can people use this tool in RoboFont without downloading the library?

If so, I’ll add that suggestion. I think I’ll also add the note about the pop up window citing changes, as that might throw people off at first. -- ——

Stephen Nixon

www.thundernixon.com

davelab6 commented 5 years ago

Git hooks still worth mentioning, since it seems many type people using git don't know they are available

thundernixon commented 5 years ago

Git hooks are so cool! I wasn't aware of them until now. I've added both Frank's suggested method and a simple method for using Git hooks.

@frankrolf do people still need to pip install ufoNormalizer to set RoboFont to normalize on save? If not, I'll update this to say that no download is necessary if they wish to use work in that way.

thundernixon commented 5 years ago

...Actually, I'm realizing that attaching this to the pre-commit event means that the lib.plist UFO files are seeming to end up as always-modified and never shown as up-to-date. Might there be a better Git event to assign this to?

benkiel commented 5 years ago

@thundernixon It does not need to be installed, it is embedded in Robofont (https://robofont.com/technical-specification/#embedded-libraries)

thundernixon commented 5 years ago

it is embedded in Robofont

Oh, excellent! I'll move that bit up in the readme, then. Thanks for the link

benkiel commented 5 years ago

@thundernixon is the pre-commit issue that the modification time is changed? If so, fee it the -m option

benkiel commented 5 years ago

Which raises, perhaps it'd be nice to list the various command line options? https://github.com/unified-font-object/ufoNormalizer/blob/ea37f454f14f77334196595afcf0201a6ac19417/src/ufonormalizer.py#L40

Sorry for the extra work/hassle!

frankrolf commented 5 years ago

I was thinking of completing the readme after this has been pushed. No need to bother @thundernixon more than necessary! ;-)

thundernixon commented 5 years ago

@benkiel it would be great to list command line options! I left that out because I wasn't sure how stable those were, and wasn't sure how much others would want to maintain the readme.

If @frankrolf is up for adding that after the readme is merged, I'm happy with that.

Git hooks problem

As for my git hook issue (let me know if I should add this to the actual /issues in the repo), I've disabled the ufoNormalizing preference in RoboFont, and here's whats happening.

I make a change to an outline. In this case, I've tweaked the weight of an /s. I add all changes:

-----------------------------------------------------------------------------------
🍕 ➡️ git add .
-----------------------------------------------------------------------------------

I check the status. I see the modified /s file, plus other metadata stuff, as expected:


-----------------------------------------------------------------------------------
🍕 ➡️ git status
-----------------------------------------------------------------------------------
On branch master
Your branch is ahead of 'origin/master' by 1 commit.
(use "git push" to publish your local commits)

Changes to be committed: (use "git reset HEAD ..." to unstage)

modified:   Route Sans-Display Bold.ufo/fontinfo.plist
modified:   Route Sans-Display Bold.ufo/glyphs.background/contents.plist
modified:   Route Sans-Display Bold.ufo/glyphs.background/layerinfo.plist
modified:   Route Sans-Display Bold.ufo/glyphs/contents.plist
modified:   Route Sans-Display Bold.ufo/glyphs/layerinfo.plist
modified:   Route Sans-Display Bold.ufo/glyphs/s.glif
modified:   Route Sans-Display Bold.ufo/layercontents.plist
modified:   Route Sans-Display Bold.ufo/lib.plist
modified:   Route Sans-Display Bold.ufo/metainfo.plist


3. I run my commit with a message. It normalizes the UFOs, _then_ records the changes in Git.

🍕 ➡️ git commit -m "lighten /s slightly"

Normalizing "Route Sans-Bold.ufo". Normalization complete (0.0232 seconds). Normalizing "Route Sans-Display Bold.ufo". Normalization complete (0.2146 seconds). [master 74aaade] lighten /s slightly 9 files changed, 736 insertions(+), 747 deletions(-) rewrite Route Sans-Display Bold.ufo/fontinfo.plist (84%) rewrite Route Sans-Display Bold.ufo/glyphs.background/contents.plist (80%) rewrite Route Sans-Display Bold.ufo/glyphs.background/layerinfo.plist (78%) rewrite Route Sans-Display Bold.ufo/glyphs/contents.plist (97%) rewrite Route Sans-Display Bold.ufo/glyphs/layerinfo.plist (95%) rewrite Route Sans-Display Bold.ufo/glyphs/s.glif (95%) rewrite Route Sans-Display Bold.ufo/lib.plist (96%)


4. I would now expect the git status to be "nothing changes to commit." However, when I check it (having made no deliberate changes), I see:

🍕 ➡️ git status

On branch master Your branch is ahead of 'origin/master' by 2 commits. (use "git push" to publish your local commits)

Changes not staged for commit: (use "git add ..." to update what will be committed) (use "git checkout -- ..." to discard changes in working directory)

modified:   Route Sans-Bold.ufo/lib.plist
modified:   Route Sans-Display Bold.ufo/fontinfo.plist
modified:   Route Sans-Display Bold.ufo/glyphs.background/contents.plist
modified:   Route Sans-Display Bold.ufo/glyphs.background/layerinfo.plist
modified:   Route Sans-Display Bold.ufo/glyphs/contents.plist
modified:   Route Sans-Display Bold.ufo/glyphs/layerinfo.plist
modified:   Route Sans-Display Bold.ufo/glyphs/s.glif
modified:   Route Sans-Display Bold.ufo/layercontents.plist
modified:   Route Sans-Display Bold.ufo/lib.plist
modified:   Route Sans-Display Bold.ufo/metainfo.plist

no changes added to commit (use "git add" and/or "git commit -a")


5. It's not until I _rerun_ add, then commit, then status, that I see what I expect:

🍕 ➡️ git add .

🍕 ➡️ git commit -m "normalizer"

Normalizing "Route Sans-Bold.ufo". Normalization complete (0.0202 seconds). Normalizing "Route Sans-Display Bold.ufo". Normalization complete (0.2117 seconds). [master 0bad8da] normalizer 10 files changed, 748 insertions(+), 737 deletions(-) rewrite Route Sans-Display Bold.ufo/fontinfo.plist (84%) rewrite Route Sans-Display Bold.ufo/glyphs.background/contents.plist (81%) rewrite Route Sans-Display Bold.ufo/glyphs.background/layerinfo.plist (78%) rewrite Route Sans-Display Bold.ufo/glyphs/contents.plist (97%) rewrite Route Sans-Display Bold.ufo/glyphs/layerinfo.plist (95%) rewrite Route Sans-Display Bold.ufo/glyphs/s.glif (96%) rewrite Route Sans-Display Bold.ufo/lib.plist (96%)

🍕 ➡️ git status

On branch master Your branch is ahead of 'origin/master' by 3 commits. (use "git push" to publish your local commits)

Changes not staged for commit: (use "git add ..." to update what will be committed) (use "git checkout -- ..." to discard changes in working directory)

modified:   Route Sans-Bold.ufo/lib.plist
modified:   Route Sans-Display Bold.ufo/lib.plist

no changes added to commit (use "git add" and/or "git commit -a")



Have I written the Git Hook incorrectly? Is it set to the wrong Git event? I'm just following the suggestion in the current version of my readme.

This does seem like a genuinely handy way to use ufoNormalizer, but as I've currently set it up, this is giving me a bunch of _extra_ Git noise 😄

benkiel commented 5 years ago

tbh, I don't know much about git hooks, so I'm not sure... I think this could be merged as is for now, however. @miguelsousa I think you can do so?

miguelsousa commented 5 years ago

Yes, merging...

unified-font-object / ufoNormalizer