ampersandtarski / documentation Goto Github PK

When I visited one of these links:

• https://ampersandtarski.gitbook.io/the-tools-we-use-for-ampersand/#contributions-to-the-documentation
• https://github.com/AmpersandTarski/TheToolsWeUse#contributions-to-the-documentation

There is a paragraph that says I can add comments and/or click a plus when hovering over a paragraph. I see no way to add a comment, nor do I see a plus. The expected behavior is of course for me to see ways to do this. If there's a different link on which this functionality does work, then I'd love to see a link there in the same paragraph.

@sjcjoosten, I have prepared a document according to the instructions in the Isabelle manual. I have checked it in on ac4ae27. However, I cannot manage to get a text produced from it. Somehow I fail to make Isabelle generate the sessions.tex file.

Could you give a hand? I wonder where I go wrong.

Here is what I did:

C:>Isabelle2016-1.exe mkroot -d "Joosten APF 2017"

C:>Isabelle2016-1.exe build -D "Joosten APF 2017"

C:>cd "Joosten APF 2017\document"

C:>pdflatex root
This is pdfTeX, Version 3.14159265-2.6-1.40.17 (MiKTeX 2.9 64-bit)
entering extended mode
(root.tex
LaTeX2e <2016/03/31> patch level 3
Babel <3.9r> and hyphenation patterns for 75 language(s) loaded.
("D:\Program Files\MiKTeX 2.9\tex\latex\base\article.cls"
Document Class: article 2014/09/29 v1.4h Standard LaTeX document class
("D:\Program Files\MiKTeX 2.9\tex\latex\base\size11.clo")) (isabelle.sty
(comm
           ... (LaTeX log made shorter by Stef)
LaTeX Warning: Citation `vdWoude2011' on page 1 undefined on input line 40.


LaTeX Warning: Citation `Nipkow2002' on page 1 undefined on input line 44.


! LaTeX Error: File `session.tex' not found.

Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: tex)

Enter file name:

In the documentation, a little script is provided to verify the workings of Ampersand after the installation process is complete. However, it happens that new Ampersands are published on the master branch that do not produce working prototypes for the code provided in the documentation. We need a procedure that allows a user to ALWAYS establish whether or not his installation works. How to do that?

Some small suggestions, please correct me if I'm wrong :)

On the following page: [(https://github.com/AmpersandTarski/documentation/blob/master/the-language-ampersand/relations.md)]

In the first table under the Properties chapter:
INJ injective For any b in B there can be not more than one a in A in the population of r. So, every b occurs not more than once in the domain of r.
Should it not be: not more than once in the target of r?

Somewhat related:
Would it not be clearer to use the same terminology consistently? In chapter 'syntax and meaning' the following is written: The left hand concept, Person, is called the source of the relation and the right concept, Building, is called the target.

Here the term 'source' is used, later on 'domain' is used.

There are additional relations that can be specified on endo relations. An endo relation is a relation where the source and target concepts are equal. r[A*A].

Shouldn't the first relations be replaced by properties?

The tutorial page where RAP3 is introduced has the following line: "When RAP3 is updated, probably your account will be reset. You need to register again." Is this still the case?

A bit further down the warning is even bigger:
"Important note:
RAP3 is being improved constantly, new releases can be done daily.
Currently all account information and scripts will be deleted with each new release.
So: keep a local copy of your scripts and if you cannot login anymore, just re-create your account."
Is that still the case?

And further down: "A note of caution: currently a new release of RAP3 will destroy all that is in the database, also your scripts. So save a copy of you script locally at the end of each working session."
This is probably the same issue as the second one. Is this still the case?

On the ampersand documentation site the search bar is not functioning properly. When trying to look for anything there is no response.

This link was lost somewhere along the line last year.
Now there is a text that the executable is not there and this will be fixed later.
page: https://ampersandtarski.gitbook.io/documentation/tutorial-rap3/example-system-enrollment

If you compile the file and give me the link, I can fix the tutorial page.

On the tutorial page where RAP3 is introduced there are two different links to RAP3:
"This section introduces the tool you will use during the course: RAP3. This tool stores Ampersand-scripts in which you can specify, analyze and build information systems. It runs in the cloud, so all you need is a browser and to click here to start using it."

Which one do students have to use?
If you let me know I will update the tutorial.

In this page:
https://github.com/AmpersandTarski/documentation/blob/master/the-language-ampersand/the-rule-statement.md

The "chapter about rules" is broken.

In the documentation page https://ampersandtarski.gitbook.io/documentation/the-language-ampersand/how-to-read-syntax-statements
the link to the sourcecode of the parser does not work.

For example, it is unclear where Dockerfile comes from, what it should look like, if it is generated or not, etc. Similar for docker-compose.yml.

In het tutorial page documentation/tutorial-rap3/conceptual-model-enrollment.md there is a picture of a conceptual model.
The picture is visible for me when I edit the page, but not when I just read the page. So I guess also for other read-only visitors, the picture is not there.

There are several places where readers are provided with examples of code that they supposedly could cut and subsequently paste in their own files. Examples are the myModel.adl in Test to see if you can build your first prototype, or code snippets that can be found in the documentation of the ExecEngine, e.g. in Example - Transitive Closure.

In courses that I recently gave, people that tried to do that complained that the stuff they paste in their editors contain weird characters, represented e.g. as A,E^ (or something like that). In other editors, these characters do not show but do lead to compiler (parse) errors.

How can this be fixed? Is this something of the documentation, or is this something that the &-parser must deal with?

In the tutorial page about conceptual modeling (documentation/tutorial-rap3/conceptual-model-enrollment.md) in the last line there is a link to "in depth information about modeling in Ampersand". This link goes to github, not to another page in the documentation.
is that what you want?

Hi Han,

It's good practice to keep the code and its documentation in one repository. Therefore I suggest to merge the README.md of this repo to the AmpersandTarski/ampersand repo.

As discussed yesterday, I will also think about the content of the doc.

See here an example of a documentation I like: https://github.com/mgonto/restangular

In our new frontend we also use that library.

Michiel