Documentation Standard

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

There is a PDF version of this document available.


Single shot standalone document:

sda chapter new 'Doc Title'        # => README-doc-title.txt

sda readme README-doc-title.txt              # => README-doc-title.html
sda readme -f p README-doc-title.txt         # => README-doc-title.pdf
sda readme --format pdf README-doc-title.txt # => README-doc-title.pdf

Book w/chapter documents:

sda init  "Project Title"          # => README.txt + doc/
sda chapter add "Title"            # => add chapter README-title.txt
sda automodule MODULE              # => module documentation from template

sda make html                      # => doc/_build/html/
sda make latexpdf                  # => doc/_build/latex/

sda view html                      # xdg-open 'doc/_build/html/index.html'
sda view pdf                       # xdg-open "$(  echo doc/_build/latex/*.aux | sed 's,\.aux$,\.pdf,;1q' )"

sda make clean                     # remove generated files => rm -rf doc/_build/
                                   # (necesary, when e.g., new chapters are added)

Update sphinx-doc framework for book documents (requires manual resolution!):

sda update                         # => book/README.txt + book/doc (re-created for update)

Find sphinx-doc directories:

sda locate --home
sda locate --sed SCRIPT

sda locate --grep [OPTIONS] [PATTERN]


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



see Abbreviation
Eclipse Advanced Scripting Environment
see HyperText Markup Language
Hypertext Transfer Protocol
Integrated Development Environment
see Joint Photographic Experts Group
Portable Document Format
see Portable Network Graphics
Representational State Transfer
Remote Procedure Call
see Specification and Description Language
Standard Generalized Markup Language
Scalable Vector Graphics
see Extensible Markup Language



As Wikipedia describes it[WPABBR]:

An abbreviation (from Latin brevis, meaning short) is a shortened form of a word or phrase. It consists of a group of letters taken from the word or phrase. For example, the word abbreviation can itself be represented by the abbreviation abbr., abbrv., or abbrev.
Extensible Markup Language
An SGML application like HTML.
HyperText Markup Language
An SGML application.
Joint Photographic Experts Group
Norm ISO/IEC 10918-1, image file format
Portable Network Graphics
An image file format (.PNG)
Specification and Description Language

A standardized language, described by Wikipedia[WPSDL]:

As of 2016 its current areas of application include process control and real-time applications in general. Due to its nature it can be used to represent simulation systems without ambiguity and with a graphical notation.


[DICTTERM], LLC. Term, Definition of Term at Retrieved 12:52, May 27, 2019, from
[WPSDL]Wikipedia contributors. (2019, March 26). Specification and Description Language. In Wikipedia, The Free Encyclopedia. Retrieved 15:46, August 25, 2019, from
[WPABBR]Wikipedia contributors. (2019, May 9). Abbreviation. In Wikipedia, The Free Encyclopedia. Retrieved 15:58, May 21, 2019, from <>
[WPTERM]Wikipedia contributors. (2019, May 15). Terminology. In Wikipedia, The Free Encyclopedia. Retrieved 12:52, May 27, 2019, from
[TORC]Torczyner, Harry. Magritte: Ideas and Images. p. 71. ISBN 978-0-8109-1300-4.