From 531128caeae48016b1aee5fdbae3944ddee1d428 Mon Sep 17 00:00:00 2001 From: Minsoo Choo Date: Wed, 24 Jan 2024 12:37:12 -0500 Subject: [PATCH 1/5] Add Markdown feature to README, INSTALL, and NEWS Signed-off-by: Minsoo Choo --- INSTALL => INSTALL.md | 0 NEWS => NEWS.md | 0 README => README.md | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename INSTALL => INSTALL.md (100%) rename NEWS => NEWS.md (100%) rename README => README.md (100%) diff --git a/INSTALL b/INSTALL.md similarity index 100% rename from INSTALL rename to INSTALL.md diff --git a/NEWS b/NEWS.md similarity index 100% rename from NEWS rename to NEWS.md diff --git a/README b/README.md similarity index 100% rename from README rename to README.md From 976bb44b9b6f2457ffdc3cef50552c4e4553dc4e Mon Sep 17 00:00:00 2001 From: Minsoo Choo Date: Wed, 24 Jan 2024 12:39:40 -0500 Subject: [PATCH 2/5] Update NEWS.md Signed-off-by: Minsoo Choo --- NEWS.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/NEWS.md b/NEWS.md index 3cb25cd..d25cc54 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,7 @@ +Major changes between releases +============================== + + Changes in version 0.4 ====================== From ad34b0d2bb170dfe3168faff0480cdb0d4b7e0ee Mon Sep 17 00:00:00 2001 From: Minsoo Choo Date: Wed, 24 Jan 2024 12:51:36 -0500 Subject: [PATCH 3/5] Update INSTALL.md Signed-off-by: Minsoo Choo --- INSTALL.md | 77 +++++++++++++++++++++++++++--------------------------- 1 file changed, 38 insertions(+), 39 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index b099c1c..0463f8d 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,5 +1,5 @@ -Introduction -============ +Installation instructions +========================= Lutok uses the GNU Automake, GNU Autoconf and GNU Libtool utilities as its build system. These are used only when compiling the library from @@ -56,17 +56,17 @@ distribution file. On the other hand, if you are building Lutok from code extracted from the repository, you must first regenerate the files used by the build -system. You will also need to do this if you modify configure.ac, -Makefile.am or any of the other build system files. To do this, simply +system. You will also need to do this if you modify `configure.ac`, +`Makefile.am` or any of the other build system files. To do this, simply run: $ autoreconf -i -s If ATF is installed in a different prefix than Autoconf, you will also -need to tell autoreconf where the ATF M4 macros are located. Otherwise, +need to tell autoreconf where the `ATF M4` macros are located. Otherwise, the configure script will be incomplete and will show confusing syntax -errors mentioning, for example, ATF_CHECK_SH. To fix this, you have -to run autoreconf in the following manner, replacing '' with +errors mentioning, for example, `ATF_CHECK_SH`. To fix this, you have +to run autoreconf in the following manner, replacing `` with the appropriate path: $ autoreconf -i -s -I /share/aclocal @@ -78,46 +78,46 @@ General build procedure To build and install the source package, you must follow these steps: 1. Configure the sources to adapt to your operating system. This is - done using the 'configure' script located on the sources' top + done using the `configure` script located on the sources' top directory, and it is usually invoked without arguments unless you want to change the installation prefix. More details on this procedure are given on a later section. 2. Build the sources to generate the binaries and scripts. Simply run - 'make' on the sources' top directory after configuring them. No + `make` on the sources' top directory after configuring them. No problems should arise. -3. Install the library by running 'make install'. You may need to +3. Install the library by running `make install`. You may need to become root to issue this step. 4. Issue any manual installation steps that may be required. These are described later in their own section. -5. Check that the installed library works by running 'make - installcheck'. You do not need to be root to do this. +5. Check that the installed library works by running `make + installcheck`. You do not need to be root to do this. Configuration flags =================== -The most common, standard flags given to 'configure' are: +The most common, standard flags given to `configure` are: -* --prefix=directory - Possible values: Any path - Default: /usr/local +* `--prefix=directory`: + **Possible values:** Any path + **Default:** `/usr/local` Specifies where the library (binaries and all associated files) will be installed. -* --help +* `--help`: Shows information about all available flags and exits immediately, without running any configuration tasks. -The following flags are specific to Lutok's 'configure' script: +The following flags are specific to Lutok's `configure` script: -* --enable-developer - Possible values: yes, no - Default: 'yes' in Git HEAD builds; 'no' in formal releases. +* `--enable-developer`: + **Possible values:** `yes`, `no` + **Default:** `yes` in HEAD builds; `no` in release builds. Enables several features useful for development, such as the inclusion of debugging symbols in all objects or the enforcement of compilation @@ -125,35 +125,35 @@ The following flags are specific to Lutok's 'configure' script: The compiler will be executed with an exhaustive collection of warning detection features regardless of the value of this flag. However, such - warnings are only fatal when --enable-developer is 'yes'. + warnings are only fatal when `--enable-developer` is `yes`. -* --with-atf - Possible values: yes, no, auto. - Default: auto. +* `--with-atf`: + **Possible values:** `yes`, `no`, `auto`. + **Default:** `auto`. Enables usage of ATF to build (and later install) the tests. - Setting this to 'yes' causes the configure script to look for ATF - unconditionally and abort if not found. Setting this to 'auto' lets + Setting this to `yes` causes the configure script to look for ATF + unconditionally and abort if not found. Setting this to `auto` lets configure perform the best decision based on availability of ATF. - Setting this to 'no' explicitly disables ATF usage. + Setting this to `no` explicitly disables ATF usage. When support for tests is enabled, the build process will generate the test programs and will later install them into the tests tree. - Running 'make check' or 'make installcheck' from within the source + Running `make check` or `make installcheck` from within the source directory will cause these tests to be run with Kyua (assuming it is also installed). -* --with-doxygen - Possible values: yes, no, auto or a path. - Default: auto. +* `--with-doxygen`: + **Possible values:** `yes`, `no`, `auto` or a path. + **Default:** `auto`. Enables usage of Doxygen to generate documentation for internal APIs. - Setting this to 'yes' causes the configure script to look for Doxygen - unconditionally and abort if not found. Setting this to 'auto' lets + Setting this to `yes` causes the configure script to look for Doxygen + unconditionally and abort if not found. Setting this to `auto` lets configure perform the best decision based on availability of Doxygen. - Setting this to 'no' explicitly disables Doxygen usage. And, lastly, + Setting this to `no` explicitly disables Doxygen usage. And, lastly, setting this to a path forces configure to use a specific Doxygen binary, which must exist. @@ -161,7 +161,7 @@ The following flags are specific to Lutok's 'configure' script: HTML documentation for the Lutok API. This documentation will later be installed in the HTML directory specified by the configure script. You can change the location of the HTML documents by providing your - desired override with the '--htmldir' flag to the configure script. + desired override with the `--htmldir` flag to the configure script. Run the tests! @@ -174,8 +174,7 @@ follows: $ kyua test -k /usr/local/tests/lutok/Kyuafile -And if you see any tests fail, do not hesitate to report them in: - - https://github.com/freebsd/lutok/issues/ +And if you see any tests fail, do not hesitate to report them on +[GitHub issues](https://github.com/freebsd/lutok/issues/) Thank you! From 7f8d72b517078c03a3138dc5daf1cef4a68ecf9f Mon Sep 17 00:00:00 2001 From: Minsoo Choo Date: Wed, 24 Jan 2024 12:51:43 -0500 Subject: [PATCH 4/5] Update README.md Signed-off-by: Minsoo Choo --- README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index e818ac9..bb027d4 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,7 @@ -Lutok is a lightweight C++ API library for Lua. +Welcome to the Kyua project! +============================ + +Lutok is a **lightweight C++ API library** for Lua. Lutok provides thin C++ wrappers around the Lua C API to ease the interaction between C++ and Lua. These wrappers make intensive use of @@ -19,9 +22,7 @@ please refer to the following other documents: * AUTHORS: List of authors and contributors to this project. * COPYING: License information. -* INSTALL: Compilation and installation instructions. -* NEWS: List of major changes between formal releases. - -For general project information, please visit: +* INSTALL.md: Compilation and installation instructions. +* NEWS.md: List of major changes between formal releases. - https://github.com/freebsd/lutok/ +For general project information, please visit [Lutok on GitHub](https://github.com/freebsd/lutok/) From dbcc408f587e4d9150a4c4627d2906acb9580a06 Mon Sep 17 00:00:00 2001 From: Minsoo Choo Date: Wed, 24 Jan 2024 13:27:06 -0500 Subject: [PATCH 5/5] Format Markdown Github web and mobile apps show Markdown files in a nicer way than just a text file. With Markdown files, users can copy and paste commands from web page, and this improves accessibility. Level of headings is more readable on Markdown using #, and it uses only one line for headings. Signed-off-by: Minsoo Choo --- INSTALL.md | 18 ++++++------------ NEWS.md | 16 +++++----------- README.md | 11 +++++------ 3 files changed, 16 insertions(+), 29 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 0463f8d..bbcf768 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,5 +1,4 @@ -Installation instructions -========================= +# Installation instructions Lutok uses the GNU Automake, GNU Autoconf and GNU Libtool utilities as its build system. These are used only when compiling the library from @@ -25,8 +24,7 @@ Or alternatively, install as a regular user into your home directory: $ make installcheck -Dependencies -============ +## Dependencies To build and use Lutok successfully you need: @@ -48,8 +46,7 @@ need the following tools: * GNU Libtool. -Regenerating the build system -============================= +## Regenerating the build system This is not necessary if you are building from a formal release distribution file. @@ -72,8 +69,7 @@ the appropriate path: $ autoreconf -i -s -I /share/aclocal -General build procedure -======================= +## General build procedure To build and install the source package, you must follow these steps: @@ -97,8 +93,7 @@ To build and install the source package, you must follow these steps: installcheck`. You do not need to be root to do this. -Configuration flags -=================== +## Configuration flags The most common, standard flags given to `configure` are: @@ -164,8 +159,7 @@ The following flags are specific to Lutok's `configure` script: desired override with the `--htmldir` flag to the configure script. -Run the tests! -============== +## Run the tests! Lastly, after a successful installation (and assuming you built the sources with support for ATF), you should periodically run the tests diff --git a/NEWS.md b/NEWS.md index d25cc54..5b4e65c 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,9 +1,6 @@ -Major changes between releases -============================== +# Major changes between releases - -Changes in version 0.4 -====================== +## Changes in version 0.4 Released on 2013/12/07. @@ -28,8 +25,7 @@ Interface changes: pcall call. -Changes in version 0.3 -====================== +## Changes in version 0.3 Released on 2013/06/14. @@ -51,8 +47,7 @@ Interface changes: * Removed global constants: globals_index. -Changes in version 0.2 -====================== +## Changes in version 0.2 Released on 2012/05/30. @@ -64,8 +59,7 @@ Released on 2012/05/30. * Acknowledged that Lua 5.2 is currently not supported. -Changes in version 0.1 -====================== +## Changes in version 0.1 Released on 2012/01/29. diff --git a/README.md b/README.md index bb027d4..b376abf 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ -Welcome to the Kyua project! -============================ +# Welcome to the Lutok project! Lutok is a **lightweight C++ API library** for Lua. @@ -20,9 +19,9 @@ performance. For further information on the contents of this distribution file, please refer to the following other documents: -* AUTHORS: List of authors and contributors to this project. -* COPYING: License information. -* INSTALL.md: Compilation and installation instructions. -* NEWS.md: List of major changes between formal releases. +* `AUTHORS`: List of authors and contributors to this project. +* `COPYING`: License information. +* `INSTALL.md:` Compilation and installation instructions. +* `NEWS.md`: List of major changes between formal releases. For general project information, please visit [Lutok on GitHub](https://github.com/freebsd/lutok/)