.. -*- coding: utf-8 -*-












.. role:: sref(numref)
.. role:: xref(numref)
.. Copyright (C) 2013, 2025, Wolfgang Scherer, <Wolfgang.Scherer at gmx.de>

.. This file is part of Satoku Matrix.

.. Permission is granted to copy, distribute and/or modify this document
.. under the terms of the GNU Free Documentation License, Version 1.3
.. or any later version published by the Free Software Foundation;
.. with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
.. A copy of the license is included in the section entitled "GNU
.. Free Documentation License".

.. inline comments (with du_comment_role)
.. role:: rem(comment)
.. role:: html(raw)
   :format: html
.. role:: shx(code)
   :language: sh

.. rst-class:: narrow xmedium xlarge xhuge xultra

##################################################
:rem:`|||:sec:|||`\ Satoku Matrix
##################################################

.. . (progn (forward-line 1) (snip-insert "rst_b.peek-a-boo" t t "rst") (insert ""))

.. >>CODD See `the components of a doctoral dissertation and their order <http://site.uit.no/english/writing-style/bookstructure/>`_
.. >>CODD Dedication
.. >>CODD Epigraph
.. >>CODD Abstract

.. raw:: html

   <p>
   There is a  <a href="../latex/SatokuMatrix.pdf">PDF version of this document</a> available.
   </p>

.. raw:: latex

   \iffalse

.. rubric:: Quickstart
.. raw:: latex

   \fi
   \providecommand{\sddlytocignore}[1]{#1\ignorespaces}
   \sddlytocignore{%
   \pagebreak[3]%
   \addcontentsline{toc}{\sdseclevel}{Quickstart}%
   \markboth{}{}%
   \phantomsection
   }%
   \begingroup
   \renewcommand{\abstractname}{Quickstart}
   \pagebreak[3]
   \begin{abstract}
   \nobreak\noindent\setlength{\parindent}{0pt}%

See http://sw-amt.ws/README-Satoku.html for an explanation of the satoku matrix.

To get started load :file:`satoku.el`:

Press :kbd:`C-x C-e` at end of the following expression:

.. code-block:: elisp

  (load-file "satoku.el")

or press:

.. code-block:: text

   M-x load-file RET satoku.el RET

Then execute the command satoku-insert-matrix:

.. code-block:: text

   M-x satoku-insert-matrix RET

Which will give you a Satoku matrix with a single clause sub-matrix:

.. code-block:: text

    // |    ||   S||  0|   0|| 1 1 1 |
    // +----++----++---+----++-------+
    // +-----+----++---+----++-------+
    // |     |   0||   |    || 1 * * |
    // |     |   1||   |    || * 1 * |
    // |     |   2||   |    || * * 1 |
    // +-----+----++---+----++-------+
    // |:info:| move point inside and press `C-u M-x satoku-mode RET'

Position point somewhere inside the matrix and execute:

.. code-block:: text

   C-u M-x satoku-mode RET

This constrains your cursor movements to the matrix and assigns
special commands to certain keys. (Note: Outside the matrix, the keys
work as usual).

Press :kbd:`?` for help.

Some commands are prefix commands (e.g. :kbd:`g`).  Press :kbd:`?` after the
prefix command to get help.

To extend the matrix with another 3x3 clause sub-matrix, press
:kbd:`C-u 3 > >`:

.. code-block:: text

    // |    ||   S||  0|   0|| 1 1 1 | 1 1 1 |
    // +----++----++---+----++-------+-------+
    // +-----+----++---+----++-------+-------+
    // |     |   0||   |    || 1 * * | _ _ _ |
    // |     |   1||   |    || * 1 * | _ _ _ |
    // |     |   2||   |    || * * 1 | _ _ _ |
    // +-----+----++---+----++-------+-------+
    // |     |   3||   |    || _ _ _ | 1 * * |
    // |     |   4||   |    || _ _ _ | * 1 * |
    // |     |   5||   |    || _ _ _ | * * 1 |
    // +-----+----++---+----++-------+-------+
    // |:info:| move point inside and press `C-u M-x satoku-mode RET'

Press :kbd:`> >` to get a separator line:

.. code-block:: text

    // |    ||   S||  0|   0|| 1 1 1 | 1 1 1 ||
    // +----++----++---+----++-------+-------++
    // +-----+----++---+----++-------+-------++
    // |     |   0||   |    || 1 * * | _ _ _ ||
    // |     |   1||   |    || * 1 * | _ _ _ ||
    // |     |   2||   |    || * * 1 | _ _ _ ||
    // +-----+----++---+----++-------+-------++
    // |     |   3||   |    || _ _ _ | 1 * * ||
    // |     |   4||   |    || _ _ _ | * 1 * ||
    // |     |   5||   |    || _ _ _ | * * 1 ||
    // +-----+----++---+----++-------+-------++
    // +-----+----++---+----++-------+-------++
    // |:info:| move point inside and press `C-u M-x satoku-mode RET'

Press :kbd:`C-u 2 > >` to get a 2x2 clause sub-matrix, repeat, and
repeat again (hint: you can use keyboard macros).

Normal keys are disabled inside the matrix (but not the legend), use
:kbd:`0` to mark selection conflicts, :kbd:`-` to clear a
cell. (Mirror cells are automatically changed accordingly.)

Do not use :kbd:`1` to mark required selections. Exclude all other
selections with :kbd:`0` instead:

.. code-block:: text

    // |    ||   S||  0|   0|| 1 1 1 | 1 1 1 || 1 1 | 1 1 | 1 1 |
    // +----++----++---+----++-------+-------++-----+-----+-----+
    // +-----+----++---+----++-------+-------++-----+-----+-----+
    // |     |   0||   |    || 1 * * | 0 _ _ || _ 0 | _ _ | _ _ |
    // |     |   1||   |    || * 1 * | _ _ 0 || _ _ | _ _ | _ _ |
    // |     |   2||   |    || * * 1 | _ _ 0 || _ _ | _ _ | _ _ |
    // +-----+----++---+----++-------+-------++-----+-----+-----+
    // |     |   3||   |    || 0 _ _ | 1 * * || 0 _ | _ _ | _ _ |
    // |     |   4||   |    || _ _ _ | * 1 * || _ _ | _ _ | _ _ |
    // |     |   5||   |    || _ 0 0 | * * 1 || _ _ | _ _ | _ _ |
    // +-----+----++---+----++-------+-------++-----+-----+-----+
    // +-----+----++---+----++-------+-------++-----+-----+-----+
    // |     |   6||   |    || _ _ _ | 0 _ _ || 1 * | _ _ | _ _ |  a
    // |     |   7||   |    || 0 _ _ | _ _ _ || * 1 | _ _ | _ _ | ¬a
    // +-----+----++---+----++-------+-------++-----+-----+-----+
    // |     |   8||   |    || _ _ _ | _ _ _ || _ _ | 1 * | _ _ |  b
    // |     |   9||   |    || _ _ _ | _ _ _ || _ _ | * 1 | _ _ | ¬b
    // +-----+----++---+----++-------+-------++-----+-----+-----+
    // |     |  10||   |    || _ _ _ | _ _ _ || _ _ | _ _ | 1 * |  c
    // |     |  11||   |    || _ _ _ | _ _ _ || _ _ | _ _ | * 1 | ¬c
    // +-----+----++---+----++-------+-------++-----+-----+-----+
    // |:info:| move point inside and press `C-u M-x satoku-mode RET'

Then press :kbd:`r u` to run the requirements update algorithm, which
detects and fills in the *hard one* requirements.

If you did use :kbd:`1` and are no longer sure, whether the matrix
conditions are proper, press :kbd:`r c` to clear all *hard one*
requirements. Then press :kbd:`r u` to run the requirements update
algorithm.

.. code-block:: text

    // |    ||   S||  0|   0|| 1 1 1 | 1 1 1 || 1 1 | 1 1 | 1 1 |
    // +----++----++---+----++-------+-------++-----+-----+-----+
    // +-----+----++---+----++-------+-------++-----+-----+-----+
    // |     |   0||   |    || 1 * * | 0 _ _ || 1 0 | _ _ | _ _ |
    // |     |   1||   |    || * 1 * | _ _ 0 || _ _ | _ _ | _ _ |
    // |     |   2||   |    || * * 1 | _ _ 0 || _ _ | _ _ | _ _ |
    // +-----+----++---+----++-------+-------++-----+-----+-----+
    // |     |   3||   |    || 0 _ _ | 1 * * || 0 1 | _ _ | _ _ |
    // |     |   4||   |    || _ _ _ | * 1 * || _ _ | _ _ | _ _ |
    // |     |   5||   |    || 1 0 0 | * * 1 || 1 0 | _ _ | _ _ |
    // +-----+----++---+----++-------+-------++-----+-----+-----+
    // +-----+----++---+----++-------+-------++-----+-----+-----+
    // |     |   6||   |    || _ _ _ | 0 _ _ || 1 * | _ _ | _ _ |  a
    // |     |   7||   |    || 0 _ _ | _ _ 0 || * 1 | _ _ | _ _ | ¬a
    // +-----+----++---+----++-------+-------++-----+-----+-----+
    // |     |   8||   |    || _ _ _ | _ _ _ || _ _ | 1 * | _ _ |  b
    // |     |   9||   |    || _ _ _ | _ _ _ || _ _ | * 1 | _ _ | ¬b
    // +-----+----++---+----++-------+-------++-----+-----+-----+
    // |     |  10||   |    || _ _ _ | _ _ _ || _ _ | _ _ | 1 * |  c
    // |     |  11||   |    || _ _ _ | _ _ _ || _ _ | _ _ | * 1 | ¬c
    // +-----+----++---+----++-------+-------++-----+-----+-----+
    // |:info:| move point inside and press `C-u M-x satoku-mode RET'

.. \|:here:|

.. raw:: latex

   \end{abstract}
   \endgroup


.. raw:: latex

   \iffalse

.. rubric:: Abstract
.. raw:: latex

   \fi
   \providecommand{\sddlytocignore}[1]{#1\ignorespaces}
   \sddlytocignore{%
   \pagebreak[3]%
   \addcontentsline{toc}{\sdseclevel}{Abstract}%
   \markboth{}{}%
   \phantomsection
   }%
   \pagebreak[3]
   \begin{abstract}
   \nobreak\noindent\setlength{\parindent}{0pt}%


.. \|:here:|

.. raw:: latex

   \end{abstract}

.. raw:: latex

   \providecommand{\sddlytoctableofcontents}{}
   \sddlytoctableofcontents


.. raw:: latex

   \iffalse

.. rubric:: Contents
.. raw:: latex

   \fi
.. toctree::
   :numbered:

   overview
   bit-counter

..
   add documents to toctree without the extension like this:

     module

.. the ReST document name without the extension

.. >>CODD Acknowledgments
.. >>CODD Note on Transliterations
.. >>CODD List of Abbreviations

.. include:: abbrevs.inc

.. >>CODD Reference List/Bibliography
.. ==================================================
.. :rem:`|||:sec:|||`\ Glossary
.. ==================================================

.. include:: glossary.inc

.. ==================================================
.. :rem:`|||:sec:|||`\ References
.. ==================================================

.. raw:: latex

   \iffalse

.. rubric:: References
.. raw:: latex

   \fi

.. include:: bibliography.inc

.. \|:info:| put local references here
.. \|:info:| put local definitions here
.. include:: doc_defs.inc
.. include:: abbrev_defs.inc
.. include:: doc_defs_combined.inc
..
  .. \||<-snap->|| doc_standalone
  .. include:: doc/doc_defs_secret.inc
  .. \||<-snap->|| doc_standalone
  .. \||<-snap->|| not_doc_standalone
  .. include:: doc_defs_secret.inc
  .. \||<-snap->|| not_doc_standalone

.. _`Wolfgang Scherer`: wolfgang.scherer@gmx.de