From e77677e476ae8aef549a867ba389c22c23d680fd Mon Sep 17 00:00:00 2001
From: "xanthos@durruti" <xanthos.papanikolaou@gmail.com>
Date: Wed, 23 Oct 2024 10:43:56 +0300
Subject: [PATCH] minor

---
 CMakeLists.txt  | 33 +++++++++++++------
 doc/tutorial.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 106 insertions(+), 13 deletions(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 6bdb5d0..1de3ab6 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -10,6 +10,9 @@ project(
 # Enable clang-tidy option
 option(ENABLE_CLANG_TIDY "Enable clang-tidy checks" OFF)
 
+# Define an option for building tests (defaults to ON)
+option(BUILD_TESTING "Enable building of tests" ON)
+
 # compiler flags
 set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED On)
@@ -83,17 +86,27 @@ target_include_directories(integral_seconds_limits PRIVATE ${CMAKE_CURRENT_SOURC
 set(CMAKE_CXX_CLANG_TIDY "")
 
 # The tests
-include(CTest)
-add_subdirectory(test/unit_tests)
-add_subdirectory(test/should_not_compile)
-find_library(sofa sofa_c)
-if (sofa)
-  add_subdirectory(test/sofa)
-  message(STATUS "found sofa lib, will compile relevant tests")
-else()
-  message(STATUS "sofa lib not found; tests in test/sofa will not be compiled.")
+if(BUILD_TESTING)
+  include(CTest)
+  add_subdirectory(test/unit_tests)
+  add_subdirectory(test/should_not_compile)
+  find_library(sofa sofa_c)
+  if (sofa)
+    add_subdirectory(test/sofa)
+    message(STATUS "found sofa lib, will compile relevant tests")
+  else()
+    message(STATUS "sofa lib not found; tests in test/sofa will not be compiled.")
+  endif()
+  enable_testing()
 endif()
-enable_testing()
+
+# Install the executables
+install(TARGETS ymd2mjd
+        RUNTIME DESTINATION bin)
+install(TARGETS mjd2ymd
+        RUNTIME DESTINATION bin)
+install(TARGETS mjd2ydoy
+        RUNTIME DESTINATION bin)
 
 # install library
 install(TARGETS datetime
diff --git a/doc/tutorial.md b/doc/tutorial.md
index 9fd41be..4ed053e 100644
--- a/doc/tutorial.md
+++ b/doc/tutorial.md
@@ -26,16 +26,27 @@ Installation steps:
 
 * use [cmake](https://cmake.org/) to build the library and executables, e.g. 
 ```
+# Step (1)
 $> cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+# Step (2)
 $> cmake --build build --target all --config Release -- -j4
-# optionally run tests
+# Step (3) optionally run tests
 $> ctest --test-dir build
-## Install, system-wide (needs root)
+## Step (4) Install, system-wide (needs root)
 $> cd build && sudo make install
 ```
 
 ### Compilation Options
 
+#### Skip Building Test (Recommended for non-developers)
+
+By default, when building the source code a series of test programs 
+will be build. To circumvent this, you can use the `-DBUILD_TESTING=OFF` 
+option in Step (1); i.e. change Step (1) to:
+```
+$> cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF
+```
+
 #### `ALLOW_DT_INTEGRAL_MATH`
 
 This option will allow (some) selected operations between DateTime fundamental 
@@ -46,9 +57,12 @@ mjd += 1;
 // Now mjd's internal member, will have a value of 124.
 ```
 
+By default, this option is not allowed to preserve type-safety.
+
 #### Build in DEBUG mode
 
-You can easily change to building the DEBUG version, e.g.
+You can easily change to building the DEBUG version, e.g. changing 
+Steps (1) and (2) to:
 ```
 $> cmake -S . -B build -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug
 $> cmake --build build --target all --config Debug -- -j4
@@ -130,6 +144,72 @@ handled-specially-(see-[Epochs-in-Continuous-Time-Scales-aka-UTC](#epochs-in-con
 > [!CAUTION]
 > **Latest leap second considered in datetime library occured at: 2017/01/01**
 
+## Executables 
+
+Along with the library, the project builds by default a small set of executables/programs that 
+perform fundamental date transformations. These are:
+* ymd2mjd
+* mjd2ymd
+* mjd2ydoy
+
+They came with help, which can be triggered by the `-h` switch (e.g. `$> ymd2mjd -h`), listing 
+options and usage instructions. They all except input from STDIN and write results to 
+STDOUT, so you can [pipe](https://en.wikipedia.org/wiki/Pipeline_(Unix)) results and input. 
+
+By default, the programs will be installed at `/usr/local/bin` on Linux systems.
+
+The following examples should be self explanatory:
+
+```
+$> cat dates
+2014:01:09
+2014:01:9
+2014:1:09
+2014:01:08
+2014:01:07
+2014:01:0
+2014:01:1
+2014T01:1
+2014TT01:1
+2014:01:1with some string
+2014/01/1with some string
+$> cat dates | ymd2mjd
+56666
+56666
+56666
+56665
+56664
+ERROR. Failed parsing/transforming line: 2014:01:0
+56658
+56658
+ERROR. Failed parsing/transforming line: 2014TT01:1
+56658
+56658
+$> cat dates | ymd2mjd | mjd2ymd
+ERROR. Failed parsing/transforming line: 2014:01:0
+ERROR. Failed parsing/transforming line: 2014TT01:1
+2014/01/09
+2014/01/09
+2014/01/09
+2014/01/08
+2014/01/07
+2014/01/01
+2014/01/01
+2014/01/01
+2014/01/01
+$> cat dates | ymd2mjd | mjd2ydoy 
+ERROR. Failed parsing/transforming line: 2014:01:0
+ERROR. Failed parsing/transforming line: 2014TT01:1
+2014/009
+2014/009
+2014/009
+2014/008
+2014/007
+2014/001
+2014/001
+2014/001
+2014/001
+```
 
 ## For Developers