carnap/carnap-documentation

Documentation for Carnap

Carnap-Documentation

Documentation for Carnap

You can view a live site of this documentation, updated daily, at https://carnap.io/srv/doc/.

carnap-documentation's Issues

Can doc files be downloaded?

In doc/pandoc.md https://carnap.io/srv/doc/pandoc.md it says the file can be downloaded at https://carnap.io/srv/doc/pandoc.md/download
That link doesn't work. Should it? If not, I'll link to the source of pandoc.md on GitHub instead.

Email link

In doc/dashboard.md we ask instructors to email you. But the link text has your gmail addy and the mailto: link the ksu addy. Which one do you prefer?

Documentation for building and administering servers

@gleachkr and I were talking offline about setting up documentation for people who want to a) run their own servers (maybe on their laptops) just to play around, b) people with Haskell skills who want to help with development, c) server admins who are tasked with setting up and running a Carnap server, and d) server admins who have to do things like promote users to instructors, set up LTI integration, and find things in logs. We want:

• An installing Carnap quick start guide (step-by-step instructions for downloading Carnap to the point where you have your own instance on localhost that you can play with). #14
• Instructions aimed a developers (including documentation of configuration files, possible build workflows, etc.) #15
• Instructions aimed at server admins (how to set up a production server; possibly how to run a build/test server and deploying to a production server; info on database configuration; info on doing this on different platforms). #16 #17
• Instructions for administering a running server. #18
• Instructions for LTI integration. #19

@lf- already has started some of that:
https://github.com/Carnap/Carnap-Documentation/blob/master/doc/administration.md
https://github.com/Carnap/Carnap-Documentation/blob/master/doc/lti.md
and there's also the Readme at
https://github.com/Carnap/Carnap/blob/master/README.md
but many things are not documented; many things assume knowledge or prerequisites that aren't listed or that can't be expected of the reader (esp. a and c); and there the documentation (I think) gives alternative/conflicting ways of doing things.

Document set theory systems

Documentation for the OLP set theory systems is coming, but I don't know what the syntax of separative abstractions is. Are there rules for it (e.g., t in {x : phi(x)} / phi(t) or something?)

Automatic updating broken?

Updates of 4 days ago haven't shown up yet on carnap.io.

Server configuration

Info for server admins on how Carnap has to be configured on a server, eg:

• configure posgres (if you're not going to use a preassembled setup like the one that nixos
  provides)
• where to put the "outside" URL of the server and how to set up reverse proxy
• Google OAuth configuration
• Instructions for testing/deploying, backup, migrating (where is the data and what has to be recompiled/what can be copied from one system to another)

Deploying Carnap

Instructions on how to deploy a Carnap server with some suggestions about build tools like the nixos approach and docker.

Implement auto-update from documentation repo

Well, I haven't done anything yet, since I didn't want to put in work I'd have to undo because the documentation I start from has changed.

I suggest the way to do this is:

1. implement the scripts/Github action/cron job that pulls the MD files from here and changes them on the server when they change in the repo;
2. populate the repo with existing documentation, and freeze the documentation;
3. test if it works ok;
4. when it works, start improving the documentation incrementally, and make any changes to existing documentation here only.

If we want the documentation to remain in the shared files and be searchable/filterable by tag there, the script that inserts the MD file will need a way to take/overwrite things like page title, description, tags, and possibly restrictions (if we want some things only be available to instructors, say, although since this repo is public, maybe everything can just be public).

Developer documentation

Documentation for the Haskell-savvy on how to build Carnap. A guide to how to configure and run Carnap locally. What do all the files do? Which settings are there and how are they set?

Document all proof systems

Currently the documentation only describes the following systems in detail:

• Carnap/Montague
• Logic Book
• forall x (OG and YYC only)
• Gentzen systems

Need documentation for:

• Allen
• Bonevac
• EbelsDuggan
• Gallow/forall x:Pitt
• Gamut
• Goldfarb
• Hardegree
• Hausman
• Howard-Snyder
• Hurley
• Ichikawa-Jenkins/forall x:UBC
• Tomassi

Server administration

Instructions for administering a running server.

Documentation on separate servers

There should probably be a way to pull the documentation into the dataroot/srv directory of other servers; maybe document or check in the script that does that?

LTI integration

Expand on https://github.com/Carnap/Carnap-Documentation/blob/master/doc/lti.md to cover other LMS

Installation quick-start guide

A document aimed at someone not afraid of a CLI with step-by-step instructions on getting a Carnap server running locally to experiment with.

I think something like this is minimal. (It worked for me yesterday but when I redid it today it errored out but that's probably an issue with a package nix loads.)

• Download Carnap using git:

  $ git clone [email protected]:Carnap/Carnap.git
  

• Change into Carnap directory:

  $ cd Carnap
  

• Install Nix using instructions at:
  https://nixos.org/manual/nix/unstable/installation/installing-binary.html

• Follow https://github.com/Carnap/Carnap/blob/master/README.md to build and run Carnap-Server:

  $ nix-env -iA cachix -f https://cachix.org/api/v1/install
  $ cachix use carnap
  $ make run
  

• This will build all the required packages and then run Carnap-Server. Now Carnap should be available at http://localhost:3000

• You’ll see the familiar Carnap front page. Click Login.

• Carnap asks: “Your new identifier is: ____” and a button that says “Dummy Login”

• Put in your desired user ID and click the button. NB this will be your one and only administrator account. If you plan on switching to Google Authentication, make this ID the full email address of an account you can use Google login with (eg a Gmail address), otherwise you will not be able to access it later.

• You’ll see the registration page. Put in your name &c. and click “Register”. Now you’ll be on your “Student page”

• Go to http://localhost:3000/admin_promote to make yourself the site administrator

• You can now go to the administration page http://localhost:3000/master_admin to administer the site. There you can promote users to instructor. Any instructor can then log in and create courses, upload documents, etc.

Need to adjust links after rename

Since a lot of the internal links still use the carnap- prefix.

Semantic Tableaux/Truth Trees Documentation

Now that we've got Rudolf merged, it'd be good to have some documenation on how to create truth tree exercises, and how to interact with them. @lf- , @McTano, either of you up for this?

AllenSL

Cool page for the documentation. I wouldn't say that this is in urgent need of documentation, but if, eventually, you want the list to be complete, I've been using AllenSL. (It's sort of based on the rules in Allen & Hand's Logic Primer, and it goes with the version of Forall x that my students use). After Graham got it rolling, I described it here: http://blog.loighic.net/the-allensl-system-in-carnap. You can take anything you want from there, or, when I have a chance, I can write up a documentation page that would be appropriate for Carnap.io.

Greg