search

anki-geo / ultimate-geography

Geography flashcard deck for Anki
https://ankiweb.net/shared/info/2109889812
Other
819 stars 81 forks source link

Consider moving repository format to `ki` #541

Closed langfield closed 2 years ago

langfield commented 2 years ago

Disclaimer. This is a shameless plug for my own tool.

This is probably the only major deck under version control. I just wanted to see if you folks would be interested in considering a different repository format, different from Brain Brew. Here's an example of the note grammar:

## Note
nid: 1574587965526
model: Ultimate Geography-7c473
tags: UG::Europe, UG::Sovereign_State
markdown: false

### Country
Abkhazia

### Country info
Independent state claimed by Georgia.

### Capital
Sukhumi

### Capital info

### Capital hint

### Flag
<img src="ug-flag-abkhazia.svg">

### Flag similarity

### Map
<img src="ug-map-abkhazia.png">

You can check out the tool here: https://github.com/langfield/ki

And I've made a fork of your repository and committed a version of it in the above format here: https://github.com/langfield/ultimate-geography

Github thinks the image links in the markdown sources are borked, but the media import works fine. Let me know what you think!

aplaice commented 2 years ago

Unfortunately, I don't have too much time for a comprehensive (or even properly-edited) answer and won't in the near future.

Above all, I'm excited about ki — it's doing many things right (I fully agree that using git for managing deck collaboration is the right approach, by avoiding reinventing the DVCS wheel) and in some ways is better than BrainBrew/CrowdAnki (e.g. the markdown format is definitely nicer than CrowdAnki's JSON format and arguably better than BrainBrew's CSV format* (in some ways more convenient, in others less)), and it's really nice that somebody else is working in this area!

* though AFAIU in principle BrainBrew could also support a markdown-based input/output format (as far as I remember this was discussed as a possible option in the future)

However, AFAICT, ki doesn't currently do everything that BrainBrew can (e.g. easily generate multiple different decks ("standard"/"extended" and the many translated versions of each) and I don't think that it makes sense for you to focus on supporting this part of the functionality (being able to generate multiple deck versions has contributed to BrainBrew's complexity, but (while this is essential for AUG) most decks probably won't need anything like this, so you'd arguably be over-complicating ki in a way that's not essential (given that BrainBrew exists and is filling this particular niche)).

Also, I have some minor quibbles about some of ki's design (though I'm not 100% sure that I'm right, and I'm glad that somebody is trying these alternative approaches). Firstly, having it as a CLI tool that runs when Anki is closed has many advantages, but it also makes things more complicated for the end-user (having an Anki add-on like CrowdAnki is considerably easier (though obviously BrainBrew is still a separate tool (though there have been nebulous long-term plans to combine the two)).

Secondly, I think that the CrowdAnki approach of using (Anki's built-in) GUIDs to identify/track notes and UUIDs to identify to track note models and decks is on the whole preferable to using note IDs and names. (This is a bit of a trade-off between simplicity and edge-case behaviour. (I don't have time to go into detail, but using GUIDs/UUIDs allows tracking the note/note model/deck even in edge cases where names have changed, there are duplicate names etc.))

(I haven't looked too closely, so there might be other points of disagreement (or possibly agreement that your approach is superior! :))

Summarising, I'm not inherently opposed to using ki, but:

  1. It's not quite ready (for our relatively niche use-case (multiple deck versions))
  2. I don't think it's worth it for you to work on resolving 1, at this stage, as I'd expect this use-case (multiple deck versions (as opposed to decks managed in git — I don't understand why these aren't more frequent and I hope that ki will make them more common!)) to be relatively rare.
  3. Even if 1 were resolved I'd still be in favour of using BrainBrew and CrowdAnki, since I mildly prefer some of their features (and we're quite satisfied using them (so there's an argument for avoiding change for the sake of change)).

(I can't speak for the other maintainers, and if they disagree with me, I'd be happy to switch to ki.)

However, I wish you the very, very best of luck and I hope that you convince some decks not currently managed with git to switch to ki, as I think that the entire Anki/SRS ecosystem would benefit from it! (I've also added a link to ki in the CrowdAnki wiki.)

langfield commented 2 years ago

Thanks very much for the detailed feedback! I am certainly in favor of not fixing what isn't broken, I think that's a very wise decision.

I definitely agree that functionality to generate notes from many translations of the same data is out of the scope of the tool I'm building. That sounds like you need some sort of build tool, to be honest. The CSV format does seem unexpectedly convenient for making translation-agnostic changes to the deck structure (like e.g. adding a new country).

Ki is a CLI tool to avoid scope creep, mainly. Building an addon around it would be pretty trivial, since there are only three operations, but would require switching to Dulwich from GitPython in order to package all its dependencies on AnkiWeb, and possibly dropping support for HTML-tidying, or using a different utility. It would also mean either severely limiting the user's ability to inspect what the tool is doing, or dumping a lot of output to a GUI box that they might not understand. Handling merge conflicts would also have to be figured out, probably by adding documentation on how to use a GUI git porcelain. I may build one eventually, but it is not a priority.

The use of UUIDs is something I've thought a lot about, but is low on the priority list because the tool works without them. I think it's fairly trivial to implement these from scratch (just store a mapping in a JSON file in the repository), at least for nids. Models I haven't come up with a solution that I think is perfect yet. I think that blindly enforcing uniqueness everywhere is not the move. I have considered using content-addressed models, but further work is needed to see if this is viable. What is the advantage of using UUIDs for decks?

aplaice commented 2 years ago

That sounds like you need some sort of build tool, to be honest.

Yes, BrainBrew is intended to be that build tool, but still with the possibility of importing changes from Anki (it's the historical "reason" for the current complicated system, which uses both BrainBrew and CrowdAnki).

Ki is a CLI tool to avoid scope creep, mainly. Building an addon around it would be pretty trivial, since there are only three operations, but would require switching to Dulwich from GitPython in order to package all its dependencies on AnkiWeb, and possibly dropping support for HTML-tidying, or using a different utility. It would also mean either severely limiting the user's ability to inspect what the tool is doing, or dumping a lot of output to a GUI box that they might not understand. Handling merge conflicts would also have to be figured out, probably by adding documentation on how to use a GUI git porcelain. I may build one eventually, but it is not a priority.

Yeah, I see where you're coming from and it makes sense!

What is the advantage of using UUIDs for decks?

Currently (i.e. with current CrowdAnki), the main advantage is that if two different people create two different collaborative decks with the same name, then it's possible to distinguish the two decks going forward (i.e. after both are imported, one will be called, say X and the other X1, the user can optionally rename each to something more convenient, add some notes to each deck, reimport the two decks (e.g. to get updates), and their added notes will remain associated with the correct of the two (e.g. because they want to share their additions back to the two respective "upstreams").

In principle it allows dealing more intelligently with renames (by the user and/or creator) of decks/subdecks, though CrowdAnki doesn't do this yet.

(On the whole, the benefits are relatively small — the benefits of UUIDs for note models are IMO greater, but even there I don't think they're essential (as I wrote they're a bit of a trade-off between complexity and being able to be pedantic...).

langfield commented 2 years ago

Ah your example for decks is indeed something ki does not successfully handle, I think. Thanks, that is very valuable to know. I'll have to write a test for that.

From: aplaice @.> Sent: Sunday, June 19, 2022 8:02:14 PM To: anki-geo/ultimate-geography @.> Cc: William Blake @.>; Author @.> Subject: Re: [anki-geo/ultimate-geography] Consider moving repository format to ki (Issue #541)

That sounds like you need some sort of build tool, to be honest. Yes, BrainBrew is intended to be that build tool, but still with the possibility of importing changes from Anki (it's the historical "reason" for the current complicated system,

That sounds like you need some sort of build tool, to be honest.

Yes, BrainBrew is intended to be that build tool, but still with the possibility of importing changes from Anki (it's the historical "reason" for the current complicated system, which uses both BrainBrew and CrowdAnki).

Ki is a CLI tool to avoid scope creep, mainly. Building an addon around it would be pretty trivial, since there are only three operations, but would require switching to Dulwich from GitPython in order to package all its dependencies on AnkiWeb, and possibly dropping support for HTML-tidying, or using a different utility. It would also mean either severely limiting the user's ability to inspect what the tool is doing, or dumping a lot of output to a GUI box that they might not understand. Handling merge conflicts would also have to be figured out, probably by adding documentation on how to use a GUI git porcelain. I may build one eventually, but it is not a priority.

Yeah, I see where you're coming from and it makes sense!

What is the advantage of using UUIDs for decks?

Currently (i.e. with current CrowdAnki), the main advantage is that if two different people create two different collaborative decks with the same name, then it's possible to distinguish the two decks going forward (i.e. after both are imported, one will be called, say X and the other X1, the user can optionally rename each to something more convenient, add some notes to each deck, reimport the two decks (e.g. to get updates), and their added notes will remain associated with the correct of the two (e.g. because they want to share their additions back to the two respective "upstreams").

In principle it allows dealing more intelligently with renames (by the user and/or creator) of decks/subdecks, though CrowdAnki doesn't do this yet.

(On the whole, the benefits are relatively small — the benefits of UUIDs for note models are IMO greater, but even there I don't think they're essential (as I wrote they're a bit of a trade-off between complexity and being able to be pedantic...).

— Reply to this email directly, view it on GitHubhttps://urldefense.com/v3/__https://github.com/anki-geo/ultimate-geography/issues/541*issuecomment-1159793336__;Iw!!KGKeukY!w0hdWWrRKGPHTu0Bv9rBvHZYtdHNULfA_tkN-dtrIcjLDV6xqEG7jhpEzWwAQ6LFDX2xho-OYAB7_uLCbhpdXQE9hEFLVg$, or unsubscribehttps://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AISQNI4IJQIGEN2XKO35INTVP5VDNANCNFSM5Y74XNVQ__;!!KGKeukY!w0hdWWrRKGPHTu0Bv9rBvHZYtdHNULfA_tkN-dtrIcjLDV6xqEG7jhpEzWwAQ6LFDX2xho-OYAB7_uLCbhpdXQGrWeBtOQ$. You are receiving this because you authored the thread.Message ID: @.***>

axelboc commented 2 years ago

Closing the issue, but thanks for letting us know about ki, and for adding your stone to the Anki ecosystem! 🏆 Feel free to let us know about future developments in the Discussions. 😉