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












.. role:: sref(numref)
.. role:: xref(numref)
.. Copyright (C) 2018, 2019, 2021 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:: narrow xmedium xlarge xhuge xultra
.. _`sec:Documentation Standard`:

##################################################
:rem:`|||:sec:|||`\ Documentation Standard
##################################################

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

.. epigraph::

    |this is not a pipe|_ The famous pipe. How people reproached me for it! And yet, could
    you stuff my pipe? No, it's just a representation, is it not? So
    if I had written on my picture 'This is a pipe', I'd have been
    lying!

    -- René Magritte\ [TORC]_

    No software survives contact with the user.

    -- not `Helmuth von Moltke the Elder`_

.. |this is not a pipe| image:: _static/MagrittePipe.jpg
   :height: 30px

.. _`this is not a pipe`: https://en.wikipedia.org/wiki/The_Treachery_of_Images#/media/File:MagrittePipe.jpg
.. _`Helmuth von Moltke the Elder`: https://en.wikipedia.org/wiki/Helmuth_von_Moltke_the_Elder

.. >>CODD Abstract

.. raw:: html

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

.. raw:: latex

   \iffalse

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

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

.. include::  sphinx-doc-quickstart.inc

.. \|:here:|

.. raw:: latex

   \end{abstract}
   \endgroup


.. raw:: latex

   \iffalse

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

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

.. highlights::

   - Documentation is maintained in the source code and in ASCII
     files named :file:`README.txt` or :file:`README-topic.txt`,
     since binary documentation (Word, Visio) that requires a
     graphical user interface for viewing/editing is extremely
     counterprodcutive (See |chapter-relevance|).

   - `reStructuredText`_ is used as markup language. It also happens
     to be the official markup language for the `Python`_ programming language.

   - `Sphinx`_ extends the `roles`_ and `directives`_ of
     `reStructuredText`_. It converts documents and `Python`_ doc
     strings to various formats such as HTML, PDF and EPUB. (See
     |chapter-sphinx|).

   - `UML diagrams`_ are used to visualize programm design and script
     algorithms. (See |chapter-uml|).

   - `PlantUML`_ is the program of choice for converting textual
     diagram descriptions into SVG, PNG or PDF images. (See local copy
     of :download:`PlantUML Language Reference Guide
     <_static/PlantUML_Language_Reference_Guide.pdf>`).

   - |:todo:| Integrate `Lightbox2
     <https://lokeshdhakar.com/projects/lightbox2/>`_ to display full
     version of images.

   .. \|:here:|

.. _`Roles`: http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
.. _`Directives`: http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html

.. code-block:: text

   | README-redistribution-of-info-items.txt                  | * /home/sw/project/administration     | #mv# /home/da/project/documentation |

.. raw:: latex

   \end{abstract}

.. raw:: latex

   \providecommand{\sddlytoctableofcontents}{}
   \sddlytoctableofcontents


.. raw:: latex

   \iffalse

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

   \fi
.. toctree::
   :numbered:

   overview
   sphinx-doc
   sda-chapter-new-is-faulty
   figures
   citations
   glossary
   uml-annotations-line-diversion
   doc-relevance
   version-control-system
   vcs-mercurial
   vcs-git
   uml
   tools
   sphinx
   diagram-generators
   emacs-vi-eclipse
   document-snippets
   snippets
   high-contrast-colors
   x11-colors
   knowledge
   scratch
   questions
   rst-mode-etags-support

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