Sanitize in-plugin documentation

plugins/autojump

@@ -2,9 +2,10 @@
 
 # Description: Navigate to directory using jump/autojump/zoxide
 #
-# Dependencies: jump - https://github.com/gsamokovarov/jump
+# Dependencies:
-#               OR autojump - https://github.com/wting/autojump
+#   - jump - https://github.com/gsamokovarov/jump
-#               OR zoxide - https://github.com/ajeetdsouza/zoxide
+#   - OR autojump - https://github.com/wting/autojump
+#   - OR zoxide - https://github.com/ajeetdsouza/zoxide
 #
 # Note: The dependencies STORE NAVIGATION PATTERNS
 #

plugins/bookmarks

@@ -7,7 +7,6 @@
 # Usage:
 #   1. Create a $BOOKMARKS_DIR directory
 #      By default, $BOOKMARKS_DIR is set to: ${XDG_CACHE_HOME:-$HOME/.cache}/nnn/bookmarks
-#
 #   2. Create symlinks to directories
 #     `cd $BOOKMARKS_DIR`
 #     `ln -s /path/to/useful/directory    bookmark_name`
@@ -20,7 +19,7 @@
 # https://linux.101hacks.com/cd-command/cdpath/
 #
 # TODO:
-#   1. Remove `fzf` dependency
+#   - Remove `fzf` dependency
 #
 # Shell: POSIX compliant
 # Author: Todd Yamakawa

plugins/boom

@@ -1,7 +1,10 @@
 #!/usr/bin/env sh
 
-# Description: Play random music from current directory. Identifies MP3, FLAC, M4A, WEBM, WMA.
+# Description: Play random music (MP3, FLAC, M4A, WEBM, WMA) from current dir.
-#              You may want to set GUIPLAYER.
+#
+# Dependencies: mocp (or custom)
+#
+# Note: You may want to set GUIPLAYER.
 #
 # Shell: POSIX compliant
 # Author: Arun Prakash Jana

plugins/bulknew

@@ -1,7 +1,7 @@
 #!/usr/bin/env sh
 
-# Description: Allows for creation of multiple files/directories at the same time.
+# Description: Allows for creation of multiple files/dirs simultaneously
-#              Plugin opens a temp file where each entry is to be written on a separate line
+#              Creates a tmp file to write each entry in a separate line
 #
 # Note: Only relative paths are supported. Absolute paths are ignored
 #       Leading and trailing whitespace in path names is also ignored

plugins/chksum

@@ -2,13 +2,14 @@
 
 # Description: Create and verify checksums
 #
-# For selection: it will generate one file containing the checksums with file names
+# Details:
-#                [and with paths if they are in another directory]
+#   - selection: it will generate one file with the checksums and filenames
-#                the output checksum filename will be checksum_timestamp.checksum_type
+#                (and with paths if they are in another directory)
-# For file: if the file is a checksum, the plugin does the verification
+#                output checksum filename format: checksum_timestamp.checksum_type
+#   - file: if the file is a checksum, the plugin does the verification
 #           if the file is not a checksum, checksum will be generated for it
 #           the output checksum filename will be filename.checksum_type
-# For directory: recursively calculates checksum for all the files in the directory
+#   - directory: recursively calculates checksum for all the files in the dir
 #                the output checksum filename will be directory.checksum_type
 #
 # Shell: POSIX compliant

plugins/diffs

@@ -2,7 +2,8 @@
 
 # Description: Show diff of 2 directories or multiple files in vimdiff
 #
-# Note: 1. vim may show the warning: 'Vim: Warning: Input is not from a terminal'
+# Notes:
+#   1. vim may show the warning: 'Vim: Warning: Input is not from a terminal'
 #      press 'Enter' to ignore and proceed.
 #   2. if only one file is in selection, the hovered file is considered as the
 #      second file to diff with

plugins/dragdrop

@@ -3,13 +3,13 @@
 # Description: Open a Drag and drop window, to drop files onto other programs.
 #              Also provides drag and drop window for files.
 #
-# Dependencies: https://github.com/mwh/dragon
+# Dependencies: dragon - https://github.com/mwh/dragon
 #
 # Notes:
-# - Files that are dropped will be added to nnn's selection
+#   1. Files that are dropped will be added to nnn's selection
-#   Some webbased files will be downloaded to current directory with curl
+#      Some web-based files will be downloaded to current dir
-#   and it may overwrite some existing files
+#      with curl and it may overwrite some existing files
-# - The user has to mm to clear nnn's selection first
+#   2. The user has to mm to clear nnn's selection first
 #
 # Shell: POSIX compliant
 # Author: 0xACE

plugins/dups

@@ -1,18 +1,18 @@
 #!/usr/bin/env sh
 
-# Description: List non-empty duplicate files in the current directory (based on size followed by MD5)
+# Description: List non-empty duplicates in the current dir (based on size followed by MD5)
 #
 # Source: https://www.commandlinefu.com/commands/view/3555/find-duplicate-files-based-on-size-first-then-md5-hash
 #
 # Dependencies: find md5sum sort uniq xargs gsed
 #
-# Note: bash compatible required for mktemp
+# Notes:
-#
+#   1. If the file size exceeds $size_digits digits the file will be misplaced
-# Shell: bash
-# Authors: syssyphus, KlzXS
-
-# If the size of a file has more that $size_digits digits the file will be misplaced
 #      12 digits fit files up to 931GiB
+#   2. bash compatible required for mktemp
+#
+# Shell: Bash
+# Authors: syssyphus, KlzXS
 
 EDITOR="${EDITOR:-vi}"
 TMPDIR="${TMPDIR:-/tmp}"

plugins/fzhist

@@ -1,7 +1,9 @@
 #!/usr/bin/env sh
 
-# Description: Fuzzy find a command from history, edit in $EDITOR and run as a command
+# Description: Fuzzy find a command from history,
-#              Currently supports only bash and fish history
+#              edit in $EDITOR and run as a command
+#
+# Note: Supports only bash and fish history
 #
 # Shell: POSIX compliant
 # Author: Arun Prakash Jana

plugins/fzplug

@@ -1,21 +1,27 @@
 #!/usr/bin/env sh
 
-# Description: Fuzzy find and execute nnn plugins (and, optionally, custom scripts located elsewhere).
+# Description: Fuzzy find and execute nnn plugins (and optionally,
-# Description and details of plugins can be previewed from the fzf interface. Use `?` to toggle preview
+#              custom scripts located elsewhere).
+#              Description and details of plugins can be previewed
+#              from the fzf interface. Use `?` to toggle preview
 #              pane on and off, ^Up/^Dn to scroll.
 #
-# For better compatibility with as many nnn plugins as possible, fzplug will first execute
-# the chosen script on the file hovered in nnn, and upon failure, try to run it with no target
-# (i.e on an active selection, if present).
-#
 # Dependencies: find, fzf, cat (or bat, if installed)
+#
+# Note: For better compatibility with as many nnn plugins as possible,
+#       fzplug will first execute the chosen script on the file hovered
+#       in nnn, and upon failure, try to run it with no target (i.e on
+#       an active selection, if present).
+#
 # Shell: POSIX compliant
 # Author: Kabouik
 
 # Optional scripts sources
-# Leave blank or fill with the absolute path of a folder containing executable scripts other than nnn plugins
+# Leave blank or fill with the absolute path of a folder containing executable
-# (e.g., "$HOME/.local/share/nautilus/scripts", since there are numerous Nautilus script git repositories).
+# scripts other than nnn plugins (e.g., "$HOME/.local/share/nautilus/scripts",
-# Add extra variables if need be, but be sure to call them in the find command below at lines 27 and 33.
+# since there are numerous Nautilus script git repositories).
+# Add extra variables if needed, make sure you call them in the find command.
+
 #CUSTOMDIR1="$HOME/.local/share/nautilus/scripts"
 CUSTOMDIR1=""
 CUSTOMDIR2=""
@@ -38,7 +44,8 @@ else
         --bind="?:toggle-preview")
 fi
 
-# Try running the script on the hovered file, and abort if no plugin was selected (ESC or ^C pressed),
+# Try running the script on the hovered file, and abort
+# abort if no plugin was selected (ESC or ^C pressed).
 err=0
 if ! [ "$plugin" = "" ]; then
     "$plugin" "$1" || err=1

plugins/gpgd

@@ -1,8 +1,10 @@
 #!/usr/bin/env sh
 
-# Description: Decrypts selected files using gpg. The contents of the decrypted file are stored in a file with extension .dec
+# Description: Decrypts selected files using gpg. The contents of the
+#              decrypted file are stored in a file with extension .dec
 #
-# Note: If an appropriate private key cannot be found gpg silently prints a message in the background and no files are written.
+# Note: If an appropriate private key cannot be found gpg silently
+#       prints a message in the background and no files are written.
 #
 # Shell: POSIX compliant
 # Author: KlzXS

plugins/gpge

@@ -1,9 +1,11 @@
 #!/usr/bin/env sh
 
-# Description: Encrypts selected files using gpg. Can encrypt either asymmetrically (key) or symmetrically (passphrase).
+# Description: Encrypts selected files using gpg. Can encrypt
-#              If asymmetric encryption is chosen a key can be chosen from the list of capable public keys using fzf.
+#              asymmetrically (key) or symmetrically (passphrase).
+#              If asymmetric encryption is chosen a key can be
+#              chosen from the list of capable public keys using fzf.
 #
-# Note: symmetric encryption only works for a single (current) file as per gpg limitations
+# Note: Symmetric encryption only works for a single (current) file as per gpg limitations
 #
 # Shell: POSIX compliant
 # Author: KlzXS

plugins/hexview

@@ -1,6 +1,7 @@
 #!/usr/bin/env sh
 
 # Description: View a file in hex
+#
 # Dependencies: hx (https://github.com/krpors/hx)/xxd and $PAGER
 #
 # Shell: POSIX compliant

plugins/imgresize

@@ -1,10 +1,11 @@
 #!/usr/bin/env sh
 
 # Description: Resize images in a directory to screen resolution with imgp
-# imgp homepage: https://github.com/jarun/imgp
+#
+# Dependencipes: imgp - https://github.com/jarun/imgp
 #
 # Notes:
-# 1. Set res if you don't want to be prompted for desktop resolution every time
+#   1. Set res to avoid the desktop resolution prompt each time
 #   2. MINSIZE is set to 1MB by default, adjust it if you want
 #   3. imgp options used:
 #      a - adaptive mode

plugins/imgthumb

@@ -2,6 +2,8 @@
 
 # Description: View thumbnail of an image or a directory of images with lsix
 #
+# Dependencies: lsix
+#
 # Shell: POSIX compliant
 # Author: Arun Prakash Jana
 

plugins/imgur

@@ -32,7 +32,7 @@
 #
 # Slightly modified for `nnn` integration
 #
-# Shell: bash
+# Shell: Bash
 # Description: Upload an image file to imgur
 
 if [ "${1}" = "--debug" ]; then

plugins/imgview

@@ -2,9 +2,11 @@
 
 # Description: Open images in hovered  directory and thumbnails
 #              open hovered image in sxiv or viu and browse other images in the directory
-# Dependencies: imv (https://github.com/eXeC64/imv) or,
+#
-#               sxiv (https://github.com/muennich/sxiv) or,
+# Dependencies:
-#               viu (https://github.com/atanunq/viu), less
+#   - imv (https://github.com/eXeC64/imv) or,
+#   - sxiv (https://github.com/muennich/sxiv) or,
+#   - viu (https://github.com/atanunq/viu), less
 #
 # Shell: POSIX compliant
 # Author: Arun Prakash Jana

plugins/kdeconnect

@@ -1,6 +1,7 @@
 #!/usr/bin/env sh
 
-# Description: Send the selected files to your Android device using kdeconnect-cli. You must have installed and configured kdeconnect both on the Android device and on the PC.
+# Description: Send the selected files to your Android device using kdeconnect-cli.
+#              kdeconnect must be configured on the Android device and the PC.
 #
 # Shell: POSIX compliant
 # Author: juacq97

plugins/moclyrics

@@ -1,6 +1,7 @@
 #!/usr/bin/env sh
 
 # Description: Fetches the lyrics of the track currently playing in MOC
+#
 # Dependencies: ddgr (https://github.com/jarun/ddgr)
 #
 # Shell: POSIX compliant

plugins/mp3conv

@@ -2,7 +2,7 @@
 
 # Description: Extract audio from multimedia files and convert to mp3
 #
-# Dependency: ffmpeg compiled with libmp3lame audio codec support
+# Dependencies: ffmpeg compiled with libmp3lame audio codec support
 #
 # Shell: POSIX compliant
 # Author: Arun Prakash Jana

plugins/mtpmount

@@ -5,6 +5,8 @@
 #              'n' integer associated to device to mount
 #              'q'/'Return' exit
 #
+# Dependencies: gvfs-mtp
+#
 # Notes: The MTP device should be mounted at /run/user/$UID/gvfs.
 #        Put /run/user/$UID/gvfs to bookmark entries (NNN_BMS) for faster access.
 #        Make sure the device is unlocked when mounting.
@@ -14,8 +16,6 @@
 #        That just means the file is copied but timestamp won't be preserved.
 #        It's like doing `cp -p localfile.txt file-to-SMB.txt`.
 #
-# Dependencies: gvfs-mtp
-#
 # Shell: POSIX compliant
 # Author: Benawi Adha
 

plugins/nmount

@@ -4,9 +4,11 @@
 #              If the device is not mounted, it will be mounted.
 #              If the device is mounted, it will be unmounted and powered down.
 #
-#              Runs `lsblk` if 'l' is entered, exits on 'Return`.
+# Dependencies: lsblk
 #
-# Note:
+# Usage: Runs `lsblk` on 'l', exits on 'Return`.
+#
+# Notes:
 #   - The script uses Linux-specific lsblk to list block devices. Alternatives:
 #       macOS: "diskutil list"
 #       BSD: "geom disk list"

plugins/nuke

@@ -1,6 +1,5 @@
 #!/usr/bin/env sh
 
-# #############################################################################
 # Description: Sample script to play files in apps by file type or mime
 #
 # Shell: POSIX compliant
@@ -60,10 +59,9 @@
 #      text/* | */xml: vi
 #      image/vnd.djvu): djvutxt, exiftool
 #
-# ToDo:
+# TODO:
 #   1. Adapt, test and enable all mimes
 #   2. Clean-up the unnecessary exit codes
-# #############################################################################
 
 # set to 1 to enable GUI apps
 GUI="${GUI:-0}"

plugins/preview-tabbed

@@ -2,33 +2,30 @@
 
 # Description: tabbed/xembed based file previewer
 #
-# Note: This plugin needs a "NNN_FIFO" to work. See man.
-#
 # Dependencies:
 #   - tabbed (https://tools.suckless.org/tabbed): xembed host
 #   - xterm (or urxvt or st) : xembed client for text-based preview
 #   - mpv (https://mpv.io): xembed client for video/audio
 #   - sxiv (https://github.com/muennich/sxiv): xembed client for images
-#  - zathura (https://pwmt.org/projects/zathura): xembed client for PDF documents
+#   - zathura (https://pwmt.org/projects/zathura): xembed client for PDF
-#  - nnn's nuke plugin for text preview and fallback (should be in plugins directory)
+#   - nnn's nuke plugin for text preview and fallback
-#    nuke is a fallback for 'mpv', 'sxiv', and 'zathura', but it has has its own
+#     nuke is a fallback for 'mpv', 'sxiv', and 'zathura', but has its
-#    dependencies, see the script itself
+#     own dependencies, see the script for more information
 #   - vim (or any editor/pager really)
 #   - file
 #   - mktemp
 #   - xdotool (optional, to keep main window focused)
 #
-# How to use:
+# Usage:
-#  First, install the dependencies. Then you need to set a NNN_FIFO path
+#   - Install the dependencies. Then set a NNN_FIFO
 #     and set a key for the plugin, then start `nnn`:
-#
 #       $ NNN_FIFO=/tmp/nnn.fifo nnn
+#   - Launch the plugin with the designated key from nnn
 #
-#  Then in `nnn`, launch the `preview-tabbed` plugin.
+# Notes:
-#
+#   1. This plugin needs a "NNN_FIFO" to work. See man.
-#  If you provide the same NNN_FIFO to all nnn instances, there will be a
+#   2. If the same NNN_FIFO is used in multiple nnn instances, there will be one
-#  single common preview window. I you provide different FIFO path, they
+#      common preview window. With different FIFO paths, they will be independent.
-#  will be independent.
 #
 # How it works:
 #   We use `tabbed` [1] as a xembed [2] host, to have a single window
@@ -45,7 +42,7 @@
 # [1]: https://tools.suckless.org/tabbed/
 # [2]: https://specifications.freedesktop.org/xembed-spec/xembed-spec-latest.html
 #
-# Shell: bash (job control is weakly specified in POSIX)
+# Shell: Bash (job control is weakly specified in POSIX)
 # Author: Léo Villeveygoux
 
 

plugins/preview-tui

@@ -21,11 +21,9 @@
 #   - optional: bat for code syntax highlighting
 #   - optional: ueberzug, kitty terminal, viu or catimg for images.
 #   - optional: scope.sh file viewer from ranger.
-#                To use:
 #       1. drop scope.sh executable in $PATH
 #       2. set/export $USE_SCOPE as 1
 #   - optional: pistol file viewer (https://github.com/doronbehar/pistol).
-#                To use:
 #       1. install pistol
 #       2. set/export $USE_PISTOL as 1
 #
@@ -39,7 +37,7 @@
 #
 #     $ NNN_FIFO=/tmp/nnn.fifo nnn
 #
-#   Then in `nnn`, launch the `preview-tui` plugin.
+#   Then launch the `preview-tui` plugin in `nnn`.
 #
 #   If you provide the same NNN_FIFO to all nnn instances, there will be a
 #   single common preview window. If you provide different FIFO path (e.g.

plugins/renamer

@@ -5,9 +5,9 @@
 # Notes:
 #   - Try to mimic current batch rename functionality but with correct
 #     handling of edge cases by qmv or vidir.
-#	Qmv opens with hidden files if no selection is used. Selected
+#   - Qmv opens with hidden files if no selection is used. Selected
 #	  directories are shown.
-#   Vidir don't show directories nor hidden files.
+#   - Vidir don't show directories nor hidden files.
 #
 # Shell: POSIX compliant
 # Author: José Neder

plugins/uidgid

@@ -3,7 +3,6 @@
 # Description: list uid and gid of files
 #
 # Note: To list UID and GID of all users in a pretty format, run:
-#
 #           cut -d':' -f1,3,4,5 < /etc/passwd | column -ts ":"
 #
 # Shell: POSIX compliant

plugins/unmount-parent

@@ -1,15 +1,19 @@
 #!/usr/bin/env sh
 
-# Description: Autodetects a nnn remote mountpoint (mounted with `c`) from any of its subfolders and allows unmounting it
+# Description: Autodetects a nnn remote mountpoint (mounted with `c`)
-# from there without first going back to the top or entering the remote name. Also works when hovering the mountpoint
+#              from any of its subfolders and allows unmounting it
-# directly like vanilla `u`.
+#              from the subdir without navigating to the mountppoint
+#              or entering the remote name. Also works when hovering
+#              the mountpoint directly like vanilla `u`.
 #
 # Dependencies: fusermount
+#
 # Shell: POSIX compliant
 # Authors: Kabouik & 0xACE
 #
-# TODO: Try better avoiding lazy unmount by forcing nnn context to leave the subfolder before fusermount.
+# TODO:
-# I tried `printf "%s" "0c$m" > "$NNN_PIPE"` but this would break nnn UI all the time, see #854.
+# - Avoid lazy unmount by forcing nnn context to leave the subfolder before fusermount.
+#   Tried `printf "%s" "0c$m" > "$NNN_PIPE"` but it breaks the nnn interfacee, see #854.
 
 err=0
 m=$HOME/.config/nnn/mounts

plugins/upgrade

@@ -4,7 +4,7 @@
 #
 # Note: This script installs a package, should be issued with admin privilege
 #
-# Shell: POSIX-compliant
+# Shell: POSIX compliant
 # Author: Arun Prakash Jana
 
 cur="$(nnn -v)"

plugins/upload

@@ -3,7 +3,9 @@
 # Description: Upload to Firefox Send if ffsend is found, else
 #              Paste contents of a text a file http://ix.io
 #              Upload a binary file to file.io
+#
 # Dependencies: ffsend (https://github.com/timvisee/ffsend), curl, jq, tr
+#
 # Note: Binary file set to expire after a week
 #
 # Shell: POSIX compliant

plugins/vidthumb

@@ -3,8 +3,8 @@
 # Description: Generate video thumbnails and view them
 #
 # Dependencies:
-#    ffmpegthumbnailer: https://github.com/dirkvdb/ffmpegthumbnailer
+#   - ffmpegthumbnailer: https://github.com/dirkvdb/ffmpegthumbnailer
-#    lsix: https://github.com/hackerb9/lsix
+#   - lsix: https://github.com/hackerb9/lsix
 #
 # Shell: POSIX compliant
 # Author: Arun Prakash Jana

plugins/wall

@@ -1,9 +1,10 @@
 #!/usr/bin/env sh
 
 # Description: Set the selected image as wallpaper using nitrogen or pywal.
+#
 # Usage: Hover on an image and run the script to set it as wallpaper.
 #
-# Shell: POSIX Compliant
+# Shell: POSIX compliant
 # Author: juacq97
 
 if [ -n "$1" ]; then

plugins/x2sel

@@ -1,6 +1,7 @@
 #!/usr/bin/env sh
 
 # Description: Copy system clipboard newline-separated file list to selection
+#
 # Dependencies:
 #   - tr
 #   - xclip/xsel (Linux)
@@ -11,7 +12,8 @@
 #   - wl-paste (Wayland)
 #   - clipboard (Haiku)
 #
-# Limitation: breaks if a filename has newline in it
+# Note:
+#   - Limitation: breaks if a filename has newline in it
 #
 # Shell: POSIX compliant
 # Author: Léo Villeveygoux, after Arun Prakash Jana's .cbcp
@@ -21,7 +23,6 @@ IFS="$(printf '%b_' '\n')"; IFS="${IFS%_}" # protect trailing \n
 selection=${NNN_SEL:-${XDG_CONFIG_HOME:-$HOME/.config}/nnn/.selection}
 
 getclip () {
-
 	if type xsel >/dev/null 2>&1; then
 		# Linux
 		xsel -bo
@@ -47,7 +48,6 @@ getclip () {
 		# Haiku
 		clipboard --print
 	fi
-
 }
 
 CLIPBOARD=$(getclip)

plugins/xdgdefault

@@ -1,13 +1,13 @@
 #!/usr/bin/env sh
 
-# Description: Sets the xdg-open's default application for the current entry's
+# Description: Sets the xdg-open's default application for the current entry's file
-# file type. ${XDG_DATA_DIRS} and ${XDG_DATA_HOME} are set to the recommended
+#              type. ${XDG_DATA_DIRS} and ${XDG_DATA_HOME} are set to the recommended
-# defaults if unset, as specified in XDG Base Directory Specification,
+#              defaults if unset, as specified in XDG Base Directory Specification
-# [ http://specifications.freedesktop.org/basedir-spec/ ].
+#              - http://specifications.freedesktop.org/basedir-spec/.
 #
 # Dependencies: xdg-utils, fzf
 #
-# Shell: POSIX
+# Shell: POSIX compliant
 # Author: lwnctd
 
 if [ -z "$1" ] || ! command -v fzf > /dev/null 2>& 1; then