From e04356fc52a5f4eed6e6cc415d433b249b31d6ab Mon Sep 17 00:00:00 2001 From: Jason Eisner Date: Mon, 29 Jul 2013 15:42:35 -0400 Subject: [PATCH] Filled in spec outline in Sphinx documentation. Other small changes to documentation organization, configuration, comments, emacs -*- settings, --- docs/sphinx/conf.py | 5 +- docs/sphinx/index.rst | 35 +- docs/sphinx/manual/builtins.rst | 1 + docs/sphinx/manual/index.rst | 1 + docs/sphinx/manual/pragmas.rst | 1 + docs/sphinx/spec/glossary.rst | 5 +- docs/sphinx/spec/index.rst | 514 +++++++++++++++++++++++++++++- docs/sphinx/spec/syntax.rst | 1 + docs/sphinx/tutorial/dijkstra.rst | 1 + docs/sphinx/tutorial/errors.rst | 1 + docs/sphinx/tutorial/hello.rst | 1 + docs/sphinx/tutorial/index.rst | 3 + 12 files changed, 554 insertions(+), 15 deletions(-) diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py index 5b8acf4..05278bb 100644 --- a/docs/sphinx/conf.py +++ b/docs/sphinx/conf.py @@ -95,8 +95,11 @@ exclude_patterns = ['_build'] # output. They are ignored by default. #show_authors = False +# Default language for syntax highlighting +highlight_language = 'none' # eventually change to 'dyna' + # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +# pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] diff --git a/docs/sphinx/index.rst b/docs/sphinx/index.rst index 81bbe05..155baf9 100644 --- a/docs/sphinx/index.rst +++ b/docs/sphinx/index.rst @@ -1,23 +1,32 @@ -.. Dyna2 documentation master file +.. -*- compile-command: "make html" -*- +.. Dyna documentation master file -Welcome to Dyna2's documentation! +.. todo:: use a theme. At the moment I followed the suggestion in + sampledoc to copy stuff from the sphinx documentation, but + nowadays there is explicit support for themes (I like + "agogo" or "sphinxdoc"), as explained in the sphinx manual. + +Welcome to Dyna! ================================= -Dyna2 is an experimental new logic programming language developed at -`Johns Hopkins University `_ +Dyna is an new declarative programming language developed at +`Johns Hopkins University `_. + +This site documents the new version being developed at http://github.com/nwf/dyna. +The new version has been used to teach but is not yet complete or +efficient; you may file issues at http://github.com/nwf/dyna/issues. +An older design with a fairly efficient compiler can be found at http://dyna.org. .. warning:: Please be advised that this documentation, the implementation, and indeed the language itself are rapidly changing. -.. warning:: Attempting to run Dyna programs may often crash our interpreter - or yield programs which run forever. (In the latter case, Control-C will - stop the program's execution.) If either of these things happen - unexpectedly, please contact a TA. +.. warning:: Some programs may not terminate. Control-C will + interrupt the program's execution. Contents: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 tutorial/index @@ -27,9 +36,17 @@ Contents: Bibliography +.. todo:: add a "cookbook" that shows how to accomplish various common tasks +.. todo:: not sure whether we want a top-level bibliography +.. todo:: We may want to generate a separate PDF file for each directory + + Indices and tables ================== +* :doc:`spec/glossary` * :ref:`genindex` * :ref:`search` +.. todo:: should we also try to add something like the automatic + Python module index (modindex), but for dynabases? diff --git a/docs/sphinx/manual/builtins.rst b/docs/sphinx/manual/builtins.rst index a154492..6ce54e1 100644 --- a/docs/sphinx/manual/builtins.rst +++ b/docs/sphinx/manual/builtins.rst @@ -1,3 +1,4 @@ +.. -*- compile-command: "make -C .. html" -*- .. Builtins Here we describe the primitives available by default. diff --git a/docs/sphinx/manual/index.rst b/docs/sphinx/manual/index.rst index ecaf535..344eaa8 100644 --- a/docs/sphinx/manual/index.rst +++ b/docs/sphinx/manual/index.rst @@ -1,3 +1,4 @@ +.. -*- compile-command: "make -C .. html" -*- .. Manual index This file is enumerated in the toctree directive of index.rst diff --git a/docs/sphinx/manual/pragmas.rst b/docs/sphinx/manual/pragmas.rst index 647a802..5b58a05 100644 --- a/docs/sphinx/manual/pragmas.rst +++ b/docs/sphinx/manual/pragmas.rst @@ -1,3 +1,4 @@ +.. -*- compile-command: "make -C .. html" -*- .. Pragmas This file documents the pragma assertions our pipeline understands. diff --git a/docs/sphinx/spec/glossary.rst b/docs/sphinx/spec/glossary.rst index c08f965..0056416 100644 --- a/docs/sphinx/spec/glossary.rst +++ b/docs/sphinx/spec/glossary.rst @@ -1,8 +1,9 @@ +.. -*- compile-command: "make -C .. html" -*- .. Spec glossary This file is enumerated in the toctree of spec/index.rst -Specification Glossary -###################### +Dyna Glossary +############# .. glossary:: diff --git a/docs/sphinx/spec/index.rst b/docs/sphinx/spec/index.rst index dbe48a7..a65db77 100644 --- a/docs/sphinx/spec/index.rst +++ b/docs/sphinx/spec/index.rst @@ -1,10 +1,518 @@ +.. -*- compile-command: "make -C .. html" -*- .. Specification index This file is enumerated in the toctree directive of index.rst -Specifications -############## +.. todo:: + Fill in to-do items from various sources, then break this into + multiple files. (I believe that in the HTML rendering, each file is a webpage.) + +################################## +Specification of the Dyna Language +################################## + +************ +Introduction +************ + +What is Dyna? +============= + +.. todo:: keep it brief + +Intended users +============== + +Key features +============ + +Relation to other work +====================== + +.. todo:: where to learn more + +******************************** + How to read this specification +******************************** + +Organization +============ +.. todo:: Reading in order is ok + +Notation +======== +.. todo:: Unless otherwise noted, we'll spell things using default syntax table. + +User comments +============= + +Coloring and formatting conventions +=================================== + +Cross-refs +========== + +Sidebars +======== + +Notifications +============= +.. todo: deprecation, bugs, future work + +Links to examples +================= + +Links to issue tracker +====================== + +Glossary/Index +============== + +*************************** +Terms (i.e., ground terms) +*************************** + +Overview +======== + +Primitive terms +=============== + +Booleans +-------- + +Numbers +------- + +Strings +------- + +Escape codes +^^^^^^^^^^^^ +.. todo:: including \' and \" -- borrow from Python + +Blobs +----- + +Compound terms +============== + +.. todo:: Note: We'll use the format foo[3,4] or foo[] + +Functors +-------- + +Single quotes +^^^^^^^^^^^^^ +.. todo:: Escape codes as for strings except we need \' +.. todo:: What space are these in? How do they relate to strings and dynabases? See https://github.com/nwf/dyna/issues/49] + + +Positional arguments +-------------------- + +Operator syntax +^^^^^^^^^^^^^^^ + +Keyword arguments +----------------- + +List syntax +----------- + +Reserved functors +----------------- + +``$`` convention +^^^^^^^^^^^^^^^^ + +``$error`` +^^^^^^^^^^ + +``$null`` +^^^^^^^^^ + +Dynabases +========= + +Full discussion in :ref:`frozen`. + +Frozen terms +============ + +Full discussion in :ref:`dynabase`. + + +********************************* +Patterns (i.e., non-ground terms) +********************************* + +Variables +========= + +Variable names +-------------- + +Underscores +----------- + +Non-ground terms +================ + +Types +===== + +Type declarations +----------------- + +Typed variables +--------------- + +Co-inductive types +------------------ + +Possible future extensions +-------------------------- +Guarded types? Nonlinear types? Parametric types? + +Type coercion +============ + + +Unification +=========== + +.. _frozen: + +Frozen terms +============ + +.. _dynabase: + +********* +Dynabases +********* + +Overview +======== + + +Items +===== + +Null items +---------- + +Syntax for items +================ + +.. todo:: possibly mention :ref:`dispos` + +Brackets vs. parentheses +------------------------ + +Quoting items with ``&`` +------------------------ + +Evaluating terms with ``*`` +--------------------------- + +Queries +======= + +Simple queries +-------------- + +Complex queries +--------------- +.. todo:: joins with commas + +Expressions +----------- +.. todo:: (auto-evaluation) ("nested queries") + +Aggregating queries +------------------- + +Accessors +--------- +.. todo:: Dot and arrow expressions to access elements of a dynabase + +Query modes +=========== + +Some discussion of current approach is in :doc:`/manual/pragmas`. + +.. todo:: + Language for specifying modes as generalization of types. + Output format: Finite, sorted, consolidated, ground, etc. + Det/semidet/etc. Overall, or per-variable? What if it binds a sequence of variables? + +Lambdas +======= + +Terms as dynabases +================== +.. todo:: querying and destructuring terms + +Updates +======= +.. todo:: Ownership [forward reference] + +Update modes +============ +.. todo:: must discuss aggregators as well as groundedness and form of body + +Stability +========= +.. todo:: guarantees on queries (what can change as a result of updates; is a := update a definite override?) + +Dynabase types +============== +.. todo:: i.e., advertised public interface + +Extensions +========== + +Const declaration +----------------- + +Snapshots +========= + +************************************ + Inspecting and modifying dynabases +************************************ + +Abstract API +============ + +.. todo:: this is really described above. +.. todo:: Discuss ad hoc, continuous, peeking queries. + +Command line interface +====================== + +Graphical interface +=================== + +Programming interface +===================== + +*************** + Dyna programs +*************** + + +Programs +======== + +File format +=========== +.. todo:: UTF-8, BOM +.. todo:: #! and possibly multiline #! + +Rules +===== + +Definition +---------- + +Aggregation +----------- + +Semantics +--------- + +Cycles +^^^^^^ + +Errors +^^^^^^ + +See discussion of current implementation in :doc:`/tutorial/errors`. + +Head destructuring +------------------ + +Dynabase literals +================= + +Syntax +------ + +Ownership +--------- + +Semantics +--------- + +Declarations +============ + +Some documentation of currently implemented declarations is in :doc:`/manual/pragmas`. + + +Type declarations +----------------- +.. todo:: [backward reference] - maybe uses const defs + +.. _dispos: + +Evaluation declarations +----------------------- + +There is currently some documentation in :doc:`syntax`. + + +Default arguments +----------------- +.. todo:: in constructors + + +Visibility declarations +----------------------- +.. todo:: readable, writeable + +Const +----- + +Import +------ + +Syntax declarations +------------------- +.. todo:: forward ref +.. todo:: Which things affect only subsequent lines? + +Declaring new aggregators +------------------------- + + +Scripting commands +================== + +Include +======= +.. todo:: what is interaction with syntax table? + + +Foreign function interface +========================== + +*************** +Concrete syntax +*************** + +Overview +======== + +Standard syntactic sugar +======================== + +Default syntax table +==================== + +Changing the syntax table +========================= + +Printing +======== + +Readable printing +----------------- + +Prettyprinting +-------------- + +****************** + Standard library +****************** + +There is currently some documentation in :doc:`/manual/builtins`. + +Generic operators and aggregators +================================= + +.. todo:: :=, =, ?=, comma/for + +Boolean operators and aggregators +================================= + +Numeric operators and aggregators +================================= + +Randomness +========== + +String operators and aggregators +================================ + +Array operators and aggregators +=============================== + +Set operators and aggregators +============================= + +Graph operators and aggregators +=============================== + +Other standard encodings +======================== +.. todo:: see ~/jot/dyna 12/14/12 et seq. + +****************************** + Inspecting program execution +****************************** + +$rule +===== + +Voodoo items +============ + +Reflection on types, modes, cost estimates, cardinality estimates, plans, etc. +============================================================================== + +******************************* + Controlling program execution +******************************* + +Storage classes +=============== + +Priorities +========== + +Query costs and plans +===================== + +Features for learning +===================== + +***************** +Foreign dynabases +***************** + +Files +===== + +Processes +========= + +Sockets +======= + +Servers +======= + +********** +Appendices +********** .. toctree:: - syntax glossary + + + + diff --git a/docs/sphinx/spec/syntax.rst b/docs/sphinx/spec/syntax.rst index 8541cab..8409fcd 100644 --- a/docs/sphinx/spec/syntax.rst +++ b/docs/sphinx/spec/syntax.rst @@ -1,3 +1,4 @@ +.. -*- compile-command: "make -C .. html" -*- .. Syntax ****** diff --git a/docs/sphinx/tutorial/dijkstra.rst b/docs/sphinx/tutorial/dijkstra.rst index 5eb4d74..7e98d09 100644 --- a/docs/sphinx/tutorial/dijkstra.rst +++ b/docs/sphinx/tutorial/dijkstra.rst @@ -1,3 +1,4 @@ +.. -*- compile-command: "make -C .. html" -*-g .. Dijkstra tutorial page This file is enumerated in the toctree of tutorial/index.rst diff --git a/docs/sphinx/tutorial/errors.rst b/docs/sphinx/tutorial/errors.rst index 53c647a..6788ad8 100644 --- a/docs/sphinx/tutorial/errors.rst +++ b/docs/sphinx/tutorial/errors.rst @@ -1,3 +1,4 @@ +.. -*- compile-command: "make -C .. html" -*- .. Tutorial chapter on errors This file is enumerated in the toctree directive of /tutorial/index.rst diff --git a/docs/sphinx/tutorial/hello.rst b/docs/sphinx/tutorial/hello.rst index 012fe3e..6b9c627 100644 --- a/docs/sphinx/tutorial/hello.rst +++ b/docs/sphinx/tutorial/hello.rst @@ -1,3 +1,4 @@ +.. -*- compile-command: "make -C .. html" -*- .. Hello World tutorial page This file is enumerated in the toctree of tutorial/index.rst diff --git a/docs/sphinx/tutorial/index.rst b/docs/sphinx/tutorial/index.rst index 4a601e6..5c3b9ef 100644 --- a/docs/sphinx/tutorial/index.rst +++ b/docs/sphinx/tutorial/index.rst @@ -1,9 +1,12 @@ +.. -*- compile-command: "make -C .. html" -*- .. Tutorial index This file is enumerated in the toctree directive of /index.rst Tutorial ######## +.. warning:: This tutorial is incomplete. + .. toctree:: hello -- 2.50.1