improve dox a bit

add dedication
add -v option

Author: mulle-nat

README.md

@@ -2,19 +2,66 @@
 
 #### ➿ mulle-c-string-escape turns data into C-strings
 
-It will escape non-ASCII characters to hex or octal, and use C-escapes for the
-known C escapes. It will separate the output into lines not longer than
-80 charactes.
+Non-ASCII characters will be escaped to hex or octal. C-escapes are used for
+known C escapes like '\b'. The output is separated into lines of approximately
+even length and does not exceed the chosen line length. An example output
+is [usage.inc](src/usage.inc)
+You can feed it binary or text files.
 
-You can easily `#include` the output, or just copy/paste it.
+You can then easily `#include` the output as string contents, or copy/paste it
+into your C program like so:
 
-Reads from standard input and writes to standard output. You can also use
-it on binary files.
+```
+static char  text[] =
+#include "data.inc"
+;
+```
+
+> #### Note
+>
+> C will append a "\0" to strings!
+
+See the [usage.txt](src/usage.txt) for options.
+
+## Example
+
+Use mulle-c-string-escape to create a string representation of itself. We use
+`cmake` here instead of `mulle-sde craft --release` here too ease the fear
+of the unkown:
+
+```
+mkdir -p kitchen/Release
+cmake -B kitchen/Release -DCMAKE_BUILD_TYPE=Release
+cmake --build kitchen/Release
+./kitchen/Release/mulle-c-string-escape \
+   ./kitchen/Release/mulle-c-string-escape \
+   x.inc
+```
 
-So use it with redirection like:
+To verify that this has actually worked:
 
-```console
-mulle-c-string-escape < mytext.txt
+```
+cat <<EOF > x.c
+#include <stdio.h>
+
+
+static char  text[] = "" // useful in case x.inc can be empty
+#include "x.inc"
+;
+
+int  main( int argc, char *argv[])
+{
+   FILE   *fp;
+
+   fp = fopen( "verify.exe", "wb");
+   fwrite( text, sizeof( text) - 1, 1, fp); // -1 because C appends a \0
+   return( fclose( fp));
+}
+EOF
+
+cc -o x x.c
+./x
+diff verify.exe ./kitchen/Release/mulle-c-string-escape
 ```
 
 ## Build
@@ -27,3 +74,7 @@ To fetch and build everything say:
 ```
 mulle-sde craft
 ```
+
+## Dedication
+
+This little tool is dedicated to the memory of Oliver Mondry (mondry@me.com)

src/Makefile-usage

@@ -4,5 +4,5 @@ COMPILE=../kitchen/Debug/mulle-c-string-escape
 
 
 usage.inc:	usage.txt Makefile-usage
-	$(COMPILE) -0 -e -l 120  < $< > $@
+	$(COMPILE) -0 -e -l 120 $< $@
 

src/main.c

@@ -1,3 +1,37 @@
+//
+//  main.c
+//  mulle-c-string-escape
+//
+//  Created by Nat! on 03.11.21
+//  Copyright © 2021 Mulle kybernetiK. All rights reserved.
+//  Copyright (C) 2021 Nat!, Mulle kybernetiK.
+//
+//  Redistribution and use in source and binary forms, with or without
+//  modification, are permitted provided that the following conditions are met:
+//
+//  Redistributions of source code must retain the above copyright notice, this
+//  list of conditions and the following disclaimer.
+//
+//  Redistributions in binary form must reproduce the above copyright notice,
+//  this list of conditions and the following disclaimer in the documentation
+//  and/or other materials provided with the distribution.
+//
+//  Neither the name of Mulle kybernetiK nor the names of its contributors
+//  may be used to endorse or promote products derived from this software
+//  without specific prior written permission.
+//
+//  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+//  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+//  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+//  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+//  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+//  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+//  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+//  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+//  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+//  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+//  POSSIBILITY OF SUCH DAMAGE.
+//
 #include "include-private.h"
 
 #include <stdio.h>
@@ -14,7 +48,7 @@ static void   usage( void)
    printf( "%s", "" // keep ""
 #include "usage.inc"
          );
-   exit( 0);
+   exit( 1);
 }
 
 static inline size_t   calc_emit_buf_size( size_t prefix_length,
@@ -361,6 +395,13 @@ int  main( int argc, char *argv[])
                usage();
             continue;
 
+         case 'v' :
+            printf( "mulle-c-string-escape %u.%u.%u\n",
+                              mulle_c_string_escape_get_version_major(),
+                              mulle_c_string_escape_get_version_minor(),
+                              mulle_c_string_escape_get_version_patch());
+            exit( 0);
+
          default:
             usage();
          }

src/mulle-c-string-escape-version.h

@@ -4,7 +4,7 @@
 /*
  *  version:  major, minor, patch
  */
-#define MULLE_C_STRING_ESCAPE_VERSION  ((0 << 20) | (7 << 8) | 56)
+#define MULLE_C_STRING_ESCAPE_VERSION  ((1 << 20) | (0 << 8) | 0)
 
 
 static inline unsigned int   mulle_c_string_escape_get_version_major( void)

src/usage.inc

@@ -3,23 +3,32 @@
 "\n"
 "\xe2\x9e\xbf mulle-c-string-escape turns data into C-strings\n"
 "\n"
-"It will escape non-ASCII characters to hex or octal, and use C-escapes for the\n"
-"known C escapes. It will separate the output into lines so they should fit\n"
-"a visually pleasing line length.\n"
+"Non-ASCII characters will be escaped to hex or octal. C-escapes are used for\n"
+"known C escapes like '\\b'. The output is separated into lines of approximately\n"
+"even length and does not exceed the chosen line length.\n"
+"You can feed it binary or text files.\n"
 "\n"
-"You can easily `#include` the output, or just copy/paste it.\n"
+"You can then easily `#include` the output, or copy/paste it into your\n"
+"C program like so:\n"
 "\n"
-"Reads from standard input and writes to standard output. You can also use\n"
-"it on binary files.\n"
+"   static char  data[] =\n"
+"   #include \"data.inc\"\n"
+"   ;\n"
+"   #define s_data  (sizeof( data) - 1)\n"
 "\n"
 "Example:\n"
 "\tmulle-c-string-escape -0 -l 120 < mytext.txt\n"
 "\n"
 "Options:\n"
 "\t-[01234] : zero to four space prefix (TAB)\n"
-"\t-h       : help\n"
+"\t-h       : this help\n"
 "\t-e       : escape TAB characters\n"
 "\t-l <n>   : targetted line length (80)\n"
 "\t-n       : don't create a new line for linefeeds in text\n"
 "\t-p <s>   : use a custom prefix instead of spaces or TAB\n"
 "\t-t <s>   : visual size of TAB in text (8)\n"
+"   -v       : print version information and exit\n"
+"\n"
+"Dedication:\n"
+"   This little tool is dedicated to the memory of Oliver Mondry (mondry@me.com)\n"
+"\n"

src/usage.txt

@@ -3,23 +3,32 @@ Usage:
 
 ➿ mulle-c-string-escape turns data into C-strings
 
-It will escape non-ASCII characters to hex or octal, and use C-escapes for the
-known C escapes. It will separate the output into lines so they should fit
-a visually pleasing line length.
+Non-ASCII characters will be escaped to hex or octal. C-escapes are used for
+known C escapes like '\b'. The output is separated into lines of approximately
+even length and does not exceed the chosen line length.
+You can feed it binary or text files.
 
-You can easily `#include` the output, or just copy/paste it.
+You can then easily `#include` the output, or copy/paste it into your
+C program like so:
 
-Reads from standard input and writes to standard output. You can also use
-it on binary files.
+   static char  data[] =
+   #include "data.inc"
+   ;
+   #define s_data  (sizeof( data) - 1)
 
 Example:
 	mulle-c-string-escape -0 -l 120 < mytext.txt
 
 Options:
 	-[01234] : zero to four space prefix (TAB)
-	-h       : help
+	-h       : this help
 	-e       : escape TAB characters
 	-l <n>   : targetted line length (80)
 	-n       : don't create a new line for linefeeds in text
 	-p <s>   : use a custom prefix instead of spaces or TAB
 	-t <s>   : visual size of TAB in text (8)
+   -v       : print version information and exit
+
+Dedication:
+   This little tool is dedicated to the memory of Oliver Mondry (mondry@me.com)
+