Add developer notes to the language README files

languages/befunge93/README.md

@@ -1,10 +1,33 @@
 # Befunge-93
 
-## References
+Befunge-93 is a two-dimensional esolang created by Chris Pressey, with the goal of being as difficult to compile
+as possible. The program is a finite 2D grid of operations, and execution can proceed in any of the four main
+directions. This makes watching the execution of a Befunge-93 program particularly satisfying.
 
-- Esolangs wiki: https://esolangs.org/wiki/Befunge
+Memory in Befunge-93 is a stack of integers. In addition, Befunge-93 programs can be self-modifying - there are
+operations that allow accessing and editing the content of the source code at runtime. This means you can also store
+runtime data in the source code itself, if space permits.
+
+The [esolang wiki page](https://esolangs.org/wiki/Befunge) contains the complete language-specification, along with
+some interesting sample programs.
+
+## Notes for the user
+
+- The program grid is padded with space to size 80x25 before execution.
+- Interactive input is not supported in Esolang Park, so currently division-by-zero throws a runtime error.
+- `g` and `p` calls that access coordinates outside of the 80x25 grid result in a runtime error.
+- Due to being two-dimensional, the breakpoint functionality is rather uncomfortable to use in Befunge-93.
 
 ## Implementation details
 
-- Interactive input is not supported yet, so currently division-by-zero throws a runtime error.
-- `g` and `p` calls that access coordinates outside of the 80x25 grid result in a runtime error.
+- To avoid long no-op stretches, the engine keeps track of the bounds of the user's source code. If the pointer reaches
+  the end of the _set_ portion of a horizontal line, it immediately loops over to the opposite end of the line. The same
+  happens in vertical lines. Try executing `>>>>` to visualise this.
+
+  Note that this does not happen in string mode. In string mode the pointer loops over the full grid, pushing ` ` (space)
+  characters onto the stack.
+
+## Possible improvements
+
+- There seems to be some minor issue in the initial grid padding. Some lines get padded to 81 characters instead
+  of 80. This is only cosmetic though - the program executes correctly.

languages/brainfuck/README.md

@@ -1,12 +1,23 @@
 # Brainfuck
 
-## References
+Brainfuck is perhaps the most popular esoteric programming language, created by Urban Müller in 1993.
+It is Turing-complete and has 8 instructions which operate on a linear array of cells storing integer values.
+The [esolangs wiki page](https://esolangs.org/wiki/Brainfuck) contains the language specification and some
+sample programs.
 
-- Esolangs wiki: https://esolangs.org/wiki/Brainfuck
+Note that brainfuck has minor variants which primarily differ in the workings of the cell array. You may find
+many brainfuck programs which don't work correctly on Esolang Park.
 
-## Implementation details
+## Notes for the user
 
-- The tape is semi-unbounded (0, 1, 2 ...)
-- Cell size is 8 bits, and allows values in the range `[-128, 127]`.
-- Value `10` is designated for newlines.
-- The value `0` is returned on reaching `EOF`.
+- The cell array is semi-infinite. There is no cell to the left of the initial cell, and trying to go left
+  anyway will result in a runtime error. The right side of the cell array is unbounded.
+- Cell size is 8 bits, and allows values in the range `[-128, 127]`. Values loop over to the other side on reaching the bounds.
+- The usual ASCII value `10` is designated for newlines.
+- The value `0` is returned in input (`,`) operations on reaching `EOF`.
+
+## Possible improvements
+
+- The renderer currently uses Blueprint's `Card` component. This leads to performance issues when the stack grows large.
+  Usage of this component should be replaced by a simple custom component to drastically improve performance. Look at the
+  `SimpleTag` component used in the Shakespeare renderer for an example.

languages/chef/README.md

@@ -1,10 +1,11 @@
 # Chef
 
-## References
+Chef is a stack-based Turing-complete esolang created by David Morgan-Mar in 2002, in which programs read
+like cooking recipes. An important guideline while writing Chef programs/recipes is for the recipe to be easy
+to prepare and delicious. The complete language specification is available on the
+[official Chef homepage](https://www.dangermouse.net/esoteric/chef.html).
 
-- David Morgan-Mar's Chef page: https://www.dangermouse.net/esoteric/chef.html
-
-## Implementation details
+## Notes for the user
 
 - Ingredient names are case-sensitive and must contain only letters and spaces.
 
@@ -33,3 +34,21 @@
   <other instructions>
   Shake the mixture until blend.
   ```
+
+## Implementation details
+
+- The parser is hand-built and uses regular expressions for basically everything.
+- The engine is split in two classes: `Kitchen` handles kitchen-related operations while the main class
+  handles control-flow operations and manages the call-stack.
+
+## Possible improvements
+
+- Allow case-insensitive usage of auxiliary recipe names.
+
+- Chef syntax is flat and simple, easily representable by regular expressions. This means that syntax highlighting for
+  Chef can easily be made perfect by slightly modifying and reusing parser regexes for the Monarch tokenizer. Currently
+  the method part of syntax highlighting just highlights the known keywords.
+
+- We need to find a sensible solution for the verb tense issue mentioned above. Currently, any Chef program involving loops
+  requires modifications to be run in Esolang Park. Importing a very lightweight English verb-dictionary and only allowing
+  verbs from this dictionary is a possible way to resolve this.

languages/deadfish/README.md

@@ -1,9 +1,8 @@
 # Deadfish
 
-## References
+Deadfish is a dead-simple esolang created by Jonathan Todd Skinner. Four straightforward commands, no conditionals,
+no loops. It was the second language to be added to Esolang Park simply because I was feeling a bit lazy. The
+[esolangs wiki page](https://esolangs.org/wiki/Deadfish) is the only resource used for this implementation.
 
-- Esolangs wiki: https://esolangs.org/wiki/Deadfish
-
-## Implementation details
-
-- The value is unbounded, but is reset to `0` whenever it equals `-1` or `256`.
+In all honesty, Esolang Park does not do Deadfish justice. Deadfish is designed for writing highly interactive
+programs, but due to the lack of support for interactive input a lot of Deadfish's power is taken away.

languages/shakespeare/README.md

@@ -1,13 +1,33 @@
 # Shakespeare
 
-## References
+Shakespeare is a programming language that reads like a Shakespearean play, usually involving characters  
+appreciating and (rather roughly) criticizing other characters. It was created by Karl Wiberg and Jon Åslund
+as part of a university course assignment in 2001.
 
-- Official documentation and implementation: http://shakespearelang.sourceforge.net
+The original resource page is [hosted on Sourceforge](http://shakespearelang.sourceforge.net). It contains the
+[language specification PDF](http://shakespearelang.sourceforge.net/report/shakespeare.pdf) and a Shakespeare-to-C
+transpiler written with Flex and Bison in C, along with links to some other related resources.
 
-## Implementation details
+The specification and the transpiler source code are the only references used while implementing the Shakespeare
+language for Esolang Park.
+
+## Notes for the user
 
 - It is not necessary for questions to immediately be followed by conditionals. Conditionals
   must immediately follow a question though - a runtime error is thrown otherwise.
 
 - Empty acts and scenes are invalid. An act must contain at least one scene, and a scene must contain
   at least one dialogue set or entry-exit clause.
+
+## Implementation details
+
+- The parser is implemented with [Chevrotain](https://chevrotain.io).
+- The engine is quite small in size, and is a single file (`runtime.ts`).
+- The renderer uses a custom component instead of Blueprint's `Tag` component for much better performance.
+
+## Possible improvements
+
+- Currently, the check that conditionals must be preceded immediately by a question is done at runtime. It is a static
+  check and should be done while parsing the program instead.
+
+- Syntax highlighting doesn't work for multi-word keywords that break into two lines (`... summer's \n day ...`).

scripts/new-lang-template/README.md

@@ -1,5 +1,20 @@
 # $LANG_NAME
 
-## References
+Add a short summary about the language, including link(s) to the language specification and sample programs.
+
+## Notes for the user
+
+- Add details and quirks (if any) about the Esolang Park implementation of this esolang.
+- These are details that the user may want to know while executing or debugging programs on the editor.
 
 ## Implementation details
+
+- Add notes that a contributor may want to read while looking at the source code of the language provider.
+- This includes any third-party libraries you've used, something you've done for performance, or just the
+  main decisions you took while implementing the language provider.
+- If the source code is simple enough, you can simply omit this section.
+
+## Possible improvements
+
+- Add any bugs or suboptimalities in the language provider that a contributor can work on.
+- (this section doesn't mean you can add a half-baked interpreter and leave, though.)