Skip to content

Commit

Permalink
general: Reformat documentation with better formatting and wording
Browse files Browse the repository at this point in the history 
General purpose reformating and rewording in (a few places). This should
also make markdown linting happier.

Prefer back-ticks wherever useful and use `console` for code blocks to
be executed on terminal.

Also, update references links wherever possible (including update from
'http://' to 'https://').
  • Loading branch information
@indrajitr
indrajitr committed May 5, 2021
1 parent 8edc5e9 commit d80e393
Show file tree
Hide file tree
Showing 44 changed files with 1,245 additions and 1,453 deletions.
65 changes: 32 additions & 33 deletions CONTRIBUTING.md
View file
@@ -1,42 +1,41 @@
Contributing
------------
# Contributing

This project would not exist without all of its users and [contributors][1].

If you have ideas on how to make the configuration easier to maintain or
improve its performance, do not hesitate to fork and send pull requests.

### Issue Reporting
## Issue Reporting

- Check that the issue has not already been reported.
- Check that the issue has not already been fixed in the latest code.
- Open an issue with a clear title and description in grammatically correct,
complete sentences.
- Check that the issue has not already been reported.
- Check that the issue has not already been fixed in the latest code.
- Open an issue with a clear title and description in grammatically correct,
complete sentences.

### Pull Request
## Pull Request

- Read [how to properly contribute to open source projects on GitHub][2].
- Use a topic branch to easily amend a pull request later, if necessary.
- Write [good commit messages][3].
- Squash commits on the topic branch before opening a pull request.
- Use the same coding style and spacing.
- Open a [pull request][4] that relates to but one subject with a clear
title and description in grammatically correct, complete sentences.
- Read [how to properly contribute to open source projects on GitHub][2].
- Use a topic branch to easily amend a pull request later, if necessary.
- Write [good commit messages][3].
- Squash commits on the topic branch before opening a pull request.
- Use the same coding style and spacing.
- Open a [pull request][4] that relates to but one subject with a clear title
and description in grammatically correct, complete sentences.

#### Code Style
### Code Style

This project follows the [Google Shell Style Guide][5] when possible. However,
there are a number of additional things to keep in mind.

- Local variables should be used whenever possible.
- Prefer `zstyle` over environment variables for configuration.
- Prefer (( ... )) over [[ ... ]] for arithmetic expression.
- Use the function keyword to define functions.
- The 80 character hard limit can be waived for readability.
- Local variables should be used whenever possible.
- Prefer `zstyle` over environment variables for configuration.
- Prefer (( ... )) over [[ ... ]] for arithmetic expression.
- Use the function keyword to define functions.
- The 80 character hard limit can be waived for readability.

#### Using an Alternative zprezto Directory
### Using an Alternative *zprezto* Directory

To work on zprezto without messing with your current configuration:
To work on Prezto without affecting your current configuration:

```sh
mkdir devel-zprezto
Expand All @@ -52,24 +51,24 @@ done

Then to start zsh in this development environment you will run:

```sh
```console
ZDOTDIR=/path/to/devel-zprezto zsh
```

#### Modules
### Modules

- A *README.md* must be present.
- Large functions must be placed in a *functions* directory.
- Functions that take arguments must have completion.
- A *README.md* must be present.
- Large functions must be placed in a *functions* directory.
- Functions that take arguments must have completion.

#### Themes
### Themes

- A screenshots section must be present in the file header.
- The pull request description must have [embedded screenshots][6].
- A screenshots section must be present in the file header.
- The pull request description must have [embedded screenshots][6].

[1]: https://github.com/sorin-ionescu/prezto/contributors
[2]: http://gun.io/blog/how-to-github-fork-branch-and-pull-request
[2]: https://gun.io/blog/how-to-github-fork-branch-and-pull-request
[3]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
[4]: https://help.github.com/articles/using-pull-requests
[5]: https://google.github.io/styleguide/shell.xml
[6]: http://daringfireball.net/projects/markdown/syntax#img
[6]: https://github.github.com/gfm/#images
154 changes: 74 additions & 80 deletions README.md
View file
@@ -1,66 +1,64 @@
Prezto — Instantly Awesome Zsh
==============================
# Prezto — Instantly Awesome Zsh

Prezto is the configuration framework for [Zsh][1]; it enriches the command line
interface environment with sane defaults, aliases, functions, auto completion,
and prompt themes.

Installation
------------
## Installation

Prezto will work with any recent release of Zsh, but the minimum required
version is 4.3.11.
version is **4.3.11**.

1. Launch Zsh:
01. Launch Zsh:

```console
zsh
```
```console
zsh
```

2. Clone the repository:
02. Clone the repository:

```console
git clone --recursive https://github.com/sorin-ionescu/prezto.git "${ZDOTDIR:-$HOME}/.zprezto"
```
```console
git clone --recursive https://github.com/sorin-ionescu/prezto.git "${ZDOTDIR:-$HOME}/.zprezto"
```

3. Create a new Zsh configuration by copying the Zsh configuration files
provided:
03. Create a new Zsh configuration by copying the Zsh configuration files
provided:

```sh
setopt EXTENDED_GLOB
for rcfile in "${ZDOTDIR:-$HOME}"/.zprezto/runcoms/^README.md(.N); do
ln -s "$rcfile" "${ZDOTDIR:-$HOME}/.${rcfile:t}"
done
```
```console
setopt EXTENDED_GLOB
for rcfile in "${ZDOTDIR:-$HOME}"/.zprezto/runcoms/^README.md(.N); do
ln -s "$rcfile" "${ZDOTDIR:-$HOME}/.${rcfile:t}"
done
```

Note: If you already have any of the given configuration files, `ln` will
cause error. In simple cases you can load prezto by adding the line
`source "${ZDOTDIR:-$HOME}/.zprezto/init.zsh"` to the bottom of your
`.zshrc` and keep the rest of your Zsh configuration intact. For more
complicated setups, it is recommended that you back up your original
configs and replace them with the provided prezto runcoms.
**Note:** If you already have any of the given configuration files, `ln` in
the above operation will cause an error. In simple cases, you can load
Prezto by adding the line `source "${ZDOTDIR:-$HOME}/.zprezto/init.zsh"` to
the bottom of your *${ZDOTDIR:-$HOME}/.zshrc* and keep the rest of your Zsh
configuration intact. For more complicated setups, we recommend that you
back up your original configs and replace them with the provided Prezto
*runcoms*.

4. Set Zsh as your default shell:
04. Set Zsh as your default shell:

```console
chsh -s /bin/zsh
```
```console
chsh -s /bin/zsh
```

5. Open a new Zsh terminal window or tab.
05. Open a new Zsh terminal window or tab.

### Troubleshooting

If you are not able to find certain commands after switching to *Prezto*,
modify the `PATH` variable in *~/.zprofile* then open a new Zsh terminal
window or tab.
If you are not able to find certain commands after switching to Prezto, modify
the `PATH` variable in *${ZDOTDIR:-$HOME}/.zprofile* then open a new Zsh
terminal window or tab.

Updating
--------
## Updating

Run `zprezto-update` to automatically check if there is an update to zprezto.
If there are no file conflicts, zprezto and its submodules will be
automatically updated. If there are conflicts you will be instructed to go into
the `$ZPREZTODIR` directory and resolve them yourself.
Run `zprezto-update` to automatically check if there is an update to Prezto.
If there are no file conflicts, Prezto and its submodules will be automatically
updated. If there are conflicts you will be instructed to go into the
`$ZPREZTODIR` directory and resolve them yourself.

To pull the latest changes and update submodules manually:

Expand All @@ -70,67 +68,63 @@ git pull
git submodule update --init --recursive
```

Usage
-----
## Usage

Prezto has many features disabled by default. Read the source code and
accompanying README files to learn of what is available.
Prezto has many features disabled by default. Read the source code and the
accompanying README files to learn about what is available.

### Modules

1. Browse */modules* to see what is available.
2. Load the modules you need in *~/.zpreztorc* then open a new Zsh terminal
window or tab.
01. Browse */modules* to see what is available.
02. Load the modules you need in *${ZDOTDIR:-$HOME}/.zpreztorc* then open a new
Zsh terminal window or tab.

### Themes

1. For a list of themes, type `prompt -l`.
2. To preview a theme, type `prompt -p name`.
3. Load the theme you like in *~/.zpreztorc* then open a new Zsh terminal
window or tab.
01. For a list of themes, type `prompt -l`.
02. To preview a theme, type `prompt -p name`.
03. Load the theme you like in *${ZDOTDIR:-$HOME}/.zpreztorc* then open a new
Zsh terminal window or tab.

![sorin theme][2]
Note that the 'git' module may be required for special symbols to appear,
such as those on the right of the above image. Add `'git'` to the `pmodule`
list (under `zstyle ':prezto:load' pmodule \` in your *~/.zpreztorc*) to
enable this module.
![sorin theme][2]
Note that the *git* module may be required for special symbols to appear,
such as those on the right of the above image. Add `'git'` to the `pmodule`
list (under `zstyle ':prezto:load' pmodule \` in your
*${ZDOTDIR:-$HOME}/.zpreztorc*) to enable this module.

### External Modules

1. By default modules will be loaded from */modules* and */contrib*.
2. Additional module directories can be added to the
`:prezto:load:pmodule-dirs` setting in *~/.zpreztorc*.
01. By default modules will be loaded from */modules* and */contrib*.
02. Additional module directories can be added to the
`:prezto:load:pmodule-dirs` setting in *${ZDOTDIR:-$HOME}/.zpreztorc*.

Note that module names need to be unique or they will cause an error when
loading.
Note that module names need to be unique or they will cause an error when
loading.

```sh
zstyle ':prezto:load' pmodule-dirs $HOME/.zprezto-contrib
```
```console
zstyle ':prezto:load' pmodule-dirs $HOME/.zprezto-contrib
```

Customization
-------------
## Customization

The project is managed via [Git][3]. It is highly recommended that you fork this
project; so, that you can commit your changes and push them to [GitHub][4] to
not lose them. If you do not know how to use Git, follow this [tutorial][5] and
bookmark this [reference][6].
The project is managed via [Git][3]. We highly recommend that you fork this
project so that you can commit your changes and push them to your fork on
[GitHub][4] to preserve them. If you do not know how to use Git, follow this
[tutorial][5] and bookmark this [reference][6].

Resources
---------
## Resources

The [Zsh Reference Card][7] and the [zsh-lovers][8] man page are indispensable.

License
-------
## License

This project is licensed under the MIT License.

[1]: http://www.zsh.org
[2]: http://i.imgur.com/nrGV6pg.png "sorin theme"
[3]: http://git-scm.com
[1]: https://www.zsh.org
[2]: https://i.imgur.com/nrGV6pg.png "sorin theme"
[3]: https://git-scm.com
[4]: https://github.com
[5]: http://gitimmersion.com
[5]: https://gitimmersion.com
[6]: https://git.github.io/git-reference/
[7]: http://www.bash2zsh.com/zsh_refcard/refcard.pdf
[8]: http://grml.org/zsh/zsh-lovers.html
[8]: https://grml.org/zsh/zsh-lovers.html

0 comments on commit d80e393

Please sign in to comment.