From bf132438307779f8e60f5f4544c48213a043a5eb Mon Sep 17 00:00:00 2001 From: Arun Prakash Jana Date: Sat, 17 Aug 2019 11:59:39 +0530 Subject: [PATCH] Update docs --- README.md | 54 +++++++++-------------------------------------- plugins/README.md | 23 +++++++++++++++----- 2 files changed, 28 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 4250366..4886814 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,6 @@ Travis Status CircleCI Status License -Donate via PayPal!

@@ -24,7 +23,7 @@

Modes of nnn (light with filter, detail, du analyzer) with memory usage (click for a demo video)

-## ToC +## Index - [Introduction](#introduction) - [Features](#features) @@ -49,24 +48,20 @@ - [Filters](#filters) - [Navigate-as-you-type](#navigate-as-you-type) - [File indicators](#file-indicators) - - [Hot-plugged drives](#hot-plugged-drives) -- [Why fork?](#why-fork) - [Mentions](#mentions) - [Developers](#developers) ## Introduction -`nnn` is a full-featured file manager for low-end devices and the regular desktop. It's extremely light and fast (**[performance](https://github.com/jarun/nnn/wiki/info:-performance)**). +`nnn` is a full-featured terminal file manager. It's extremely light and fast (**[performance](https://github.com/jarun/nnn/wiki/Performance)**). `nnn` is also a disk usage analyzer, a fuzzy app launcher, a batch file renamer and a file picker. -Many **[plugins](https://github.com/jarun/nnn/tree/master/plugins)** are available to extend its power. Plugins can be run directly with custom keybinds. There's an independent [(neo)vim picker plugin](https://github.com/mcchrish/nnn.vim) project. Custom plugins are easy to add. +It runs smoothly on the Raspberry Pi, Termux on Android ([demo video](https://www.youtube.com/watch?v=AbaauM7gUJw)), Linux, macOS, BSD, Cygwin and Linux subsystem for Windows. `nnn` works seamlessly with DEs and GUI utilities. It's nearly zero-config (with sensible defaults) and can be setup in less than 5 minutes. -It runs on Linux, macOS, Raspberry Pi, BSD, Cygwin, Linux subsystem for Windows and Termux on Android. `nnn` works seamlessly with DEs and GUI utilities. It's nearly zero-config (with sensible defaults) and can be setup in less than 5 minutes. +**[Plugins](https://github.com/jarun/nnn/tree/master/plugins)** can be run with custom keybinds. There's an independent [(neo)vim plugin](https://github.com/mcchrish/nnn.vim). Custom plugins are easy to add. -Visit the **[wiki](https://github.com/jarun/nnn/wiki)** for more information on configuration, operational notes and tips. - -Here's a video of [`nnn` on Termux (Android)](https://www.youtube.com/watch?v=AbaauM7gUJw). +Visit the **[Wiki](https://github.com/jarun/nnn/wiki)** for how tos, use cases, chronology and insights. ## Features @@ -94,24 +89,8 @@ Here's a video of [`nnn` on Termux (Android)](https://www.youtube.com/watch?v=Ab - Information - Detailed file information - Media information (needs mediainfo/exiftool) -- Plugins - - (Un)mount external drives - - File and directory diff - - Play selection in MOC - - View PDF as text - - View images/thumbnails in terminal - - View video thumbnails in terminal - - Upload image to Imgur - - Paste to Ubuntu pastebin - - Upload file to transfer.sh - - Split and join files - - Create MP3 ringtones - - Calculate and verify checksums - - Read a text file - - Hex viewer - - and more... - Convenience - - Needs minimal configuration + - Minimal configuration - Plugin keybinds - Select files across dirs; all/range selection - Copy, move, delete, archive, link selection @@ -130,6 +109,7 @@ Here's a video of [`nnn` on Termux (Android)](https://www.youtube.com/watch?v=Ab - Take quick notes - Lock the terminal (needs a locker) - Shortcut reference a keypress away +- Plugins - Unicode support - Follows Linux kernel coding style - Highly optimized, static analysis integrated code @@ -158,7 +138,7 @@ Here's a video of [`nnn` on Termux (Android)](https://www.youtube.com/watch?v=Ab #### From a package manager -There's a good chance `nnn` is already available in the default repos of your distro. Find a list of known packagers below. +`nnn` may be available in the default repos of your distro already. Find a list of known packagers below. - [Alpine Linux](https://pkgs.alpinelinux.org/packages?name=nnn) (`apk add nnn`) - [Arch Linux](https://www.archlinux.org/packages/community/x86_64/nnn/) (`pacman -S nnn`) @@ -200,8 +180,8 @@ To cook yourself, download the [latest stable release](https://github.com/jarun/ `PREFIX` is supported, in case you want to install to a different location. -- Compilation notes for [Raspberry Pi](https://github.com/jarun/nnn/issues/182) -- Instructions for [Cygwin](https://github.com/jarun/nnn/wiki/dev:-compile-on-Cygwin) +- Compilation notes on [Raspberry Pi](https://github.com/jarun/nnn/wiki/Compile-for-Pi) +- Instructions for [Cygwin](https://github.com/jarun/nnn/wiki/Compile-on-Cygwin) #### Shell completion @@ -413,20 +393,6 @@ The following indicators are used in the detail view: | `c` | Character Device | | `?` | Unknown | -#### Hot-plugged drives - -External storage devices can be (un)mounted using the plugin [nmount](https://github.com/jarun/nnn/blob/master/plugins/nmount). - -For auto-mounting external storage drives use udev rules or udisks wrappers. - -## Why fork? - -`nnn` was initially forked from [noice](http://git.2f30.org/noice/) but is significantly [different](https://github.com/jarun/nnn/wiki/info:-nnn-vs.-noice) today. I chose to fork because: -- one can argue my approach deviates from the goal of the original project - keep the utility `suckless`. `noice` was rudimentary. In my opinion evolution is the taste of time. -- I would like to have a bit of control on what features are added in the name of desktop integration. A feature-bloat is the last thing in my mind. Check out the [design considerations](https://github.com/jarun/nnn/wiki/info:-design-considerations) for more details. - -Trivia: The name `nnn` is a recursive acronym for the initial words from _Noice is Not Noice, a noicer fork..._, suggested by a longtime friend. - ## Mentions - [FOSSMint](https://www.fossmint.com/nnn-linux-terminal-file-browser/) diff --git a/plugins/README.md b/plugins/README.md index d81cb6f..fc4810c 100644 --- a/plugins/README.md +++ b/plugins/README.md @@ -33,13 +33,13 @@ The currently available plugins are listed below. | vidthumb | sh | [ffmpegthumbnailer](https://github.com/dirkvdb/ffmpegthumbnailer),
[lsix](https://github.com/hackerb9/lsix) | Show video thumbnails in terminal | | viuimg | sh | [viu](https://github.com/atanunq/viu), less | View an image or images in a directory | -#### Installing plugins +## Installing plugins Download the `getplugs` plugin and execute it anywhere to get all the plugins installed to `${XDG_CONFIG_HOME:-$HOME/.config}/nnn/plugins`. You can run it again later to update the plugins. It backs up earlier plugins. **NOTE:** `getplugs` also downloads the launcher `nlaunch` and tries to place it at `/usr/local/bin/` using `sudo`. If it fails you have to place `nlauch` manually somewhere in your `$PATH`. -#### File access from plugins +## File access from plugins Plugins can access: - all files in the directory (`nnn` switches to the dir where the plugin is to be run so the dir is `$PWD` for the plugin) @@ -48,7 +48,7 @@ Plugins can access: Each script has a _Description_ section which provides more details on what the script does, if applicable. -#### Usage +## Usage There are 2 ways to run plugins: @@ -60,8 +60,21 @@ There are 2 ways to run plugins: 2. Use the _pick plugin_ shortcut to visit the plugin directory and execute a plugin. Repeating the same shortcut cancels the operation and puts you back in the original directory. -#### Contributing plugins +## Create your own plugins -Plugins are scripts and all scripting languages should work. However, POSIX-compliant shell scripts runnable in `sh` are preferred. If that's too rudimentary for your use case, use Python, Perl or Ruby. Please keep non-portable commands (like `notify-send`) commented so users from any other OS/DE aren't surprised. +Plugins are scripts and all scripting languages should work. However, POSIX-compliant shell scripts runnable in `sh` are preferred. If that's too rudimentary for your use case, use Python, Perl or Ruby. + +You can create your own plugins by putting them in `${XDG_CONFIG_HOME:-$HOME/.config}/nnn/plugins`. + +For example, you could create a executable shell script `git-changes`: + + #!/usr/bin/env sh + git log -p -- "$@" + +And then trigger it by hitting the pick plugin key and selecting `git-changes` which will conveniently show the git log of changes to the particular file along with the code for a quick and easy review. + +## Contributing plugins + +Please keep non-portable commands (like `notify-send`) commented so users from any other OS/DE aren't surprised. The plugins should be executable. Please add an entry in the table above.