Add support for offline AnkiDroid manual and help pages

[ShridharGoel]

Purpose / Description

Add support for offline AnkiDroid manual.

Fixes

Fixes #6829

How Has This Been Tested?

Verified on an emulator.

Checklist

• You have not changed whitespace unnecessarily (it makes diffs hard to read)
• You have a descriptive commit message with a short title (first line, max 50 chars).
• Your code follows the style of the project (e.g. never omit braces in if statements)
• You have commented your code, particularly in hard-to-understand areas
• You have performed a self-review of your own code
• UI changes: include screenshots of all affected screens (in particular showing any new or changed strings)
• UI Changes: You have tested your change using the Google Accessibility Scanner

[david-allison]

This looks good to me. One question regarding the release script.

My main question/issue is that we don't seem to be handling translations here.

@mikehardy what was intended here for this use case?

[ShridharGoel]

My main question/issue is that we don't seem to be handling translations here.

Translated HTML files are not present in ankidroiddocs currently.

[abdnh]

Translated HTML files are not present in ankidroiddocs currently.

Translation sources are present in https://github.com/ankidroid/ankidroiddocs so they can be simply rendered and copied here as it's done for the English files. Can't they?

[ShridharGoel]

Translated HTML files are not present in ankidroiddocs currently.

Translation sources are present in https://github.com/ankidroid/ankidroiddocs so they can be simply rendered and copied here as it's done for the English files. Can't they?

Yes, didn't notice earlier that they are present. Thanks for the information.

[mikehardy]

I appear to have damaged this PR via a merge of a Kotlin migration PR @ShridharGoel apologies - please forgive me/us as we work through Kotlin migration and it impacts other PRs

The use case here is to in general have the app be as "offline first" as possible, so I like this change. With regard to translations it appears that is handled much more thoroughly now with the last couple of commits.

Now I have a slightly different concern which is that we will eventually use the .abb format (vs the .apk format) to publish AnkiDroid to the play store, and with that format Google will be able to "render" a downloaded apk that has only the localizations that are actually needed. In that way it will keep the download/install size on device as small as possible.

On the other hand we let the user switch to whatever localization they want (and that's actually a feature...) so it I think we actually need to keep all the localizations, so this works for me

[mikehardy]

except for the Kotlin-merge on HelpDialog this LGTM

[david-allison]

Took a conflict.

What impact does this have on the apk size? I'm concerned about the translated manuals - they're big.

[ShridharGoel]

After:

Before:

[david-allison]

1MB hurts, but seems acceptable as long as we have a follow up issue to split them out.

@mikehardy Thoughts?

[david-allison]

@ShridharGoel Could you rebase this onto master - we can't rebase/merge this currently

[mikehardy]

Dang. I'm really conflicted here. 1MB is a lot, it's a lot a lot - especially since this cost will scale linearly with any added translations in the future. We should want that, the more translations of Help and Manual we get the better. But if it's increasing APK size at this rate I'll have a nagging feeling like I don't want the translations ;-). That's not good.

With sincere regret I think this kills the idea for me temporarily, I don't think we can support even 1MB for current ones right now, that would feel like a regression to many users I think, for functionality they didn't even need.

I still like the goal of having an offline manual + help etc though. And ideally it should be in the users preferred language.

Here is my thinking on moving forward.

1. Actionable now: require that the resources for the manual / help for all languages are provided in the standard "alternative resources" / locale-specific style that google understands and move the current English ones to it as proof of concept, as the "default" resource for locales missing a translation: https://developer.android.com/guide/topics/resources/providing-resources#AlternativeResources
2. make the extension of adding new languages dependent / blocked-for-merge on the move from APK to ABB (Switch AnkiDroid publishing from APK-first to AAB-first #9259). Why? Once we ship .abb as our default, then our verify that Google is shipping optimized apks to end users - https://developer.android.com/guide/app-bundle - at that point users will get at most 2 translations, the default/English one, and whatever their device locale is set to
3. Stretch goal: for users that have set a non-default locale on their device, somehow download their preferred translation ? I'm not even sure how that will work. To be honest, that's a problem with the ABB format's optimized delivery system and I suppose we'll have to handle that somehow, perhaps with a "feature pack" where all translations are downloaded for users that specify a non-device locale in our app preferences. Otherwise they'll never get the locale resources needed to translate....I'll add that to the ABB issue.

[ShridharGoel]

@mikehardy For now, should we go ahead with only the English version?

[mikehardy]

Having the English version included, in a locale-specific resource directory would be perfect to start - it will get us on the path towards having it included, having it included in the user's language, but not bloating the app too much (concretely: having at most 2 manuals for non-English users, and at most 3 manuals for non-English users who use custom locales - vs O(n) manuals for all users 😅 )

[ShridharGoel]

@mikehardy Is there a way to use HTML file in a resource specific directory?

[mikehardy]

I wish I knew, and even better: I wish I knew and I wish I knew it was easy. But I don't apologies

[ShridharGoel]

@mikehardy I think asset folder is not based on locales, so if we add the English version then it will be included for all languages.

[mikehardy]

I believe you are correct, above I was thinking it would be in values somewhere, that's locale specific

[david-allison]

This looks good to me, and I'm looking forward to getting this in.

• Could you squash the commits (or split them out + remove the revert), and add a descriptive commit message explaining briefly how the files are created and updated.

@mikehardy I'd like consider a README.md inside the assets to explain the manual generation process

I think we want to include the manual and help on all releases, not just the public (non-alpha) release.

What do you think about the above?

[mikehardy]

I'd prefer for the rendered versions of help.html and manual.html to not be committed, I normally prefer for "derivative" artifacts to remain out of source control as they are just a source of confusion and possible merge conflict. Just removing them entirely seems fine to me, or if necessary putting a placeholder in similar to the changelog that just explains these files are rendered during the release process and if you are seeing the placeholder, something went wrong with the release process

I had a separate question about locale-specific assets overlay - I'm not certain they actually do overlay? And that's an important problem to solve if not

Removing the public conditional in the release script seems like an easy change

[mikehardy]

are these directories actually locale-specific? That is, currently the change you made renders in to src/main/assets/manual.html, If I had a device set to locale es-EC, and there was a manual in src/main/assets-es-EC/manual.html would that load in it's place?

[ShridharGoel]

assets directory is not locale-specific.

[mikehardy]

If the assets folder is not locale-specific this is a no-go for me. We cannot include locale-specific manuals in non-locale-specific places I think or we'll be headed down the wrong path. This may actually represent a regression for most as opening the web manual for most people where the manual is not in their language should at least trigger their web browser to offer to translate it for them automatically, whereas including it locally like this will force them to English with no ability to override

We must figure out locale-specific asset loading

[ShridharGoel]

@mikehardy The earlier solution had included separate files based on language but it was creating an increase in the APK size.

[krmanik]

I am converting the manual pages to mdbook. It is not complete but it is coming soon.
ankidroid/ankidroiddocs#97

Instead of adding manual to app, it will be to better download the file after installation of AnkiDroid.
Or an option for user to download the manual for offline view.

[mikehardy]

@ShridharGoel I don't feel like I have communicated my desire clearly

In the future, we will generate ABB files for distribution, and Google will remove versions of the manual for locales that are not your system locale.

We can use Google APIs to download locale-specific manuals for users that have used our in-app selector to choose a non-default locale.

For this to work, the manuals must be in a location that is part of the general locale-specific android file organization / build process.

We are not ready for ABB distribution yet, and we do not have the non-default-locale API in use yet to download non-default-locale translations. That means that we cannot put multiple translations in without increasing app size. However the English translation can can go in now, so long as it is in a locale-specific location

In order for this to not be a regression for locales where there is no translation, or it is not packaged at all, there should be a button or toast that says "Read the manual online", which opens it in a browser and then the user has access to google translate etc

If that's not clear in any way, please let me know.

@krmanik I actually would like to have the manual available offline in a way that works (offline) for the majority of users, not for it to be downloaded dynamically except for the rare case where the user has chosen a non-English non-default version of the manual. This is not an issue about the format of the manual, this is about packaging and distribution

[github-actions]

Hello 👋, this PR has been opened for more than 2 months with no activity on it. If you think this is a mistake please comment and ping a maintainer to get this merged ASAP! Thanks for contributing! You have 7 days until this gets closed automatically