ViennaDoc: An Animatable and Testable Specification Documentation - - PowerPoint PPT Presentation

▶
viennadoc
SMART_READER_LITE
LIVE PREVIEW

ViennaDoc: An Animatable and Testable Specification Documentation - - PowerPoint PPT Presentation

Jul 26, 2023 102 likes •374 views

ViennaDoc: An Animatable and Testable Specification Documentation Tool Tomohiro Oda Keijiro Araki Yasuhiro Yamamoto Kumiyo Nakakoji Hiroshi Sako Han-Myung Chang Peter Gorm Larsen outline background demo ViennaDoc:

slide-1
SLIDE 1

ViennaDoc:

An Animatable and Testable Specification Documentation Tool

Tomohiro Oda Keijiro Araki Yasuhiro Yamamoto Kumiyo Nakakoji Hiroshi Sako Han-Myung Chang Peter Gorm Larsen

slide-2
SLIDE 2
  • utline
  • background
  • demo
  • ViennaDoc: overview
  • html
  • discussions
  • summary

2

slide-3
SLIDE 3

background

3

slide-4
SLIDE 4

Who cares functional specifications?

  • formal specification engineers
  • architects/designers/implementors
  • test enginners
  • document (manuals, references,...) writers
  • UI designers
  • development managers
  • product owners
  • end user representatives

4

slide-5
SLIDE 5

ViennaTalk is an environment for exploratory specification

  • communication media

○ with UI designers ... Lively Walk-Through ○ with web frontend engineers ... Webly Walk-Through ○ to fill gaps between formal engineers and stakeholders with less formal engineering background

  • powered by animation

○ using VDMJ ○ using Smalltalk transpiler ○ provides web API for animation 5

slide-6
SLIDE 6

demo

6

slide-7
SLIDE 7

ViennaDoc: overview

7

slide-8
SLIDE 8

formal specification and specification document should be engaged

  • perations

inc : () ==> nat -- increments inc() == (count := count + 1; return count); The inc operation increments the count and returns it.

8

slide-9
SLIDE 9

ViennaDoc = HTML + VDM animation

9

Web Browser JavaScript engine counter.html (specification document) ViennaClient.js ViennaDoc.js (animation states, DOM manipulations) counter.js (spec source) VDMPad or ViennaServer

https://vdmpad.viennatalk.org/

/eval

slide-10
SLIDE 10

ViennaDoc

JavaScript library enables HTML documents

  • to include specification source,
  • to insert buttons to evaluate quoted expressions, and
  • to test assertions on the browser.

10

slide-11
SLIDE 11

ViennaDoc

JavaScript library enables HTML documents

  • to include specification source,

→ to keep the document up-to-date

  • to insert buttons to evaluate quoted expressions, and
  • to test assertions on the browser.

11

slide-12
SLIDE 12

ViennaDoc

JavaScript library enables HTML documents

  • to include specification source,
  • to insert buttons to evaluate quoted expressions, and

→ to explain by animating the formal spec

  • to test assertions on the browser.

12

slide-13
SLIDE 13

ViennaDoc

JavaScript library enables HTML documents

  • to include specification source,
  • to insert buttons to evaluate quoted expressions, and
  • to test assertions on the browser.

→ to confirm consistency with the formal spec 13

slide-14
SLIDE 14

html

14

slide-15
SLIDE 15

load

<script src="ViennaClient.js"></script> <script src="ViennaDoc.js"></script> <script src="Counter.js"></script> 15

slide-16
SLIDE 16

source inclusion

<code vienna="source" src="Counter`inc"> </code> 16

slide-17
SLIDE 17

evaluation

<code vienna="eval" prestates="count" poststates="count" module="Counter"> inc() </code> 17

slide-18
SLIDE 18

watch expression

<code vienna="watch" module="Counter"> counter </code> 18

slide-19
SLIDE 19

assertion

<code vienna="assert" module="Counter" prestates="count=6" eval="mk_(reset(), count).#2"> </code> 19

slide-20
SLIDE 20

discussions

20

slide-21
SLIDE 21

ViennaDoc vs LaTeX literate styles

  • VDM spec and html

managed sperately

  • best for online browsing
  • processed on a browser

(testing/animating)

  • one can choose either

monolithic or modular

  • best for printing
  • processed at build-time

(e.g. testing a doc) 21

slide-22
SLIDE 22

LaTeX / ViennaDoc / VDMPad

22

Overture w/ LaTeX ViennaTalk w/ ViennaDoc VDMPad read VDM source

○ ○ ○

read informal text.

○ ○

△ eval a given exp

○/× ○ ○

eval a free exp

○/× ○/× ○

test a document

× ○ ×

test a spec

○/× ○/×

△ large spec

○ ○ ×

VDM++/VDM-RT

○ × ×

slide-23
SLIDE 23

Specification document in the "programming-as-common-literacy" era

Hypothetical assumptipon:

  • In near future, most stakeholders will have a certain

level of programming skills.

  • We don't have to hide formal specifications. We can

simply explain them in a plain specification language and a plain natural language. 23

slide-24
SLIDE 24

Summary Formal Specifications and Specification Documents

24

slide-25
SLIDE 25

Summary

ViennaDoc provides specification documents

  • to include VDM source for the constructs of concern,
  • to exemplify behaviors of a particular functionality, and
  • to validate the document by assertions

for readers with programming literacy skills demo page: https://viennatalk.org/ViennaDoc/counter.html 25

slide-26
SLIDE 26

We need more!

  • diagram notation like VDMPad
  • previews on ViennaTalk
  • in-browser authoring
  • testing infrastructure on CI
  • support for handy notations, e.g. markdown, pillar
  • export to static documents, e.g. epub, LaTeX, pdf
  • integration / collaboration with Paul's HTML generator
  • VDM-SL language tutorial

26