From 53a62cf2b06ea58973a7880096d959bfc42677d6 Mon Sep 17 00:00:00 2001
From: Owen Ou <169064+owenthereal@users.noreply.github.com>
Date: Thu, 3 Aug 2023 06:27:09 -0700
Subject: [PATCH] Improve README to be more structural and more readable
 (#2814)

---
 README.md | 94 +++++++++++++++++++++++--------------------------------
 1 file changed, 39 insertions(+), 55 deletions(-)

diff --git a/README.md b/README.md
index f71577eded..fb0730f491 100644
--- a/README.md
+++ b/README.md
@@ -1,76 +1,60 @@
-jq
-==
+# jq
 
-jq is a lightweight and flexible command-line JSON processor.
+`jq` is a lightweight and flexible command-line JSON processor akin to`sed`,`awk`,`grep`, and friends for JSON data. It's written in portable C and has zero runtime dependencies, allowing you to easily slice, filter, map, and transform structured data.
 
-If you want to learn to use jq, read the documentation at
-[https://jqlang.github.io/jq](https://jqlang.github.io/jq).  This
-documentation is generated from the docs/ folder of this repository.
-You can also try it online at [jqplay.org](https://jqplay.org).
+## Documentation
 
-If you want to hack on jq, feel free, but be warned that its internals
-are not well-documented at the moment. Bring a hard hat and a
-shovel.  Also, read the wiki: https://github.com/jqlang/jq/wiki, where
-you will find cookbooks, discussion of advanced topics, internals,
-release engineering, and more.
+- **Official Documentation**: [jqlang.github.io/jq](https://jqlang.github.io/jq)
+- **Try jq Online**: [jqplay.org](https://jqplay.org)
 
-Source tarball and built executable releases can be found on the
-homepage and on the github release page, https://github.com/jqlang/jq/releases.
-Docker image is available at https://github.com/jqlang/jq/pkgs/container/jq.
+## Installation
 
-If you're building directly from the latest git, you'll need libtool, make, automake,
-and autoconf installed.
-To get regexp support you'll also need to install Oniguruma or clone it as a
-git submodule as per the instructions below. To build, run:
+### Prebuilt Binaries
 
-    git submodule update --init # if building from git to get oniguruma
-    autoreconf -i               # if building from git
-    ./configure --with-oniguruma=builtin
-    make -j8
-    make check
+Download the latest releases from the [GitHub release page](https://github.com/jqlang/jq/releases).
 
-Developers must `--enable-maintainer-mode` when making changes to the
-jq parser and lexer which also requires bison and flex to be installed.
+### Docker Image
 
-To build a statically linked version of jq, run:
+Pull the [jq image](https://github.com/jqlang/jq/pkgs/container/jq) to start quickly with Docker.
 
-    make LDFLAGS=-all-static
+### Building from source
 
-After make finishes, you'll be able to use `./jq`.  You can also
-install it using:
+#### Dependencies
 
-    sudo make install
+- libtool
+- make
+- automake
+- autoconf
 
-If you're not using the latest git version but instead building a
-released tarball (available on the website), then you won't need to
-run `autoreconf` (and shouldn't), and you won't need flex or bison.
+#### Instructions
 
-To cross-compile for OS X and Windows, see docs/Rakefile's build task
-and scripts/crosscompile.  You'll need a cross-compilation environment,
-such as Mingw for cross-compiling for Windows.
+```console
+git submodule update --init # if building from git to get oniguruma
+autoreconf -i               # if building from git
+./configure --with-oniguruma=builtin
+make -j8
+make check
+sudo make install
+```
 
-Cross-compilation requires a clean workspace, then:
+Build a statically linked version:
 
-    # git clean ...
-    autoreconf -i
-    ./configure
-    make distclean
-    scripts/crosscompile <name-of-build> <configure-options>
+```console
+make LDFLAGS=-all-static
+```
 
-Use the `--host=` and `--target=` ./configure options to select a
-cross-compilation environment.  See also
-["Cross compilation"](https://github.com/jqlang/jq/wiki/Cross-compilation) on
-the wiki.
+If you're not using the latest git version but instead building a released tarball (available on the release page), skip the `autoreconf` step, and flex or bison won't be needed.
 
-To compile jq to WebAssembly, install the [Emscripten SDK](https://emscripten.org/docs/getting_started/downloads.html), then:
+##### Cross-Compilation
 
-    git submodule update --init # if building from git to get oniguruma
-    autoreconf -i               # if building from git
-    emconfigure ./configure --with-oniguruma=builtin
-    emmake make EXEEXT=.js CFLAGS="-O2" LDFLAGS="-s EXPORTED_RUNTIME_METHODS=['callMain']"
+For details on cross-compliation, check out the [GitHub Actions file](.github/workflows/ci.yml) and the [cross-compliation wiki page](https://github.com/jqlang/jq/wiki/Cross-compilation).
 
+## Community & Support
 
-# Community
+- Questions & Help: [Stack Overflow (jq tag)](https://stackoverflow.com/questions/tagged/jq)
+- Chat & Community: [Join us on Discord](https://discord.gg/yg6yjNmgAC)
+- Wiki & Advanced Topics: [Explore the Wiki](https://github.com/jqlang/jq/wiki)
 
-* Send questions to https://stackoverflow.com/questions/tagged/jq.
-* Join our [Discord server](https://discord.gg/yg6yjNmgAC).
+## License
+
+`jq` is released under the [MIT License](COPYING).