WIP: Updating README.md

README.md

@@ -7,9 +7,10 @@
 
 # verilog-ext.el - SystemVerilog Extensions for Emacs #
 
-This package provides some extensions on top of the great Emacs [verilog-mode](https://github.com/veripool/verilog-mode):
+This package provides useful extensions on top of [`verilog-mode`](https://github.com/veripool/verilog-mode)
+and [`verilog-ts-mode`](https://github.com/gmlarumbe/verilog-ts-mode).
 
-* [Tree-sitter powered `verilog-ts-mode`](#tree-sitter)
+* [Tree-sitter `verilog-ts-mode` support](#tree-sitter)
 * [Improve syntax highlighting](#syntax-highlighting)
 * [Find definitions and references](#find-definitions-and-references)
 * [Auto-completion with dot and scope completion](#auto-completion)
@@ -29,11 +30,22 @@ This package provides some extensions on top of the great Emacs [verilog-mode](h
 * [Auto-convert block end comments to names](#block-end-comments)
 * [Port connection utilities](#port-connections)
 
+## Requirements ##
+
+- Emacs 29.1+
+- Latest `verilog-mode` version
+- Feature-specific binaries
+
+Tree-sitter is optional but recommended and only required if using `verilog-ts-mode` for some of the features above.
+
+For more info, see the [wiki](https://github.com/gmlarumbe/verilog-ext/wiki/Requirements).
+
+
 ## Installation ##
 
 ### MELPA ###
 
-`verilog-ext` and `verilog-ts-mode` are available on MELPA. `verilog-ext` includes `verilog-ts-mode` as a dependency.
+`verilog-ext` is available on MELPA.
 
 ### straight.el ###
 
@@ -76,21 +88,17 @@ By default all features are enabled:
         ports))
 (verilog-ext-mode-setup)
 (add-hook 'verilog-mode-hook #'verilog-ext-mode)
-;; To use `verilog-ts-mode' as the default major-mode also add the line below:
-(add-to-list 'auto-mode-alist '("\\.s?vh?\\'" . verilog-ts-mode))
 ```
 
 If installed and loaded via `use-package`:
 
 ```elisp
 (use-package verilog-ext
-  :after verilog-mode
-  :demand
   :hook ((verilog-mode . verilog-ext-mode))
   :init
-   ;; Can also be set through `M-x RET customize-group RET verilog-ext':
-   ;;  - Verilog Ext Feature List (provides info of different features)
-   ;; Comment out/remove the ones you do not need
+  ;; Can also be set through `M-x RET customize-group RET verilog-ext':
+  ;;  - Verilog Ext Feature List (provides info of different features)
+  ;; Comment out/remove the ones you do not need
   (setq verilog-ext-feature-list
         '(font-lock
           xref
@@ -113,10 +121,6 @@ If installed and loaded via `use-package`:
           ports))
   :config
   (verilog-ext-mode-setup))
-
-;; To use `verilog-ts-mode' as the default major-mode also add the lines below:
-(use-package verilog-ts-mode
-  :mode (("\\.s?vh?\\'" . verilog-ts-mode))
 ```
 
 ## Workspace ##
@@ -193,15 +197,18 @@ Enabling of `verilog-ext-mode` minor-mode creates the following keybindings:
 # Features #
 
 ## Tree-sitter ##
-The package `verilog-ts-mode` provides syntax highlighting,
-indentation and a backend for hierarchy extraction, definitions and
-references navigation, and some other features implemented in
-`verilog-ext`. Using tree-sitter as a backend is recommended as it is
-much faster and efficient than internal Emacs lisp parsing.
 
-`verilog-ts-mode` is derived from `verilog-mode` making AUTOs and other utilities still available.
+Some of the features that `verilog-ext` provides are based either on
+builtin `verilog-mode` Emacs lisp parsing or on tree-sitter
+`verilog-ts-mode`.  These features are hierarchy extraction and workspace
+tags collection for completion and navigation of definitions and
+references.
 
-For more information see the [wiki](https://github.com/gmlarumbe/verilog-ext/wiki/Tree-sitter).
+Using tree-sitter as a backend is recommended as it is much faster,
+efficient and accurate than internal Emacs lisp parsing.
+
+For information about installation of `verilog-ts-mode` check its
+[repo](https://github.com/gmlarumbe/verilog-ts-mode).
 
 
 ## Syntax highlighting ##
@@ -213,7 +220,7 @@ For configuration information, see the [wiki](https://github.com/gmlarumbe/veril
 
 ## Find definitions and references ##
 
-`verilog-ext` provides a builtin `xref` backend to navigate definitions and references of the [workspace](#workspace).
+`verilog-ext` provides an `xref` backend to navigate definitions and references of the [workspace](#workspace).
 
 <img src="https://github.com/gmlarumbe/verilog-ext/assets/51021955/d196a676-6d28-4bfa-9cee-2662d592b3fb" width=400 height=300>
 
@@ -425,29 +432,47 @@ For new functionality add new ERT tests if possible.
 Consider [sponsoring](https://github.com/sponsors/gmlarumbe) to help
 maintaining the project and for the development of new features. *Thank you!*
 
-## ERT Tests setup ###
+## ERT Tests ###
+
+### Setup ###
+
+To run the whole ERT test suite change directory to the `verilog-ext`
+root and make sure `test-hdl` Git submodule has been loaded:
+
+```shell
+git submodule update --init
+```
+
+### Targets ###
 
-To run the whole ERT test suite change directory to the `verilog-ext` root and run the `test` target:
+Then run the default target:
 
 ```shell
-$ cd ~/.emacs.d/verilog-ext
 $ make
 ```
 
 To run a subset of tests (e.g. navigation):
 
 ```shell
-$ cd ~/.emacs.d/verilog-ext
-$ make subset TESTS=navigation
+$ make TESTS=navigation
 ```
 
-## Other packages
+To regenerate all the expected outputs for the tests:
+
+```shell
+$ make gen
+```
 
-* [vhdl-ext](https://github.com/gmlarumbe/vhdl-ext): VHDL Extensions for Emacs
-  * Analog package to edit VHDL sources
-* [fpga](https://github.com/gmlarumbe/fpga): FPGA & ASIC Utilities for Emacs
-  * Utilities for tools of major vendors of FPGA & ASIC
-* [wavedrom-mode](https://github.com/gmlarumbe/wavedrom-mode): Wavedrom integration for Emacs
-  * Edit and render WaveJSON files to create timing diagrams
-* [vunit-mode](https://github.com/embed-me/vunit-mode.git): VUnit Mode for Emacs
-  * Integration of [VUnit](https://github.com/VUnit/vunit) workflow.
+To regenerate the expected outputs for a group of tests (e.g. navigation):
+
+```shell
+$ make gen TESTS=navigation
+```
+
+## Other packages
+* [verilog-ts-mode](https://github.com/gmlarumbe/verilog-ts-mode): SystemVerilog Tree-sitter mode
+* [vhdl-ts-mode](https://github.com/gmlarumbe/vhdl-ts-mode): VHDL Tree-sitter mode
+* [vhdl-ext](https://github.com/gmlarumbe/vhdl-ext): VHDL Extensions
+* [fpga](https://github.com/gmlarumbe/fpga): FPGA & ASIC Utilities for tools of major vendors and open source
+* [wavedrom-mode](https://github.com/gmlarumbe/wavedrom-mode): edit and render WaveJSON files to create timing diagrams
+* [vunit-mode](https://github.com/embed-me/vunit-mode.git): Integration of [VUnit](https://github.com/VUnit/vunit) workflow