README.md: Minor changes

rafael-santiago · Mar 17, 2017 · da49698 · da49698
1 parent 9eb4a3a
commit da49698
Show file tree

Hide file tree

Showing 2 changed files with 39 additions and 26 deletions.
diff --git a/README.md b/README.md
@@ -1,9 +1,19 @@
 # life
 
 This repo is a minimalist implementation of the ``Conway's Game of Life`` in ``IA-32 Assembly`` using
-``ANSI/TERM`` to handle the "graphic" stuff. Until now it was written to run on the following platforms:
+``ANSI/TERM`` to handle the "graphics". Until now it was written to run on the following platforms:
 
-![Linux](https://github.com/rafael-santiago/life/blob/master/etc/small-tux.jpg "Linux") ![FreeBSD](https://github.com/rafael-santiago/life/blob/master/etc/small-beastie.jpg "FreeBSD") ![OpenBSD](https://github.com/rafael-santiago/life/blob/master/etc/small-puffy.jpg "OpenBSD") ![NetBSD](https://github.com/rafael-santiago/life/blob/master/etc/small-netbsd-flag.jpg "NetBSD") ![MINIX](https://github.com/rafael-santiago/life/blob/master/etc/small-raccoon.jpg "MINIX") ![SOLARIS](https://github.com/rafael-santiago/life/blob/master/etc/small-solaris-sun.jpg "Solaris") ![Windows](https://github.com/rafael-santiago/life/blob/master/etc/small-windows-logo.jpg "Windows... Sorry! I was not able to find any decent logo!!! It will be changed soon...")
+![Linux](https://github.com/rafael-santiago/life/blob/master/etc/small-tux.jpg "Linux") ![FreeBSD](https://github.com/rafael-santiago/life/blob/master/etc/small-beastie.jpg "FreeBSD") ![OpenBSD](https://github.com/rafael-santiago/life/blob/master/etc/small-puffy.jpg "OpenBSD") ![NetBSD](https://github.com/rafael-santiago/life/blob/master/etc/small-netbsd-flag.jpg "NetBSD") ![MINIX](https://github.com/rafael-santiago/life/blob/master/etc/small-raccoon.jpg "MINIX") ![SOLARIS](https://github.com/rafael-santiago/life/blob/master/etc/small-solaris-sun.jpg "Solaris") ![Windows](https://github.com/rafael-santiago/life/blob/master/etc/small-windows-logo.jpg "Windows... Sorry! I am not able to find any decent logo!!! It will be changed soon...")
+
+According to some folktales, specially classroom tales, if you are seeing this repo you are hallucinating.
+Because these tales tell us that is impossible to build up any kind of portable ``ASSEMBLY`` code...
+Well, even being a pretty simple code (you should hallucinate better the next time) I think that this
+"hallucination" can dismistify a bunch of things if you are a "superstitious" programmer.
+But remember: it does not exist, it is just a bad trip... ¬¬
+
+As Mr. Stevie would say: *"superstition ain't the way..."*
+
+... boo!! ;)
 
 ## How to clone it?
 
@@ -17,13 +27,13 @@ Done.
 
 ## How to build it?
 
-I have written it using the ``GNU's Assembler`` (a.k.a ``gas``). You can use the build system or do it
-on your own (in this case my code is using the ``libc``). If you are on ``Windows`` is the
-``GCC`` is also needed because we use it to link, otherwise the linking would be much harder there.
+I have built it using the ``GNU Assembler`` (a.k.a ``gas``). You can use the build system or do it
+on your own (in this case my code is using the ``libc``). If you are on ``Windows`` the
+``MINGW`` is also needed because we use it to link, otherwise the linking would be much harder.
 
 This tiny project uses my own [build system](https://github.com/rafael-santiago/hefesto). After following
-all steps to put ``hefesto`` to work on your system, you should "teach" your build system copy how to handle the
-``GNU's Assembler``. You need three commands:
+all steps to make ``hefesto`` work on your system, you should "teach" your build system copy how to handle the
+``GNU Assembler``. You need three commands:
 
 ```
 root@SilvergunSuperman:~/src# git clone https://github.com/rafael-santiago/helios helios
@@ -34,7 +44,7 @@ root@SilvergunSuperman:~/src/helios# hefesto --install=gnu-asm-toolset
 Done.
 
 After doing it your ``hefesto`` copy will know how to handle the assembler that we need. By the way, your
-``helios`` copy can be removed...
+``helios`` copy can be deleted.
 
 Now, inside your ``life`` copy, move to the ``src`` sub-directory and just call ``hefesto`` from there.
 
@@ -59,7 +69,7 @@ If you prefer/need to inform your dynamic loader path, try to use the option ``-
 you@SilvergunSuperman:~/src/life/src# hefesto --ld-path=/usr/libexec/ld-elf.so.1
 ```
 
-If you are having some problem related with the target architecture, you should try:
+If you are facing some problems related with the target architecture, you should try:
 
 ```
 you@SilvergunSuperman:~/src/life/src# hefesto --address-model=32
@@ -72,7 +82,7 @@ to write all this stuff in one single file (``src/life.s``). If you are on a pla
 your ``as`` (Ha-Ha) command the option ``-dsym SYMBOL=1``. In **Table 1** you can find the correct symbol to your current
 platform.
 
-AFAIK, on ``Solaris`` the ``as`` is related to its native Assembler, due to it you should call ``gcc`` or ``"gas"``
+AFAIK, on ``Solaris`` the ``as`` is related to its native assembler, due to it you should call ``gcc`` or ``"gas"``
 instead of using your good and old ``"as"``, *BA DUM TSSS* ... Now if you do not have the ``GNU Assembler`` installed on
 your ``Solaris`` box I would say that your system by now is out of gas... *BA DUM TSSS*... Anyway, install it because I am
 not intending to rewrite all the code stuff only for tan as... *BA DUM TSSS*... Horrible, well, getting back to **Table 1**...
@@ -101,6 +111,7 @@ you@SilvergunSuperman:~/src/life/src# hefesto --install
 
 If your ``UNIX-like`` has the directory ``/usr/games``, ``life`` will be installed there. On some ``UNIXes`` this directory
 is not exported, so you should call ``/usr/games/life`` instead of ``life``. On ``Windows`` it will be installed on ``C:\life``.
+The path is not exported on ``Windows``, do it yourself (google about how to do it, if you do not know).
 
 If you want to uninstall:
 
@@ -112,7 +123,7 @@ you@SilvergunSuperman:~/src/life/src# hefesto --uninstall
 
 This application works based on command line, if you call on your console just ``life`` without passing any argument, as a result
 you will see a black screen. You need to inform the initial state of the board and also can inform other things if you want to. Take a look
-at the **Table 2** to see more about these command line options.
+at the **Table 2** to see more about the command line options.
 
 **Table 2**: Supported command line options until now.
 
@@ -121,7 +132,7 @@ at the **Table 2** to see more about these command line options.
 |``--interactive``          | Indicates that before each new generation an ``ENTER`` is expected | ``life --interactive`` |
 |``--alive-color=color``  | Defines the color for representing alive cells. The colors should  be: ``black``, ``red``, ``green``, ``blue``, ``magenta``, ``cyan`` or ``white`` | ``life --alive-color=cyan`` |
 |``--dead-color=color``   | Defines the color for representing dead cells. The colors should be: ``black``, ``red``, ``green``, ``blue``, ``magenta``, ``cyan`` or ``white`` | ``life --alive-dead=green`` |
-|``--delay=milliseconds`` | Indicates the amount of times (in milliseconds) to wait before the next generation | ``life --delay=1000`` |
+|``--delay=milliseconds`` | Indicates the amount of time (in milliseconds) to wait before the next generation | ``life --delay=1000`` |
 |``--generation-nr=n``      | Sets a limit for the game loop | ``life --generation=100`` |
 |``--board-size=n``         | Defines the size of the square shaped board. The values should be between ``2`` and ``45`` | ``life --board-size=10`` |
 |``--y,x.``        | Makes a cell under (y;x) coordinate alive | ``life --0,0.`` |
@@ -130,21 +141,23 @@ at the **Table 2** to see more about these command line options.
 On ``Windows`` is possible to get a colored output if you run the program from ``MSYS`` or ``Cygwin``. Still on ``Windows`` if you are
 using a normal command prompt, the program will detect it and use ``--no-ansi-term`` automatically, you do not have to worry about.
 
-Let's start with a block at the beginning of the board:
+Now let's see some practical command line samples... Let's start with a block at the beginning of the board:
 
 ```
 you@SilvergunSuperman:~/src/life/src# life --0,0. --0,1. \
 > --1,0. --1,1.
 ```
 
-Now let's define a blinker, using the color ``magenta`` for the alive cells.
+A blinker, using the color ``magenta`` for the alive cells:
 
 
 ```
 you@SilvergunSuperman:~/src/life/src# life --2,1. \
 > --2,3. --2,4. --alive-color=magenta
 ```
 
+Well, I think that you understood.
+
 The **Table 3** gathers famous patterns.
 
 **Table 3**: Some oscillators.
@@ -187,7 +200,7 @@ To exit the program you should hit ``CTRL + c``. In some shell types you must co
 
 - [Conwaylife.com](http://www.conwaylife.com)
 - [A discussion of the Game of Life](http://web.stanford.edu/~cdebs/GameOfLife)
-- [Numberphile - Inventing Game of Life](https://www.youtube.com/watch?v=R9Plq-D1gEk)
+- [Numberphile - Inventing the Game of Life](https://www.youtube.com/watch?v=R9Plq-D1gEk)
 - [The Game of Life - a beginner's guide](https://www.theguardian.com/science/alexs-adventures-in-numberland/2014/dec/15/the-game-of-life-a-beginners-guide)
 - [Logical Functions in the Game of Life](http://cogprints.org/4115/1/CollisionBasedRennard.pdf)
 - [John Conway Talks About the Game of Life](https://www.youtube.com/watch?v=FdMzngWchDk)

diff --git a/src/life.s b/src/life.s
@@ -305,7 +305,7 @@ noansi_dead_fmt:
         movl %esp, %ebp
         movl 4(%ebp), %ebx
         movl 8(%ebp), %ecx
-        # INFO(Rafael): We will parse one useless item, the argv[0] (is a nightmare getting it after on help printing).
+        # INFO(Rafael): We will parse one useless item, the argv[0] (is a nightmare get it after on help printing).
         #addl $4, %ecx
         pushl (%ecx)
         pushl 4(%ebp)
@@ -314,7 +314,7 @@ noansi_dead_fmt:
         movl %edx, %ebp
     .endif
 
-    # INFO(Rafael): Branching to --version or --help sections if the user asked us.
+    # INFO(Rafael): Branching to --version or --help sections if the user has asked us.
 
     pushl $1
     pushl $0
@@ -596,7 +596,7 @@ set_argc_argv: # set_argc_argv(argc, argv)
         movl %eax, argv
     .else
         # INFO(Rafael): Doing the Windows kernel programmer job.. :Z
-        #               ___crappy_getmainargs() sucks.. Just one more useless dependency that does obvious things.
+        #               ___crappy_getmainargs() sucks.. Just one more useless dependency that does obvious things. No!
 
         pushl %eax
         pushl %ecx
@@ -1066,7 +1066,7 @@ noansi_genprint: # noansi_genprint()
 
     xorl %eax, %eax
 
-    # INFO(Rafael): Let's avoid several calls to printf and do it once.
+    # INFO(Rafael): Let's avoid several calls to printf doing it once.
 
     movl $screen_buffer, %edi
 
@@ -1156,13 +1156,13 @@ apply_rules: # apply_rules(EAX, EBX)
     # INFO(Rafael): Basically it traverses the cells inspecting the neighbours of each one and then applies
     #               the game rules.
     #
-    #                I think that use a kind of "temp_cells", "aux_cells" only to store the next generation data
-    #                is quite useless and a waste of memory, due to it I have chosen to store the next generation
-    #                data in the most significant nibble from the "cells", it still sucks but less.
+    #               I think that use a kind of "temp_cells", "aux_cells" only to store the next generation data
+    #               is quite useless and a waste of memory, due to it I have chosen to store the next generation
+    #               data in the most significant nibble from the "cells", it still sucks but less.
     #
-    #                So, the first (row;col) iteration generates a kind of "alternative world"... the second one
-    #                takes Alice (without Bob and Eva but with us) there by right shifting our current "brana"
-    #                4 bits. ;)
+    #               So, the first (row;col) iteration generates a kind of "alternative world"... the second one
+    #               takes Alice (without Bob and Eva but with us) there by right shifting our current "brana"
+    #               4 bits. ;)
 
     xorl %eax, %eax
 
@@ -1273,7 +1273,7 @@ inspect_neighbourhood: # inspect_neighbourhood(EAX, EBX)
     #                                           T T T
     #
     # Maybe this function could be improved to evalute only the enough to take some decision instead
-    # of visiting and counting all neighbours. By now it is okay.
+    # of visiting and counting all neighbours, but by now it is okay.
     #
 
     pushl %ebp