commitid.scad.pl: Clearer docs

diff --git a/commitid.scad.pl b/commitid.scad.pl
index 9a7667dc82c9b4f1339451522e11bb6b0dc60529..ebdbe917a39a6cb73db24da322d83a22e85af045 100755 (executable)
--- a/commitid.scad.pl
+++ b/commitid.scad.pl
@@ -52,6 +52,12 @@ $SIG{__WARN__} = sub { die @_; };
 #
 # We can generate these forms:
 #
 #
 # We can generate these forms:
 #

+#  In each case:
+#    if tree is dirty, * is suffixed or prefixed to count or commitid
+#    if tree has untracked files, + is added
+#    (where it is added depends on the Form; in any case it does not
+#    change the size, but steals space from digits)
+#

 #   Small3:
 #   Small4:
 #   Small5:
 #   Small3:
 #   Small4:
 #   Small5:


@@ -63,19 +69,18 @@ $SIG{__WARN__} = sub { die @_; };
 #       git rev-list --first-parent --count HEAD
 #       typically 3-4 characters but we allow for up to 6
 #       padded with zeroes; if too long we reduce mod 10^n
 #       git rev-list --first-parent --count HEAD
 #       typically 3-4 characters but we allow for up to 6
 #       padded with zeroes; if too long we reduce mod 10^n

-#       eg
-#            Small4    1070
-#       If tree is dirty, + or * is suffixed, reducing number of
-#       digits by 1.
+#       eg if the count is 123456
+#            Small5    3456*
+#            Small8    __123456    (where _ are spaces)

 #
 #   Small4S:
 #   Small6S:   Small6T:
 #   Small8S:   Small9T:
 #   Small10S:
 #       same but split into two lines (S) or three lines (T) eg
 #
 #   Small4S:
 #   Small6S:   Small6T:
 #   Small8S:   Small9T:
 #   Small10S:
 #       same but split into two lines (S) or three lines (T) eg

-#            Small4S  10     Small6t    1
-#                     70               07
-#                                      0*
+#            Small4S  45     Small6T   _3
+#                     6*               45
+#                                      6*

 #
 #   Git4   Git4S
 #   Git6   Git6S   Git6T
 #
 #   Git4   Git4S
 #   Git6   Git6S   Git6T


@@ -83,10 +88,8 @@ $SIG{__WARN__} = sub { die @_; };
 #   Git9           Git9T
 #   Git10  Git10S
 #       git-rev-parse HEAD   (prefix of requested length)
 #   Git9           Git9T
 #   Git10  Git10S
 #       git-rev-parse HEAD   (prefix of requested length)

-#       eg
-#            Git6    82f2a2
-#       If tree is dirty, + or * is suffixed to commitid,
-#       reducing number of hex digits by 1.
+#       eg if the commitid is abcdef0123...
+#            Git5    abcd*

 
 #   Full3
 #   Full4
 
 #   Full3
 #   Full4


@@ -99,17 +102,18 @@ $SIG{__WARN__} = sub { die @_; };
 #       git-rev-list --first-parent --count HEAD
 #       git-rev-parse HEAD
 #       eg
 #       git-rev-list --first-parent --count HEAD
 #       git-rev-parse HEAD
 #       eg

-#            Full6    82f2a2
-#                       1070
-#       If tree is dirty, + or * is suffixed to count (but not to
-#       commitid) reducing number of digits by 1.
+#            Full6    abcdef       Full8     abcdef01
+#                     23456*                 _123456*

 #
 #   Full6T
 #   Full9T
 #   Full12T
 #   Full15T
 #
 #   Full6T
 #   Full9T
 #   Full12T
 #   Full15T

-#       As Full but commit is split over two lines for a 3-line message;
-#       dirty marker is in commitid.
+#       as Full but commit is split over two lines
+#       for a 3-line message; eg
+#             Full9T    abc
+#                       de*
+#                       456

 #
 #   FontDemo
 #
 #
 #   FontDemo
 #