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












.. role:: sref(numref)
.. role:: xref(numref)
.. Copyright (C) 2019, Wolfgang Scherer, <Wolfgang.Scherer at gmx.de>
..
.. This file is part of Documentation Standard.
..
.. 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:: xnarrow xmedium large xhuge xultra

######################################################
:rem:`|||:sec:|||`\ Figures
######################################################
.. >>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
.. compound::

   For best results, figures, tables and code blocks should get
   captions and they should be referenced with and ``:xref:`` for
   figures/tables/code-blocks (`:sref:` for sections).  ``:xref:`` and
   ``:sref:`` are defined as ``:numref:``, when appropriate, otherwise
   as ``:ref:``. Do not use the ``image`` directive to keep figures in
   place.

   Label prefixes allow using the same caption for different entities,
   e.g., listing and figure (see :sref:`sec:Directive figure`).

   Emacs support functions for generating labels and their shortcuts are shown in
   :xref:`tab:Emacs support functions for generating labels`.

   .. _`tab:Emacs support functions for generating labels`:
   .. table:: Emacs support functions for generating labels

      +------------------+-----------------------------------+
      | shortcut         | command                           |
      +==================+===================================+
      | :kbd:`C-c r l s` | :kbd:`M-x sdx-make-section-label` |
      +------------------+-----------------------------------+
      | :kbd:`C-c r l f` | :kbd:`M-x sdx-make-figure-label`  |
      +------------------+-----------------------------------+
      | :kbd:`C-c r l t` | :kbd:`M-x sdx-make-table-label`   |
      +------------------+-----------------------------------+
      | :kbd:`C-c r l l` | :kbd:`M-x sdx-make-listing-label` |
      +------------------+-----------------------------------+
      | :kbd:`C-c r l c` | :kbd:`M-x sdx-make-caption-label` |
      +------------------+-----------------------------------+
      | :kbd:`C-c r l r` | :kbd:`M-x sdx-make-figctr-label`  |
      +------------------+-----------------------------------+

   .. \|:here:|

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

.. _`sec:Figures with numbers`:

==================================================
:rem:`|||:sec:|||`\ Figures with numbers
==================================================

Sphinx allows certain entities to be referenced by number (see
:xref:`fig:Numeric references example`).

.. _`fig:Numeric references example`:
.. figctr:: Numeric references example

   .. code-block:: rst

      See :xref:`fig:UML test` in :sref:`sec:Directive uml`.

   renders as:

   See :xref:`fig:UML test` in :sref:`sec:Directive uml`.

This requires the option :data:`numfig` to be set to `True` in
:file:`conf.py` as shown in :xref:`lst:option numfig in fileconfpy`.

.. _`lst:option numfig in fileconfpy`:
.. code-block:: python
   :caption: option `numfig` in :file:`conf.py`
   :linenos:

   numfig = True
   numfig_format = {
       'section': 'section {number}, {name}',
       'figure': 'figure %s',
       'table': 'table %s',
       'code-block': 'listing %s',
   }

The supported entities are:

- **section** labels.

- Directive **figure** with filename as arguments, first paragraph in
  body as title, other pragraphs as legend (see :sref:`sec:Directive
  figure`).

- Directive **table** with title (caption) as arguments, body must
  contain a table (see :sref:`sec:Directive table`).

- Directive **code-block** with option `:caption:` (see
  :sref:`sec:Directive code-block`).

- Directive **uml** with option `:caption:` in `figure` namespace (see
  :sref:`sec:Directive uml`).

- Directives **graphviz**, **dot** with option `:caption:` in
  `figure` namespace (see :sref:`sec:Directives graphviz dot`).

- Directive **figctr** with title (caption) as arguments in `figure`
  namespace. Body contains arbitrary material (see
  :sref:`sec:Directive figctr`).

.. _`sec:Directive figure`:

--------------------------------------------------
:rem:`||:sec:||`\ Directive `figure`
--------------------------------------------------

As documented in `reStructuredText Directives, figure`_. See
:xref:`lst:Figure example Magrittes Pipe`) and :xref:`fig:Figure
example Magrittes Pipe`).

- **always** use **fig:** prefix for label

.. _`lst:Figure example Magrittes Pipe`:
.. code-block:: rest
   :caption: Figure example Magritte's Pipe
   :linenos:

   .. _`fig:Figure example Magrittes Pipe`:
   .. figure:: _static/MagrittePipe.jpg

      Figure example Magritte's Pipe

.. _`fig:Figure example Magrittes Pipe`:
.. figure:: _static/MagrittePipe.jpg

   Figure example Magritte's Pipe

.. _`reStructuredText Directives, figure`: http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure

.. _`sec:Directive table`:

--------------------------------------------------
:rem:`||:sec:||`\ Directive `table`
--------------------------------------------------

The body must contain a table, however, a single table cell
(rectangle) is sufficient (see :xref:`lst:table directive with single
table cell rectangle` and :xref:`tab:single table cell rectangle`).

- **always** use **tab:** prefix for label

.. _`lst:table directive with single table cell rectangle`:
.. code-block:: rest
   :caption: ``table`` directive with single table cell (rectangle)
   :linenos:

   .. _`tab:single table cell rectangle`:
   .. table:: single table cell (rectangle)

      +-----------------------+
      | .. code-block:: text  |
      |                       |
      |    code-block without |
      |    caption inside a   |
      |    single table cell  |
      +-----------------------+

.. _`tab:single table cell rectangle`:
.. table:: single table cell (rectangle)

   +-----------------------+
   | .. code-block:: text  |
   |                       |
   |    code-block without |
   |    caption inside a   |
   |    single table cell  |
   +-----------------------+

.. _`sec:Directive code-block`:

--------------------------------------------------
:rem:`||:sec:||`\ Directive `code-block`
--------------------------------------------------

`code-block` directives with a `:caption:` option can be referenced by
number, e.g., *"See :xref:`lst:Definition of a general code-block listing`"*: renders as |cb-ref|.

.. |cb-ref| replace:: "See :xref:`lst:Definition of a general code-block listing`"

- **always** use **lst:** prefix for label
- **always** specify language
- **always** use option `:linenos:`

.. _`lst:Definition of a general code-block listing`:
.. code-block:: rest
   :caption: Definition of a general code-block listing
   :linenos:

   .. _`lst:<LABEL>`:
   .. code-block:: <LANGUAGE>
      :caption: <TITLE>
      :linenos:

      <BODY>

An example is shown in :xref:`lst:Example with Elisp code`.

.. _`lst:Example with Elisp code`:
.. code-block:: rest
   :caption: Example with Elisp code
   :linenos:

   .. _`lst:Some Emacs Lisp code`:
   .. code-block:: elisp
      :caption: Some Emacs Lisp code
      :linenos:

      (if (not nil)
         (let (x) (princ x))
        (let(y) princ y))

The rendered example is shown in :xref:`lst:Some Emacs Lisp code`.

.. _`lst:Some Emacs Lisp code`:
.. code-block:: elisp
   :caption: Some Emacs Lisp code
   :linenos:

   (if (not nil)
      (let (x) (princ x))
     (let(y) princ y))

.. _`sec:Directive uml`:

--------------------------------------------------
:rem:`||:sec:||`\ Directive `uml`
--------------------------------------------------

The `uml` directive for plantuml(1) diagrams also works as figure, as
shown in :xref:`lst:uml directive for plantuml1 diagrams` and :xref:`fig:UML test`.

- **always** use **fig:** prefix for label

.. _`lst:uml directive for plantuml1 diagrams`:
.. code-block:: rest
   :caption: ``uml`` directive for plantuml(1) diagrams
   :linenos:

   .. _`fig:UML test`:
   .. uml::
      :caption: UML test

      @startuml
      A --> B : send
      A <-- B : receive
      @enduml

.. _`fig:UML test`:
.. uml::
   :caption: UML test

   @startuml
   A --> B : send
   A <-- B : receive
   @enduml

.. _`sec:Directives graphviz dot`:

--------------------------------------------------
:rem:`||:sec:||`\ Directives `graphviz`, `dot`
--------------------------------------------------

Obviously, the `graphviz` directive for dot(1) diagrams also works as
figure, as shown in :xref:`lst:graphviz directive for dot1 graph
diagrams` and :xref:`fig:dot test`.

- **always** use **fig:** prefix for label

.. _`lst:graphviz directive for dot1 graph diagrams`:
.. code-block:: rest
   :caption: `graphviz` directive for dot(1) graph diagrams
   :linenos:

   .. _`fig:dot test`:
   .. graphviz::
      :caption: dot test

      digraph xx {
      A -> B;
      }

.. _`fig:dot test`:
.. graphviz::
   :caption: dot test

   digraph xx {
   A -> B;
   }

.. _`sec:Directive figctr`:

--------------------------------------------------
:rem:`||:sec:||`\ Directive `figctr`
--------------------------------------------------

Since single cell tables end up in the table namespace, the extension
`ws_figure_container` provides the ``figctr`` directive, which works
like a container in the figure namespace (see :xref:`lst:figctr
directive` and :xref:`fig:Fig Ctr Caption`).

.. _`lst:figctr directive`:
.. code-block:: rst
   :caption: ``figctr`` directive

   .. _`fig:Fig Ctr Caption`:
   .. figctr:: Fig Ctr Caption

      Arbitrary things like this:

      .. code-block:: sh

         if test -r "file"
         then
             cat "file"
         fi

.. _`fig:Fig Ctr Caption`:
.. figctr:: Fig Ctr Caption

   Arbitrary things like this:

   .. code-block:: sh

      if test -r "file"
      then
          cat "file"
      fi

==================================================
:rem:`|||:sec:|||`\ See also
==================================================

- `How to number figures in Sphinx. How to do subfigures`_

.. _`How to number figures in Sphinx. How to do subfigures`: https://gist.github.com/sstirlin/9127984

.. _`sec:Check README for figure requirements`:

========================================================
:rem:`|||:sec:|||`\ Check README for figure requirements
========================================================

Before a README is done, it is useful to check, if every figure has a
caption, directive and a reference.

       figure-regexp::

           ^ *\([.][.]  *\(\(table\|figure\|uml\|graphviz\|graph\|digraph\)::\|_`\(tab\|fig\):\)\|:caption:\)\|:xref:

        figure-grep-cmd::

          /bin/grep --color -nH README-fillme.txt -e '{figure-regexp}'

        Search with

        - :kbd:`M-x occur RET {figure-regexp} RET`
        - :kbd:`M-x grep RET {figure-grep-cmd} RET`

        - For creating figure labels, use emacs commands

          - :kbd:`C-c r l c`, :kbd:`M-x sdx-make-caption-label`
          - :kbd:`C-c r l f`, :kbd:`M-x sdx-make-figure-label`
          - :kbd:`C-c r l t`, :kbd:`M-x sdx-make-table-label`

        See :xref:`fig:complete figure requirements`

        .. _`fig:complete figure requirements`:
        .. uml::
           :caption: complete figure requirements

            @startuml
            package "complete figure requirements" {
              start
              floating note right
              figure requirements:
              * caption
              * directive
              * reference
              end note
              :grep for uml/table (figure-regexp);
              while (for each matched directive line) is (do)
                while (caption, label or reference is missing?)
                  if (caption is missing?) then (yes)
                  :* add caption
                  * correct label, if present
                  * correct reference, if present;
                  elseif (label is missing?) then (yes)
                  :* move before figure
                  * add label with `C-c r l [cft]`
                  * correct reference, if present;
                  else (reference\nis missing)
                  :add reference;
                  endif
                end while
              end while
              stop
            }
            @enduml

==========================================================
:rem:`|||:sec:|||`\ Templating with automatic labels (NO!)
==========================================================

| |:q:| |:da:| :kbd:`f5` Sections (:kbd:`3`, :kbd:`4`, :kbd:`5`) yank a new section title, why not also a .. _`sec:fillme`: above it?
| |:a:| because:

- Do not inflate the use of section labels! if a section is **not** referenced, it should **not** have a label.
- Why would want write the section title three times?

  The correct template would be:

  .. code-block:: rst

      :xref:`sec:::fillme::`
      .. _`sec:::fillme::`:

      ================
      :sec: ::fillme::
      ================

  Filling in the section title must be done anyway:

  - change tag delimiter to "::" (C-c C-x)
  - move to beginning of `fillme` (M-left)
  - delete `fillme` (M-k)

  Alternative 1: Copy title and replace label `fillme`

  - mark beginning of title (C-SPC)
  - enter title
  - copy title (M-w)

  - go to label `fillme` (M-left)
  - delete `fillme` (M-k)
  - insert title (C-y)

  - Clean up label (remove all non-ascii characters) 0 - aleph_0 keystrokes
  - If the title ws not clean, copy the label title (many keystrokes)

  - go to :xref: `sec:::fillme::` (M-left)
  - delete `fillme` (M-k)
  - insert title (C-y)

  Minimum keystrokes: 8, Maximum keystrokes: aleph_0

  Alternative 2: Write title and generate label with emacs function (C-c r l s)

  - enter title
  - go before :sec: line (up)
  - generate xref + label (:kbd:`C-c r l s`)

  Minimum keystrokes: 5, Maximum keystrokes: 5

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

.. \|:here:|

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

:html:`<hr>`

.. \[#]

.. include:: doc_defs.inc
.. include:: doc_defs_combined.inc
.. include:: abbrev_defs.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