update texinfo manual + update .gitignore

Signed-off-by: Mattias Andrée <maandree@member.fsf.org>

6 files changed, 80 insertions, 15 deletions

diff --git a/.gitignore b/.gitignore
index 7796969..34dfab1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,7 @@
 _/
+/bin/
+/obj/
+/aux/
 __pycache__/
 .*
 !.git*
diff --git a/Makefile.in b/Makefile.in
index 6d05299..18b0b10 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -67,7 +67,8 @@ _TEXINFO_DIRLEVELS = 2
 _INFOPARTS = 0
 _HAVE_TEXINFO_MANUAL = yes
 _HTML_FILES = Free-Software-Needs-Free-Documentation.html  GNU-Free-Documentation-License.html  \
-              GNU-General-Public-License.html  index.html  Invoking.html  Overview.html
+              GNU-General-Public-License.html  index.html  Invoking.html  Overview.html  \
+              Rationale.html
 
 # Used by mk/man.mk
 _MAN_PAGE_SECTIONS = 1
@@ -79,7 +80,7 @@ _COPYING = COPYING
 # Used by mk/dist.mk
 ___EVERYTHING_INFO = scrotty titlepage-data content hardcopy-copying  \
                      appx/fdl appx/free-software-needs-free-documentation appx/gpl  \
-                     chap/invoking chap/overview  \
+                     chap/invoking chap/overview chap/rationale  \
                      reusable/macros reusable/paper reusable/titlepage
 _EVERYTHING = $(foreach F,$(___EVERYTHING_INFO),doc/info/$(F).texinfo)  \
               $(__EVERYTHING_ALL_COMMON) DEPENDENCIES INSTALL NEWS
diff --git a/doc/info/chap/invoking.texinfo b/doc/info/chap/invoking.texinfo
index 5545c4c..adfc866 100644
--- a/doc/info/chap/invoking.texinfo
+++ b/doc/info/chap/invoking.texinfo
@@ -1,14 +1,39 @@
 @node Invoking
 @chapter Invoking
 
-@emph{Do not use this if you have epilepsia}
+@emph{You must not run this program if you are epileptic.}
+Seek someone else how can do it for you.
 
-@command{unstickpixels} will not run in a graphical environment.
-If you are using a graphical environment and do not know how
-to access the Linux VT, here is how you do it: press @kbd{Ctrl+Alt+F1},
-if this does not open non-graphical login screen, press @kbd{Alt+Right}
-until you get one. To get back to graphical environment, hold
-down @kbd{Alt+Right} until it appears.
+@command{unstickpixels} recognises the following options
+@table @option
+@item -v
+Use the Linux VT instead of the graphics cards' colour
+lookup tables (CLUT). This requires that the program runs
+under the Linux VT, otherwise known as the TTY. This may
+not work too great one all graphics cards, some very
+expensive graphics cards are really bad. NVIDIA is known
+case of this, why the CLUT utilisation was added.
 
-Run @command{unstickpixels} without arguments.
+If you are using a graphical environment and do not know
+how to access the Linux VT, here is how you do it: press
+@kbd{Ctrl+Alt+F1}, if this does not open non-graphical
+login screen, press @kbd{Alt+Right} until you get one.
+To get back to graphical environment, hold down
+@kbd{Alt+Right} until it appears.
+
+Whilst @command{unstickpixels} may run on most systems
+(although Mir and, by Wayland's design, Wayland are
+not supported) this option is only known to function on Linux.
+@end table
+
+@command{unstickpixels} accepts at most one non-option
+argument. This argument is the number of milliseconds
+to sleep between each color switch. This may be useful
+to optimise the effect. It may help to sleep 10 milliseconds
+between each colour switch rather than switching the
+colours as fast as possible.
+
+You should disable powersaving on your monitors and
+disable the screensaver whilst running this program,
+or otherwise make sure that screen loop is always displayed.
 
diff --git a/doc/info/chap/overview.texinfo b/doc/info/chap/overview.texinfo
index fff14e9..32d191c 100644
--- a/doc/info/chap/overview.texinfo
+++ b/doc/info/chap/overview.texinfo
@@ -2,13 +2,23 @@
 @chapter Overview
 
 @command{unstickpixels} tries to unstick stuck pixels.
+It does this by rapidly switching between the colours
+sRGB(100 %, 0, 0), sRGB(0, 100 %, 0), and sRGB(0, 0, 100 %),
+which are displayed on the entire monitor. On all of the
+monitors. It helps to massage defective dots.
+
+Running this program for a number of hours, especially if
+combined with massaging defective dots, may heal defective
+dots. Dead dots (always black) are hard to revive, but stuck
+dots are more probable to get fixed.
 
 Dead (always black) pixels are hard to revive, stuck pixels
 on the other hand are more probable to get fixed.
 
-This program should be run under the Linux VT. It works by
-cycling the colour on the screen between sRGB(100 %, 0, 0),
-sRGB(0, 100 %, 0) and sRGB(0, 0, 100 %), as fast as possible.
-If you want to slow down the cycling you can add, as the only
-argument, the millisecond time sleep between the colours.
+@command{unstickpixels} uses the graphics cards' colour lookup
+tables to switch the colour displayed on the screen. If your
+computers does not supports this, the option @option{-v} may
+help, it will use the framebuffer indirectly, via the terminal.
+Unless @option{-v} is used, @command{unstickpixels} runs both
+in @command{X} and on the Linux VT.
 
diff --git a/doc/info/chap/rationale.texinfo b/doc/info/chap/rationale.texinfo
new file mode 100644
index 0000000..a3eaa19
--- /dev/null
+++ b/doc/info/chap/rationale.texinfo
@@ -0,0 +1,24 @@
+@node Rationale
+@chapter Rationale
+
+Acer/Packard Bell is not willing to repair all defects
+on my computer, but at least I can run this for several
+hours and try to revive dead pixels. Playing back a
+video that is already available on the Internet has
+some deficiencies:
+
+@itemize @bullet{}
+@item
+Requires a graphics card and video player that can play
+back the video in full screen mode efficiently.
+@item
+Requires @command{X} or a video player than can play
+video outside @command{X} efficiently.
+@item
+Requires the video to be downloaded if it was uploaded
+on Youtube, because Youtube does not properly support
+full screen.
+@item
+video playback is required per defective monitor.
+@end itemize
+
diff --git a/doc/info/content.texinfo b/doc/info/content.texinfo
index 3a4578e..985c27c 100644
--- a/doc/info/content.texinfo
+++ b/doc/info/content.texinfo
@@ -10,6 +10,7 @@
 @menu
 * Overview::                                Brief overview of @command{unstickpixels}.
 * Invoking::                                Invocation of @command{unstickpixels}.
+* Rationale::                               Rationale for writing @command{unstickpixels}.
 
 * Free Software Needs Free Documentation::  Why free documentation is important.
 * GNU General Public License::              Copying and sharing @command{unstickpixels}.
@@ -20,6 +21,7 @@
 
 @include chap/overview.texinfo
 @include chap/invoking.texinfo
+@include chap/rationale.texinfo
 
 @include appx/free-software-needs-free-documentation.texinfo