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












.. role:: sref(numref)
.. role:: xref(numref)
.. Copyright (C) 2023, 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:|||`\ rst-mode etags Support
##################################################
.. >>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::

   .. \|:here:|

.. >>CODD Introduction

==================================================
:rem:`|||:sec:|||`\ Resources
==================================================

- :file:`README-rst-mode-etags-support.txt`
- :file:`bin/diffmap.py`
- :file:`bin/rst_tags.py`
- :file:`_static/rst-TAGS linked to TAGS`

.. _`fig:workspace register setup`:
.. code-block:: elisp
   :caption: workspace register setup

   (workspace-set-locations '(
    ("/home/sw/project/documentation/README-rst-mode-etags-support.txt" 5122 "README-rst-mode-etags-support.txt" 49 nil)
    ("/home/ws/project/documentation/bin/rst_tags.py" 15145 "rst_tags.py" 50 nil)
    ("/home/ws/project/documentation/bin/diffmap.py" 3482 "diffmap.py" 51 nil)
    ("/home/sw/project/documentation/_static/rst-TAGS" 1 "rst-TAGS" 55 nil)
   ) nil t t)

After evaluating the expression in :xref:`fig:workspace register
setup` (:kbd:`C-x C-e` at end of expression, or copy expression,
:kbd:`M-:`, yank expresssion, :kbd:`RET`),

.. code-block:: text

   +-------+-------+-------+
   |       |       |   9   |
   |       |   8   |       |
   |   7 _____________________ • /home/sw/project/documentation/_static/rst-TAGS
   +-------+-------+-------+
   |       |       |   6   |
   |       |   5   |       |
   |   4   |       |       |
   +-------+-------+-------+
   |       |       |   3 _____ • /home/ws/project/documentation/bin/diffmap.py
   |       |   2 _____________ • /home/ws/project/documentation/bin/rst_tags.py
   |   1 _____________________ • /home/sw/project/documentation/README-rst-mode-etags-support.txt
   +-------+-------+-------+
   |       |
   |   0   |
   |       |
   +-------+

.. . ||:here:||

.. >>CODD Chapter

==================================================
:rem:`|||:sec:|||`\ etags Interface
==================================================

A special include entry is useful to combine several files:

.. literalinclude:: _static/include-TAGS-emacs.txt

This file should be installed in directory :file:`"${HOME}/project"`
as :file:`TAGS` with:

.. include:: _static/include-TAGS.inc

:kbd:`M-x t-r-t-t` expands to :func:`tags-reset-tags-tables` which
allows changing the active TAGS file.

The Emacs rst tags support is supplied by
:func:`find-tag-default-rst`, which is already integrated in package
emacs-init.

Etags generation is provided by :program:`rst_tags.py`, which is also
integrated in the snippets framework:

.. code-block:: sh

   sda make tags

For this to work, a project update (:samp:`sda update`) might be
needed, or the `tags` rule can be extracted from the snippet with:

.. code-block:: sh

   snc -m mak '^mak_sphinx.makefile-footer$' | sed '/^tags:/p;1,/tags:/d' | sed '/^ *$/,$d'

which at the time of this rendering was:

.. code-block:: makefile


--------------------------------------------------
:rem:`||:sec:||`\ TAGS File Structure
--------------------------------------------------

A TAGS file has one or more entries describing the tags in a file, see
e.g. `Understanding the 'ctags -e' file format (ctags for emacs) -
Stack Overflow
<https://stackoverflow.com/questions/1990579/understanding-the-ctags-e-file-format-ctags-for-emacs>`_.

An etags file entry consists of

.. code-block:: text

   <\014> file name "," size of following tag entries

An etags tag entry has the following structure:

.. code-block:: text

   line text <\177> tag <\001> line no (1-based) "," char position (0-based)

.. _`sec:Sample TAGS File`:

--------------------------------------------------
:rem:`||:sec:||`\ Sample TAGS File
--------------------------------------------------

The TAGS file as seen in Emacs:

.. literalinclude:: _static/rst-TAGS-emacs.txt

The TAGS file with special characters represented as octal escape sequences in brackets:

.. literalinclude:: _static/rst-TAGS.txt

.. . ||:here:||

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

==================================================
:rem:`|||:sec:|||`\ diffmap
==================================================

.. automodule:: diffmap
   :members:

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