From 858a4a31a251d0eab21dffb96776aca007dafb07 Mon Sep 17 00:00:00 2001 From: Chloe Kudryavtsev Date: Fri, 14 Feb 2020 19:11:04 -0500 Subject: Squashed 'dot_local/share/toasty/' content from commit aee4da7 git-subtree-dir: dot_local/share/toasty git-subtree-split: aee4da752bdb07b0524bb8803ead46d4093fa57f --- README.adoc | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 README.adoc (limited to 'README.adoc') diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..8ecf7dd --- /dev/null +++ b/README.adoc @@ -0,0 +1,202 @@ +:icons: font +:source-highlighter: pygments +:toc: preamble + +// Links +:license: LICENSE.md +:example: examples/zshrc.local + +:img-license: https://img.shields.io/github/license/5pacetoast/toasty-zsh.svg + +:license-omz: third-party-licenses/LICENSE.OMZ.md +:license-pure: third-party-licenses/LICENSE.pure.txt +:license-purer: third-party-licenses/LICENSE.purer.txt +:license-shellder: third-party-licenses/LICENSE.shellder.txt + +:repo-omz: https://github.com/robbyrussell/oh-my-zsh[Oh My Zsh] +:repo-pure: https://github.com/sindresorhus/pure[Pure] +:repo-purer: https://github.com/dfurnes/purer[Purer] +:repo-shellder: https://github.com/simnalamburt/shellder[Shellder] + +:brpaste: https://brpaste.xyz[BRPaste] +:sprunge: http://sprunge.us[Sprunge] +:zshwiki: http://zshwiki.org[Zsh Wiki] + +// Github-specific workarounds +ifdef::env-github[] +:tip-caption: :bulb: +:note-caption: :information_source: +:important-caption: :heavy_exclamation_mark: +:caution-caption: :fire: +:warning-caption: :warning: +endif::[] + += Toasty Zsh + +image::{img-license}[License, link={license}] + +The zsh framework made to facilitate management, not dictate it. + +== Quickstart +1. Clone this repository somewhere +2. `echo ZDOTDIR=/path/to/repo > ~/.zshenv` +3. Restart your z shell + +=== Expanding on it +- Drop files you want to be sourced during startup into `$zd/source/` +- Drop functions you want to potentially use/autoload into `$zd/functions/` +- Drop plugins you want to source on-demand into `$zd/plugins/` +- Drop custom completions into `$zd/completions/` +- Drop custom prompts into `$zd/prompts/` + +NOTE: Most of these are for mindspace separation, the completions, prompts and functions directories are functionally identical, and as such you can use any of them for any purpose. + +WARNING: Don't run compinit yourself! It happens at the very end (after sourcing `zshrc.local`) as is. All it'll do is make your performance worse. + +NOTE: If you want `$zd` to be anywhere but `~/.zsh`, set it in `~/.zshenv`. + +=== Full List of Supported Installation Methods +==== Local +- Setting `$ZDOTDIR` (usually in `~/.zshenv`) to point to the repository. ++ +WARNING: This may, however, dirty your repository, depending on what `$ZDOTDIR` ends up being used for. +- Sourcing `zshrc` in `~/.zshrc`. +- Linking `zshrc` to `~/.zshrc`. + +==== Global +- Cloning toasty-zsh into `/etc/zsh` (on distributions with sane/common zsh defaults). +- Sourcing `zshrc` in `/etc/zsh/zshrc`. +- Linking `zshrc` to `/etc/zsh/zshrc`. + +WARNING: You may want to `touch ~/.zshrc` when installing globally, to avoid zsh complaining about it being missing. + +NOTE: If you have a global install of toasty-zsh, or some other framework, and have a local version, you can `setopt NO_GLOBAL_RCS` in `~/.zshenv` to skip loading the global variant. + +== Structure +Toasty Zsh provides a structure under `~/.zsh` for you to use. Everything except `zshrc.local` is optional. + +`$zshd`:: Dynamically set to wherever the Toasty Zsh repository copy is. +`$zd`:: Your "Z Directory". Set to `~/.zsh` by default. The rest of this list is inside of this. +completions/:: Added to your `$fpath`. Serves to put custom completions into without muddying up your functions. +functions/:: Added to your `$fpath`. Serves to put your functions into, for autoloading. +plugins/:: Added to your `$spath`. Serves for optionally-sourced plugins. See <> for more details. +prompts/:: Added to your `$fpath`. Serves to throw your custom prompts into without muddying up your functions. +source/:: Added to your `$apath`. Serves for automatic sourcing on-demand/startup. See <> for more details. +pre:: Sourced right before running <>, giving you a chance to edit the sane-default `${fpath,spath,apath}` values. +zshrc.local:: Sourced right before compinit. + +== API +=== Functions +Various functions for use. Some are used internally. + +NOTE: Enabling (autoloading) a function in zsh defers loading - it makes the function available from the moment you do it, but it won't be actually loaded until you first use it, making them much more efficient than sourced files. + +==== Autosource +Iterates over `$spath` until it finds a matching `$1`, then sources it. + +Examples: +[source,sh] +---- +spath=( "$PWD" ) autosource a # <1> +spath=( a b ) autosource c # <2> +spath=( "$PWD" ) autosource foo/bar # <3> +---- +<1> will source `./a` if it exists +<2> will source `./a/c`, and then `./b/c` if that fails +<3> will source `./foo/bar` if it exists + +WARNING: Relative entries will always be relative. If you set `$spath` to `.` and then change directories, it'll continue using `.`, which is potentially insecure. + +NOTE: For convenience's sake, `$spath` and `$SPATH` are bound - you can manipulate `$SPATH` (which is formatted like `$PATH`) to modify `$spath`. + +==== Sourceall +Will source every file in every directory in `$apath`. If an argument is provided, will only source files that end in `.$1`. + +Examples: +[source,sh] +---- +apath=( a b ) sourceall # <1> +apath=( "$PWD" ) sourceall zsh # <2> +---- +<1> will source `a/*` and `b/*` +<2> will source `./*.zsh` + +NOTE: By default, Toasty Zsh will run `sourceall zsh` between sourcing `$zd/pre` and `zshrc.local`. By default, it only goes through `$zshd/source` and `$zd/source`. You can customize this behavior in `$zd/pre`. + +WARNING: Sourceall does not recurse into subdirectories, though you can work around that by adding a `99-subdir.zsh` file or similar where you call it with a custom `$apath` set. + +NOTE: As with `$spath`, `$apath` is bound to a `$PATH`-like `$APATH`. + +==== Brpaste +Simple wrapper around {brpaste}. +Takes thing in stdin, or uses the first argument as the file to upload. +Outputs the paste url. + +Examples: +[source,sh] +---- +echo hi | brpaste # <1> +brpaste file # <2> +bsdtar -cf- --format shar dir | brpaste # <3> +brpaste file | xsel -ib # <4> +---- +<1> upload "hi\n" to brpaste.xyz +<2> upload file to brpaste.xyz +<3> upload a "shar" archive of dir to brpaste.xyz +<4> upload file to brpaste.xyz and place the non-raw link into the clipboard + +==== Sprunge +Simple wrapper around {sprunge}. Takes things in stdin, outputs the url into stdout. + +Examples: +[source,sh] +---- +echo hi | sprunge # <1> +sprunge < file # <2> +bsdtar -cf - --format shar dir | sprunge # <3> +---- +<1> upload `"hi\n"` to sprunge.us +<2> upload file to sprunge.us +<3> upload a "shar" archive of dir to sprunge.us + +=== Plugins +Plugins are just files you source! See <> for a convenient way to do so. + +You can add your own by dropping them into a directory in your `$spath` (such as `$zd/plugins`). + +==== Sudo +Press `` twice to either add or remove `sudo` from the beginning of your line. + +If the current line is empty, operates on the previous line instead. + +==== Xterm-Title +Sets up a simple hook system to print what's currently being executed into an xterm-compatible terminal's title. + +WARNING: some prompts (such as {repo-pure}) do this for you aleady! If you use both, they won't conflict, but you'd be wasting cycles *and* might see some strange text flashing through on every command. + +== External Projects +I didn't write everything in here, some of it is bundled. + +Note that you do not pay (except with drive space) for most of these unless you choose to use them. + +=== Plugins + +Sudo:: From {repo-omz}. + +=== Prompts + +Pure:: From {repo-pure}. +Purer:: From {repo-purer}. +Shellder:: From {repo-shellder}. +Toasty:: Written from scratch by me, but takes heavy inspiration from robbyrussel's theme from {repo-omz}. + +=== Other + +`bindkeys.zsh`:: Written by me, but heavily inspired by similar content from {repo-omz} and the {zshwiki}. + +=== Licenses + +- Oh My Zsh link:{license-omz}[LICENSE] +- Pure link:{license-pure}[LICENSE] +- Purer link:{license-purer}[LICENSE] +- Shellder link:{license-shellder}[LICENSE] -- cgit v1.2.3