Add more documentation

zrep 2024-04-01 16:12:39 +02:00
parent 821171dee1
commit ea21ee7057
7 changed files with 106 additions and 30 deletions

17
Contributing.md Normal file

@ -0,0 +1,17 @@
# Contribute to zrep
I am one person and I love what I'm doing. At the moment, I can handle what needs to be done but I'm expecting things to change.
In time, what I will be looking for are
- Editors - A role that is a power user below Administrator
- This role entails taking responsibility of
- issues from registered users
- looking at abuse reports, enable or disable scripts
- zrep issues
- Moderators - A role that will have access to a limited set of Administrator functions
- This role entails
- basic issue tracking
- first line abuse tracking
- Contributions, bug fixes and more to [zrep](https://git.kekepower.com/kekePower/zrep)
- Helpdesk to help with the [issue tracker](https://github.com/kekePower/zrep/issues)

33
Create-Your-Script.md Normal file

@ -0,0 +1,33 @@
# How to create your own script
The scripts used in `zrep` are using the `autoload` function of Zsh. This means that your script have to be in `$fpath` to be found by Zsh.
This is where `zrep` comes in.
`zrep` is created to handle the installation and management of scripts.
## Create your script
Zsh has a [certain way it works](Zsh-Autoload.md) and this influences how your scripts should be created.
The script should only contain one main function that has the same name as the file.
Example:
- my_script
- function my_script()
Based on my research, it is possible to have functions within the main function, so it should be possible to create complex and very interesting scripts for the community.
`zrep` depends on one file to display help information to the user.
Using `zrep author/package help` will display the information in the file `USAGE`.
The file `README.md` is used on the web page when people visit your package page. This file is optional, but highly recommended.
In other words, the file structure you should aim for is:
- script_name
- USAGE
- README.md
Once you've [registered for an account](https://zrep.kekepower.com/register/), you can then add your scripts and files.
They will then be packaged, uploaded to the repository and made available to the community.
On [your zrep account](Your-zrep-Account.md) page, you will have access to statistics and other goodies.

39
Home.md

@ -1,6 +1,6 @@
# zrep - Zsh Repository Tool # zrep - Zsh Repository Tool
Welcome to the official Wiki for `zrep`, a comprehensive Zsh Repository Tool designed to enhance your Zsh experience. Developed with flexibility and ease of use in mind, `zrep` allows for the efficient management of Zsh functions, scripts, and addons. Welcome to the official Wiki for [zrep](https://git.kekepower.com/kekePower/zrep), a comprehensive Zsh Repository Tool designed to enhance your Zsh experience. Developed with flexibility and ease of use in mind, `zrep` allows for the efficient management of Zsh functions, scripts, and addons.
`zrep` is meant to be used on a per user basis and not globally. This means that you, the user, have full control over what is installed and activated. `zrep` is meant to be used on a per user basis and not globally. This means that you, the user, have full control over what is installed and activated.
@ -13,44 +13,23 @@ Welcome to the official Wiki for `zrep`, a comprehensive Zsh Repository Tool des
## Getting Started ## Getting Started
### Installation ### Create your own scripts
1. Clone the `zrep` repository to your local machine. To create you own scripts, follow this How-to.
2. Run the script with `zrep init` to initialize the installation process. **[Create Your Script](Create-Your-Script.md)**
### Configuration ### [Installation](Installing-zrep.md)
Upon first run, `zrep` will prompt you to specify the installation directory, defaulting to `$HOME/.zrep` if left unspecified. This path will be used to store scripts, functions, and configuration files.
### `.zreprc` Configuration
The `.zreprc` file located in your home directory (`$HOME/.zreprc`) contains all configurable settings for `zrep`. Initially, this file will include the installation directory path. You can edit this file to adjust `zrep` settings to your liking.
## Usage ## Usage
### Basic Commands ### [How to use zrep](Using-zrep.md)
- `zrep init`: Initializes `zrep`, setting up necessary directories and configuration files.
- `zrep install <author/package>`: Installs a specified package.
- `zrep remove <author/package>`: Removes a specified package.
- `zrep enable <author/package>`: Enables a package, adding it to your `fpath`.
- `zrep disable <author/package>`: Disables a package, removing it from your `fpath`.
- `zrep list`: Lists all installed packages along with their status (active/inactive).
- `zrep <author/package> help`: Show the included usage information for package.
### Advanced Features
- **Color Customization:** Customize console output colors by editing the `colors` associative array within the script.
- **Package Management:** Leverage `zrep` to manage external Zsh scripts and functions efficiently, keeping your shell environment clean and organized.
## Contributing ## Contributing
Contributions to `zrep` are welcome! Whether it's adding new features, improving existing ones, or fixing bugs, your help is appreciated. Please follow the standard GitHub pull request process to submit your contributions. ### [Contribute to zrep](Contributing.md)
## License ## License
`zrep` is licensed under the MIT License. See the LICENSE file for more details. `zrep` is licensed under the [MIT License](https://git.kekepower.com/kekePower/zrep/src/branch/main/LICENSE).
---
For more detailed information on each command and feature, please refer to the corresponding sections of this Wiki or the `zrep` script comments.

15
Installing-zrep.md Normal file

@ -0,0 +1,15 @@
# zrep - Zsh Repository Tool
### Installation
1. Clone the `zrep` [repository](https://git.kekepower.com/kekePower/zrep) to your local machine.
2. Run the script with `zrep init` to initialize the installation process.
### Configuration
Upon first run, `zrep` will prompt you to specify the installation directory, defaulting to `$HOME/.zrep` if left unspecified. This path will be used to store scripts, functions, and configuration files.
### `.zreprc` Configuration
The `.zreprc` file located in your home directory (`$HOME/.zreprc`) contains all configurable settings for `zrep`. Initially, this file will include the installation directory path. You can edit this file to adjust `zrep` settings to your liking.

14
Using-zrep.md Normal file

@ -0,0 +1,14 @@
# zrep - Zsh Repository Tool
## Usage
### Basic Commands
- `zrep init`: Initializes `zrep`, setting up necessary directories and configuration files.
- `zrep install <author/package>`: Installs a specified package.
- `zrep remove <author/package>`: Removes a specified package.
- `zrep enable <author/package>`: Enables a package, adding it to your `fpath`.
- `zrep disable <author/package>`: Disables a package, removing it from your `fpath`.
- `zrep list`: Lists all installed packages along with their status (active/inactive).
- `zrep <author/package> help`: Show the included usage information for package.

7
Your-zrep-Account.md Normal file

@ -0,0 +1,7 @@
# Your zrep Account
Begin by [registering for an account](https://zrep.kekepower.com/register/)
After registration, you will receive an email asking you to verify your email address. Until you've done this, you will not be able to do anything on your account.
Once verified, you will be able to add your scripts, view statistics for your scripts, update or delete.

11
Zsh-Autoload.md Normal file

@ -0,0 +1,11 @@
# Zsh and autoload
The main function behind `zrep` is Zsh's autoload feature. It searches through a variable called `fpath` and anything in this path can be loaded and used.
`autoload` loads the contents of the files, so it usually contains a function. It is the function that gets executed by Zsh when the command is used, not the file itself.
As far as I know, Zsh allows for nested functions, meaning you can have functions within functions.
You can see an example in my [update-dynamic-ip](/source/kekePower/update-dynamic-ip) script.
Zsh lazy loads the files in `fpath` and this means that it's not in memory until you actually executes the function.
This means that it won't have an effect on your shell in terms of speed or memory usage.