github-docs VS ShellCheck

In college, an English professor would ask me and other students the following question when reviewing our essays, “Where are the examples?” Developers ask the same question when reading your documentation. To write good technical writing documents, include examples that developers can see themselves implementing in their work. How can this be done? By adding examples from your product’s codebase! 🙂 Let’s look at this code snippet from my contribution to GitHub’s documentation:

Need an example? Check the GitHub docs contributing guide.

git clone https://github.com/github/docs.git 123.57s user 37.02s system 74% cpu 3:35.73 total

git clone --depth 1 https://github.com/github/docs.git 3.37s user 1.83s system 35% cpu 14.521 total

Not a scientific test at all, but the second one was literally 35x faster, wall clock time.

Docs

The strange thing is that I only have this problem with github, all other websites work just fine. And even docs.github.com works fine...

99.9 at best for enterprise cloud: https://github.com/github/docs/blob/main/content/site-policy/site-policy-deprecated/github-enterprise-service-level-agreement.md

A project repository typically has a license file at the top-level indicating which license the code falls under. See here for an example license file.

ncurse, dialog, zenity[2]. i/o buffering may be an issue [3a,3b]

Assuming using same account, use history command to show past commands[0a, 0b]

'load random example' on shellcheck using own custom examples from history command.[1]

--------

[3a] : http://www.gnu.org/software/coreutils/manual/html_node/stdbu...

[3b] : http://unix.stackexchange.com/questions/25372/how-to-turn-of...

[2] : http//funprojects.blog/2021/01/25/zenity-command-line-dialogs/

[1] : http://www.shellcheck.net/

[0a] : http://www.tecmint.com/history-command-examples/

[0b] : http://www.tecmint.com/remember-linux-commands/

web based documentation: https://www.tecmint.com/linux-commands-cheat-sheet/

commands grouped by typical usage patterns : https://www.tecmint.com/essential-linux-commands/

... #************************** Terraform ************************************* ARG TERRAFORM_VERSION=1.7.3 RUN set -ex \ && curl -O https://releases.hashicorp.com/terraform/${TERRAFORM_VERSION}/terraform_${TERRAFORM_VERSION}_linux_amd64.zip && unzip terraform_${TERRAFORM_VERSION}_linux_amd64.zip -d /usr/local/bin/ RUN set -ex \ && mkdir -p $HOME/.terraform.d/plugin-cache && echo 'plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"' > ~/.terraformrc #************************* Terragrunt ************************************* ARG TERRAGRUNT_VERSION=0.55.1 RUN set -ex \ && wget https://github.com/gruntwork-io/terragrunt/releases/download/v${TERRAGRUNT_VERSION}/terragrunt_linux_amd64 -q \ && mv terragrunt_linux_amd64 /usr/local/bin/terragrunt \ && chmod +x /usr/local/bin/terragrunt #*********************** Terramate **************************************** ARG TERRAMATE_VERSION=0.4.5 RUN set -ex \ && wget https://github.com/mineiros-io/terramate/releases/download/v${TERRAMATE_VERSION}/terramate_${TERRAMATE_VERSION}_linux_x86_64.tar.gz \ && tar -xzf terramate_${TERRAMATE_VERSION}_linux_x86_64.tar.gz \ && mv terramate /usr/local/bin/terramate \ && chmod +x /usr/local/bin/terramate #*********************** tfsec ******************************************** ARG TFSEC_VERSION=1.28.5 RUN set -ex \ && wget https://github.com/aquasecurity/tfsec/releases/download/v${TFSEC_VERSION}/tfsec-linux-amd64 \ && mv tfsec-linux-amd64 /usr/local/bin/tfsec \ && chmod +x /usr/local/bin/tfsec \ && terragrunt --version #**********************Terraform docs ************************************ ARG TERRRAFORM_DOCS_VERSION=0.17.0 RUN set -ex \ && curl -sSLo ./terraform-docs.tar.gz https://terraform-docs.io/dl/v${TERRRAFORM_DOCS_VERSION}/terraform-docs-v${TERRRAFORM_DOCS_VERSION}-$(uname)-amd64.tar.gz \ && tar -xzf terraform-docs.tar.gz \ && chmod +x terraform-docs \ && mv terraform-docs /usr/local/bin/terraform-docs #********************* ShellCheck ***************************************** ARG SHELLCHECK_VERSION="stable" RUN set -ex \ && wget -qO- "https://github.com/koalaman/shellcheck/releases/download/${SHELLCHECK_VERSION?}/shellcheck-${SHELLCHECK_VERSION?}.linux.x86_64.tar.xz" | tar -xJv \ && cp "shellcheck-${SHELLCHECK_VERSION}/shellcheck" /usr/bin/ \ && shellcheck --version ...

ShellCheck: https://github.com/koalaman/shellcheck

If I want to write better shell scripts I usually run shellcheck and adjust accordingly or if I need facilities not provided by the shell i switch to a full fledged programming language. Ans oh yes, `sh` is present almost on every BSD and Linux box for free so I consider it an important thing to at least be comfortable with.

shellcheck: https://www.shellcheck.net/

When I run nix-shell at the root of the project it puts me in a Nix shell that contains, among other programs, caddy and shellcheck. Notice that in the shellHook I add the project's shell scripts to the PATH. So once I'm in the Nix shell I can, among other things:

I have also seen some projects on github like ShellCheck which first make a library, expose all the modules and then simple add that do build-depends of the final executable. Is this the recommended approach than having just one executable and adding all the modules to other-modules:?

The error checks can be pretty arcane:

   https://github.com/koalaman/shellcheck/wiki/Checks

Similar to for instance shellcheck to check the syntax of shell scripts, is there an equivalent for the set of roff commands typically used in a (Linux) man page? I'm aware that e.g. pandoc permits the conversion of an other format (e.g., org) to both roff man and roff ms.