feat (3.4.0): add platform option, Android and BSD platforms #421

kbdharun · 2023-10-05T09:40:40Z

Description

This PR updates the --os and -o option to --platform and -p. This change would make the official client comply with the last client specification and #420 is expected to add support for the recent client specification 2.0. (Supersedes #337, thanks to the original authors and reviews for initial work on this transition)

This PR also adds support for Android and other BSD platforms (~~there might be another platform openbsd in future, subscribe to tldr-pages/tldr#10698 to stay tuned~~ Edit. added it too).

Checklist

Please review this checklist before submitting a pull request.

Code compiles correctly
Created tests, if possible
All tests passing (npm run test:all)
Extended the README / documentation, if necessary

Related PRs

Closes #337
Fixes #395

Signed-off-by: K.B.Dharun Krishna <[email protected]>

bin/tldr

Signed-off-by: K.B.Dharun Krishna <[email protected]>

lib/platform.js

Signed-off-by: K.B.Dharun Krishna <[email protected]>

sebastiaanspeck

LGTM!

sebastiaanspeck · 2023-10-23T20:24:17Z

Any update on this?

kbdharun · 2023-10-24T01:21:55Z

Any update on this?

I am planning on adding support for openbsd platform too in this, will do this later today, along with another change.

MasterOdin

LGTM to me.

We could simplify adding new platforms by doing something like this:

diff --git a/bin/tldr b/bin/tldr
index 59e0b91..21e28ba 100755
--- a/bin/tldr
+++ b/bin/tldr
@@ -22,12 +22,11 @@ program
   .option('-e, --random-example', 'Show a random example')
   .option('-f, --render [file]', 'Render a specific markdown [file]')
   .option('-m, --markdown', 'Output in markdown format')
-  .option('-p, --platform [type]', 'Override the current platform [android, linux, osx, sunos, windows]')
-  .option('--android', 'Override the platform with Android')
-  .option('--linux', 'Override the platform with Linux')
-  .option('--osx', 'Override the platform with OSX')
-  .option('--sunos', 'Override the platform with SunOS')
-  .option('--windows', 'Override the platform with Windows')
+  .option('-p, --platform [type]', `Override the current platform [${platforms.supportedPlatforms.join(', ')}]`);
+for (const platform of platforms.supportedPlatforms) {
+  program.option(`--${platform}`, `Override the platform with ${platform}`);
+}
+program
   .alias('-o', '-p') // Alias -o to -p
   .alias('--os', '--platform') // Alias --os to --platform
   .option('-t, --theme [theme]', 'Color theme (simple, base16, ocean)')
@@ -65,24 +64,10 @@ program.on('--help', () => {

 program.parse(process.argv);

-if(program.android) {
-  program.platform = 'android';
-}
-
-if (program.linux) {
-  program.platform = 'linux';
-}
-
-if (program.osx) {
-  program.platform = 'osx';
-}
-
-if (program.sunos) {
-  program.platform = 'sunos';
-}
-
-if (program.windows) {
-  program.platform = 'windows';
+for (const platform in platforms.supportedPlatforms) {
+  if (program[platform]) {
+    program.platform = platform;
+  }
 }

 let cfg = config.get();
diff --git a/lib/platforms.js b/lib/platforms.js
index c938363..25f6a49 100644
--- a/lib/platforms.js
+++ b/lib/platforms.js
@@ -12,6 +12,8 @@ const folders = {
   'win32': 'windows'
 };

+const supportedPlatforms = Array.from(new Set(Object.values(folders))).sort();
+
 // Check if the platform is there in the list of platforms or not
 function isSupported(platform) {
   return Object.prototype.hasOwnProperty.call(folders, platform);
@@ -36,5 +38,6 @@ function getPreferredPlatformFolder(config) {
 module.exports = {
   isSupported,
   getPreferredPlatform,
-  getPreferredPlatformFolder
+  getPreferredPlatformFolder,
+  supportedPlatforms
 };

Now won't fill up bin/tldr with nearly identical if statements as new platforms are added.

bin/tldr

Co-authored-by: Matthew Peveler <[email protected]>

Signed-off-by: K.B.Dharun Krishna <[email protected]>

README.md

bin/completion/bash/tldr

bin/completion/zsh/_tldr

bin/tldr

Signed-off-by: K.B.Dharun Krishna <[email protected]>

kbdharun · 2023-10-29T14:50:46Z

@MasterOdin I have rearranged the options in alphabetical order as requested.

Changes in the last 3 commits

Added support for FreeBSD and NetBSD platforms.
Added the Client specification indication to the version's output.
Updated website link and tags in package.json.

In package.json, I have bumped the version to 3.4.0 as I plan on making a release after this PRs merge. With this the Node client is fully compliant with the latest client specification.

Reference outputs

➜  bin git:(feat/platform-option) ✗ ./tldr -v       
v3.3.8
Client Specification: 2.0
➜  bin git:(feat/platform-option) ✗ ./tldr -h
Usage: tldr|-o command [options]

Simplified and community-driven man pages

Options:
  -v, --version            Display version
  -l, --list               List all commands for the chosen platform in the cache
  -a, --list-all           List all commands in the cache
  -1, --single-column      List single command per line (use with options -l or -a)
  -r, --random             Show a random command
  -e, --random-example     Show a random example
  -f, --render [file]      Render a specific markdown [file]
  -m, --markdown           Output in markdown format
  -p, --platform [type]    Override the current platform [android, darwin, freebsd, linux, macos, netbsd, openbsd, osx, sunos,
                           win32, windows]
  --android                Override the platform with android
  --darwin                 Override the platform with darwin
  --freebsd                Override the platform with freebsd
  --linux                  Override the platform with linux
  --macos                  Override the platform with macos
  --netbsd                 Override the platform with netbsd
  --openbsd                Override the platform with openbsd
  --osx                    Override the platform with osx
  --sunos                  Override the platform with sunos
  --win32                  Override the platform with win32
  --windows                Override the platform with windows
  -t, --theme [theme]      Color theme (simple, base16, ocean)
  -s, --search [keywords]  Search pages using keywords
  -u, --update             Update the local cache
  -c, --clear-cache        Clear the local cache
  -h, --help               Show this help message

  Examples:

    $ tldr tar
    $ tldr du --platform=linux
    $ tldr --search "create symbolic link to file"
    $ tldr --list
    $ tldr --list-all
    $ tldr --random
    $ tldr --random-example

  To control the cache:

    $ tldr --update
    $ tldr --clear-cache

  To render a local file (for testing):

    $ tldr --render /path/to/file.md

Signed-off-by: K.B.Dharun Krishna <[email protected]>

kbdharun · 2023-10-29T16:06:06Z

Changes in last commit

Updated render.js to use the 'he' library to decode HTML entities in email addresses, ensuring proper rendering. In it, I removed the "mailto:" prefix from email addresses, improving their presentation in the rendered content.

Content

This fixes #395 where the GPG page would render with broken mail addresses like:

➜  bin git:(feat/platform-option) ✗ ./tldr --render /home/kbdharunkrishna/Downloads/gpg.md

  gpg

  GNU Privacy Guard.
  See gpg2 for GNU Privacy Guard 2. Most operating systems symlink gpg to gpg2.
  More information: https://gnupg.org.

  - Create a GPG public and private key interactively:
    gpg --full-generate-key

  - Sign doc.txt without encryption (writes output to doc.txt.asc):
    gpg --clearsign doc.txt

  - Encrypt and sign doc.txt for mailto:&#x61;&#108;&#x69;&#x63;&#101;&#x40;&#x65;&#x78;&#x61;&#109;&#x70;&#108;&#101;&#46;&#x63;&#111;&#109; and mailto:&#98;&#x6f;&#98;&#x40;&#x65;&#x78;&#x61;&#109;&#112;&#x6c;&#x65;&#x2e;&#99;&#x6f;&#x6d; (output to doc.txt.gpg):
    gpg --encrypt --sign --recipient [email protected] --recipient [email protected] doc.txt

  - Encrypt doc.txt with only a passphrase (output to doc.txt.gpg):
    gpg --symmetric doc.txt

  - Decrypt doc.txt.gpg (output to stdout):
    gpg --decrypt doc.txt.gpg

  - Import a public key:
    gpg --import public.gpg

  - Export public key for mailto:&#x61;&#x6c;&#x69;&#x63;&#x65;&#x40;&#x65;&#120;&#x61;&#x6d;&#112;&#108;&#x65;&#x2e;&#99;&#x6f;&#x6d; (output to stdout):
    gpg --export --armor [email protected]

  - Export private key for mailto:&#97;&#108;&#105;&#99;&#101;&#64;&#x65;&#120;&#x61;&#109;&#112;&#x6c;&#x65;&#x2e;&#99;&#111;&#109; (output to stdout):
    gpg --export-secret-keys --armor [email protected]


See also: gpg2

Post the changes, it now renders like this:

➜  bin git:(feat/platform-option) ✗ ./tldr --render /home/kbdharunkrishna/Downloads/gpg.md

  gpg

  GNU Privacy Guard.
  See gpg2 for GNU Privacy Guard 2. Most operating systems symlink gpg to gpg2.
  More information: https://gnupg.org.

  - Create a GPG public and private key interactively:
    gpg --full-generate-key

  - Sign doc.txt without encryption (writes output to doc.txt.asc):
    gpg --clearsign doc.txt

  - Encrypt and sign doc.txt for [email protected] and [email protected] (output to doc.txt.gpg):
    gpg --encrypt --sign --recipient [email protected] --recipient [email protected] doc.txt

  - Encrypt doc.txt with only a passphrase (output to doc.txt.gpg):
    gpg --symmetric doc.txt

  - Decrypt doc.txt.gpg (output to stdout):
    gpg --decrypt doc.txt.gpg

  - Import a public key:
    gpg --import public.gpg

  - Export public key for [email protected] (output to stdout):
    gpg --export --armor [email protected]

  - Export private key for [email protected] (output to stdout):
    gpg --export-secret-keys --armor [email protected]


See also: gpg2

agnivade · 2023-11-02T05:02:23Z

I am removing myself. Feel free to merge when you have 2 or more approvals.

sebastiaanspeck · 2023-11-05T17:50:30Z

Do we have an ultimatum to merge this?

kbdharun · 2023-11-05T17:52:03Z

Do we have an ultimatum to merge this?

Waiting for @MasterOdin's review. After that is is GTG.

sbrl

Lots of changes here, but a quick review doesn't reveal any major issues here. I suggest this is okay to merge. Stopping short of an approval though, since I'm not as involved in implementing the node client. /cc @MasterOdin.

kbdharun · 2023-11-12T06:47:14Z

@agnivade Sorry for the ping, I have a few doubts about how we publish a new release to NPM (so that I can do it after this PR).

I don't notice a release action (like the Python client) here. Would it automatically show up on NPM after creating a tagged release here? (If not can you add me to the Org over there as a collaborator [In this case, I will work on a release CI]).

sbrl · 2023-11-12T12:59:55Z

I think it would be helpful to have multiple people on the npm org, but unfortunately I don't have access. Might be worth checking who published recent versions of the Node client to see who to pester, @kbdharun?

kbdharun · 2023-11-12T13:01:22Z

I think it would be helpful to have multiple people on the npm org, but unfortunately I don't have access. Might be worth checking who published recent versions of the Node client to see who to pester, @kbdharun?

I did the same 😅, after noticing the last release was made by @agnivade.

ivanhercaz · 2023-11-12T20:37:20Z

how we publish a new release to NPM (so that I can do it after this PR)

Hi @kbdharun! As far I know, and according to npm documentation, to publish a new release you must change the version in package.json and then run npm publish, but I think that if the git repo is linked with the npm package, npm read the git tags and update it to the latest.

I will research more.

agnivade · 2023-11-13T04:06:50Z

Yes I release the npm package. Let me see if I can add you.

kbdharun · 2023-11-14T05:52:07Z

Yes I release the npm package. Let me see if I can add you.

Thanks received the invite, accepted it. Can you do the same for tldr-lint too?

~~Kinda curious, don't we have all these packages inside a single Org on NPM?~~ Edit. Seems like we don't. The tldr username is used by somebody else.

kbdharun · 2023-11-14T06:21:04Z

Update: I have set up a new Org (https://www.npmjs.com/org/tldr-pages) in NPM. And added our existing unscoped tldr package to it. While this isn't a package transfer, what is the benefit of the approach is we can set up new org-scoped packages in future and this allows adding collaborators via teams (for these packages alone) with ease.

Sent an invite to Org to @agnivade, @sbrl and @owenvoke.

Signed-off-by: K.B.Dharun Krishna <[email protected]>

kbdharun · 2023-11-14T10:43:57Z

Do we have an ultimatum to merge this?

Waiting for @MasterOdin's review. After that is is GTG.

I think this PR is GTG now will merge it (after passing checks), the only unreviewed change is in render.js with mail URL decoding, other parts are cosmetic changes with reordering options (already reviewed and approved by Masterodin).

I have reverted the initial suggestion to add -o and --os as .aliases for backward compatibility as our current version of commander in package.json doesn't support it (updating dependencies with dependabot was problematic with us supporting Node versions 16 and above). IG we can have the newer options alone (as we would drop the older ones in future releases anyway).

Other than that I have tested all other changes and the client works as expected.

This is the changelog I prepared for the release:

> [!WARNING]  
> **Breaking change**: This release drops support for Node 14 and lower.

> [!NOTE]  
> The default branch of this repository has been updated to `main`.

### Added

- Support to download cache for English and specific languages only based on the system's locale configuration (#420) (thanks @vivekjoshi556)
- Support for Android and BSD platforms (#421) (thanks @kbdharun)
- New `-p` and `--platform` option replacing `-o` and `--os` option (#421) (thanks @kbdharun)

### Fixed

- Escaping in Zsh autocompletion (#384) (thanks @nonZero)
- Variable assignment in Zsh (#386) (thanks @JakobMiksch)
- URL encoded email address rendering (#421) (thanks @kbdharun)

### Enhancements

- Added Funding information to `package.json` (#401) (thanks @kbdharun)
- Moved to `v2` format for `package-lock.json` (#409) (thanks @MasterOdin)
- Update homepage link to <https://tldr.sh> in `package.json` (#421) (thanks @kbdharun)
- The Client Specification version is now displayed when checking the version (#421) (thanks @kbdharun)

feat: add platform option, Android platform

0225293

Signed-off-by: K.B.Dharun Krishna <[email protected]>

kbdharun requested review from agnivade, MasterOdin, SethFalco and CleanMachine1 October 5, 2023 09:42

kbdharun linked an issue Oct 5, 2023 that may be closed by this pull request

-o and --os is not compliant with the client spec #336

Closed

kbdharun mentioned this pull request Oct 5, 2023

curl, open, powershell, wget: remove "view in older versions of tldr" tldr-pages/tldr#10851

Merged

MasterOdin reviewed Oct 5, 2023

View reviewed changes

bin/tldr Outdated Show resolved Hide resolved

MasterOdin reviewed Oct 5, 2023

View reviewed changes

bin/tldr Outdated Show resolved Hide resolved

bin/tldr Outdated Show resolved Hide resolved

feat/test: update code, add alias for old options

57a44c7

Signed-off-by: K.B.Dharun Krishna <[email protected]>

kbdharun requested a review from MasterOdin October 5, 2023 18:26

MasterOdin reviewed Oct 13, 2023

View reviewed changes

lib/platform.js Outdated Show resolved Hide resolved

MasterOdin mentioned this pull request Oct 13, 2023

change -o/--os to -p/--platform #337

Closed

feat: rename platform lib to platforms

adb6430

Signed-off-by: K.B.Dharun Krishna <[email protected]>

kbdharun requested a review from MasterOdin October 18, 2023 10:24

sebastiaanspeck approved these changes Oct 19, 2023

View reviewed changes

MasterOdin approved these changes Oct 24, 2023

View reviewed changes

bin/tldr Outdated Show resolved Hide resolved

Update bin/tldr

7bd80b9

Co-authored-by: Matthew Peveler <[email protected]>

kbdharun marked this pull request as draft October 24, 2023 15:48

feat: add support for OpenBSD and update code

a99971f

Signed-off-by: K.B.Dharun Krishna <[email protected]>

kbdharun marked this pull request as ready for review October 24, 2023 16:28

kbdharun changed the title ~~feat: add platform option, Android platform~~ feat: add platform option, Android and OpenBSD platform Oct 24, 2023

kbdharun requested a review from MasterOdin October 24, 2023 16:30

Merge branch 'main' into feat/platform-option

1928b2f

sebastiaanspeck approved these changes Oct 24, 2023

View reviewed changes

fix: add back updated platform options

b97e8a7

Signed-off-by: K.B.Dharun Krishna <[email protected]>

MasterOdin reviewed Oct 24, 2023

View reviewed changes

cleanup: update files

5446c05

Signed-off-by: K.B.Dharun Krishna <[email protected]>

kbdharun marked this pull request as draft October 29, 2023 11:03

kbdharun added 2 commits October 29, 2023 16:34

Merge branch 'main' into feat/platform-option

7a202f9

feat: add support for FreeBSD and NetBSD

00d2119

Signed-off-by: K.B.Dharun Krishna <[email protected]>

kbdharun marked this pull request as ready for review October 29, 2023 13:57

kbdharun requested review from owenvoke and removed request for CleanMachine1 October 29, 2023 14:00

cleanup: rearrange options, prepare for 3.4.0

0f93a98

Signed-off-by: K.B.Dharun Krishna <[email protected]>

kbdharun changed the title ~~feat: add platform option, Android and BSD platforms~~ feat (3.4.0): add platform option, Android and BSD platforms Oct 29, 2023

kbdharun added 2 commits October 29, 2023 20:24

README: minor fixes

0da22d8

Signed-off-by: K.B.Dharun Krishna <[email protected]>

Fix URL-encoded email highlighting

b5e9cc2

Signed-off-by: K.B.Dharun Krishna <[email protected]>

agnivade removed their request for review November 2, 2023 05:01

sbrl reviewed Nov 11, 2023

View reviewed changes

Merge branch 'main' into feat/platform-option

e623e5d

kbdharun added 2 commits November 14, 2023 14:49

cleanup: add release CI, drop Node 14 support

957aa05

Signed-off-by: K.B.Dharun Krishna <[email protected]>

cleanup: remove not working alias option

864dcea

Signed-off-by: K.B.Dharun Krishna <[email protected]>

kbdharun merged commit 98de9cb into main Nov 14, 2023
11 checks passed

kbdharun deleted the feat/platform-option branch November 14, 2023 11:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat (3.4.0): add platform option, Android and BSD platforms #421

feat (3.4.0): add platform option, Android and BSD platforms #421

kbdharun commented Oct 5, 2023 •

edited

Loading

sebastiaanspeck left a comment

sebastiaanspeck commented Oct 23, 2023

kbdharun commented Oct 24, 2023

MasterOdin left a comment

kbdharun commented Oct 29, 2023

kbdharun commented Oct 29, 2023 •

edited

Loading

agnivade commented Nov 2, 2023

sebastiaanspeck commented Nov 5, 2023 •

edited

Loading

kbdharun commented Nov 5, 2023

sbrl left a comment •

edited

Loading

kbdharun commented Nov 12, 2023 •

edited

Loading

sbrl commented Nov 12, 2023

kbdharun commented Nov 12, 2023

ivanhercaz commented Nov 12, 2023

agnivade commented Nov 13, 2023

kbdharun commented Nov 14, 2023 •

edited

Loading

kbdharun commented Nov 14, 2023 •

edited

Loading

kbdharun commented Nov 14, 2023 •

edited

Loading

feat (3.4.0): add platform option, Android and BSD platforms #421

feat (3.4.0): add platform option, Android and BSD platforms #421

Conversation

kbdharun commented Oct 5, 2023 • edited Loading

Description

Checklist

Related PRs

sebastiaanspeck left a comment

Choose a reason for hiding this comment

sebastiaanspeck commented Oct 23, 2023

kbdharun commented Oct 24, 2023

MasterOdin left a comment

Choose a reason for hiding this comment

kbdharun commented Oct 29, 2023

Changes in the last 3 commits

Reference outputs

kbdharun commented Oct 29, 2023 • edited Loading

Changes in last commit

Content

agnivade commented Nov 2, 2023

sebastiaanspeck commented Nov 5, 2023 • edited Loading

kbdharun commented Nov 5, 2023

sbrl left a comment • edited Loading

Choose a reason for hiding this comment

kbdharun commented Nov 12, 2023 • edited Loading

sbrl commented Nov 12, 2023

kbdharun commented Nov 12, 2023

ivanhercaz commented Nov 12, 2023

agnivade commented Nov 13, 2023

kbdharun commented Nov 14, 2023 • edited Loading

kbdharun commented Nov 14, 2023 • edited Loading

kbdharun commented Nov 14, 2023 • edited Loading

kbdharun commented Oct 5, 2023 •

edited

Loading

kbdharun commented Oct 29, 2023 •

edited

Loading

sebastiaanspeck commented Nov 5, 2023 •

edited

Loading

sbrl left a comment •

edited

Loading

kbdharun commented Nov 12, 2023 •

edited

Loading

kbdharun commented Nov 14, 2023 •

edited

Loading

kbdharun commented Nov 14, 2023 •

edited

Loading

kbdharun commented Nov 14, 2023 •

edited

Loading