* add usage to README.md (and improve some text at the same time)

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ jobs:
         os: [ ubuntu-latest, macos-latest ]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
     - name: Test
       run: |

README.md

@@ -8,7 +8,7 @@ tested on **Debian**, **FreeBSD**, **macOS**, **Manjaro**, **MinGW**,
 
 | Release Version                                       | Release Notes
 |-------------------------------------------------------|--------------
-| ![Mulle kybernetiK tag](https://img.shields.io/github/tag/mulle-nat/mulle-bashfunctions.svg?branch=release) [![Build Status](https://github.com/mulle-nat/mulle-bashfunctions/workflows/CI/badge.svg?branch=release)](//github.com/mulle-nat/mulle-bashfunctions/actions)| [RELEASENOTES](RELEASENOTES.md) |
+| ![Mulle kybernetiK tag](https://img.shields.io/github/tag/mulle-nat/mulle-bashfunctions.svg?branch=release) [![Build Status](https://github.com/mulle-nat/mulle-bashfunctions/workflows/CI/badge.svg?branch=release)](//github.com/mulle-nat/mulle-bashfunctions/actions) | [RELEASENOTES](RELEASENOTES.md) |
 
 ## Executables
 
@@ -20,7 +20,48 @@ tested on **Debian**, **FreeBSD**, **macOS**, **Manjaro**, **MinGW**,
 
 ## API
 
-With `mulle-bashfunction.sh` preloaded you have access to a basic selection
+Use mulle-bashfunctions for discovery and documentation about itself.
+
+You can list all the functions in **mulle-bashfunctions** like
+this:
+
+``` sh
+for i in `mulle-bashfunctions libraries`
+do
+    echo "### $i"
+    mulle-bashfunctions functions "$i"
+    echo
+done
+```
+
+but you can also use `apropos` to discover functionality:
+
+``` sh
+mulle-bashfunctions apropos uppercase
+```
+
+Once you have found a function of interest, you can checkout its description
+with
+
+
+``` sh
+mulle-bashfunctions man r_uppercase
+```
+and try it out with `eval` for functions printing to standard output,
+or `r-eval`, for functions that return values in the `RVAL` global variable
+(these functionss are prefixed with `r_`):
+
+
+``` sh
+$ mulle-bashfunctions r-eval r_uppercase xyz
+XYZ
+```
+
+
+### Libraries
+
+Your script running under `#! /usr/bin/env mulle-bash` will have
+`mulle-bashfunction.sh` preloaded. So you have access to a basic selection
 of libraries, namely:
 
 
@@ -36,7 +77,7 @@ of libraries, namely:
 
 
 Use `include "<name>"` to get access to the functions not included in
-`mulle-bashfunctions.sh` (but in `mulle-bashfunctions-all.sh`), namely:
+`mulle-bashfunctions.sh` namely:
 
 | Name                              | Descriptions                                                    |
 |-----------------------------------|-----------------------------------------------------------------|
@@ -48,6 +89,77 @@ Use `include "<name>"` to get access to the functions not included in
 | [version](src/mulle-version.sh)   | semver version management major.minor.version                   |
 
 
+### Example
+
+This example loads some additional functionality into a mulle-bashfunctions
+script and executes it:
+
+
+``` sh
+#! /usr/bin/env mulle-bash
+
+
+include "case"
+
+r_smart_downcase_identifier "${1:-EO.Foundation}"
+printf "%s\n" "${RVAL}"
+```
+
+
+## Usage
+
+```
+Usage:
+   mulle-bashfunctions [command]
+
+   mulle-bashfunctions main purpose is to help load the library functions
+   into an interactive shell. The library functions are almalgamated in a
+   file called "mulle-bashfunctions.sh". There are variants though (none,
+   minimal, all) with different sizes.
+
+   But mulle-bashfunctions can also
+
+   * embed "mulle-bashfunctions.sh" into another shell script
+   * show the path to "mulle-bashfunctions.sh"
+   * locate the "mulle-bashfunctions.sh" install path for a desired variant
+   * show documentation for any of the defined functions
+   * list the available libraries, which you can "include"
+   * run an arbitrary mulle-bashfunction with eval and r-eval
+
+Examples:
+   Load "mulle-bashfunctions-all.sh" into the current interactive shell:
+
+      eval `mulle-bashfunctions load all`
+
+Commands:
+   apropos <f>    : search for a function by keywords
+   embed          : embed mulle-bashfunctions into a script
+   env            : environment needed for "mulle-bashfunctions.sh"
+   eval <cmd>     : evaluate cmd inside of mulle-bashfunctions
+   functions      : list defined functions
+   hostname       : show system hostname used by mulle-bashfunctions
+   libraries      : list available libraries
+   load [variant] : use  eval `mulle-bashfunctions load`  to load
+   man <function> : show documention for function, if available
+   path [variant] : path to "mulle-bashfunctions.sh"
+   r-eval <cmd>   : evaluate cmd inside of mulle-bashfunctions and print RVAL
+   username       : show username used by mulle-bashfunctions
+   uname          : show system short name used by mulle-bashfunctions
+   version        : print currently used version
+   versions       : list installed versions
+
+```
+
+
+
+### How to write single-file mulle-bash scripts
+
+1. Say `mulle-sde add my-script.sh` to create a mulle-bash script skeleton.
+2. ... actually write the script ...
+3. Say `mulle-bashfunction embed < my-script-sh` to create a standalone script.
+
+The resulting script will run with `#! /bin/sh` and does not need a
+mulle-bashfunctions installation.
 
 
 ### Runtime environment
@@ -60,21 +172,22 @@ and `setopt POSIX_ARGZERO` and will also `set -o GLOB_SUBST`.
 * `expand_aliases` is set and required for use of the `.for .do .done` macros.
 * `-u` or `+u` should work
 * `-e` will not work (!)
+* `posix` is turned off
 
 Glob settings are unaffected and expected to be enabled by default.
 
 ### Conventions
 
 `RVAL` is a global variable. It is used to pass return values from functions.
 The RVAL value can be clobbered by **any** function. Functions that return RVAL
-are prefixed with `r_` or `_r_` or somesuch. Functions that return multiple
+are prefixed with `r_` or `_r_` or some such. Functions that return multiple
 values are currently prefixed with `__`. This may change to `g_` in the
 future.
 
 
 ### Develop
 
-Do not edit the almagamated `mulle-bashfunctions*.sh` files, they are generated
+Do not edit the amalgamated `mulle-bashfunctions*.sh` files, they are generated
 by running `cmake .` in the project directory.
 Check out the small pamphlet [Modern Bash (Zsh) Scripting](https://www.mulle-kybernetik.com/modern-bash-scripting)
 by yours truly, for some background information on the techniques being used.
@@ -85,6 +198,7 @@ by yours truly, for some background information on the techniques being used.
 
 
 
+
 ## Install
 
 The command to install the latest mulle-bashfunctions into `/usr/local` (with **sudo**) is:

RELEASENOTES.md

@@ -1,3 +1,7 @@
+### 6.2.4
+
+* add usage to README.md (and improve some text at the same time)
+
 ### 6.2.3
 
 * fix `MULLE_BASH_EXE_SHELL` not being honored (any more ?)

cola/api.md.bud

@@ -1,6 +1,47 @@
 ## API
 
-With `mulle-bashfunction.sh` preloaded you have access to a basic selection
+Use mulle-bashfunctions for discovery and documentation about itself.
+
+You can list all the functions in **mulle-bashfunctions** like
+this:
+
+``` sh
+for i in `mulle-bashfunctions libraries`
+do
+    echo "### $i"
+    mulle-bashfunctions functions "$i"
+    echo
+done
+```
+
+but you can also use `apropos` to discover functionality:
+
+``` sh
+mulle-bashfunctions apropos uppercase
+```
+
+Once you have found a function of interest, you can checkout its description
+with
+
+
+``` sh
+mulle-bashfunctions man r_uppercase
+```
+and try it out with `eval` for functions printing to standard output,
+or `r-eval`, for functions that return values in the `RVAL` global variable
+(these functionss are prefixed with `r_`):
+
+
+``` sh
+$ mulle-bashfunctions r-eval r_uppercase xyz
+XYZ
+```
+
+
+### Libraries
+
+Your script running under `#! /usr/bin/env mulle-bash` will have
+`mulle-bashfunction.sh` preloaded. So you have access to a basic selection
 of libraries, namely:
 
 
@@ -16,7 +57,7 @@ of libraries, namely:
 
 
 Use `include "<name>"` to get access to the functions not included in
-`mulle-bashfunctions.sh` (but in `mulle-bashfunctions-all.sh`), namely:
+`mulle-bashfunctions.sh` namely:
 
 | Name                              | Descriptions                                                    |
 |-----------------------------------|-----------------------------------------------------------------|
@@ -28,3 +69,19 @@ Use `include "<name>"` to get access to the functions not included in
 | [version](src/mulle-version.sh)   | semver version management major.minor.version                   |
 
 
+### Example
+
+This example loads some additional functionality into a mulle-bashfunctions
+script and executes it:
+
+
+``` sh
+#! /usr/bin/env mulle-bash
+
+
+include "case"
+
+r_smart_downcase_identifier "${1:-EO.Foundation}"
+printf "%s\n" "${RVAL}"
+```
+

cola/info.md.bud

@@ -1,12 +1,12 @@
 ### How to write single-file mulle-bash scripts
 
-Use `mulle-sde add my-script.sh` to create a mulle-bash script skeleton. This
-script needs mulle-bashfunctions installed to work.
-Search for desired functionality with `mulle-bashfunctions apropos`. Once your
-script is ready for distribution, say `mulle-bashfunction embed < my-script-sh`.
-Now you have a single script file, that you can copy to any other host/OS that
-has bash or zsh installed, but needs no mulle-bashfunctions installation.
-(Undo with `mulle-bashfunction extract`).
+1. Say `mulle-sde add my-script.sh` to create a mulle-bash script skeleton.
+2. ... actually write the script ...
+3. Say `mulle-bashfunction embed < my-script-sh` to create a standalone script.
+
+The resulting script will run with `#! /bin/sh` and does not need a
+mulle-bashfunctions installation.
+
 
 ### Runtime environment
 

cola/properties.plist

@@ -3,6 +3,7 @@
    {
       showButtons = YES;
       showCodacy = NO;
+      createUsage = YES;
    };
    authors =
    (

cola/usage.md.bud

@@ -0,0 +1,33 @@
+{%
+   haveFile = [exists file:"usage.txt"]
+   usage    = nil
+
+   if not haveFile and config.createUsage
+      pwd        = [[NSFileManager defaultManager] currentDirectoryPath]
+      name       = [pwd lastPathComponent]
+      executable = [pwd stringByAppendingPathComponent:name];
+      cmdline    = [executable stringByAppendingString:" "];
+      cmdline    = [cmdline stringByAppendingString:"help"];
+      taskInfo   = [NSTask mulleStringSystemCallWithCommandString:cmdline]
+      if taskInfo[ "standardErrorString"]
+         usage = taskInfo[ "standardErrorString"]
+      endif
+   endif
+%}
+{% if haveFile or usage %}
+## Usage
+
+{%  if usage %}
+```
+{{ usage }}
+```
+{%  else %}
+```
+{% includes optionally verbatim "usage.txt" %}
+```
+{%  endif %}
+{% else %}
+# No usage
+{% endif %}
+
+

mulle-bash

@@ -149,7 +149,7 @@ fi
 # this is "our" version
 # the actual loaded version may differ (and will change this variable)
 #
-MULLE_BASHFUNCTIONS_VERSION="6.2.3"
+MULLE_BASHFUNCTIONS_VERSION="6.2.4"
 MULLE_BASHFUNCTIONS_LIBEXEC_DIRNAME="libexec"
 MULLE_EXECUTABLE="$1"
 

mulle-bashfunctions

@@ -42,7 +42,7 @@ usage()
 {
    [ ! -z "$*" ] && echo "error: $*" >&2
 
-   cat <<EOF
+   cat <<EOF >&2
 Usage:
    ${MULLE_EXECUTABLE_NAME} [command]
 

src/mulle-bashfunctions-all.sh

@@ -163,6 +163,7 @@ then
    fi
 fi
 
+
 if ! [ ${MULLE_BASHLOADER_SH+x} ]
 then
    MULLE_BASHLOADER_SH='included'

src/mulle-bashfunctions-minimal.sh

@@ -163,6 +163,7 @@ then
    fi
 fi
 
+
 if ! [ ${MULLE_BASHLOADER_SH+x} ]
 then
    MULLE_BASHLOADER_SH='included'

src/mulle-bashfunctions-none.sh

@@ -163,6 +163,7 @@ then
    fi
 fi
 
+
 if ! [ ${MULLE_BASHLOADER_SH+x} ]
 then
    MULLE_BASHLOADER_SH='included'

src/mulle-bashfunctions.sh

@@ -163,6 +163,7 @@ then
    fi
 fi
 
+
 if ! [ ${MULLE_BASHLOADER_SH+x} ]
 then
    MULLE_BASHLOADER_SH='included'

src/mulle-file.sh

@@ -1029,8 +1029,9 @@ function dir_has_files()
 #
 # dir_list_files <directory> [pattern] [filetypes]
 #
-#    Lists file in <directory> (or directories as <directory> may contain
-#    wildcards) line by line.
+#    Lists file in <directory> line by line.
+#    (<directory> may contain wildcards). Filenames will have the directory
+#    prepended, which maybe absolute or not.
 #    <directory> may contain white space but no tabs. filetypes may be "f" for
 #    files or "d" for directories or "l" for symlinks. It can be a combination
 #    of these filetypes.