Readme improvements

[greenfork]

Hi, I have read several blog posts about this package and watched several videos and I still have hard time understanding what this package does. There were several good pieces of advice on reddit which are mostly related to blog posts. I'd like to help making this readme more understandable by providing some observations I have.

1. The word "story" is over-used. It is used in BDD, Storybook and probably in more places. The common thing I find across all of them is that the word "story" is a bad analogy for technical people which makes it hard to understand what it really does, but apparently it is a very easy to grasp analogy for non-technical people who don't need to understand what it really is. Current readme seems to use this word in a similar fashion "You have a story in mind", with an example story “Given a code buffer, I want to see duplicated code because I copy-pasted a lot and I want to cleanup.”. If we were to give a definition of this sample "story", I would say it is "What I want to do" + "What I need to have already" or in technical terms function + precondition. Immediate solution might be to remove the word "story" and describe it without any analogies, just say what it really is.
2. I think an important question the readme should address is how this package is better than other similar solutions. What even are similar solutions? Readme should specify similar concepts so we, humans, can build our understanding upon some previous knowledge we have with similar tools. I don't believe this package realizes a unique idea that has never been invented before even approximately or badly.
3. I can summarize my current misunderstanding in a simple question: "how is this different from just a function with a precondition?". I will provide some examples from the readme:
   • "Molds “mold” the data in your context into the data of your result" - this is exactly what a pure function does, transforms data from one form to another form
   • "The power of moldable-emacs is to make this micro-tools highly composable" - pure functions are highly composable, probably no need to comment further

I used the term "pure function" because it is not strictly true for non-pure functions. But if we speak in terms of Emacs, "creating a buffer with some text" might as well qualify as "pure" in certain contexts, and I believe this is also the main point of this package that we use Emacs buffers as input and output of the functions.

[ag91]

Thanks for your observations: I am happy to improve things.

1. I use story because is where I want to go towards with this mode: I want to easily communicate meaning supported by moldable-emacs. What moldable-emacs does is providing you with views of some context (by default a buffer, but often even just a selection of text). I call these views molds and they can be combined to produce more complex views to communicate more complex stories to others. If one day Emacs could write the molds for me and I could focus only on the story I want to say, I would be happy.
2. I need help with this. My intuition is that other modes focus on a single view of something (e.g., Magit presents you git data in a way you can easily manipulate), while moldable-emacs tries to make inexpensive to create custom views and compose them.
3. Not different at all. That is roughly the way it is implemented. What I want to focus though is what you can express with its features. This moldable-emacs is a framework to create molds (pure functions) so that you can easily compose them. It comes with examples that I use often (I use the mold CodeAsTree to tell a story to myself like "Given this code, I have to refactor it because I got a lot of duplication" by viewing a source file as a todo list of the duplicated code elements).

I am pretty sure I am confusing people at the moment and you could view this mode differently. For example, in https://github.com/ag91/moldable-emacs/issues/11 you can find

That's certainly a great use. I suggest that it can also be a tool to allow user's to solve specific problems they might have by solving general problems in molds. E.g. your excellent blog post about moving private functions to the bottom. I hate having to solve the same problem over and over again in different contexts. I would much rather solve the general problem once, and then be able to use it in many contexts.

I totally agree with her. You can use moldable-emacs to solve problems in a generic way. I see this as included: if I am pair-programming with you and I am telling you this story "Given these 100 files that have a misspelt string in one of their else statement, we would take forever to do it by hand. But we can do it in in one swoop if we define the correct pattern!", I can actually solve a boring problem in a generic way through views/molds. I can also give to you the "story" by serializing the views I used and their contents (I didn't work on this, but is simple to achieve).

In summary: moldable-emacs aims to bring your focus on what you want to communicate to others (yourself included) by making that simple to express (with molds).

-- Probably this message will not make things better, sigh..

[greenfork]

Thanks for the reply! What you have described actually makes a lot of sense.

1. I will try to describe the problem with the word "story" a little bit more. I understand that this is the core concept used throughout the whole description and you may feel like the "story" concept just has to be there, so I will try my best to explain how I see it. The readme introduces two new concepts simultaneously: first it introduces a concept of a "story", then it introduces the concept of a "mold". The story concept is new here - because it doesn't use any conventional definition of the word "story". An already existing definition of what is called "story" in the readme would probably be "desire" or "wish". "given all the expenses I had this year, I want to see what kind of holiday I can afford" - "I want" represents a wish here. It's true that there's no concept of a "wish with a condition" in English that I know of, so the readme says that this concept is called "story". And right after that the readme explains the concept of a "mold" with a newly introduced concept of a "story". This is why I think it can cause a confusion, two concepts are introduced too fast in a succession with one of them having a "stretched definition" of a real word. Although mold also has a real world definition, here we can clearly understand that readme introduces a very different meaning of the word so it doesn't feel like a "stretched definition" because mold usually means a physical object and here we give it a more abstract meaning.

There's also a bit forced nature of a condition, not every "story" has to be formulated this way. "Given this code, I have to refactor it because I got a lot of duplication" - in this example a better English would be to say "I have to refactor this code because I got a lot of duplication". So here it is just a "wish", an "obligation" or anything else but "story".

I have come up with an example of how I would describe this package in the simplest form possible which only introduces the single concept of a "mold":

Moldable Emacs introduces a new concept - Mold. Mold is a function with a precondition which may use Emacs buffers as inputs and outputs. Molds can be highly composable and one mold can fulfill a precondition for another mold. Molds can show a multi-faceted view of some data, for example ...

It's fine to have an abstract explanation of the general idea of what molds are for but I feel like the down-to-Earth explanation is missing.

2. Some examples which do similar job: Jupyter notebook, literate programming in org-mode, visible/infrared light cameras, gnu plot and similar programs which have graph variations: line graph, bar chart, pie chart etc.; google/youtube/grafana/whatever analytics. I don't know which example would be the best but there are definitely some existing implementations which have similar ideas.

In summary: moldable-emacs aims to bring your focus on what you want to communicate to others (yourself included) by making that simple to express (with molds).

I'm sold on the second part, molds are simple to express, they are just functions and functions can be indeed easy to express. But the first part about "bring your focus on what you want to communicate" - this sounds good and I want to believe it but in essence it looks like a sales pitch to me, when I look at the example:

(me-register-mold
 :key "FinancesToHoliday" ; your mold/story name
 :given (:fn (I-can-retrieve-my-finances?)) ; the context
 :then (:fn ; the result
        (let* ((my-finances ...)
               (my-holiday-savings (learn-that-from my-finances)))
          (with-current-buffer buffername
            (show-prettily my-holiday-savings)
            (setq-local self (list :finances my-finances :holiday-savings my-holiday-savings)) ; this sets a state that the next mold can compose upon
            ))))

I ask a question, how does this bring focus to communication in any way? There's a general idea that there are "stories" and you tell a "story" and you communicate. But how is this package unique in enabling this idea? The underlying idea about stories and communication can be applied to a wide variety of things in a similar fashion. There's a structure to molds which helps with understanding but saying that it helps to communicate is a bit over-reach in my opinion, the structure to functions is a widely known concept: Eiffel probably pioneered post/preconditions, Racket's contracts and more languages use the word "contract" to describe the idea of a structure to functions; if we call this "help to communicate", then what would be a single language feature which does not contribute to helping to communicate? The whole programming language is a tool which helps us communicate with the computer machinery.

Thanks again for reading it, it came out quite long.

[ag91]

Thanks for that. Sorry for the late reply, your comment is full of interesting points and I am still thinking about all of that :)

I understand where you are coming from. Definitely the story bit is a stretch: the tension comes from what I want this mode to be and the current status of things.

I like your description, I will think some more and then I can try to inject it in the README.

About "bring your focus on what you want to communicate": when I wrote that I was focusing on the presentation aspect not the extension aspect (i.e, how to write a new mold). 90% of the time I work with moldable-emacs I focus on taking some data and making it easy to read for me (or others). I do that mostly by composing existing molds. Only a 10% of time I write a new mold for myself.

For example, I have a mold to list live production errors and I show them to myself grouped by categories and (when I can) with links to the failing source code. This is a view target to me, a developer. Still these categories of errors are kept in an Elisp plist. The strength of the presentation layer of moldable-emacs is that I can now transform that plist (targeting a developer) into a bar chart with a pre-existing mold (no code to write, it's immediate), which could make it easy to communicate to management for example. So I can communicate to different audiences the same data without needed new code or integration (unless I need a completely new way of seeing things).

[greenfork]

Thanks! I don't think I have something to add to the discussion, so feel free to close this issue. I will also think about this unique concept, that is an interesting approach to information and representation!

[ag91]

Thanks again for your help. I have used your snippet and I have rewritten the README once more. Surely requires some more work but I hope it got closer to be understandable :)