Clean up semver() docstring

src/include/facts.sh

 
 semver() {
     #
-    # Build semver version string with build metadata
+    # Build proper SemVer version string
     #
     # Build version string from available info using following
     # logic:
     #
     # Examples:
     #
-    #     myprog v1.0.7                         # all clear
-    #     myprog v1.0.7-alpha                   # mkit.ini: project:prerl="alpha"
-    #     myprog v1.0.7-alpha+g1aef811.master   # ^^ + some commits after
-    #     myprog v1.0.7-alpha+gf14fc4f.api2     # ^^ + on a feature branch
-    #     myprog v1.0.7-alpha+gf14fc4f.api2.dirty  # ^^ + tree edited
-    #     myprog v1.0.7-alpha+dirty             # tag OK but tree edited
-    #     myprog v1.0.7+dirty                   # ^^ but no pre-release id
+    #     foo v1.0.7                            # all clear; proper release
+    #     foo v1.0.7-beta                       # mkit.ini: project:prerl="beta"
+    #     foo v1.0.7-beta+g1aef811.master       # ^^ + some commits after
+    #     foo v1.0.7-beta+gf14fc4f.api2         # ^^ + on a feature branch
+    #     foo v1.0.7-beta+gf14fc4f.api2.dirty   # ^^ + tree edited
+    #     foo v1.0.7-beta+dirty                 # tag OK but tree edited
+    #     foo v1.0.7+dirty                      # ^^ but no pre-release id
     #
     # Note that versions with "dirty" should be perceived as kind of
     # dangerous outside developer's own machine.  Versions with sha1 are
     # safer but must not be released.
     #
-    # I have considered decorating the git commit refs to make them
-    # sort of sortable (e.g. "r1.g1aef811"), but on second thought,
-    # I don't think it's good idea to give *any* semantics to meta-data
-    # at all.  First, there is no rule that r1<r2<r3; a commit can be
-    # removing what other just added and one change can be split to
-    # multiple commits.  Also, the whole thing breaks anyway once you
-    # rebase your branch (no, it's not a sin).  The sole purpose of
-    # meta-data is to *identify* the code, and provide safe path back
-    # to tree; commit refs are already perfect for that.
-    #
     # FIXME:  Using project:prerl for release IDs may not be compatible with
     #         release strategy implemented in release.sh
     #
     local xyz           # base version string
-    local prerl         # pre-release keyword (from mkit.ini, eg. 'alpha')
+    local prerl         # pre-release keyword (from mkit.ini, eg. 'beta')
     local latest_tag    # latest git tag
     local commit        # commit indicator (CURRENT_BRANCH.gHASH)
     local dirty         # 0 if dirty, 1 if clean