diff --git a/FAQ.md b/FAQ.md index c81ed30..3cae64a 100644 --- a/FAQ.md +++ b/FAQ.md @@ -22,7 +22,7 @@ A 'cli' is a [command-line interface](https://en.wikipedia.org/wiki/Command-line ## How do I incorporate BASH3 Boilerplate into my own project? -You can incorporate BASH3 Boilerplate into your project one of three ways: +You can incorporate BASH3 Boilerplate into your project in one of three ways: 1. Copy the desired portions of [main.sh](https://github.com/kvz/bash3boilerplate/blob/master/main.sh) into your own script. 1. Download [main.sh](https://github.com/kvz/bash3boilerplate/blob/master/main.sh) and start pressing the delete-key for unwanted things @@ -43,13 +43,13 @@ Once the `main.sh` has been tailor-made for your project you could either append 1. Copy the line the main.sh [read block](https://github.com/kvz/bash3boilerplate/blob/master/main.sh#L53) that most resembles the desired behavior and paste the line into the same block. 1. Edit the single-character (e.g., -d) and, if present, the multi-character (e.g., --debug) versions of the flag in the copied line. -1. Omit the "[arg]" text in the copied line if the desired flag takes no arguments. +1. Omit the "[arg]" text in the copied line, if the desired flag takes no arguments. 1. Omit or edit the text after "Default:" to set or not set default values, respectively. -1. Omit the "Required." text if the flag is optional. +1. Omit the "Required." text, if the flag is optional. ## How do I access the value of a command-line argument? -To evaluate the value of an argument, append the corresponding single-character flag to the text `$arg_`. For example, if the [read block] +To find out the value of an argument, append the corresponding single-character flag to the text `$arg_`. For example, if the [read block] contains the line ```bash -t --temp [arg] Location of tempfile. Default="/tmp/bar" @@ -63,7 +63,7 @@ __temp_file_name="${arg_t}" ## What is a magic variable? -The [magic variables](https://github.com/kvz/bash3boilerplate/blob/master/main.sh#L63) in `main.sh` are special in that they have a different value, depending on your environment. You can use `${__file}` to get a reference to your current script, `${__dir}` to get a reference to the directory it lives in. This is not to be confused with the location of the calling script that might be sourcing the `${__file}`, which is accessible via `${0}`, and the current directory of the administrator running the script, accessible via `$(pwd)`. +The [magic variables](https://github.com/kvz/bash3boilerplate/blob/master/main.sh#L63) in `main.sh` are special in that they have a different value, depending on your environment. You can use `${__file}` to get a reference to your current script, and `${__dir}` to get a reference to the directory it lives in. This is not to be confused with the location of the calling script that might be sourcing the `${__file}`, which is accessible via `${0}`, or the current directory of the administrator running the script, accessible via `$(pwd)`. ## How do I submit an issue report? @@ -71,20 +71,20 @@ Please visit our [Issues](https://github.com/kvz/bash3boilerplate/issues) page. ## How can I contribute to this project? -Please fork this repository. Then create a branch containing your suggested changes and submit a pull request based on the master branch -of . We're a welcoming bunch, happy to accept your contributions! +Please fork this repository. After that, create a branch containing your suggested changes and submit a pull request based on the master branch +of . We are always more than happy to accept your contributions! ## Why are you typing BASH in all caps? As an acronym, Bash stands for Bourne-again shell, and is usually written with one uppercase. -This project's name however is "BASH3 Boilerplate" as a reference to +This project's name, however, is "BASH3 Boilerplate". It is a reference to "[HTML5 Boilerplate](https://html5boilerplate.com/)", which was founded to serve a similar purpose, only for crafting webpages. -Somewhat inconsistent but true to Unix ancestry, the abbreviation for our project is "b3bp". +Somewhat inconsistent – but true to Unix ancestry – the abbreviation for our project is "b3bp". ## How can I locally develop and preview the b3bp website? -You should have a working Node.js >=10 and Ruby >=2 install on your workstation. Afterwards, you can run: +You should have a working Node.js >=10 and Ruby >=2 install on your workstation. When that is the case, you can run: ```bash npm run web:preview @@ -94,36 +94,36 @@ This will install and start all required services and automatically open a webbr The source mainly consists of: -- `./README.md` Front page -- `./FAQ.md` FAQ page -- `./CHANGELOG.md` Changelog page -- `./website/_layouts/default.html` Design in which all pages are rendered -- `./website/public/app.js` Main JS file -- `./website/public/style.css` Main CSS file +- `./README.md` (Front page) +- `./FAQ.md` (FAQ page) +- `./CHANGELOG.md` (changelog page) +- `./website/_layouts/default.html` (the design in which all pages are rendered) +- `./website/public/app.js` (main JS file) +- `./website/public/style.css` (main CSS file) -The rest is dark magic you should probably steer clear from : ) +The rest is dark magic from which you should probably steer clear. : ) Any changes should be proposed as PRs. Anything added to `master` is automatically deployed using a combination of Travis CI and GitHub Pages. -## You're saying you are portable - why won't b3bp code run in dash / busybox / posh / ksh / mksh / zsh? +## You are saying you are portable, but why won't b3bp code run in dash / busybox / posh / ksh / mksh / zsh? When we say _portable_, we mean across Bash versions. Bash is widespread and most systems -offer at least version 3 of it. Make sure you have that available, and b3bp will work for you. +offer at least version 3 of it. Make sure you have that available and b3bp will work for you. -We run automated tests to make sure that it will, here's proof for the following platforms: +We run automated tests to make sure that it will. Here is some proof for the following platforms: - [Linux](https://travis-ci.org/kvz/bash3boilerplate/jobs/109804166#L91) `GNU bash, version 4.2.25(1)-release (x86_64-pc-linux-gnu)` - [OSX](https://travis-ci.org/kvz/bash3boilerplate/jobs/109804167#L2453) `GNU bash, version 3.2.51(1)-release (x86_64-apple-darwin13)` -This portability however does not mean we try to be compatible with -KornShell, Zsh, posh, yash, dash or other shells. We allow syntax that would explode if +This portability, however, does not mean that we try to be compatible with +KornShell, Zsh, posh, yash, dash, or other shells. We allow syntax that would explode if you pasted it in anything but Bash 3 and up. ## How do I do Operating System detection? -We used to offer a magic `__os` variable, but quickly [discovered](https://github.com/kvz/bash3boilerplate/issues/38) that it would be hard -to create a satisfactory abstraction that is correct, covers enough use-cases, -and still has a relatively small footprint in `main.sh`. +We used to offer a magic `__os` variable, but we quickly [discovered](https://github.com/kvz/bash3boilerplate/issues/38) that it would be hard +to create a satisfactory abstraction that is not only correct, but also covers enough use-cases, +while still having a relatively small footprint in `main.sh`. For simple OS detection, we recommend using the `${OSTYPE}` variable available in Bash as is demoed in [this stackoverflow post](http://stackoverflow.com/a/8597411/151666):