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.

Quickstart

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]

Abstract

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

Contents

Abbreviations

abbr
see Abbreviation
EASE
Eclipse Advanced Scripting Environment
HTML
see HyperText Markup Language
HTTP
Hypertext Transfer Protocol
IDE
Integrated Development Environment
JPEG
see Joint Photographic Experts Group
PDF
Portable Document Format
PNG
see Portable Network Graphics
REST
Representational State Transfer
RPC
Remote Procedure Call
SDL
see Specification and Description Language
SGML
Standard Generalized Markup Language
SVG
Scalable Vector Graphics
XML
see Extensible Markup Language

Glossary

Abbreviation

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.

References

[DICTTERM]Dictionary.com, LLC. Term, Definition of Term at Dictionary.com. Retrieved 12:52, May 27, 2019, from https://www.dictionary.com/browse/term
[WPSDL]Wikipedia contributors. (2019, March 26). Specification and Description Language. In Wikipedia, The Free Encyclopedia. Retrieved 15:46, August 25, 2019, from https://en.wikipedia.org/w/index.php?title=Specification_and_Description_Language&oldid=889575411
[WPABBR]Wikipedia contributors. (2019, May 9). Abbreviation. In Wikipedia, The Free Encyclopedia. Retrieved 15:58, May 21, 2019, from <https://en.wikipedia.org/w/index.php?title=Abbreviation&oldid=896285984>
[WPTERM]Wikipedia contributors. (2019, May 15). Terminology. In Wikipedia, The Free Encyclopedia. Retrieved 12:52, May 27, 2019, from https://en.wikipedia.org/w/index.php?title=Terminology&oldid=897146677
[TORC]Torczyner, Harry. Magritte: Ideas and Images. p. 71. ISBN 978-0-8109-1300-4.