pages/common/*: replace unportable shell syntax in command examples

[tricantivu]

• The page(s) are in the correct platform directories: common, linux, osx, windows, sunos, android, etc.
• The page(s) have at most 8 examples.
• The page description(s) have links to documentation or a homepage.
• The page(s) follow the content guidelines.
• The PR title conforms to the recommended templates.
• Version of the command being documented (if known):

As proposed in #12694, I think the command examples of pages in the directory common must should adhere to the latest POSIX standard to have some degree of certainty that the commands will function properly in many shells.

To find pages with unportable syntax, I used the following:

#!/usr/bin/env bash

codes=(SC{3000..4000})

for f in pages/common/*.md; do
    echo "Page: ${f}"
    grep -Ex '`.+`' -- "${f}" | sed 's/`//g' | shellcheck -i "$(echo "${codes[@]}" | tr " " ",")" -s sh -f gcc -
done

• Process substitution:

grep -FR --exclude-dir=pages.en '<(' pages*

• Extended globs:

grep -RE --exclude-dir=pages.en '[?*+@!]\(.*\)' pages*

• function keyword

grep -RE --exclude-dir=pages.en 'function [A-Za-z0-9_]+(\(\))?' pages*

• "File slurps" ¹:

grep -RExl --exclude-dir=pages.en '`.*\$\(<.*\).*`' pages*

It is worth noting that the grep commands and the script are nowhere near foolproof, I encountered many false positives, especially about brace expansions. Therefore, there are probably more pages out there with unportable shell syntax.

Footnotes

1. https://mywiki.wooledge.org/Bashism#Syntax ↩

[gutjuri]

Thanks! Even though this is still WIP I have added some comments. I think that we should proceed very carefully to preserve the original meaning of the examples.

[gutjuri]

Diff doesn't work for encrypted files. The sops -d command must be called to decrypt the sops files.

[tricantivu]

Would replacing the placeholder for {{decrypted_sops_file}} cut it?

[gutjuri]

In my opinion not, because decrypted sops files are just plain json or yaml files if I understand the docs of sops correctly.

Also, I do not think that we should eliminate process substitution from our examples. I highly doubt that any user uses a shell that doesn't support process substitution as their daily driver (no beginner user, anyway). I think that tldr pages remain more useful with the process substitution examples left in.

[spageektti]

In my opinion not, because decrypted sops files are just plain json or yaml files if I understand the docs of sops correctly.

Also, I do not think that we should eliminate process substitution from our examples. I highly doubt that any user uses a shell that doesn't support process substitution as their daily driver (no beginner user, anyway). I think that tldr pages remain more useful with the process substitution examples left in.

SOPS is an editor of encrypted files that supports YAML, JSON, ENV, INI and BINARY formats [...]
from here
so the decrypted sops file is in one of the formats above.

[spageektti]

Is this PR ready to review or still WIP?

[tricantivu]

Is this PR ready to review or still WIP?

The latter