branch: externals/denote-sequence
commit 1f282a28229b9f62b1048b66c50a14c125cd70d0
Author: Protesilaos Stavrou <[email protected]>
Commit: Protesilaos Stavrou <[email protected]>
Expand the manual about the alphanumeric-delimited scheme
---
README.org | 62 ++++++++++++++++++++++++++++++++++++++------------------------
1 file changed, 38 insertions(+), 24 deletions(-)
diff --git a/README.org b/README.org
index 67c5033aaa..e203cf3bd3 100644
--- a/README.org
+++ b/README.org
@@ -106,37 +106,51 @@ manually. The purpose of this extension is to streamline
this work.
:CUSTOM_ID: h:select-a-sequencing-scheme-for-denote-sequence-scheme
:END:
+[ The =alphanumeric-delimited= scheme is part of {{{development-version}}}. ]
+
#+vindex: denote-sequence-scheme
-The user option ~denote-sequence-scheme~ allows users to select either
-the =numeric= scheme, which is like ~1=1=2~ or the =alphanumeric=
-scheme, which is =1a2= for the same sequence
([[#h:convert-from-one-sequencing-scheme-to-another][Convert from one
sequencing scheme to another]]):
-
-- Numeric sequencing scheme :: A numeric sequence consists only of
- numbers. The level of depth is derived from the number of fields in
- the sequence, separated by the equals sign. Thus, the sequence
- ~1=1=2~ consists of three levels of depth. For deeper sequences, the
- numeric scheme will get longer, which some users may consider
- unwieldy. The upside, however, is that is easier to reason about
- larger numbers, such as ~1=100=2=50~.
-
-- Alphanumeric sequencing scheme :: An alphanumeric sequence combines
- numbers and letters. The level of depth is undestand by the
- alteration from numbers to letters and vice versa. As such, the
- sequence =1a2= has three levels of depth. This scheme is more
- compact, which users may like but can be harder to reason about
- large numbers, such as =1zzzv2zx= corresponding to the numeric
- ~1=100=2=50~ (this is because the number 26 is z, 27 is za, 52 is
- zz, and so on). In practice, large numbers may not be a problem,
- though this is something to keep in mind.
-
-*** Convert from one sequencing scheme to another
+The user option ~denote-sequence-scheme~ allows users to select among
+the =numeric=, =alphanumeric=, and =alphanumeric-delimited= schemes,
+as a symbol.
+
+All schemes are mutually convertable
([[#h:convert-from-one-sequencing-scheme-to-another][Convert from one sequence
scheme to another]]).
+
+- =numeric= :: A numeric sequence consists only of numbers. The level
+ of depth is derived from the number of fields in the sequence,
+ separated by the equals sign. Thus, the sequence ~1=1=2~ consists of
+ three levels of depth. For deeper sequences, the numeric scheme will
+ get longer, which some users may consider unwieldy. The upside,
+ however, is that is easier to reason about large numbers, such as
+ ~1=100=2=50~.
+
+- =alphanumeric= :: An alphanumeric sequence combines numbers and
+ letters. The level of depth is communicated by the alteration from
+ numbers to letters and vice versa. As such, the sequence =1a2= has
+ three levels of depth. This scheme is more compact, which users may
+ like but can be harder to reason about large numbers, such as
+ =1zzzv2zx= corresponding to the numeric ~1=100=2=50~ (this is
+ because the number 26 is z, 27 is za, 52 is zz, and so on). In
+ practice, large numbers may not be a problem, though this is
+ something to keep in mind.
+
+- =alphanumeric-delimited= :: The alphanumeric delimited scheme is
+ like the aforementioned alphanumeric scheme except for the fact that
+ it adds the equals sign as a delimiter. The delimiter is placed
+ after the first level of depth and then after every third level of
+ depth. For example: ~1=a2b=a1c~. Note that this is about levels of
+ depth, not triplets, so ~1=zx1zza=1~ is valid because =zx= is one
+ level of depth as is =zza=, as noted above. The =alphanumeric-delimited=
+ scheme is optimal for those who prefer the alphanumeric notation and
+ want to make very long sequences easier to read.
+
+*** Convert from one sequence scheme to another
:PROPERTIES:
:CUSTOM_ID: h:convert-from-one-sequencing-scheme-to-another
:END:
#+findex: denote-sequence-convert
The command ~denote-sequence-convert~ makes it easy to switch from one
-~denote-sequence-scheme~ to another
([[#h:select-a-sequencing-scheme-for-denote-sequence-scheme][Select a
sequencing scheme for ~denote-sequence-scheme~]]).
+~denote-sequence-scheme~ to another
([[#h:select-a-sequencing-scheme-for-denote-sequence-scheme][Select a sequence
scheme for ~denote-sequence-scheme~]]).
This command has a "do what I mean behaviour" with regard to which
file or files it should operate on:
