Updates to the README and some documentation (#681)

Author: NWilson

AUTHORS.md

@@ -1,14 +1,14 @@
 PCRE2 Authorship and Contributors
 =================================
 
-COPYRIGHT
+Copyright
 ---------
 
 Please see the file [LICENCE](./LICENCE.md) in the PCRE2 distribution for
 copyright details.
 
 
-MAINTAINERS
+Maintainers
 -----------
 
 The PCRE and PCRE2 libraries were authored and maintained by Philip Hazel.
@@ -62,7 +62,7 @@ Both administrators are volunteers acting in a personal capacity.
 </table>
 
 
-CONTRIBUTORS
+Contributors
 ------------
 
 Many others have participated and contributed to PCRE2 over its history.

LICENCE.md

@@ -99,5 +99,3 @@ not apply all the way down a chain of software. If binary package A includes
 PCRE2, it must respect the condition, but if package B is software that
 includes package A, the condition is not imposed on package B unless it uses
 PCRE2 independently.
-
-End

NON-AUTOTOOLS-BUILD

@@ -1,5 +1,5 @@
 Building PCRE2 without using autotools
---------------------------------------
+======================================
 
 This document contains the following sections:
 
@@ -16,7 +16,8 @@ This document contains the following sections:
   Building PCRE2 under VMS
 
 
-GENERAL
+General
+-------
 
 The source of the PCRE2 libraries consists entirely of code written in Standard
 C, and so should compile successfully on any system that has a Standard C
@@ -37,7 +38,8 @@ provided for those who build PCRE2 without using "configure" or CMake. If you
 use "configure" or CMake, the .generic versions are not used.
 
 
-GENERIC INSTRUCTIONS FOR THE PCRE2 C LIBRARIES
+Generic instructions for the PCRE2 C libraries
+----------------------------------------------
 
 There are three possible PCRE2 libraries, each handling data with a specific
 code unit width: 8, 16, or 32 bits. You can build any combination of them. The
@@ -207,20 +209,23 @@ example.
      defining SUPPORT_JIT, pcre2grep does not try to make use of JIT.
 
 
-STACK SIZE IN WINDOWS ENVIRONMENTS
+Stack size in Windows environments
+----------------------------------
 
 Prior to release 10.30 the default system stack size of 1MiB in some Windows
 environments caused issues with some tests. This should no longer be the case
 for 10.30 and later releases.
 
 
-LINKING PROGRAMS IN WINDOWS ENVIRONMENTS
+Linking programs in Windows environments
+----------------------------------------
 
 If you want to statically link a program against a PCRE2 library in the form of
 a non-dll .a file, you must define PCRE2_STATIC before including src/pcre2.h.
 
 
-CALLING CONVENTIONS IN WINDOWS ENVIRONMENTS
+Calling conventions in Windows environments
+-------------------------------------------
 
 It is possible to compile programs to use different calling conventions using
 MSVC. Search the web for "calling conventions" for more information. To make it
@@ -231,7 +236,8 @@ not set, it defaults to empty; the default calling convention is then used
 (which is what is wanted most of the time).
 
 
-COMMENTS ABOUT WIN32 BUILDS (see also "BUILDING PCRE2 ON WINDOWS WITH CMAKE")
+Comments about Win32 builds (see also "Building PCRE2 on Windows with CMake")
+---------------------------
 
 There are two ways of building PCRE2 using the "configure, make, make install"
 paradigm on Windows systems: using MinGW or using Cygwin. These are not at all
@@ -293,7 +299,8 @@ newline option that includes LF as a valid newline, it may be necessary to
 change the line terminators in the test files to get some of the tests to work.
 
 
-BUILDING PCRE2 ON WINDOWS WITH CMAKE
+Building PCRE2 on Windows with CMake
+------------------------------------
 
 CMake is an alternative configuration facility that can be used instead of
 "configure". CMake creates project files (make files, solution files, etc.)
@@ -364,7 +371,8 @@ be deleted.
    Regardless of build system used, `ctest` will run the tests.
 
 
-BUILDING PCRE2 ON WINDOWS WITH VISUAL STUDIO
+Building PCRE2 on Windows with Visual Studio
+--------------------------------------------
 
 The code currently cannot be compiled without an inttypes.h header, which is
 available only with Visual Studio 2013 or newer. However, this portable and
@@ -376,7 +384,8 @@ alternative:
 Just rename it and drop it into the top level of the build tree.
 
 
-TESTING WITH RUNTEST.BAT
+Testing with RunTest.bat
+------------------------
 
 If configured with CMake, building the test project ("make test" or building
 ALL_TESTS in Visual Studio) creates (and runs) pcre2_test.bat (and depending
@@ -410,7 +419,8 @@ Otherwise:
 To independently test the just-in-time compiler, run pcre2_jit_test.exe.
 
 
-BUILDING PCRE2 ON NATIVE Z/OS AND Z/VM
+Building PCRE2 on native z/OS and z/VM
+--------------------------------------
 
 z/OS and z/VM are operating systems for mainframe computers, produced by IBM.
 The character code used is EBCDIC, not ASCII or Unicode. In z/OS, UNIX APIs and
@@ -429,7 +439,8 @@ z/OS file formats. The port provides an API for LE languages such as COBOL and
 for the z/OS and z/VM versions of the Rexx languages.
 
 
-BUILDING PCRE2 UNDER VMS
+Building PCRE2 under VMS
+------------------------
 
 Alexey Chuphin has contributed some auxiliary files for building PCRE2 under
 OpenVMS. They are in the "vms" directory in the distribution tarball. Please

README

@@ -1,5 +1,5 @@
 README file for PCRE2 (Perl-compatible regular expression library)
-------------------------------------------------------------------
+==================================================================
 
 PCRE2 is a re-working of the original PCRE1 library to provide an entirely new
 API. Since its initial release in 2015, there has been further development of

README.md

@@ -1,6 +1,6 @@
 <picture>
-  <source media="(prefers-color-scheme: dark)" width="100%" height="100px" srcset="https://raw.githubusercontent.com/PCRE2Project/pcre2/refs/heads/pages/pages/assets/pcre2-readme-dark.svg">
-  <img alt="PCRE2: Perl-Compatible Regular Expressions" width="100%" height="100px" src="https://raw.githubusercontent.com/PCRE2Project/pcre2/refs/heads/pages/pages/assets/pcre2-readme-light.svg">
+  <source media="(prefers-color-scheme: dark)" width="100%" height="100px" srcset="https://raw.githubusercontent.com/PCRE2Project/pcre2/refs/heads/pages/pages/static/images/pcre2-readme-dark.svg">
+  <img alt="PCRE2: Perl-Compatible Regular Expressions" width="100%" height="100px" src="https://raw.githubusercontent.com/PCRE2Project/pcre2/refs/heads/pages/pages/static/images/pcre2-readme-light.svg">
 </picture>
 
 ## Overview
@@ -64,7 +64,7 @@ x86, ARM, RISC-V, POWER, S390X; many others known to work
 
 <picture>
   <source media="(prefers-color-scheme: dark)" width="787px" srcset="https://github.com/user-attachments/assets/1886bc4b-2e05-4827-af83-e4ed45f25ab1">
-  <img width="787px" src="https://github.com/user-attachments/assets/7b90180e-276e-4202-b590-b72871cff91a">
+  <img alt="Recording of a terminal session showing the PCRE2 quickstart; reproduced in text form below" width="787px" src="https://github.com/user-attachments/assets/7b90180e-276e-4202-b590-b72871cff91a">
 </picture>
 
 <details>
@@ -86,12 +86,20 @@ git clone https://github.com/PCRE2Project/pcre2.git ./pcre2 \
 
 # Here's a quick little demo to show how we can make use of PCRE2.
 # For a fuller example, see './pcre2/src/pcre2demo.c'.
-# Try this pre-prepared sample code:
-cat demo.c
+# See below for the demo code.
 
-----------------------------------------------------------------------
-File: demo.c
-----------------------------------------------------------------------
+# Compile the demo:
+gcc -g -I./pcre2/build -L./pcre2/build demo.c -o demo -lpcre2-8
+
+# Finally, run our demo:
+./demo 'c.t' 'dogs and cats'
+
+# We fetched, built, and called PCRE2 successfully! :)
+```
+
+File `demo.c`:
+
+```c
 /* Set PCRE2_CODE_UNIT_WIDTH to indicate we will use 8-bit input. */
 #define PCRE2_CODE_UNIT_WIDTH 8
 #include <pcre2.h>
@@ -150,15 +158,6 @@ int main(int argc, char* argv[]) {
     pcre2_code_free(re);
     return 0;
 }
-----------------------------------------------------------------------
-
-# Compile the demo:
-gcc -g -I./pcre2/build -L./pcre2/build demo.c -o demo -lpcre2-8
-
-# Finally, run our demo:
-./demo 'c.t' 'dogs and cats'
-
-# We fetched, built, and called PCRE2 successfully! :)
 ```
 
 </details>
@@ -213,7 +212,7 @@ There are accompanying utility functions for converting glob patterns and POSIX
 
 As well as the PCRE2 API, the library also offers a POSIX-compatible `<regex.h>` header and `regexec()` function. However, this does not provide the ability to pass PCRE2 flags, so we recommend users consume the PCRE2 API if possible.
 
-See the [full library and API documentation](https://pcre2project.github.io/pcre2/doc/html/index.html) for further details.
+See the [full library and API documentation](https://pcre2project.github.io/pcre2/doc/) for further details.
 
 For third-party documentation, see further:
 
@@ -241,7 +240,7 @@ Other systems are likely to work (including mobile, embedded platforms, and comm
 
 PCRE2 releases support CMake for building, and for UNIX platforms include a `./configure` script built by Autoconf. Build files for the Bazel build system and `zig build` are also included. Integrating PCRE2 with other systems can be done by including the `.c` files in an existing project.
 
-Please see the files [README](./README) and [NON-AUTOTOOLS-BUILD](./NON-AUTOTOOLS-BUILD) for full build documentation, as well as the man pages, including [`man pcre2/doc/pcre2build.3`](https://pcre2project.github.io/pcre2/doc/html/pcre2build.html).
+Please see the files [README](./README) and [NON-AUTOTOOLS-BUILD](./NON-AUTOTOOLS-BUILD) for full build documentation, as well as the man pages, including [`man pcre2/doc/pcre2build.3`](https://pcre2project.github.io/pcre2/doc/pcre2build/).
 
 ## Licence
 

SECURITY.md

@@ -1,6 +1,8 @@
-# Security policies
+Security policies
+=================
 
-## Release security
+Release security
+----------------
 
 The PCRE2 project provides source-only releases, with no binaries.
 
@@ -20,7 +22,8 @@ Git checkout of the (GPG-signed) release tag.
 Please contact the maintainers for any queries about release integrity or the
 project's supply-chain.
 
-## Reporting vulnerabilities
+Reporting vulnerabilities
+-------------------------
 
 The PCRE2 project prioritises security. We appreciate third-party testing and
 security research, and would be grateful if you could responsibly disclose your

doc/html/NON-AUTOTOOLS-BUILD.txt

@@ -1,5 +1,5 @@
 Building PCRE2 without using autotools
---------------------------------------
+======================================
 
 This document contains the following sections:
 
@@ -16,7 +16,8 @@ This document contains the following sections:
   Building PCRE2 under VMS
 
 
-GENERAL
+General
+-------
 
 The source of the PCRE2 libraries consists entirely of code written in Standard
 C, and so should compile successfully on any system that has a Standard C
@@ -37,7 +38,8 @@ provided for those who build PCRE2 without using "configure" or CMake. If you
 use "configure" or CMake, the .generic versions are not used.
 
 
-GENERIC INSTRUCTIONS FOR THE PCRE2 C LIBRARIES
+Generic instructions for the PCRE2 C libraries
+----------------------------------------------
 
 There are three possible PCRE2 libraries, each handling data with a specific
 code unit width: 8, 16, or 32 bits. You can build any combination of them. The
@@ -207,20 +209,23 @@ example.
      defining SUPPORT_JIT, pcre2grep does not try to make use of JIT.
 
 
-STACK SIZE IN WINDOWS ENVIRONMENTS
+Stack size in Windows environments
+----------------------------------
 
 Prior to release 10.30 the default system stack size of 1MiB in some Windows
 environments caused issues with some tests. This should no longer be the case
 for 10.30 and later releases.
 
 
-LINKING PROGRAMS IN WINDOWS ENVIRONMENTS
+Linking programs in Windows environments
+----------------------------------------
 
 If you want to statically link a program against a PCRE2 library in the form of
 a non-dll .a file, you must define PCRE2_STATIC before including src/pcre2.h.
 
 
-CALLING CONVENTIONS IN WINDOWS ENVIRONMENTS
+Calling conventions in Windows environments
+-------------------------------------------
 
 It is possible to compile programs to use different calling conventions using
 MSVC. Search the web for "calling conventions" for more information. To make it
@@ -231,7 +236,8 @@ not set, it defaults to empty; the default calling convention is then used
 (which is what is wanted most of the time).
 
 
-COMMENTS ABOUT WIN32 BUILDS (see also "BUILDING PCRE2 ON WINDOWS WITH CMAKE")
+Comments about Win32 builds (see also "Building PCRE2 on Windows with CMake")
+---------------------------
 
 There are two ways of building PCRE2 using the "configure, make, make install"
 paradigm on Windows systems: using MinGW or using Cygwin. These are not at all
@@ -293,7 +299,8 @@ newline option that includes LF as a valid newline, it may be necessary to
 change the line terminators in the test files to get some of the tests to work.
 
 
-BUILDING PCRE2 ON WINDOWS WITH CMAKE
+Building PCRE2 on Windows with CMake
+------------------------------------
 
 CMake is an alternative configuration facility that can be used instead of
 "configure". CMake creates project files (make files, solution files, etc.)
@@ -364,7 +371,8 @@ be deleted.
    Regardless of build system used, `ctest` will run the tests.
 
 
-BUILDING PCRE2 ON WINDOWS WITH VISUAL STUDIO
+Building PCRE2 on Windows with Visual Studio
+--------------------------------------------
 
 The code currently cannot be compiled without an inttypes.h header, which is
 available only with Visual Studio 2013 or newer. However, this portable and
@@ -376,7 +384,8 @@ alternative:
 Just rename it and drop it into the top level of the build tree.
 
 
-TESTING WITH RUNTEST.BAT
+Testing with RunTest.bat
+------------------------
 
 If configured with CMake, building the test project ("make test" or building
 ALL_TESTS in Visual Studio) creates (and runs) pcre2_test.bat (and depending
@@ -410,7 +419,8 @@ Otherwise:
 To independently test the just-in-time compiler, run pcre2_jit_test.exe.
 
 
-BUILDING PCRE2 ON NATIVE Z/OS AND Z/VM
+Building PCRE2 on native z/OS and z/VM
+--------------------------------------
 
 z/OS and z/VM are operating systems for mainframe computers, produced by IBM.
 The character code used is EBCDIC, not ASCII or Unicode. In z/OS, UNIX APIs and
@@ -429,7 +439,8 @@ z/OS file formats. The port provides an API for LE languages such as COBOL and
 for the z/OS and z/VM versions of the Rexx languages.
 
 
-BUILDING PCRE2 UNDER VMS
+Building PCRE2 under VMS
+------------------------
 
 Alexey Chuphin has contributed some auxiliary files for building PCRE2 under
 OpenVMS. They are in the "vms" directory in the distribution tarball. Please

doc/html/README.txt

@@ -1,5 +1,5 @@
 README file for PCRE2 (Perl-compatible regular expression library)
-------------------------------------------------------------------
+==================================================================
 
 PCRE2 is a re-working of the original PCRE1 library to provide an entirely new
 API. Since its initial release in 2015, there has been further development of