#+title: Initialism

* Table Of Contents
:PROPERTIES:
:TOC:      :include all :ignore (this)
:END:
:CONTENTS:
- [[#justification-for-existence][Justification For Existence]]
- [[#key-binding][Key Binding]]
- [[#master-usage][Master Usage]]
- [[#usage][Usage]]
  - [[#building][Building]]
  - [[#reviewing][Reviewing]]
  - [[#inserting][Inserting]]
  - [[#deleting][Deleting]]
  - [[#reflecting][Reflecting]]
  - [[#going-a-lot-faster][Going A Lot Faster]]
- [[#installation][Installation]]
  - [[#traditional][Traditional]]
  - [[#package][Package]]
    - [[#manually][Manually]]
    - [[#automatically][Automatically]]
- [[#is-it-an-initialism-acronym-or-abbreviation][Is It An Initialism, Acronym, or Abbreviation?]]
- [[#definitions][Definitions]]
- [[#frequently-answered-questions][Frequently Answered Questions]]
  - [[#no-end-of-line-support][No End Of Line Support]]
    - [[#position-1][Position 1]]
    - [[#position-2][Position 2]]
  - [[#no-region-processing][No Region Processing]]
  - [[#no-insertion-post-processing-function][No Insertion Post-Processing Function]]
  - [[#other-initialism-creators][Other Initialism Creators]]
  - [[#no-rebus-generation][No Rebus Generation]]
  - [[#this-is-perfect-for-prefix-arguments][This Is Perfect For Prefix Arguments]]
  - [[#it-isnt-named-acronym-or-abbreviate][It Isn't Named Acronym or Abbreviate]]
  - [[#why-not-use-customize][Why not use customize?]]
:END:

* Justification For Existence

*This tool makes memorizing scripts and speeches easier!*

Why struggle with the tedious and error-prone task of creating initialisms for
an entire script by hand? This program does it with impeccable precision for you
every time, allowing you to format the output to your liking. Experience the
ease and convenience for yourself―your brain will love it!

- Before using this program
  - Watch [[https://www.youtube.com/watch?v=Jbe1-oHnR6k][Lauren Tothero]] explain how this technique works

* Key Binding

For easier usage―key bind ~initialism-dispatch~.

~A-b~ is particularly nice to avoid stomping on existing bindings.

Even better: make it available *everywhere*.

Here is how:

#+begin_src emacs-lisp
(global-set-key [(alt b)] #'initialism-dispatch)
(global-set-key [(alt shift ?b)] #'initialism-complete)
#+end_src

Note: consider ~initialism-complete~ a teaser until you dig a little deeper!

* Master Usage

For the truly impatient like myself, this package is already configured for the most common scenario of adding initialisms to list items created by breaking sentences into a sensible number of words. For example, here are some short examples (just imagine I broke up a speech or something). Position your cursor at the ~@~ and start madly stomping away, and watch the initialisms get inserted at the end.

#+begin_src org
- Eventually Munches All Computer Storage (*EMACS*)
- Compact Disc Read Only Memory (*CDROM*)
- National Aeronautics Space Administration (*NASA*)
#+end_src

Read on for an intricate and detailed overview of how this works behind the scenes, building up to a final conclusion about using it quickly within an explanatory context. If you prefer this approach then add this to your configuration first:

#+begin_src elisp
(setopt initialism-auto-complete nil)
#+end_src

* Usage

In this example, create the initialism =EMACS= from the phrase "Eventually
Munches All Computer Storage," following the most frequently used functions in
the typical workflow's order. You can use the dispatcher function to do the work
using prefix arguments or call the functions individually. This example uses
prefix arguments:

- Building it
  - ~initialism-dispatch~: Calls ~initialism-build~
- Reviewing it
  - ~C-u initialism-dispatch~: Calls ~initialism-view~
- Inserting it
  - ~C-u C-u initialism-dispatch~: Calls ~initialism-insert~
- Deleting it
  - ~C-u C-u C-u initialism-dispatch~: Calls ~initialism-delete~

** Building

Start by positioning the Cursor at the start of the first word. Call
~initialism-dispatch~. Notice that the value of the initialism appears in the
Echo Area. The message is prefixed with the model length purely to assist in
understanding the model assembly process: it is NOT part of the underlying model
itself. Then the Cursor moves one step forward. Call ~initialism-dispatch~
again, and the Cursor moves, but nothing appears in the Echo Area. You can't make
an initialism using whitespace characters, so it is ignored. Call
~initialism-dispatch~ noting that the current initialism value is again
displayed in the Echo Area, and the Cursor moves forward, this time with an
additional character appended. Call
~initialism-dispatch~, and the space character is then ignored. As you repeatedly
call ~initialism-dispatch~, you can watch the initialism built until you finally
reach the end of the line, and I don't know how to proceed.

/@ represents the cursor location before calling/ ~initialism-dispatch~

#+begin_src text
@Eventually Munches All Computer Storage
(E)
Eventually @Munches All Computer Storage
(EM)
Eventually Munches @All Computer Storage
(EMA)
Eventually Munches All @Computer Storage
(EMAC)
Eventually Munches All Computer @Storage
(EMACS)
#+end_src

Thank you ~emacs-name~ for the acronym!

** Reviewing

Review the initialism value by calling ~C-u initialism-dispatch~ and observing
the Echo Area.

#+begin_src text
(EMACS)
#+end_src

** Inserting

Insert the initialism value by calling ~C-u C-u initialism-dispatch~.

For convenience, the inserted value is also added to the ~kill-ring~.

#+begin_src text
/@\
/(EMACS)@\
#+end_src

Finally it mimics [[https://en.wikipedia.org/wiki/Carriage_return#Computers][CRLF]] behavior. This is particularly helpful if you are processing a lot of single-line content. For example Org mode list items. You can /disable/ this by using ~(setq-default initialism-crlf nil)~ . You might use this style of processing when you are extracting content from within long sentences.

It's important to understand that the format of the initialism is separate from
the data itself. The actual initialism data, the /Model/, is stored in a private
variable that you won't need to touch. What you see presented from that data,
the /View/, is the result of formatting the /Model/ with the
~initialism-format-string~, which you can modify to your liking.

Consider this example so far.

- The /Model/: EMACS
- The /View/: (EMACS)

Imagine that you want to format the initialism as bold text in LaTeX without
parentheses around it. You can customize it using
~(setq-default initialism-format-string " \\textbf{%s}")~

- The /Model/: EMACS
- The /View/: =\textbf{EMACS}=

** Deleting

Delete the initialism value by calling ~C-u C-u C-u initialism-dispatch~ and
note in the Echo Area the message.

#+begin_src text
(initialism) View deleted.
#+end_src

** Reflecting

This example reflects the typical workflow for building an initialism. Call
~initialism-help~ to review the workflow. If you want to call the individual
functions for each workflow step, you'll also find their names.

Whenever I work, I try to explain what I'm doing in the Echo Area. If something
doesn't work right, start there, and if I failed you, please create a support
ticket.

Now, start creating your next initialism.

** Going A Lot Faster

Now that you've got the hang of it you'll surely move on to longer passages. For
example you could use [[file:Theodore_Roosevelt_MAN_IN_THE_ARENA_SPEECH.org][this speech]].
Indeed, you never sought to create an initialism for one word: you are likely
working on an entire speech or script! Your work will now go something like
this:

- Take the script and read it out loud.
- Note the obvious break points in speaking for example impact or breath.
- Generally, good breaks are at 5-7 words. However, this is not written in stone; it is very natural to find much longer passages. Note them.
- This time read the passage while building the initialism. Note the word count and see what works for your speaking style and speed.
- When you are ready insert the initialism right there in the passage and continue.
- Read the script again and try it out. You'll quickly find that you have some personal preferences developed for how you build your initialism. It also depends on the content itself. Consequently, you'll perform multiple iterations until you figure out what works best for you.
- By now you should have a sense of your development style and built initialisms
  for your script. Additionally, you should notice the massive elephant in the
  living room: once you get fast designing them, the actual build process slows
  you down! Consequently, there is a solution: instead of performing each step
  in the building process individually you can do it all in one fell swoop.

Instead of performing all of the steps individually, which you may think of as
working in "development mode", you can perform them all in one fell swoop using
~initialism-complete~. Nothing revolutionary, but it will speed things up.

Surely now you must be asking yourself "Why didn't you tell me about this
sooner?" Simple answer: you wouldn't have understood how to use the tool in the
first place, let alone speed it up. Remember that first you build initialisms in
your mind, and then you use the tool to facilitate that process.

Finally, have fun with this too flying through the process!

* Installation

** Traditional

Download =initialism.el= into =~/src= and add this to your configuration file:

#+begin_src emacs-lisp
(add-to-list 'load-path "~/src")
(require 'initialism)
#+end_src

** Package
*** Manually

Download =initialism.el=, call ~package-install-file~, and specify that file.

Add ~(require 'initialism)~ to your configuration file.

*** Automatically

Eventually this will get added to [[https://melpa.org/#/][MELPA]].

* Is It An Initialism, Acronym, or Abbreviation?

- What is the difference between an acronym and an initialism?
  - Both acronyms and initialisms are made up of the first letter or letters
    of the words in a phrase. The word /acronym/ typically applies when the
    resulting thing can be read as a word; for example, /radar/ comes from
    "𝙧𝙖dio 𝙙etection 𝙖nd 𝙧anging" and /scuba/ comes from
    "𝙨elf-𝙘ontained 𝙪nderwater 𝙗reathing 𝙖pparatus." The word
    /initialism/ only applies when the resulting thing is read as an
    abbreviation; for example /DIY/, which comes from "𝙙o 𝙞t
    𝙮ourself," is pronounced by saying the names of the letters. Note that
    the word /acronym/ is also sometimes used to mean "initialism."
- What is the difference between an acronym and an abbreviation?
  - An acronym is a kind of abbreviation. Abbreviations can be shortened
    forms of any kind. For example, /appt/ is an abbreviation of
    /appointment/, and /ASAP/ is an abbreviation of 𝙖s 𝙨oon 𝙖s 𝙥ossible.
    /ASAP/, however, also qualifies as an acronym because it is made up of
    the initial letters of the phrase it comes from: 𝙖s 𝙨oon 𝙖s 𝙥ossible.
- Source: "Acronym. (Frequently Asked Questions)" Merriam-Webster.com
  Dictionary, Merriam-Webster,
  https://www.merriam-webster.com/dictionary/acronym. Accessed 19 Apr. 2024.

* Definitions

- initialism :: :an abbreviation formed from initial letters
  - Source: "Initialism." Merriam-Webster.com Dictionary, Merriam-Webster,
    https://www.merriam-webster.com/dictionary/initialism. Accessed 19
    Apr. 2024.
- acronym :: :a word (such as /NATO/, /radar/, or /laser/) formed from the
  initial letter or letters of each of the successive parts or major parts of a
  compound term
  - /also/ :an abbreviation (such as FBI) formed from initial letters:
    initialism
    - Is OK an acronym?
      - /OK/ is technically an acronym. It comes from the phrase "oll korrect," a
        humorous alteration of "all correct."
  - Examples of acronym in a Sentence
    - The North Atlantic Treaty Organization is known by the /acronym/ "NATO."
  - Source: "Acronym." Merriam-Webster.com Dictionary, Merriam-Webster,
    https://www.merriam-webster.com/dictionary/acronym. Accessed 19 Apr. 2024.
- abbreviation :: :a shortened form of a written word or phrase used in place of
  the whole word or phrase
  - "Amt" is an /abbreviation/ for "amount."
  - "USA" is an /abbreviation/ of "United States of America."
  - Did you know?
    - What's the difference between an /abbreviation/ and an /acronym/?
      - Some people are unsure of whether to call /ASAP/ or /appt/ abbreviations or
        acronyms. Both /abbreviation/ and /acronym/ are used to refer to a shortened
        form, but an acronym is a shortened form of a phrase and is usually made
        up of the initial letters of that phrase. For example, /NATO/ comes from
        "North Atlantic Treaty Organization," and /ASAP/ comes from "as soon as
        possible." Abbreviations, on the other hand, can be shortened forms of
        words or phrases, and need not necessarily be made up of the initial
        letters of either. /ASAP/ and /appt/ (for /appointment/) are both considered
        abbreviations, but only /ASAP/ is an acronym. Acronyms are a type of
        abbreviation.
  - Source: "Abbreviation." Merriam-Webster.com Dictionary, Merriam-Webster,
    https://www.merriam-webster.com/dictionary/abbreviation. Accessed 19
    Apr. 2024.

* Frequently Answered Questions
*** No End Of Line Support
**** Position 1

Indeed, now you must ask yourself, "But why can't you handle the end-of-line
character, my dear system?" The answer is simple: it makes it easy for you to
create initialism starting from wherever you like, skipping lines, paragraphs,
or whatever you wish; there are no limits on the source and sequencing of your
initialism. Therefore, I assume nothing beyond the fact that building the
initialism using only the [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Char-Classes.html#Char-Classes][Character Classes]] =[[:alnum:]]= and =[[:punct:]]=

**** Position 2

This idea initially lacked evidence, but after using it, I've found that breaking content into list items is the easiest way to develop initialisms. Using this tool can be tedious due to the need to frequently navigate back to the start of the next line (i.e., CRLF behavior). Evidence suggests adding a feature to address this issue, yet the original style remains valid and continues to function as intended.

Thus, =initialism= upholds a standard behavior by managing specified character types while allowing for precise individual actions. This feature remains unchanged. The =CRLF= behavior was introduced as a helpful addition, giving us an effective solution that combines both methods.

*** No Region Processing

It might sound like a good idea to support processing a marked region. However,
that goes against the workflow of iteratively creating the initialism. Once in a
while, your words will work /perfectly/ for an enormous amount of text, but that
is rare enough to omit the feature.

*** No Insertion Post-Processing Function

Suppose you always want to process the Model with a post-processing every time
you insert it into the buffer. Providing a "default customizable function to
handle insertion" might make sense. For example, you could configure it to split
the Model into separate boxes in LaTeX. However, if you already know how to
perform this step using your function, it doesn't add much value using a
configurable function in addition to that.

*** Other Initialism Creators

Since every acronym is an initialism, you will [[https://duckduckgo.com/?q=acronym+generator][find many]]. However, I've yet to
find an interactive app like this one. Understandably, though, this is a
specialized approach.

That said, the [[https://www.dcode.fr/about][dCode]] application is entertaining.

*** No Rebus Generation

This application does not generate rebuses.

- rebus :: : a representation of words or syllables by pictures of objects or by
  symbols whose names resemble the intended words or syllables in sound
  - /also/ : a riddle made up of such pictures or symbols
  - Did you know?
    - /Rebus/ and a Lack of Words
      - A rebus communicates its message by means of pictures or symbols whose
        names sound like various parts of a word, phrase, or sentence. For
        example, a picture of a can of tomatoes followed by the letters UC and a
        picture of a well means "Can you see well?" In Latin, the word /rebus/
        means "by things"; /rebus/ is a form of the Latin word /res/, which means
        "thing." English speakers started using the word /rebus/ for picture
        writing in the early 1600s.
  - Source: "Rebus" Merriam-Webster.com Dictionary, Merriam-Webster,
    https://www.merriam-webster.com/dictionary/rebus. Accessed 17 May. 2024.

While interesting, they are generally unrelated to the goals of this project.

*** This Is Perfect For Prefix Arguments

~initialism-dispatch~ delegates work to four other functions (see above). Why
not bind keys to each of them instead? You can and should: it is all personal
preference.

Given the workflow above, the four steps of building an initialism prefix
arguments feel like a natural approach. Specifically, when you follow the
workflow, you are /already/ taking "breaks" between the steps. Creating them
doesn't require lightning; it makes the task harder. Consequently, prefix
arguments get you back into the mindset of making it easy to develop
initialisms.

One idea for the future is switching over the interface to use a Hydra. They are easy for the user, easy to implement and maintain, and a great looking UI.

*** It Isn't Named Acronym or Abbreviate

Shouldn't it be named Acronym or abbreviated? No, neither should be.

Every /acronym/ is an /initialism/, but not vice versa. You must design the
words of the /acronym/ yourself and then use this library to create it. This library doesn't help you choose those words.

An /abbreviation/ is a shortened or contracted phrase. It might be an
/initialism/, an/acronym/, or more. This library doesn't help you figure out how to build the last two.

Consequently, it /should/ be named Initialism.

*** Why not use ~customize~?

~customize~ is great when it is great and fiddly when it is fiddly.

In this utility it will be greater without it.