It’s summer, which means its time for GSoC/Outreachy. This is the third year the Crosswords team is participating, and it has been fantastic. We had a noticeably large number of really strong candidates who showed up and wrote high-quality submissions — significantly more than previous years. There were a more candidates then we could handle, and it was a shame to have to turn some down.

In the end, Tanmay, Federico, and I got together and decided to stretch ourselves and accept three interns for the summer: Nancy, Toluwaleke, and Victor. They will be working on word lists, printing, and overlays respectively, and I’m so thrilled to have them helping out.

A result of this is that there will be a larger number of Crossword posts on planet.gnome.org this summer. I hope everyone is okay with that, and encourages them so they stay involved with GNOME and Free Software.

Release

This last release was mostly a bugfix release. The intern candidates outdid themselves this year by fixing a large number of bugs — so many that I’m releasing this to get them to users. Some highlights:

• Mahmoud added an open dialog to the game and got auto-download of puzzles working. He also created an arabic .ipuz file to test with which revealed quite a few rendering bugs.

• Toluwaleke refined the selection code. This was accidentally marked as a newcomer issue, and was absolutely not supposed to be. Nevertheless, he nailed it and has left selection in a much healthier state.
  • [ It’s worth highlighting that the initial MR for this issue is a masterclass in contributions, and one of the best MRs I’ve ever received. If you’re a potential GSoC intern, you could learn a lot from reading it. ]
• Victor fixed divided cells and a number of small behavior bugs. He also did methodical research into other crossword editors.

• Patel and Soham contributed visual improvements for barred and acrostic puzzles

In addition, GSoC-alum Tanmay has kept plugging on his Acrostic editor. It’s gotten a lot more sophisticated, and for the first time we’re including it in the stable build (albeit as a Beta). This version can be used to create a simple acrostic puzzle. I’ll let Tanmay post about it in the coming days. 

Coordinates

Specs are hard, especially for file formats. We made an unfortunate discovery about the ipuz spec this cycle. The spec uses a coordinate system to refer to cells in a puzzle — but does not define what the coordinate system means. It provides an example with the upper left corner being (0,0) and that’s intuitively a normal addressing system. However, they refer to (ROW1, COL1) in the spec, and there are a few examples in the spec that start the upper left at (1, 1).

When we ran across this issue while writing libipuz we tried a few puzzles in puzzazz (the original implementation) to confirm that (0,0) was the intended origin coordinate. However, we have run across some implementations and puzzles in the wild starting at (1,1). This is going to be pretty painful to untangle, as they two interpretations are largely incompatible. We have a plan to detect the coordinate system being used, but it’ll be a rough heuristic at best until the spec gets clarified and revamped.

By the Numbers

With this release, I took a step back and took stock of my little project. The recent releases have seemed pretty substantial, and it’s worth doing a little introspection. As of this release, we’ve reached:

• 85KLOC total. 60KLOC in the app and 25KLOC in the library
• 27K words of design docs (development guide)
• 126 distinct test cases
• 33 different contributors. I’m now at 82% of the commits and dropping
• 6 translations (and hopefully many more some day)
• Over 100 unencumbered puzzles in the base puzzle sets. This number needs to grow.

All in all, not too shabby, and not so little anymore.

A Final Request

Crosswords has an official flatpak, an unofficial snap, and Fedora and Arch packages. People have built it on Macs, and there’s even an APK that exists. However, there’s still no Debian package. That distro is not my world: I’m hoping someone out there will be inspired to package this project for us.

GUADEC was in Denver this year! I meant to write an update right after the conference, but Real Life™ got in the way and it took a while to finish this post. I finally found a little spare time to collect my thoughts and finish writing this.

It was a smaller crowd than normal this year. There were ~100 people registered, though unfortunately a number of people were unable to make it at the last minute due to Cloudstrike– and visa– related issues.

I gave two talks: Crosswords, Year Three (slides) and a spur-of-the-moment lightning talk on development docs. The first talk was nominally about authoring crosswords, but I also presented the architecture we used to create the game. Although rushed, I hope I got most of the points about our design across. It’s definitely worth a full blog post at a future date.

Other highlights of the conference included Martin’s very funny (and brave) live demo of gameeky, Scott’s talk about being bold with design, the AGM, and a fabulous Thunderbird keynote about the power of money. That last one spurred conversations about putting a fundraising request popup in GNOME itself to raise funds. The yearly popup in Thunderbird appears to continue being wildly successful. Since GUADEC, I see that KDE has attempted to do that as well. I’d love for GNOME to do something similar. Maybe this is something the new board can pick up.

It was a very chill GUADEC, and I enjoyed the change of pace. I had never spent time in Denver (other than at the airport), and found it to be a surprisingly intimate city with a very walkable downtown. The venue was absolutely fabulous. Every conference should have a pub on-site, and the Tivoli Brewing Co definitely surpassed expectations. It even has an original Nikolai Tesla generator in its basement.

Reflections

It was really nice having GUADEC relatively close to me for once. There was a different crowd than normal: there were long-time GNOME people I haven’t seen in a very long time (Hi Owen, Behdad, and Michael!) as well as numerous new folks (welcome Richard!) Holding it in North America opened us up to different contributors, and maybe let us reengage with long-time gnomies.

On the other hand, it did feel like the community was split. Sam said it extremely well in his blog post.

Let’s not pretend that a video conference or a hybrid BOF is the same as an in-person meetup. Once you’ve sung karaoke with someone, or explored Meow Wolf, or camped in the desert in Utah together, your relationship is richer than when you only interacted via Gitlab pull requests and BigBlueButton. You have more empathy and you can resolve conflicts better.

Fragmentation is always a danger with distributed endeavors and any group bigger than two will have politics, but it feels like our best tool to deal with those issues is fragmenting too.

Personally, as someone who has schlepped across the Atlantic for over two decades to meet with other folks, it doesn’t feel great to have comparatively few people come the other direction. There are a plenty of good individual decisions that lead to this, but collectively it felt like a misfire.

I also really appreciate the commitment of our South American / Asian / African developers who have tough travel routes to get to the Euro/American events.

In some sense, it feels like we’ve gone full-circle. When GNOME started, development was strongly centered in North America. The GIMP started in Berkeley, and GNOME itself was founded in Mexico, and there were quite a few other pockets of GNOME activity (Boston, North Carolina, etc). Proportionally, Europe was underrepresented — so GUADEC was proposed as a way to build a European community. It took sustained engagement to build it up. Twenty-four years on, it appears we need to do the reverse.

What’s next? Well for me, it’s time to look more local. We used to have a Bay Area GNOME community and it has fallen on hard times. Maybe it’s worth trying to push some local enthusiasm. If you’re a Bay Area GNOME person, drop me a note. We should hold a release party!

Nonograms

While in Denver, ptomato and I nerd-sniped each other into writing a nonogram game. Nonograms are a popular puzzle-type, and are quite common on existing mobile platforms. Conceptually, they’re pen-and-paper grid-based games and could easily be implemented as an .ipuz extension.

I’ve been slowly changing the libipuz API over the summer to work with gobject-introspection, and was excited at the chance to get someone to test it out. Meanwhile, Philip had been wanting to write an app with typescript. So, I sketched out an extension and put together an API for Philip to use. With a little back-and-forth, he got something to render. Exciting!

I don’t think it is playable yet but it’s lovely to see the potential emerging. There’s a lot of great pixel art floating around GNOME. Some of it might make the basis for a really fun nonogram game.

As a bonus, Philip has been experimenting with using the stateless design we use in Crosswords. I’m hoping he’ll be able to provide additional validation and feedback to our architectural approach.

It’s time for another Crosswords release.

I’ll keep this update short and sweet. I had grand plans last cycle to work on the word data and I did work a little on it — just not in the way I intended. Instead, a number of new contributors showed up which sent me in a different direction. I’m always happy to get new contributors and wanted to make sure they had a good experience. It ended up being a fun set of side quests before returning to the main set of features in the editor.

Cursor behavior

New contributor Adam filed a series of absolutely fantastic bug reports about the cursor behavior in the game. Adam fixed a couple bugs himself, and then pointed out that undo/redo behavior is uniquely weird with crosswords. Unlike text boxes, cursors have a natural direction associated with them that matters for the flow of editing.

In a nutshell, when you undo a word you want the cursor to be restored at the same orientation as where it was at the start of the guess. On the other hand, when redoing a guess, you want the cursor to advance normally, which might be in a different place or orientation. It’s subtle, but is the kind of user touch that you would normally never notice. It just feels “clunky” without a fix. With all these changes, the cursor behavior feels a lot more natural.

Can you spot the difference?

Selections and Intersections

Another side quest was to change the Autofill dialog to operate in-place. I foolishly thought that this would be a relatively quick change, but it ended up being a lot more work than expected. I’ll spare the details, but along the way, I also had to add three more features as dependencies.

First, I’ve wanted a way to leave pencil markings for a long time. These would transient markings that show possibilities for a square without marking. We use it to show the results of the in-place autofill operation.

Second I fixed an old bug that I’ve wanted to fix for a long time. Previously, the word list showed all possible words independently. Now it only shows words that show in both directions. As an example, in the grid below we don’t show “ACID — (80)”  in the Down list as that final “D” would mean the Across clue would have “WD” as its prefix.

This required writing code to efficiently calculate the intersection of two lists. It sounds easy enough, but the key word here is “efficient”. While I’m sure the implementation could be improved, it’s fast enough for now for it to be used synchronously.

Finally, I was able to use the intersection function to optimize the autofill algorithm itself. It’s significantly faster also more correct than the previous implementation, which means that the resulting boards will be more usable. It still can’t do a full 15×15 grid in a reasonable time, but it can solve about 1/3 of a grid.

Other

• Federico and I are working with Pranjal as a GSOC student for the summer. He’s going to work on porting libipuz to rust, and we spent a good amount of time planning the approach for that as well as prepping the library.
• Tanmay has continued to work on the acrostic generator as part of last summer’s GSoC project. I’m so proud of his continued efforts in this space. Check out his recent post!
• Gwyneth showed up with support for UTF-8 embedding in puz files as well as support for loading .xd crossword files.
• I updated our use of libadwaita widgets to the latest release, and enabled style settings per-cell in the editor.

Until next time!

Happy 2024! It’s time for the first GNOME Crosswords update of the year. A ton of work happened since the last release — primarily in the Editor. I’ll try to keep this update short and sweet. Packages will be available in flathub momentarily.

Move to libadwaita-1.4

The biggest visual change is that we moved away from libpanel in the Editor window. I found I was fighting with that library constantly due to the mode changes in the Editor, and I wasn’t able to take advantage of many of libpanel’s cooler features. Ultimately, libpanel wasn’t designed for workspaces and it looked like it would be a prohibitive amount of work to add them. Instead, I’m using an AdwOverlaySplitView, custom paned widget, and a lot of GtkStacks. This results in a cleaner appearance at the cost of a lot of flexibility. As an additional plus, it gives the Editor the snazzy two-toned look that’s currently in vogue:

The plan for the bottom of the content section is to provide some useful information for whatever operation was being shown. I put in some rudimentary statistics about the grid, as well as some basic support for authoring clues. I added three simple sections just to get something up and running: Anagrams, Odds, and Evens. The anagram calculations was based on work done by Pratham for his GSoC project. I was able to finish it and incorporate it into the UI.

Also, note that the histogram bars are rendered via GtkLabels with repeated block characters (U+2588). Thanks to Christian for that great suggestion — it was a quick way to get something visible.

Stateless Apps

For this release, we fully embraced a stateless control flow for the Editor. Federico and I have been talking about this for a while and it took some experimenting to find a model that works well. But given the complexity of the app (data and flow), it ended up simplifying the codebase substantially.

A neat example of why this is useful: there are three distinct grids in the main content section for each stage (GRID, CLUES, and STYLE). Instead of using the traditional GtkStack to swap between them, I’m able to simply swap out the state to render the correct one.

What’s next?

Word data

It’s become clear that the most important feature needed for the editor to be competitive is to improve the word list and the clue authoring section. Both the data and the filtering code need to be revisited. The word list code was originally written just for the autofill dialog and had to be fast for that. But as it’s progressed we’ve needed a lot more flexibility with the filtering. I don’t want to implement full regexp support as it won’t be fast enough, but something like nutrimatic might be more warranted (though it can be slow as well).

The data, too, needs attention. The Broda word-list is serviceable, but provides options that aren’t appropriate for all puzzles. A co-worker pointed me to the free wordnik wordlist, which I was able to add as a compile-time alternative. Libreoffice also has its own wordlists, though they aren’t designed for puzzle writing. But beyond the words, I’m going to need:

• Definitions of words
• Synonyms of words
• Multi-word combos (along with punctuation)
• Word frequency counts, to give prioritization to words/phrases
• Offline support. As much as possible, not requiring network access is preferred

In addition, to the extent there’s interest, I’d love to support this in other languages beyond English.

I know there are a number of options for these already for free desktops. If you work in this space (or are interested in seeing GNOME’s options improved here) drop me a line.

Acrostics

I also want to highlight that Tanmay has continued to work hard on Acrostic support long after his GSoC internship ended. Not content with just adding acrostic support to the game, he has been adding acrostics to the Editor as well. It’s turned out to be quite a hard problem, with a lot of algorithmic complexity involved with auto-generating the grid in a reasonable amount of time. It has also required him to fix issues all over the codebase (including in glib!) Great work, Tanmay!

Thanks

• Christian for libpanel advice and that cute histogram trick
• Federico for helping me reason about complexity, CI fixes, and translations
• Tanmay for tests and charset work (and future Acrostic work)
• Pratham for anagram support (GSoC)
• Rosanna for wording and UX suggestions
• Davide for doc fixes and translations

Long time, no release.

When I last blogged about GNOME Crosswords, I had a design plan to improve the editing API. It’s been a busy summer since then. The crosswords team rewrote large chunks of code to implement and use this new API:

crosswords: 146 files changed, 10545 insertions(+), 4915 deletions(-)
libipuz:  53 files changed, 8224 insertions(+), 961 deletions(-)

There’s now over 38KLOC between the two codebases — this is starting to look like a real application!

Editor and libpanel

The biggest change this cycle is the implementation of the new editing interface. I started changing the code five months ago, but it took a while to land. We now use libpanel from GNOME Builder to manage the information panels. Libpanel has a lot of the functionality I want, though unfortunately I’m fighting its geometry handling.

I really struggled getting the UI design for this to work, and I had a number of regrettable paths along the way. Fortunately, Niko agreed to help out with this, and showed up with some fabulous design work! I’m so much happier with the current approach, and am getting ready to implement more of his designs for the next cycle.

Behind the scenes, implementing this was a challenge. I blogged about those challenges previously, but in a nutshell, mutating a puzzle has a lot of side-effects which can leave you in an invalid state. For example, something simple like adding a block could completely change the numbering of the grid.

Federico and I fixed this by adding a number of functions to enforce heuristics and conventions. I also added ipuz_puzzle_fix_all() which will  get a fully well-formed puzzle regardless of the state. It’s turned out to be a really nice design pattern.

I have now released the Editor as a separate application in flathub. You can download it here.

Acrostics

Another major feature this release is Acrostic Puzzle support. Tanmay worked on that for his GSOC project and did fabulously (details in his blog post.) The end result is gorgeous:

I had a great time mentoring Tanmay for the summer, and we’re already making plans on how to add acrostic support to the Editor.

GUADEC and GNOME Mobile

GUADEC in Latvia was a blast. Riga was fun, the countryside was surprisingly interesting, and the overall feel of the conference was lovely. As always, it was great to meet so many people, new and old.

GNOME Superstar Martin came to my Crosswords BOF in Riga and got it running on an actual mobile device. The end result was.. actually usable! It seems like all the work we did on adaptive sizing paid dividends. There are some rough corners (and Martin filed a number of bugs) but it worked surprisingly well out of the box.

I also got to meet with my other GSOC student Pratham. His work on anagrams will land next release, so we’ll have more to talk about then.

libipuz.org

The final thing mentioning is that I bought the libipuz.org domain for the library. Unfortunately the main ipuz.org site has been down all summer, I put a mirror of the ipuz spec up there so people can read it.

I also managed to reach Roy Leban by phone. He’s the original author of the ipuz spec, and was able to clarify some questions I had when interpreting it. This led me down a deep rabbit hole around the part of the spec regarding clue directions, as it required a substantial rewrite to avoid hardcoding Across/Down directions everywhere.

Finally, Pranjal showed up completely out of nowhere with an MR to add ipuz_puzzle_equal(). This was a tricky function to write, and one I’ve wanted for a really long time. This has been making all our tests so much better. Hero! Pranjal is interested in adding a sudoku loader/saver to libipuz — maybe there will be more in this space in the future.

Thanks

• Niko, for massive help with the designs for the Editor
• Tanmay, for Acrostic support
• Martin, for testing Crosswords on mobile
• Pranjal, for ipuz_puzzle_equal()
• Federico, for testing fixes and overall support
• Rosanna, for continued advice and crossword support
• Pratham, for initial anagram support
• Bart, for whatever magic he did to make libipuz.org work
• The translators, for keeping us multi-lingual

Until next time!

Note: a half-written version of this blog post was accidentally published earlier, and was briefly picked up by planet.gnome.org. The [Publish] and [Preview] buttons are unfortunately right next to each other 🙁

Release

It’s time for another GNOME Crosswords release! This one is particularly exciting to me as it brings a lot of new content. The major highlights include new puzzles, a new distribution channel, and the start of adaptive behavior with an eye to working on mobile. It’s available for download in flathub.

New Puzzles

First — and most important — is the addition of new puzzles. We added three more puzzle sets from different sources. I wrote to a number of crossword creators in the local FOSS community and asked if I could include their puzzles in this release. Thanks to Bob, Carl, and dew.mountain for kindly agreeing to add their puzzles to the distribution.

Next, Rosanna and I sat down and together wrote some quick mini-puzzles. These were pretty  fun to create, so hopefully we can build a good collection over time. Let us know if you’re interested in helping us.

Finally, I wrote to Māyā of Auckland to ask if they minded if I included their puzzles. Māyā writes cryptic crosswords that are of a very high quality — and that are a lot of fun to solve. They very kindly agreed to let me distribute them, so I’ve included ~90 cryptics.

This adds up to over 100 new puzzles available in this version.

Adding these puzzles took a surprising amount of time. They ended up highlighting a half-dozen or so bugs in the code base, and lead to substantial rewriting of a number of sections. In detail:

• One of Bob’s puzzles came in puz format and used circled letters, so I added circle support to the puz importer. This is used fairly commonly. Now that we support it, I’m noticing circles a lot more in the wild.
  

• Some of Māyā’s puzzles were made available in JPZ format. As a result, I finally wrote a convertor for this format. I also refactored the convertor to make it possible to add other formats in the future.
  NOTE: I did not have a lot of jpz puzzles to test while writing this. If you have some, please try this feature out and let me know if it doesn’t load correctly.
• Māyā’s puzzles also thoroughly broke the enumeration code. The old regex-based parser wasn’t good enough to handle them, so I wrote a state-machine-based parser to handle this properly. There were really cute enumerations in those puzzles like:
  
  After first first exchange, 10 relates to blood vessels (7-)Solo star of this? Yes and no (3,3,4,1.1.1.1.1)that couldn’t be parsed with the old approach.
• These puzzles also forced me to get much more strict about the text handling. The ipuz spec allows a subset of html in certain tags, and you certainly run into puzzles with this in the wild. Complicating matters, you also come across random ampersands (&) that weren’t escaped, as well as other random entities.I wrote a simple html_to_markup() function that parses html (as best as I can) and converts it to valid GMarkup tags to pass to labels. This is mostly a matter of handling entities and escaping unknown tags, but there were definitely some subtleties involved. If someone has a better version of this functionality, let me know. On the other hand, maybe this implementation is helpful to someone else out there.

Thanks again to these puzzle authors!

Adaptive layout

The next big feature we added is making Crosswords work well at different screen sizes. I had a couple requests to make this work on mobile devices and Sam did a great design, so we tried to make this plausible. Unfortunately, there’s not a lot of formal guidance as to what’s needed here, other than to support small screens. I’d love if the GNOME Mobile folks would put together a checklist of things to support, as well as instructions as how best to test / simulate that environment without having dedicated hardware.

Nevertheless, we now support smaller screens! Here’s a video of it in action.

To make this work proved to be pretty tricky, as that packing is impossible to do with a standard GtkBox layout. The challenge is that that scrolled window holding the grid needs to have vexpand=TRUE set, but also have a maximum size so that the clue at the bottom doesn’t extend beyond the grid. I finally gave up and wrote a custom widget to do this sizing:

Note: I got a lot closer to a working solution with constraints, and was really impressed with how well they worked. Emmanuele has done a fantastic job with them. There’s a bit of a learning curve to get started, but they’re definitely worth a second look if you haven’t tried using them before. They’re more powerful than regular box-based solutions, and ended up being easier to maintain and experiment with.

For the sizing behavior to feel right, I also wrote code to restore the window size on restart. Fortunately, there’s a great example of how to do this in the tutorial. Unfortunately, the example doesn’t work correctly. After figuring out why, I wrote an MR to fix the documentation. Unfortunately I don’t know vala well enough to update that example, maybe someone who does can help me update it?

Availability

One more fantastic contribution arrived  towards the end of the release cycle: Davide and Michel packaged Crosswords for Fedora. I had never actually tried to install the game locally, but meson magically worked and they got it built. Now, running ‘sudo dnf install crosswords‘ works with f36/f37. As it’s Fedora, I may have to spend some time next cycle to straighten out all the licenses across the code base and puzzles, but that’s time worth spending.

One spooky Halloween-themed bug came with this work: word-list-tests test failure on s390x. That’s a category of bug I never expected to have to deal with ever again in my life!

In general, I’m really excited about the future of flatpak and what it means to the larger Linux ecosystem. I will continue to focus my efforts on that. But having it on Fedora is nice validation, and hopefully will lead to more people solving crosswords. I’d love it if other distros follow suit and ship this as well.

Odds and Ends

Other fixes this cycle include:

• Massive cleanup to event code (Federico). This was huge, and moves us to a simpler event system. Really appreciated!
• Also, Federico let me call him a couple Saturdays to get general design advice
• New setting to avoid changing crossword direction when arrowing through the grid (Jonathan and Rosanna)
• Mime types defined for ipuz, jpz, and puz files (Davide)
• Cleanup of the color and contrast of shapes in cells (Jonathan)
• New Italian translation (Davide)
• MacOS fixes and testing (Vinson)
• Loads of bug fixes (all)

Until next time!