From cbfa512d75ca1ee9136bb3b6f782f2512b8fa0c0 Mon Sep 17 00:00:00 2001
From: NotAShelf <raf@notashelf.dev>
Date: Mon, 2 Jun 2025 16:08:52 +0300
Subject: [PATCH] docs: improve project description and styling in README

---
 README.md | 62 ++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 41 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 66f23f0..bb49636 100644
--- a/README.md
+++ b/README.md
@@ -1,27 +1,33 @@
 # nff
 
-This is a high performance configuration parser and written in Rust. The goal is
-to receive possibly jumbled up nftables rule files, and output ✨ pretty ✨
-human readable output in return. The main emphasis is on the syntax-aware
-formatting with comprehensive grammar support. It is a future goal to allow
-editors to hook into nff in order to format your rulesets directly from your
-editor, or as a diagnostics source.
+This is a high performance, low overhead configuration parser for nftables,
+written in Rust. Syntax-aware parsing allows nff to provide a complete formatter
+_and_ a linter for nftables. With the formatter the goal is to receive possibly
+jumbled up nftables rule files, and output ✨ pretty ✨ human readable output in
+return. The linter on another hand, will demonstrate possible syntax,
+performance or stylistic errors.
+
+The main emphasis, however, is on the syntax-aware formatting with comprehensive
+grammar support.
 
 ## Features
 
-nff is in its early stages of development. While _most_ of the syntax is
-supported, I cannot guarantee that _everything_ is supported just yet.
+> [!NOTE]
+> nff is in its early stages of development. While _most_ of the syntax is
+> supported, I cannot guarantee that _everything_ is supported just yet.
 
 ### Core Functionality
 
+Basic functionality of nff that most users will be interested in
+
 - **Syntax-aware formatting** - Deep understanding of nftables grammar with
   semantic preservation
-- **Multi-family support** - Handles `inet`, `ip`, `ip6`, `arp`, `bridge`, and
-  `netdev` table families
+  - **Multi-family support** - Handles `inet`, `ip`, `ip6`, `arp`, `bridge`, and
+    `netdev` table families
+  - **CIDR notation** - Proper handling of network addresses (`192.168.1.0/24`)
+  - **Chain properties** - Hooks, priorities (including negative), policies,
+    device bindings
 - **Flexible indentation** - Configurable tabs/spaces with custom depth
-- **CIDR notation** - Proper handling of network addresses (`192.168.1.0/24`)
-- **Chain properties** - Hooks, priorities (including negative), policies,
-  device bindings
 
 ### Advanced Features
 
@@ -145,16 +151,26 @@ graph TD
 
 ## Installation
 
-Recommended way of installing nff is to use Nix.
+Recommended way of installing nff is to use Nix. Add `nff` to your flake inputs,
+and add the package to your `environment.systemPackages`. Alternatively, on
+non-NixOS systems, it is possible to use `nix profile install` to install nff.
 
 ### Editor Integration
 
+> [!TIP]
+> Your editor not here? Open an issue. I can only add support for editors I use
+> but pull requests documenting alternative editor setups are appreciated!
+
 #### Neovim Setup
 
 nff can be integrated into Neovim as a diagnostics source for nftables files.
 Here are several setup approaches:
 
-##### Option 2: Using none-ls
+##### Option 1: Using none-ls
+
+none-ls is the most common method of adding diagnostics sources in Neovim. While
+I recommend using nvim-lint for its simplicity, below instructions document how
+to set up null-ls.
 
 ```lua
 local null_ls = require("null-ls")
@@ -182,6 +198,9 @@ null_ls.setup({
 
 ##### Option 2: Using nvim-lint (recommended)
 
+Recommended way of adding nff as a diagnostics source in Neovim. Simple, low
+overhead and not as error-prone as null-ls.
+
 ```lua
 -- ~/.config/nvim/lua/config/lint.lua
 require('lint').linters.nff = {
@@ -224,7 +243,8 @@ vim.api.nvim_create_autocmd({ "BufEnter", "BufWritePost" }, {
 
 ##### Option 3: Custom Lua Function
 
-For a simple custom solution:
+Alternatively, if you don't want to use plugins, consider a setup such as this
+one to do it without any reliance on plugins:
 
 ```lua
 -- ~/.config/nvim/lua/nff.lua
@@ -564,6 +584,11 @@ style.nft:1:16: warning: Missing space after '{' [NFT503]
 
 ## Contributing
 
+### Building
+
+Build with `cargo build` as usual. If you are using Nix, you will also want to
+ensure that the Nix package builds as expected.
+
 ### Code Style
 
 - Follow `cargo fmt` formatting
@@ -578,11 +603,6 @@ style.nft:1:16: warning: Missing space after '{' [NFT503]
 - **Regression tests**: Known issue prevention
 - **Performance tests**: Benchmark critical paths
 
-### Building
-
-Build with `cargo build` as usual. If you are using Nix, you will also want to
-ensure that the Nix package builds as expected.
-
 ## Technical Notes
 
 ### CST Implementation