viennadoc
play

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:

  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

  2. outline ● background ● demo ● ViennaDoc: overview ● html ● discussions ● summary 2

  3. background 3

  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

  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

  6. demo 6

  7. ViennaDoc: overview 7

  8. formal specification and specification document should be engaged operations The inc operation inc : () ==> nat -- increments increments the count and inc() == (count := count + 1; returns it. return count); 8

  9. ViennaDoc = HTML + VDM animation VDMPad or counter.html ViennaServer (specification document) https://vdmpad.viennatalk.org/ ViennaDoc.js /eval (animation states, DOM manipulations) counter.js ViennaClient.js (spec source) JavaScript engine Web Browser 9

  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

  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

  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

  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

  14. html 14

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

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

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

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

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

  20. discussions 20

  21. ViennaDoc vs LaTeX literate styles ● VDM spec and html ● one can choose either managed sperately monolithic or modular ● best for online browsing ● best for printing ● processed on a browser ● processed at build-time (testing/animating) (e.g. testing a doc) 21

  22. LaTeX / ViennaDoc / VDMPad Overture w/ ViennaTalk w/ VDMPad LaTeX ViennaDoc 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 22 ○ × ×

  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

  24. Summary Formal Specifications and Specification Documents 24

  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

  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

Recommend

More recommend