Tldr: Removal of duplicated index.json from the generated ZIP archive, up-to-date clients tracking

[mebeim]

As stated in #2862, I'm opening this to keep track of clients' compliance with the small change to the ZIP generation, that is, adding a top-level /index.json as replacement for /pages/index.json. Right now, both files are present since some clients rely on /pages/index.json to work, but the goal is to completely remove it and only keep the top-level /index.js.

As a consequence of this, I'm going to open issues on repositories of clients which rely on /pages/index.json being in the generated ZIP to alert them of the new change. Look at the bottom to see what I'll be mostly copy-pasting around for this purpose.

---

List of up-to-date clients

Checked box == up-to-date.

• [ ] [anoopengineer/tldr](https://github.com/anoopengineer/tldr): opened issue #2.
• [x] [BrainMaestro/tldr-php](https://github.com/BrainMaestro/tldr-php): already ok.
• [x] [cs1707/tldr-alfred](https://github.com/cs1707/tldr-alfred): already ok.
• [x] [dbrgn/tealdeer](https://github.com/dbrgn/tealdeer): opened issue #80.
• [ ] DistroWatch: lacks source/repo, unknown status.
• [x] [edgurgel/tldr_elixir_client](https://github.com/edgurgel/tldr_elixir_client): already ok.
• [x] [elecprog/tldr](https://github.com/elecprog/tldr): already ok.
• [x] [ex0dus-0x/tldr-bot](https://github.com/ex0dus-0x/tldr-bot): already ok.
• [x] [freesuraj/TLDR](https://github.com/freesuraj/TLDR): already ok.
• [x] [fuerbringer/tldr-telegram](https://github.com/fuerbringer/tldr-telegram): already ok.
• [x] [gianasista/tldr-viewer](https://github.com/gianasista/tldr-viewer): already ok.
• [x] [hidroh/tldroid](https://github.com/hidroh/tldroid): already ok.
• [x] [hill/tldr-chrome](https://github.com/hill/tldr-chrome): already ok.
• [x] [hterkelsen/tldr](https://github.com/hterkelsen/tldr): already ok.
• [x] [isacikgoz/tldr](https://github.com/isacikgoz/tldr): already ok.
• [x] [joelekstrom/tldr-man](https://github.com/joelekstrom/tldr-man): already ok.
• [x] [k3mist/tldr](https://github.com/k3mist/tldr): already ok.
• [x] [kirillseva/tldrrr](https://github.com/kirillseva/tldrrr): already ok.
• [x] [kuanyui/tldr.el](https://github.com/kuanyui/tldr.el): already ok.
• [x] [leighmcculloch/tldr](https://github.com/leighmcculloch/tldr): already ok.
• [x] [lord63/tldr.py](https://github.com/lord63/tldr.py): already ok.
• [x] [mflint/ios-tldr-viewer](https://github.com/mflint/ios-tldr-viewer): opened issue #21.
• [x] [Moddus/tldr-python-dash-docset](https://github.com/Moddus/tldr-python-dash-docset): already ok.
• [x] [nutellinoit/tldr-docker](https://github.com/nutellinoit/tldr-docker): already ok.
• [x] [ostera/tldr.jsx](https://github.com/ostera/tldr.jsx): alreay ok.
• [x] [pepa65/tldr-bash-client (GitLab)](https://gitlab.com/pepa65/tldr-bash-client): opened issue #13.
• [x] [porras/tlcr](https://github.com/porras/tlcr): already ok.
• [x] [pranavraja/tldr](https://github.com/pranavraja/tldr): already ok.
• [x] [principis/tldr-sharp](https://github.com/principis/tldr-sharp): already ok.
• [x] [psibi/tldr-hs](https://github.com/psibi/tldr-hs): already ok.
• [x] [raylee/tldr](https://github.com/raylee/tldr): alreadyb ok.
• [x] [rilut/rust-tldr](https://github.com/rilut/rust-tldr): already ok.
• [x] [RosalesJ/tldr-ocaml](https://github.com/RosalesJ/tldr-ocaml): already ok.
• [x] [skaji/perl-tldr](https://github.com/skaji/perl-tldr): already ok.
• [x] [terenceng2010/tldr-electron](https://github.com/terenceng2010/tldr-electron): already ok.
• [x] [tldr-pages/tldr-cpp-client](https://github.com/tldr-pages/tldr-cpp-client): already ok.
• [x] [tldr-pages/tldr-node-client](https://github.com/tldr-pages/tldr-node-client): already ok.
• [x] [tldr-pages/tldr-python-client](https://github.com/tldr-pages/tldr-python-client): already ok.
• [x] [YellowApple/tldrb](https://github.com/YellowApple/tldrb): already ok.

---

Text of the issue I'll be opening on client repositories:

Use the new index.json file in favor of the deprecated pages/index.json

Hello, I'm from the tldr-pages/tldr repository, and I'm here to inform you that we recently changed the content of the ZIP archive your client relies upon. Here's a link to the merged PR: #2862.

Inside the generated ZIP archive, a new /index.json file has been created, to be used in favor of the now deprecated /pages/index.json file, as you can see here. Once all the clients are updated, or enough time has passed, we will completely remove the /pages/index.json file from the generated ZIP archive, and only keep the top-level /index.json.

If your client does not rely on the mentioned file to work, you can close this right away, sorry for the trouble! Otherwise, in order to support the upcoming change, this client should be updated to either:

1. Use the index.json file served by the static site itself, that is: https://tldr.sh/assets/index.json.
2. Or use the new top-level /index.json file inside the ZIP file served by the static site, which is: https://tldr.sh/assets/tldr.zip.

Once the above is taken care of, you can close this issue and your client will be marked as up to date in our tracking issue here. This change should be trivial, but if there's any problem, please do let me know.

Thank you for your work and time you put into creating this client and supporting the TLDR pages project!

[sbrl]

Ah, great idea @mebeim!

Shouldn't the URL be https://tldr.sh/assets/index.json / https://assets/tldr.zip?

The client spec should probably be updated too. Could you open a PR for that please?

[mebeim]

@sbrl you're right about the URL, changed it. About the tldr.sh domain, should that be used instead of tldr-pages.github.io? I was unsure about which one to use.

As for the PR, well sure, once the above question is answered though, don't want to link the wrong domain :')

[agnivade]

Yeah, we can use tldr.sh. It is a CF front for tldr-pages.github.io.

[mebeim]

@agnivade noted, thanks.

[owenvoke]

Just a note, tldr-php and tldr-chrome don't use the ZIP file at the moment.

For tldr-php, we have BrainMaestro/tldr-php#6 and BrainMaestro/tldr-php#7 open for updating it to use the ZIP, so I guess when those are done, we can update straight to use this new file format. 👍

[mebeim]

@pxgamer If that's the case then those two clients can be already checked. Thank you. :+1:

[mebeim]

I looked around all client repositories and to my surprise I found out that very few of them use the /pages/index.json file inside the ZIP. Most of the clients directly request each page or directly clone this repo's main branch. Most of the clients which download the ZIP just browse it manually and maybe even build a different index by theirself. Others use the index file at tldr.sh/assets/index.json. I also saw a couple which just have a static local copy of all the pages, LOL.

So, basically as you can see I only had to open 4 issues (3 on GitHub, 1 on GitLab), of which one was already resolved and closed. This means only three clients with an open issue remain right now, and that one client which does not have a source listed anywhere for me to look into (though I believe it directly queries each page).

Pretty nice I'd say :nerd_face:

[sbrl]

Gosh! Interesting. It's actually in the new client spec that clients _should_ be using index.json and the archives on tldr.sh :thinking:

[owenvoke]

I'm not sure it would be possible for the Chrome extension. But for the PHP client, I might make a PR when I'm back home.

[mebeim]

@pxgamer well I don't think that the spec should be taken that literally for every client. Clearly it is a good guideline to follow, but doesn't fit all scenarios.