Document usage

[kontur]

Hey,

apologies if this seems a trivial question. The project looks very useful and the premise makes sense to me, but as for understanding actual usage I am a bit puzzled.

Looking at the Usage section those commands make sense, but I don't understand how the make command is configured, where files need to be, and what exactly those do? Can one add others oneself to run via fontship?

If there any more documentation on that? Or where in the source code can I find those to dig deeper?

[alerque]

Fair enough, the documentation is slim. I started out with the best intentions with docs, then ripped most of them out because what I was actually doing was different than what I imagined it was going to be. I figured no documentation was better than documentation that pointed the wrong direction. Also the more font projects I've converted to use this the more I've tweaked the core defaults to just handle them out of the box. This makes for slim pickings for how it can be customized by a font project without needing to change the core.

I'll try to improve the docs, so as many specific questions as you ask will get priority getting answered and hopefully worked into documentation.

where files need to be, and what exactly those do?

As a birds eye view, the fontship cli command is more of a dispatcher. It does some things itself, but mostly it just shells out to other commands that it runs for you. Everything behind fontship make * just gets passed off to GNU make. When make is run it is setup with a bunch of relevant environment variables and default target recipes.

If you want to extend the available make targets there are various defaults that can be reset and you can even make up your own rules to add to a project. Just have a rules.mk file in the root of your repository and it will get injected via make -f rules.mk.

Can one add others oneself to run via fontship?

Yes. You can use it as a dispatcher to run virtually anything.

As as example of a project that extends the build system to do some extra/different work you can see Libertinus font's rules.mk that:

• Disables a couple types of files that would otherwise be built by default,
• Sets up a manual list of font faces and styles to generate rather than using the default discovery mechanism (which assumes that all faces have all styles, e.g. if you have 3 weights and 2 styles it assumes sources for all 6 instances should exist, the Libertinus project doesn't have some combos),
• Completely resets the template used to design OTF file targets to use a custom feature generation mechanism,
• Adds a target for generating the specimen images
• Adds targets for a special release bundle organized for publishing on CTAN.

Another extension method that is not documented at all: it's possible to customize the Docker images that run in CI environments to install custom dependencies before trying to build your targets. If you need a tool that's not included by default anything in the Arch Linux package ecosystem can be installed and/or even custom code injected.

[alerque]

Let me follow that up with this: I'm perfectly aware that GNU Makefile syntax is –to people not intimately familiar with *nix shell scripting and system automation– an extremely archaic syntax with confusing legacy idiosyncrasies and not what font design types that this system targets want to write code in. Hence the answer that "you can customize anything you want by intercepting GNU Make internals" is only going to garner the sarcastic kind of applause.

The goal of the project was/is to keep font projects from having to reinvent any wheels either in shell code or Python or makefile targets or anything else. As much as possible it should just understand font projects and build them properly, possible with a few easy to set configuration flags. The fact that it does let you do anything under the hood should be reserved for edge cases, not the standard way to use it.

As such I'd like to hear about any cases where it doesn't do the right thing out of the box to build fonts to the best specifications available. Besides helping in the short term with how to override / setup custom rules I'll also look at making the out of the box behavior smarter.

[kontur]

Thanks for the explanations. I agree it's best to have no help rather than misleading docs. As you inferred correctly I am not very familiar with makefile but have seen it often enough to have guessed that's where the magic happens in this project. I'll take a look at the sample projects using fontship to get a better idea. 👍

[alerque]

As you poke around don't spend too much time banging your head against any one topic before you ask. I'd be happy to field questions (in specific issues or intermittently in chat). Some of the info in my head needs to make in into documentation but the way I think about it is probably not the way a new user approaches the topics — sometimes real end user questions are a good trail of clues for what needs to get documented first.

[DavyOnGit]

It would be handy to have a complete example of how to build a project. For example: How would you make junction? https://github.com/theleagueof/junction

I cloned junction and ran docker run -it --volume "$(pwd):/data" --user "$(id -u):$(id -g) theleagueof/fontship:lates make all’ from the root of the project.
The output doesn’t indicate any error, but I don’t see anything being produced.

┏━ Welcome to Fontship ⁨v0.7.6⁩
┠─ Everything seems to be ship shape, anchors up!
┣━ Building target(s) using ‘make’
┗━ Fontship run complete

[alerque]

@DavyOnGit You did everything right, it just so happens that Junction is not outfitted for building at all yet, the sources are in a jumble. If you'd done exactly the same thing with any of the fonts that are ready (you can see from the README files whether there are build badges yet, all the ones that are easily buildable have Fontship badges in the README) it would have worked as you expected.

I'm working my way through the rest of the League's old font projects.