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












.. role:: sref(numref)
.. role:: xref(numref)
.. Copyright (C) 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:|||`\ Emacs Package
##################################################

.. . (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

.. \|:here:|

.. >>CODD Introduction
.. >>CODD Chapter

==================================================
:rem:`|||:sec:|||`\ Quickstart
==================================================

.. |tinker-with-emacs| replace:: Start tinkering with the *satoku matrix* in Emacs by loading

.. only:: html

   |tinker-with-emacs| `satoku.el <_static/satoku.el>`_:

.. only:: latex

   |tinker-with-emacs| `satoku.el (ext) <https://sw-amt.ws/satoku/doc/_build/html/_static/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
as shown in :xref:`fig:Satoku matrix with single clause sub-matrix`.

.. _`fig:Satoku matrix with single clause sub-matrix`:

.. code-block:: text
   :caption: Satoku matrix with single clause sub-matrix

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

Position point at the first :kbd:`*` 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.

.. raw:: latex

   \pagebreak[4]

To extend the matrix with another 3x3 clause sub-matrix, as shown in
:xref:`fig:Extend matrix with 3x3 clause sub-matrix`, press
:kbd:`C-u 3 > >`.

.. _`fig:Extend matrix with 3x3 clause sub-matrix`:

.. code-block:: text
   :caption: Extend matrix with 3x3 clause sub-matrix

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

Press :kbd:`> >` to get a separator line as shwon in :xref:`fig:Satoku
matrix with separator line`.

.. _`fig:Satoku matrix with separator line`:

.. code-block:: text
   :caption: Satoku matrix with separator line

    // |    ||   S||  0|   0|| 1 1 1 | 1 1 1 ||
    // +----++----++---+----++-------+-------++
    // +-----+----++---+----++-------+-------++
    // |  0 H|   0||   |    || 1 * * | _ _ _ ||
    // |     |   1||   |    || * 1 * | _ _ _ ||
    // |     |   2||   |    || * * 1 | _ _ _ ||
    // +-----+----++---+----++-------+-------++
    // |  1 H|   0||   |    || _ _ _ | 1 * * ||
    // |     |   1||   |    || _ _ _ | * 1 * ||
    // |     |   2||   |    || _ _ _ | * * 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 state conflicts, :kbd:`-` to clear a
state. (Mirror states are automatically changed accordingly.)

Do not use :kbd:`1` to mark required states. Exclude all other states
with :kbd:`0` instead as shown in :xref:`fig:Satoku matrix with
required state by exclusion`.

.. _`fig:Satoku matrix with required state by exclusion`:

.. code-block:: text
   :caption: Satoku matrix with required state by exclusion

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

.. raw:: latex

   \pagebreak[4]

Then press :kbd:`r u` to run the requirements update algorithm, which
detects and fills in the *hard one* requirements as shown in
:xref:`fig:Satoku matrix with refreshed requirements propagation`.

.. _`fig:Satoku matrix with refreshed requirements propagation`:

.. code-block:: text
   :caption: Satoku matrix with updated requirement propagation

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

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.

.. >>CODD Conclusion
.. >>CODD Appendix A

.. \|:here:|

.. >>CODD Notes
.. ==================================================
.. :rem:`|||:sec:|||`\ Footnotes
.. ==================================================

:html:`<hr>`

.. \[#]

.. \|: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