Proposed enhancements to runcoms repo documentation #1540
Conversation
|
To anyone interested in reviewing this, it's easiest to look at here: https://github.com/hlecuanda/prezto/blob/5d2b2a776e3ae1145c25d147869371c3ddf1b274/runcoms/README.md |
There was a problem hiding this comment.
I've left quite a few comments on this, so this is meant to be a quick summary - I like the rundown of when all the files are loaded and what they should be used for. I think that's useful and should be kept/refined.
However, I don't think the commentary on runcoms belongs in the documentation. That should be discussed in a separate issue. I would be happy to accept a pull request which either adds support for .zlogin.local files (and equivalents for other runcoms) or which changes the recommendation to copying, as long as there's discussion among the other contributors and they're alright with it as well.
Thank-you for taking the time to submit this. There's a ton here which will be helpful.
EDIT: Additionally, minor copy-editing things like capitalization and such, I'd be happy to clean up, so don't worry too much about that. There's a ton of content here, so I think that should be the focus of this PR and any reviews.
runcoms/README.md
Outdated
|
|
||
| ### zpreztorc | ||
| | always runs | when `GLOBAL_RCS` is set | when `RCS` is set | Purpose | stuff that usually goes there, and notes | |
There was a problem hiding this comment.
This table is a bit wide... I think we could probably drop a column by having File, and Triggers to replace always runs, when GLOBAL_RCS is set and when RCS is set because only one of those ever has data in it at once.
There was a problem hiding this comment.
quite right! i thought so too. and good idea i'll make it so the headers go something lije this:
system/site config (/etc/zsh/*) |
User's config (${ZDOTDIR:-$HOME}) |
Purpose | Example/Notes |
|---|---|---|---|
| stuff | ,+stuff | stuff | even more stuff |
| more stuff | user stuff | Purpose stuff | example stuff |
runcoms/README.md
Outdated
| |------------------|-----------------------------------------|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | `/etc/zshenv` | | | system provided minimal environment | Always runs! should be minimal set ZDOTDIR, minimal environment. system paths | ||
| | | | `${ZDOTDIR:-$HOME}/.zshenv` | user environment overrides non-interactive, non-login shells (when invoked via shebang in a script or via `zsh -c [script]` or when invoked by `make` | personal environment overrides, such as `MANPATH`, `TERM`, `fpath` *non interactive scripts should have their environment completly set up here* ) | ||
| | | `/etc/zshprofile` | | system profile for login shells (`zsh -ls zsh - or via _ssh forced command_`) | minimal system paths for remote interaction, site `fpath`, site `$LOCALE`, lang. |
There was a problem hiding this comment.
The man pages I looked at refer to this as /etc/zprofile
There was a problem hiding this comment.
O.o indeed... my mistake. i was having tunnel vision or "shop" blindness because i dint catch it even on proofbreading.. haha 😮
runcoms/README.md
Outdated
| | `/etc/zshenv` | | | system provided minimal environment | Always runs! should be minimal set ZDOTDIR, minimal environment. system paths | ||
| | | | `${ZDOTDIR:-$HOME}/.zshenv` | user environment overrides non-interactive, non-login shells (when invoked via shebang in a script or via `zsh -c [script]` or when invoked by `make` | personal environment overrides, such as `MANPATH`, `TERM`, `fpath` *non interactive scripts should have their environment completly set up here* ) | ||
| | | `/etc/zshprofile` | | system profile for login shells (`zsh -ls zsh - or via _ssh forced command_`) | minimal system paths for remote interaction, site `fpath`, site `$LOCALE`, lang. | ||
| | | | `${ZDOTDIR:-$HOME}/.zshprofile` | personal preferences for interactive login shells | your preferred `$LOCALE`, `$LANG`, `readlne` config, `cdpath`, session managers, additional `fpath` ) login shells (but non necessarily **ineractive** as when invoked via _ssh remote cmd_ ) will read config up to this point |
There was a problem hiding this comment.
Similarly, this was ~/.zprofile
runcoms/README.md
Outdated
| | | | `${ZDOTDIR:-$HOME}/.zshprofile` | personal preferences for interactive login shells | your preferred `$LOCALE`, `$LANG`, `readlne` config, `cdpath`, session managers, additional `fpath` ) login shells (but non necessarily **ineractive** as when invoked via _ssh remote cmd_ ) will read config up to this point | ||
| | | `/etc/zshrc` | | system provided startup script, for interactive shells, (local shells that live in an `XTerm`, `URxvt`, `gnome-terminal`) or subshells (like running `xterm` from the command prompt of a _login xterm_, | site login accounting, security monitors, site command logging policy | ||
| | | | `${ZDOTDIR:-$HOME}/.zshrc` | user customization of their *interactive* environment for terminals | sourcing custom completions (`gcloud.comp.inc`), custom user frameworks (zprezto is invoked here), additional path required by custom software installed in `/opt/*` | ||
| | | `/etc/zshlogin` | | additional customization for interactive **login** shells, such as those accessed via ssh | tmux attach to existing session |
runcoms/README.md
Outdated
| | | `/etc/zshrc` | | system provided startup script, for interactive shells, (local shells that live in an `XTerm`, `URxvt`, `gnome-terminal`) or subshells (like running `xterm` from the command prompt of a _login xterm_, | site login accounting, security monitors, site command logging policy | ||
| | | | `${ZDOTDIR:-$HOME}/.zshrc` | user customization of their *interactive* environment for terminals | sourcing custom completions (`gcloud.comp.inc`), custom user frameworks (zprezto is invoked here), additional path required by custom software installed in `/opt/*` | ||
| | | `/etc/zshlogin` | | additional customization for interactive **login** shells, such as those accessed via ssh | tmux attach to existing session | ||
| | | | `${ZDOTDIR:-$HOME}/.zshlogin` | user script for *login shell startup* (this shell is a session leader, and allocates a `ptty` | aliases, keybindings, personal startup programs, time tracking apps, session managers, quote of the day, fortunes |
runcoms/README.md
Outdated
| you would call `xterm -e zsh -ls` on tmux you may add one of the following | ||
| lines to your `.tmux.conf`: | ||
|
|
||
| ```config |
There was a problem hiding this comment.
I assume this is meant to be bash, similar to the second block.
runcoms/README.md
Outdated
| set $XTERM_CMD='xterm -e zsh -ls` | ||
| bind $mod+x $XTERM_CMD | ||
| ... | ||
| ``` |
There was a problem hiding this comment.
This is a nit-pick, but I prefer to see new-lines between paragraphs, even if it's just a code block.
There was a problem hiding this comment.
in the end i decided to drop the indent and make the example more concise. In this case, purposely added something that looked like ellipsis ( . . . ) to mean that we were only looking at a section of thee file and that further lines followed, as well as more lines before...
maybe using ellipsis is not as common a convention as i thought it was... 🤔
runcoms/README.md
Outdated
| set -g default-shell '/usr/bin/zsh -ls' | ||
| ``` | ||
|
|
||
| Here is an examplefor *i3wm* on ubuntu |
There was a problem hiding this comment.
examplefor should be two words.
There was a problem hiding this comment.
plus, should be backwards... u.u
runcoms/README.md
Outdated
| end up with bloated shells on non-interactive environments. Perhaps desktop | ||
| workstation users will not notice any difference, but in resource-constrained | ||
| environments it may be significant in terms of execution time and energy | ||
| consumption (v.gr when running a Raspberry PI on batteries or on a cell |
There was a problem hiding this comment.
v.gr : shorthand of verbi gratia / "for example" although literal latin translation would be "for the sake of a word"... she's Q.E.D.'s (Quod Erat Demostrandum) ugly cousin... 😺
runcoms/README.md
Outdated
| distributed *runcoms* **as is** which is a terrible idea, since doing | ||
| `git pull` to update your distribution will clobber your customizations. | ||
|
|
||
| it’s a better idea to *copy* the distributed *runcoms* to your `$ZDOTDIR` a |
There was a problem hiding this comment.
This is a bit of a larger discussion. There have been talks about adding zlogin.local (and equivalents for the other files) which would be automatically sourced in the official prezto runcoms... and there's been talk of copying rather than symlinking. There hasn't been a general consensus yet, but that's mostly because noone has really taken the initiative to push a change like that through. I would be fine with either solution.
The original workflow with prezto was essentially fork the repo and make your own tweaks and changes there... which I understand, but I think it does the opposite of what was intended - a smaller amount of useful changes make it back into the main repo. I believe this is the reason the runcoms are symlinked. It also removes one step of debugging if you're using the official runcoms... because we don't need to go through all the zsh startup files and figure out where loading prezto went wrong.
I don't know what to do here, but I'd be happy to see a larger discussion come from this (Probably in a new issue)... however, even if I don't agree with it, I don't think documentation included with the prezto repo should be saying that the official recommendation (at least what we're currently recommending) is a "terrible idea" and that it's a better idea to do something different from what we suggest in the main README.
That being said, there are a number of easy to make mistakes, so providing a list of potential pitfalls and how to avoid them would be useful.
There was a problem hiding this comment.
Thank you for your feedback! I'll try and incorporate your observations, and yup there are a bunch of typos and dyslexyc mistakes. let's see how the second round comes up. =)
Also, modified wording to avoid disparraging efforts on configuration style before the team addresses them
runcoms/README.md
Outdated
| |------------------|-----------------------------------------|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | `/etc/zshenv` | | | system provided minimal environment | Always runs! should be minimal set ZDOTDIR, minimal environment. system paths | ||
| | | | `${ZDOTDIR:-$HOME}/.zshenv` | user environment overrides non-interactive, non-login shells (when invoked via shebang in a script or via `zsh -c [script]` or when invoked by `make` | personal environment overrides, such as `MANPATH`, `TERM`, `fpath` *non interactive scripts should have their environment completly set up here* ) | ||
| | | `/etc/zshprofile` | | system profile for login shells (`zsh -ls zsh - or via _ssh forced command_`) | minimal system paths for remote interaction, site `fpath`, site `$LOCALE`, lang. |
There was a problem hiding this comment.
O.o indeed... my mistake. i was having tunnel vision or "shop" blindness because i dint catch it even on proofbreading.. haha 😮
|
I believe you're quite right, sometimes less is more.. If however you feel the longer writeup could be valuable for users and the team, I'd be glad to post it perhaps in the project's wiki? I've incorporated your remarks. This new version touches on the issues of configuration in a way that is positive for both schools of thought regarding copying or merging of runcoms; without digressing on the finer points of bootstrapping flows and how parameters affect them 😆 (i admit i get carried away) Now, back to holiday in MX hehe. |
|
Any chance you could allow maintainer edits? I've got a few smaller things I'd like to fix up before merging this in. |
|
um.... unless i'm missing something, maintainers should be able to edit... the "allow edits from maintainers" option is ticked on this screen... =) |
|
Hm, might be something on my end then. Thanks for checking. |
|
Unfortunately, only sorin has admin access to the repo, so I don't think I can actually enable the wiki without him getting involved, so I'd rather avoid that for now. With triaging issues and PRs, I'd be happy to have some additional help. I've been very slowly going through them in my spare time, but I haven't much lately. The ones that are left are (for the most part) issues that I'm not sure what to do about, but there's definitely still stuff to do. There are a few things to keep in mind, though: new themes and modules can be pointed at the contrib repo (we're trying to avoid merging those in here for now) and any large/breaking changes need to have a really good reason. This is still sorin's project and one of his goals was to avoid this turning into a giant mess with hundreds of modules. Thanks for offering to help! Additionally, I'm going to be out for at least the weekend so it might be a while until I make my way back to this. |
|
agreed! i guess the rule of thumb is, universal features such as syntax highlighting or performance enhancements (such as troubleshooting compdumps should live here, in core. Vertical, narrow functionality (say bindings and aliases for Ansible) clearly should resde in "/contrib" i'll see what i can do regardng some issues that can be resolved as support issues,,, |
|
Sorry didnt realise I made a horrible mes with the table. Fixed it and some embarrasing typos... |
| contain. | ||
| ```bash | ||
| if [[ -n $ZDOTDIR ]]; then | ||
| DOTFILES_PATH=$ZDOTDIR |
There was a problem hiding this comment.
Minor nit: can you remove a space from the beginning here to be consistent with the else branch?
| | system/site config </br> (`/etc/zsh/**`) [2] | User configuration </br>(`${ZDOTDIR:-$HOME}`) [3] | Purpose | stuff that usually goes there, and notes | | ||
| |----------------------------------------------|---------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | `/zshenv` [1] | | system provided minimal environment | Should be minimal set ZDOTDIR, minimal environment. system paths | | ||
| | | `.zshenv` | user environment overrides non-interactive, non-login shells (when invoked via _shebang_ in a script or via `zsh -c [script]` or when invoked by `make` | Personal environment overrides, such as `MANPATH`, `TERM`, `fpath` (*non interactive scripts should have their environment completly set up here* ) | |
| | `/zlogin` | | additional customization for interactive **login** shells, such as those accessed via ssh | `tmux attach` to existing session | | ||
| | | `.zlogin` | user script for *login shell startup* (this shell is a session leader, and allocates a `ptty`) | aliases, keybindings, personal startup programs, time tracking apps, session managers, quote of the day, fortunes | | ||
| | ... your shell.. | ..session... | ..happens... | ..here ... | | ||
| | | `.zlogout` | personal cleanup tasks | unmounting your *fuse* personal fylesystems, async encryption of sensitive directoriesm backup kickoff, setting personal `crontabs` or `at` tasks, logging checout to your time tracking software, fortune to say goodbye. | |
There was a problem hiding this comment.
Looks like a few typos here: "fylesystems", "directoriesm", "checout"
| necessary. So, with this in mind you have the flexibility to adapt the `zsh` | ||
| features that prezto surfaces to your workload and tastes, ranging from the | ||
| prompt theme, shortcut keys, favorite editor and pager, aliases and even | ||
| syntax highlighting.! **Prezto is designed in such a way to allow you to |
There was a problem hiding this comment.
Either . or ! is needed; both is extra.
| syntax highlighting.! **Prezto is designed in such a way to allow you to | ||
| configure other aspects of your shell in the appropriate files wthout breaking | ||
| the framework** or forcing you to write your preferences in a particular | ||
| plugin structure. In the end, its a matter of editing one ofthe files |
|
|
||
| That being said, you can use the runcoms files _as-is_, replacing your old | ||
| files with prezto's baseline, or you can merge your customizations with | ||
| prezto's runcoms.! |
| be set, if that is not the case, check the above discussion, you can | ||
| 'replace' your shell _in situ_ by issuing the command `exec zsh -l` | ||
|
|
||
| you can configure your graphical environment or `tmux` to lauch nteractive |
There was a problem hiding this comment.
s/lauch/launch, s/nteractive/interactive
| # LINES! or you may end up | ||
| # with nested shells | ||
| ``` | ||
| Here is an examplefor *i3wm* on ubuntu |
| use your computer. It even offers _feature parity_ between different OSs, as | ||
| long as they run `zsh` | ||
|
|
||
| So, depending on the way you are connected or using yor computer, you'd need |
| probably don't need aliases or keybindings, but a human user will certainly | ||
| appreciate it, as shortcuts can make you more productive. When Logging via an | ||
| XTerminal or remotely logging in using ssh may look like similar tasks, but | ||
| resource and configuration-wise they are worlds appart. So, so far we already |
| ## Make Prezto your own: Configuration and personal preferences | ||
|
|
||
| That is quite a few files to configure a shell. Why so many? Mostly to | ||
| accomodate different roles for shell software. Automated Shell scripts |
Mitigates #1535
Proposed Changes:
Detailed documentation for runcoms
Discussion about the most common pitfalls
(no screenshot available, it is a repo Markdown file...)