Merge pull request #36 from eshwen/esh-tidy-comments

Tidy up code comments

docs/programs/homebrew.md

@@ -15,18 +15,29 @@ Install Homebrew with the instructions at <https://brew.sh/>.(1) This should als
 ## Useful CLI utilities
 
 ```sh
-brew install bash  # for a newer version than that bundled with macOS
-brew install emacs  # since it's not provided by default as of macOS Catalina. If I can't run emacs after it's been installed, do 'brew reinstall --cask --no-quarantine emacs'
-brew install git  # for a newer version than that bundled with macOS
-brew link --overwrite git  # so it's linked by default instead of the version bundled with macOS
-brew install gnupg  # GPG key generation utility (for signing Git commits
-brew install poetry  # for Python project management
-brew install pyenv  # best way of managing Python installs on Mac
-brew install tree  # Show directory trees (use `-L <levels>` options to show set number of levels)
-brew install wget  # for wget command like on linux
-brew install zsh  # for a newer version than that bundled with macOS
+brew install bash  # (1)
+brew install emacs  # (2)
+brew install git  # (3)
+brew link --overwrite git  # (4)
+brew install gnupg  # (5)
+brew install poetry  # (6)
+brew install pyenv  # (7)
+brew install tree  # (8)
+brew install wget  # (9)
+brew install zsh  # (10)
 ```
 
+1. For a newer version than that bundled with macOS.
+2. Since it's not provided by default as of macOS Catalina. If I can't run emacs after it's been installed, do `brew reinstall --cask --no-quarantine emacs`.
+3. For a newer version than that bundled with macOS.
+4. So it's linked by default instead of the version bundled with macOS.
+5. GPG key generation utility (for signing Git commits).
+6. For Python project management.
+7. Best way of managing Python installs on Mac.
+8. Show directory trees (use `-L <levels>` options to show set number of levels).
+9. For `wget` command, like on linux.
+10. For a newer version than that bundled with macOS.
+
 ## Useful GUI applications
 
 Create a directory for games with
@@ -40,50 +51,68 @@ Then install the following GUI applications with
 
 ```sh
 brew install --cask adobe-acrobat-reader
-brew install --cask alfred  # suped version of Spotlight
-brew install --cask amazon-q  # for modern terminal settings, plugin management, etc.
-brew install --cask android-file-transfer  # For copying files to Oculus Quest
-brew install --cask ankerwork  # For configuring my webcam
-brew install --cask bartender  # for menu bar organisation
-brew install --cask blackhole-64ch  # for BlackHole (audio output from screen recording)
+brew install --cask alfred  # (1)
+brew install --cask amazon-q  # (2)
+brew install --cask android-file-transfer  # (3)
+brew install --cask ankerwork  # (4)
+brew install --cask bartender  # (5)
+brew install --cask blackhole-64ch  # (6)
 brew install --cask discord
 brew install --cask epic-games --appdir $games_dir
-brew install --cask fantastical  # Better calendar app than the default
-brew install --cask filebot --force --no-quarantine  # for batch renaming of files. Additional options required to start up properly
-brew install --cask folx  # torrent client
-brew install --cask github  # GitHub Desktop
+brew install --cask fantastical  # (7)
+brew install --cask filebot --force --no-quarantine  # (8)
+brew install --cask folx  # (9)
+brew install --cask github
 brew install --cask gog-galaxy --appdir $games_dir
 brew install --cask google-chrome
 brew install --cask google-drive
-brew install --cask handbrake  # for re-encoding videos
-brew install --cask hyper  # a nicer, modern terminal
-brew install --cask macgpt  # ChatGPT plugin
-brew install --cask mactex  # for MacTeX distro of TeXLive with GUI applications
-brew install --cask messenger  # Facebook Messenger
+brew install --cask handbrake
+brew install --cask hyper  # (10)
+brew install --cask macgpt  # (11)
+brew install --cask mactex  # (12)
+brew install --cask messenger
 brew install --cask microsoft-excel
 brew install --cask microsoft-powerpoint
 brew install --cask microsoft-word
-brew install --cask mimestream  # a modern, macOS-native Gmail client
-brew install --cask mkvtoolnix  # for quickly adding/removing embedded audio and subtitle tracks from MKV files
-brew install --cask openemu  # Old video game emulation
-brew install --cask plex  # Media player client for Plex
+brew install --cask mimestream  # (13)
+brew install --cask mkvtoolnix  # (14)
+brew install --cask openemu  # (15)
+brew install --cask plex
 brew install --cask private-internet-access
-brew install --cask pycharm  # My favourite IDE at the moment
-brew install --cask qlvideo  # for QLVideo (thumbnails for mkv and other file formats)
+brew install --cask pycharm
+brew install --cask qlvideo  # (16)
 brew install --cask raindropio
-brew install --cask readdle-spark  # For the Spark email client
+brew install --cask readdle-spark  # (17)
 brew install --cask runescape --appdir $games_dir
-brew install --cask sidequest  # For sideloading more VR content onto Oculus Quest
-brew install --cask skype
+brew install --cask sidequest  # (18)
 brew install --cask steam --appdir $games_dir
 brew install --cask todoist
-brew install --cask visual-studio-code  # A good code and text editor supporting many languages
-brew install --cask vivid  # Unlock higher brightness range on the display
+brew install --cask visual-studio-code
+brew install --cask vivid  # (19)
 brew install --cask vlc
 brew install --cask whatsapp
-brew install --cask zoom
 ```
 
+1. Suped up version of Spotlight.
+2. For modern terminal settings, plugin management, etc. Requires an AWS account.
+3. For copying files to Oculus Quest.
+4. For configuring my webcam.
+5. For menu bar organisation. Requires a licence.
+6. For capturing audio output alongside a screen recording.
+7. Better calendar app than the default.
+8. For batch renaming of files. Additional options required to start up properly.
+9. Torrent client.
+10. A nicer, modern terminal.
+11. ChatGPT plugin. Requires a licence.
+12. For MacTeX distro of TeXLive with GUI applications.
+13. A modern, macOS-native Gmail client. Requires a subscription.
+14. For quickly adding/removing embedded audio and subtitle tracks from MKV files.
+15. Retro video game emulator.
+16. For thumbnails for mkv and other file formats.
+17. Another powerful email client.
+18. For sideloading more VR content onto Oculus Quest.
+19. Unlock higher brightness range on the display. Requires a licence.
+
 Typically, the `--cask` option is used when you want to install GUI applications. Certain packages like `handbrake` can operate solely on the command line. So in that case, just doing `brew install handbrake` would install the _formula_ (the CLI-only version), where `brew install --cask handbrake` will install the GUI application that sits in my `Applications` folder.
 
 For any issues with opening these programs, see <https://support.apple.com/en-gb/guide/mac-help/mh40616/mac>.

docs/programs/latex.md

@@ -7,10 +7,13 @@ TeX Live is installed under the `mactex` cask with Homebrew. As well as the actu
 ```sh
 tex_dir="/Applications/TeX"
 mkdir $tex_dir
-brew install --cask bibdesk --appdir $tex_dir  # for LaTeX bibliography management
-brew install --cask tex-live-utility --appdir $tex_dir  # for maintaining installed LaTeX packages
+brew install --cask bibdesk --appdir $tex_dir  # (1)
+brew install --cask tex-live-utility --appdir $tex_dir  # (2)
 ```
 
+1. For managing BibTeX references.
+2. For updating TeX Live packages.
+
 MacTeX/TeX Live installs as root (possibly to avoid large installs and conflicts for multiple users). So if avoiding TeX Live Utility to update packages, I can go via the command line with `sudo` privileges. Check for outdated packages with
 
 ```sh

docs/programs/python.md

@@ -34,13 +34,15 @@ For completeness, below are instructions to install Anaconda with Homebrew:
 
 ```sh
 brew install --cask anaconda
-conda init "$(basename "${SHELL}")"  # If 'conda' executable doesn't work, run $(brew --prefix)/anaconda3/bin/conda
+conda init "$(basename "${SHELL}")"  # (1)
 <exit and reopen shell>
 conda activate
 conda config --set auto_activate_base false
 conda deactivate
 ```
 
+1. If `conda` executable doesn't work, run `$(brew --prefix)/anaconda3/bin/conda`
+
 Then, to install the Anaconda Navigator (a GUI for managing conda environments and installing related tools), do
 
 ```sh