Update all documentation for clarity and accuracy #1443
Conversation
Additionally, switch from 80 character line length limit as it is not necessary. Instead, follow the guideline of one sentence per line for documentation. This allows for easy reading of git diffs when documentation changes are made. A few text inconsistencies were also fixed throughout the code. Signed-off-by: Ethan Dye <[email protected]>
ecdye
added
enhancement
| e-mail address under which you can be reached (sorry, no github noreply e-mail | ||
| addresses (such as [email protected]) or other non-reachable | ||
| addresses are allowed). | ||
| using your real name (sorry, no pseudonyms or anonymous contributions) and an e-mail address under which you can be reached (sorry, no github noreply e-mail addresses (such as [email protected]) or other non-reachable addresses are allowed). |
There was a problem hiding this comment.
brackets inside brackets ?
| * Wrap Markdown code at 80 columns. Links and code examples may cross 80 | ||
| columns when necessary. | ||
| For example, `${COL_RED}`, additionally always be sure to reset to standard color at the end of your output statement by using `${COL_DEF}`. | ||
| * Never use absolute paths for binaries, always use the standard paths instead. For example, use `apt-get` instead of `/usr/bin/apt-get`. |
There was a problem hiding this comment.
no path actually ? and is it paths or pathes ?
| * Use all-lowercase global variables for all parametrization in `openhabian.conf`. | ||
| You may not directly read these from inside installation routines (but write if required e.g. to hide passwords after processing). | ||
| Global variables are sourced in as one batch at the beginning of code execution in both run modes. | ||
| Use local variables of the same name but applying camelCase in the install routine and initialize them with the all-lowercase global equivalent's contents before use. |
There was a problem hiding this comment.
If you have the user change any of these, you can write them back to config using store_in_conf()
| Machine and by testing on actual hardware, eg. Raspberry Pi. A Docker | ||
| installation can be performed by three commands. Firstly a Docker image is built | ||
| where the `openhabian` code is injected (see `Dockerfile.*` for details). | ||
| Test installations are done continuously using Docker on GitHub and by testing on actual hardware, eg. Raspberry Pi. |
There was a problem hiding this comment.
this sounds as if we test anything on real HW, too. I think we should differentiate CI vs real HW here
|
|
||
| * a **SD-card image pre-configured with openHAB** for all *Raspberry Pi* models | ||
| * as a set of scripts that sets up openHAB and tools on any Debian based system | ||
| * A **SD-card image pre-configured with openHAB** for all *Raspberry Pi* models |
There was a problem hiding this comment.
I have ever been wondering if its "a" or "an" in a combo like this or can you say both ?
| *** | ||
| ATTENTION:<br> | ||
| Avoid getting the 8 GB model of RPi 4.<br> | ||
| 8 GB of RAM is a waste of money and it has issues, you must [disable ZRAM](https://github.com/openhab/openhabian/blob/master/docs/openhabian.md#disable-zram) or use the 64bit image (untested). |
There was a problem hiding this comment.
not sure if we should already remove this ...
| to the system, `/etc/openhabian.conf` will be used from there on. You can change | ||
| it at any time to get output on future boot runs or if you use `openhabian-config` | ||
| interactively. | ||
| NOW, read [openhabian.md](https://github.com/openhab/openhabian/blob/main/docs/openhabian.md#openhabianconf)how to mount your SD card and how to modify the openHABian config file. |
| On ARM, we only support Raspberry Pi OS. | ||
| These are what we develop and test openHABian against. | ||
| We do **not support Ubuntu** so no promises. We provide code "as-is", it may work or not. | ||
| Several optional components such as WireGuard or Homegear are known to expose problems. | ||
| We do **not** actively **support Ubuntu** so no promises but we provide code "as-is" that is known to run on there. |
There was a problem hiding this comment.
I intentionally removed the "actively". As I had to learn there's still people to insist that wuith that in they understand it means it should work to use Ubuntu (and sooner or later show up asking for help when it does not, leading this whole paragraph ad adsurdum).
|
Would you be willing to review #1425 ? Dunno why James Bowler retracted his one on config mgmt in Github, do you ? |
Not sure. I hope he is just making changes then resubmitting. |
Additionally, switch from 80 character line length limit as it is not
necessary. Instead, follow the guideline of one sentence per line for
documentation. This allows for easy reading of git diffs when
documentation changes are made.
A few text inconsistencies were also fixed throughout the code.
Signed-off-by: Ethan Dye [email protected]