Merge pull request #1458 from AmpersandTarski/Labels-in-Documentation…

…-Generator

Labels in documentation generator

ReleaseNotes.md

@@ -1,6 +1,9 @@
 # Release notes of Ampersand
 
-## Unreleased changes
+## v5.0.1 (5 february 2024)
+- Some adaptions to w.r.t. the namespaces, in the generated funcional specification.
+
+## v5.0.0 (4 february 2024)
 
 - [Issue #1307](https://github.com/AmpersandTarski/Ampersand/issues/1307) First phase of introducing namespaces in Ampersand.
 - [Issue #1315](https://github.com/AmpersandTarski/Ampersand/issues/1315) Documentation update: landing pages for target audience, governance info for the Ampersand project added.

ampersand.cabal

@@ -5,7 +5,7 @@ cabal-version: 2.0
 -- see: https://github.com/sol/hpack
 
 name:           ampersand
-version:        5.0.0
+version:        5.0.1
 synopsis:       Toolsuite for automated design of enterprise information systems.
 description:    You can define your business processes by means of rules, written in Relation Algebra.
 category:       Database Design

docs/Examples.md

@@ -1,5 +1,5 @@
 ---
-title: Examples
+title: examples
 id: examples
 description: Examples of Ampersand programs and fragments
 ---
@@ -9,6 +9,27 @@ description: Examples of Ampersand programs and fragments
 This page is a collection of examples, meant for learning and explaining the language Ampersand.
 TODO: refactor this documentation to match the latest syntax.
 
+## Example: Multiple files
+This example illustrates how an Ampersand specification can consist of multiple files.
+
+In this example, we have two files. File `foo.adl` contains the following text:
+```Ampersand
+CONTEXT MultifileDemo
+INCLUDE "bar.adl"
+RELATION r[A*B]
+RULE r |- s
+ENDCONTEXT
+```
+and file `bar.adl` contains:
+```Ampersand
+CONTEXT MultifileDemo
+INCLUDE "bar.adl"
+RELATION s[A*B]
+ENDCONTEXT
+```
+Without the `INCLUDE` statement, file `foo.adl` does not compile because relation `s` is undefined.
+The `INCLUDE` statement causes all definitions of `bar.adl` to be included in the context of `foo.adl`, so this example compiles without errors.
+
 ## Example: Client {#interfaces-example-client}
 
 This example illustrates the structure of [interfaces in Ampersand](reference-material/syntax-of-ampersand#the-interface-statement)

docs/guides/onboarding.md

@@ -20,6 +20,8 @@ Request membership to
 - [AmpersandTarski](https://github.com/orgs/AmpersandTarski/people) organization and
 - [Ordina A-team](https://github.com/orgs/AmpersandTarski/teams/ordina-a-team/members).
 
+Above links only work for members of AmpersandTarski
+
 :::tip
 Make sure when you contact Han about this that you provide him with your Github account name (or URL to your GitHub profile page).
 :::

docs/landingpage/2-student.md

@@ -12,4 +12,5 @@ You can learn about the language Ampersand, and learn how to make a prototype of
 - Do the [tutorial](../tutorial-rap4), to get an idea of an Ampersand application
 - Learn about the [syntax of Ampersand](../reference-material/syntax-of-ampersand), to write correct Ampersand code.
 - Learn about [relation algebra](https://en.wikipedia.org/wiki/Relational_algebra) on Wikipedia, to understand more about this fascinating field of mathematics.
+- Find [examples](../examples) of Ampersand specifications, to get started making your own.
 - Find [exercises](../exercises.md) that help you improve your skills in specifying information systems.

docs/landingpage/3-ampersand-user.md

@@ -11,6 +11,7 @@ This page will help you build a working prototype of your information system and
 ## Get started
 
 - Do the [tutorial](../tutorial-rap4), to get an idea of an Ampersand application
+- Find [examples](../examples) of Ampersand specifications, to get started making your own.
 - Understand the [architecture of an Ampersand application](../reference-material/architecture-of-an-ampersand-application), so you can build, deploy, and maintain your Ampersand application better.
 - Learn about the [syntax of Ampersand](../reference-material/syntax-of-ampersand), to write correct Ampersand code.
 - Learn about [relation algebra](https://en.wikipedia.org/wiki/Relational_algebra) on Wikipedia, to understand more about this fascinating field of mathematics.

docs/reference-material/interfaces.md

@@ -276,5 +276,5 @@ When running an application in your browser, you are watching one user interface
 
 The next sections contain two examples:
 
-- a [client interface](../Examples.md#interfaces-example-client) to allow clients of a web shop to change their name and address and show them status information of their orders;
-- a [login interface](../Examples.md#interfaces-example-login) to demonstrate how to get different interface structures under varying conditions.
+- a [client interface](../examples#interfaces-example-client) to allow clients of a web shop to change their name and address and show them status information of their orders;
+- a [login interface](../examples#interfaces-example-login) to demonstrate how to get different interface structures under varying conditions.

docs/reference-material/syntax-of-ampersand.md

@@ -795,7 +795,7 @@ Interfaces are meant to expose functionality and data from a [context](#the-cont
 
 #### Description
 
-An interface is a component of an information system that exposes functionality and data from a [context](#the-context-statement), to let users or information systems interact by creating, reading, updating, and deleting data. The first [example](../Examples.md#example-interface-structure) introduces a simple interface informally. Another [example](../Examples.md#interface-introductory-example) introduces the main features of an interface with nested interfaces.
+An interface is a component of an information system that exposes functionality and data from a [context](#the-context-statement), to let users or information systems interact by creating, reading, updating, and deleting data. The first [example](../examples#example-interface-structure) introduces a simple interface informally. Another [example](../examples#interface-introductory-example) introduces the main features of an interface with nested interfaces.
 
 A _interface_ is a component of an information system. During the time that this interface can actually be used, we say it is _deployed_. We also call this the _lifetime_ of a interface. A typical instance of a interface is a user interface based on HTML-CSS that runs in a browser. But an application program interface \(API\) that serves other computers with web services is a perfectly valid instance as well.
 
@@ -859,8 +859,8 @@ When running an application in your browser, you are watching one user interface
 
 Further examples:
 
-- a [client interface](../Examples.md#interfaces-example-client) to allow clients of a web shop to change their name and address and show them status information of their orders;
-- a [login interface](../Examples.md#interfaces-example-login) to demonstrate how to get different interface structures under varying conditions.
+- a [client interface](../examples#interfaces-example-client) to allow clients of a web shop to change their name and address and show them status information of their orders;
+- a [login interface](../examples#interfaces-example-login) to demonstrate how to get different interface structures under varying conditions.
 
 ### CRUD annotations
 
@@ -1498,7 +1498,7 @@ RULE <label> <term> <meaning>* <message>* <violation>?
 The [RULE syntax](#the-rule-statement) is the same as for ordinary rules.
 However, the violations are specified differently.
 We will define the specifics by examples.
-Most of the examples are taken from the demo script [Project Administration Example](https://github.com/AmpersandTarski/ampersand-models/tree/master/Examples/ProjectAdministration). You can compile and run this script, and reproduce several of the examples that follow.
+Most of the examples are taken from the demo script [Project Administration Example](https://github.com/AmpersandTarski/ampersand-models/tree/master/examples/ProjectAdministration). You can compile and run this script, and reproduce several of the examples that follow.
 
 #### Example \(`InsPair` and `DelPair`\)
 

docs/the-tools-we-use/ampersand-language-support.md

@@ -1,22 +1,65 @@
 ---
-description: This page describes tooling and workflow in relation to our VSCode extention
+description: This page describes tooling and workflow in relation to our VSCode extension
 ---
 
-# Ampersand language support
+# Ampersand dev tools
 
-As we start fiddling around with getting a first version of VSCode extention, it turns out all kind of tooling needs to be in place. The vision of the extention is that it will eventually give ampersand modellers a rich integrated development environment, including syntax colouring, prettyprint, syntax supported editing, script execution etc etc. 
+Ampersand has various tools that help development of ampersand models.
 
-At first, I had a look at [language-haskell](https://github.com/JustusAdam/language-haskell). They have some IDE support in place, so it seems a reasonable first start. I don't like to invent the wheel myself.
+## Ampersand language support
+
+There is a VSCode extension named Ampersand language support (ampersandtarski.language-ampersand), which adds support for creating ampersand models.
+
+### Settings
+
+The extension has the following settings.
+
+#### Main script name
+
+When using one of the generate commands, this file is used as an entrypoint for the ampersand compiler. This file needs to located inside the project folder.
+
+**Default**: main.adl
+
+#### Project folder name
+
+When using one of the generate commands, this is the folder that is used to pass on to the ampersand compiler.
+
+**Default**: project
+
+### Commands
+
+Listed below are the commands made available by this extension. For these commands to work you also need to have ampersand in PATH.
 
+#### Ampersand Version
 
+Will show you which version of ampersand you have.
+
+#### Ampersand Daemon
+
+Starts the ampersand daemon. This tool will check the files listed in `.ampersand` for syntax errors.
+
+#### Ampersand Generate Functional Specifications
+
+This will take the project folder and create a word document with the functional specification of the model.
+
+#### Ampersand Generate Atlas
+
+As of this writing, this will generate a json file which describes the relations within the model.
+
+#### Ampersand Generate Protoype
+
+This command generates a Kubernetes manifest file containing a deployment and service. It will then try to apply this file and port-forward the service. To apply the file, a running Kubernetes cluster and kubectl are required. Once port-forwarded, the prototype is available at localhost:8000.
+
+As we start fiddling around with getting a first version of VSCode extension, it turns out all kind of tooling needs to be in place. The vision of the extension is that it will eventually give ampersand modellers a rich integrated development environment, including syntax colouring, prettyprint, syntax supported editing, script execution etc etc.
+
+At first, I had a look at [language-haskell](https://github.com/JustusAdam/language-haskell). They have some IDE support in place, so it seems a reasonable first start. I don't like to invent the wheel myself.
 
 ### [npm](https://docs.npmjs.com/)
 
-There is a lot of javascript going on, so we need a package manager for it. 
+There is a lot of javascript going on, so we need a package manager for it.
 
 ### Releasing of this vs-code extension
 
 We have a release pipeline in place using travis-ci. See the travis.yml file in the root directory. Documentation of extentions can be found [here](https://code.visualstudio.com/api/working-with-extensions/publishing-extension).
 
 The personal access token in use has an expiry date on it. An email is sent to the owner of that token \(currently Han\), in advance of the expiry. It can be renewed or the expire date [can be extended](https://dev.azure.com/hanjoostenhan/_usersSettings/tokens). 
-

docs/tutorial/interfaces.md

@@ -119,7 +119,7 @@ TODO
 
 ## Assignment
 
-Compile and run the script [Project Administration Example](https://github.com/AmpersandTarski/ampersand-models/tree/master/Examples/ProjectAdministration). Start by reproducing everything that is shown above. It is quite likely that you will be trying out your own ideas before you get to the end... Have fun!
+Compile and run the script [Project Administration Example](https://github.com/AmpersandTarski/ampersand-models/tree/master/examples/ProjectAdministration). Start by reproducing everything that is shown above. It is quite likely that you will be trying out your own ideas before you get to the end... Have fun!
 
 ## What have you learned?
 

package.yaml

@@ -1,5 +1,5 @@
 name: ampersand
-version: 5.0.0
+version: 5.0.1
 author: Stef Joosten
 maintainer: [email protected]
 synopsis: Toolsuite for automated design of enterprise information systems.

src/Ampersand/ADL1/P2A_Converters.hs

@@ -941,16 +941,16 @@ pCtx2aCtx
 
       pPat2aPat :: ContextInfo -> P_Pattern -> Guarded Pattern
       pPat2aPat ci ppat =
-        f <$> traverse (pRul2aRul ci (Just $ name ppat)) (pt_rls ppat)
-          <*> traverse (pIdentity2aIdentity ci (Just $ name ppat)) (pt_ids ppat)
+        f <$> traverse (pRul2aRul ci (Just $ label ppat)) (pt_rls ppat)
+          <*> traverse (pIdentity2aIdentity ci (Just $ label ppat)) (pt_ids ppat)
           <*> traverse (pPop2aPop ci) (pt_pop ppat)
           <*> traverse (pViewDef2aViewDef ci) (pt_vds ppat)
           <*> traverse (pPurp2aPurp ci) (pt_xps ppat)
-          <*> traverse (pDecl2aDecl (representationOf ci) cptMap (Just $ name ppat) deflangCtxt deffrmtCtxt) (pt_dcs ppat)
+          <*> traverse (pDecl2aDecl (representationOf ci) cptMap (Just $ label ppat) deflangCtxt deffrmtCtxt) (pt_dcs ppat)
           <*> traverse (pure . pConcDef2aConcDef (defaultLang ci) (defaultFormat ci)) (pt_cds ppat)
           <*> traverse (pure . pRoleRule2aRoleRule) (pt_RRuls ppat)
           <*> traverse pure (pt_Reprs ppat)
-          <*> traverse (pEnforce2aEnforce ci (Just $ name ppat)) (pt_enfs ppat)
+          <*> traverse (pEnforce2aEnforce ci (Just $ label ppat)) (pt_enfs ppat)
         where
           f rules' keys' pops' views' xpls relations conceptdefs roleRules representations enforces' =
             A_Pat
@@ -972,13 +972,13 @@ pCtx2aCtx
               }
       pRul2aRul ::
         ContextInfo ->
-        Maybe Name -> -- name of pattern the rule is defined in (if any)
+        Maybe Text -> -- name of pattern the rule is defined in (if any), just for documentation purposes.
         P_Rule TermPrim ->
         Guarded Rule
       pRul2aRul ci mPat = typeCheckRul ci mPat . disambiguate (conceptMap ci) (termPrimDisAmb (conceptMap ci) (declDisambMap ci))
       typeCheckRul ::
         ContextInfo ->
-        Maybe Name -> -- name of pattern the rule is defined in (if any)
+        Maybe Text -> -- name of pattern the rule is defined in (if any), just for documentation purposes.
         P_Rule (TermPrim, DisambPrim) ->
         Guarded Rule
       typeCheckRul
@@ -1010,13 +1010,13 @@ pCtx2aCtx
                 }
       pEnforce2aEnforce ::
         ContextInfo ->
-        Maybe Name -> -- name of pattern the rule is defined in (if any)
+        Maybe Text -> -- name of pattern the enforcement rule is defined in (if any), just for documentation purposes.
         P_Enforce TermPrim ->
         Guarded AEnforce
       pEnforce2aEnforce ci mPat = typeCheckEnforce ci mPat . disambiguate (conceptMap ci) (termPrimDisAmb (conceptMap ci) (declDisambMap ci))
       typeCheckEnforce ::
         ContextInfo ->
-        Maybe Name -> -- name of pattern the enforce is defined in (if any)
+        Maybe Text -> -- name of pattern the enforcement rule is defined in (if any), just for documentation purposes.
         P_Enforce (TermPrim, DisambPrim) ->
         Guarded AEnforce
       typeCheckEnforce
@@ -1095,7 +1095,7 @@ pCtx2aCtx
                     lbl' = "Compute " <> tshow rel <> " using " <> command
       pIdentity2aIdentity ::
         ContextInfo ->
-        Maybe Name -> -- name of pattern the rule is defined in (if any)
+        Maybe Text -> -- name of pattern the rule is defined in (if any), just for documentation purposes.
         P_IdentDef ->
         Guarded IdentityRule
       pIdentity2aIdentity ci mPat pidt =
@@ -1340,12 +1340,12 @@ pAtomValue2aAtomValue typ cpt pav =
 pDecl2aDecl ::
   (A_Concept -> TType) ->
   ConceptMap ->
-  Maybe Name -> -- name of pattern the rule is defined in (if any)
+  Maybe Text -> -- label of pattern the rule is defined in (if any), just for documentation purposes
   Lang -> -- The default language
   PandocFormat -> -- The default pandocFormat
   P_Relation ->
   Guarded Relation
-pDecl2aDecl typ cptMap maybePatName defLanguage defFormat pd =
+pDecl2aDecl typ cptMap maybePatLabel defLanguage defFormat pd =
   do
     checkEndoProps
     --propLists <- mapM pProp2aProps . Set.toList $ dec_prps pd
@@ -1361,7 +1361,7 @@ pDecl2aDecl typ cptMap maybePatName defLanguage defFormat pd =
           decMean = map (pMean2aMean defLanguage defFormat) (dec_Mean pd),
           decfpos = origin pd,
           decusr = True,
-          decpat = maybePatName,
+          decpat = maybePatLabel,
           dechash = hash (dec_nm pd) `hashWithSalt` decSign
         }
   where

src/Ampersand/Basics/Name.hs

@@ -228,7 +228,7 @@ class Named a => Labeled a where
     Just (Label lbl) -> lbl
 
 instance Show Label where
-  show (Label x) = "LABEL " <> T.unpack x
+  show (Label x) = T.unpack x
 
 prependToPlainName :: Text -> Name -> Name
 prependToPlainName

src/Ampersand/Core/AbstractSyntaxTree.hs

@@ -161,7 +161,7 @@ data A_Context = ACtx
     -- | used for Pandoc authors (and possibly other things)
     ctxmetas :: ![MetaData],
     ctxInfo :: !ContextInfo,
-    -- | All user defined enforce statements in this context, but outside patterns.
+    -- | All user defined enforcement rules in this context, but outside patterns.
     ctxEnforces :: ![AEnforce]
   }
   deriving (Typeable)
@@ -239,8 +239,8 @@ data AEnforce = AEnforce
     enfRel :: !Relation,
     enfOp :: !EnforceOperator,
     enfExpr :: !Expression,
-    -- | If the Enforce is defined in the context of a pattern, the name of that pattern.
-    enfPatName :: !(Maybe Name),
+    -- | If the enforcement rule is defined in the context of a pattern, the name of that pattern.
+    enfPatName :: !(Maybe Text),
     enfRules :: ![Rule]
   }
   deriving (Eq)
@@ -334,8 +334,8 @@ data Rule = Rule
     rrmsg :: ![Markup],
     -- | Custom presentation for violations, currently only in a single language
     rrviol :: !(Maybe (PairView Expression)),
-    -- | If the rule is defined in the context of a pattern, the name of that pattern.
-    rrpat :: !(Maybe Name),
+    -- | If the rule is defined in the context of a pattern, the label of that pattern for documentation purposes.
+    rrpat :: !(Maybe Text),
     -- | Where does this rule come from?
     rrkind :: !RuleKind
   }
@@ -470,8 +470,8 @@ data Relation = Relation
     decfpos :: !Origin,
     -- | if true, this relation is declared by an author in the Ampersand script; otherwise it was generated by Ampersand.
     decusr :: !Bool,
-    -- | If the relation is declared inside a pattern, the name of that pattern.
-    decpat :: !(Maybe Name),
+    -- | If the relation is declared inside a pattern, the label of that pattern, just for documentation purposes.
+    decpat :: !(Maybe Text),
     dechash :: !Int
   }
   deriving (Typeable, Data)
@@ -525,8 +525,8 @@ data IdentityRule = Id
     idlabel :: !(Maybe Label),
     -- | this term describes the instances of this object, related to their context
     idCpt :: !A_Concept,
-    -- | if defined within a pattern, then the name of that pattern.
-    idPat :: !(Maybe Name),
+    -- | if defined within a pattern, then the label of that pattern.
+    idPat :: !(Maybe Text),
     -- | the constituent attributes (i.e. name/term pairs) of this identity.
     identityAts :: NE.NonEmpty IdentitySegment
   }