docs: misc

docs/apps/api.md

@@ -1,38 +1,4 @@
-# Tilde Friends
+<!-- 
-
-## Philosophy
-
-Tilde Friends is a platform for making, running, and sharing web applications.
-
-When you visit Tilde Friends in a web browser, you are presented with a
-terminal interface, typically with a big text output box covering most of the
-page and an input box at the bottom, into which text or commands can be
-entered. A script runs to produce text output and consume user input.
-
-The script is a Tilde Friends application, and it runs on the server, which
-means that unlike client-side JavaScript, it can have the ability to read and
-write files on the server or create network connections to other machines.
-Unlike node.js or other server-side runtime environments, applications are
-limited for security reasons to not interfere with each other or bring the
-entire server down.
-
-Above the terminal, an "Edit" link brings a visitor to the source code for the
-current Tilde Friends application, which they can then edit, save as their own,
-and run.
-
-## Architecture
-
-Tilde Friends is a C++ application with a JavaScript runtime that provides
-restricted access to filesystem, network, and other system resources. The core
-process runs a core set of scripts that implement a web server, typically
-starting a new process for each visitor's session which runs scripts for the
-active application and stopping it when the visitor leaves.
-
-Only the core process has access to most system resources, but session
-processes can be given accesss through the core process.
-
-Service processes are identical to session processes, but they are not tied to
-a user session.
 
 ## Communication
 
@@ -211,3 +177,5 @@ Writes data to the connection.
 #### connection.close()
 
 Closes the connection.
+
+ -->

docs/apps/quickstart.md

@@ -47,4 +47,8 @@ TODO
 
 TODO: tfrpc
 
+Apps can interact with Tilde Friends using tfrpc.
+
+Read <tfrpc.md>
+
 TODO: sharing apps

docs/apps/tfrpc.md

@@ -0,0 +1,8 @@
+# RPC documentation
+
+Quick start
+
+Complete documentation
+
+
+TODO

docs/building.md

@@ -45,8 +45,9 @@ Now that you have a binary, head over to <running.md>.
 
 ## Troubleshooting
 
-### The compiler throws an error and I can't build the binary
+### The compiler throws a warning and I can't build the binary
 
+You can choose to tell the compiler to ignore warnings.
 Open `GNUMakefile` and edit the CFLAGS environment variable around line 50.
 
 For example given this error:
@@ -74,3 +75,4 @@ CFLAGS += \
 ```
 
 Now the compiler will ignore this error and *should* continue building anyways.
+Note this is a dirty hack to get Tilde Friends to compile and you should not propose to keep this flag on. Instead, open a bug report.

docs/contributing.md

@@ -1,20 +1,30 @@
 # How to contribute
 
+## Philosophy
+
+TODO
+
+## Best practices
+
+TODO
+
+## How to get your changes merged
+
 - Fork this repository
 
 - Clone your repository
 
   1. Alternatively, you can add a remote called `fork`:
 
-  `git remote add fork https://dev.tildefriends.net/YOUR_USERNAME/tildefriends.git`
+  `$  git remote add fork https://dev.tildefriends.net/YOUR_USERNAME/tildefriends.git`
 
   You'll need to set your branch's upstream to `fork`:
 
-  `git push --set-upstream fork my-branch`
+  `$ git push --set-upstream fork my-branch`
 
   2. or you can change the `origin` remote on your existing clone altogether:
 
-  `git remote set-url origin https://dev.tildefriends.net/YOUR_USERNAME/tildefriends.git`
+  `$ git remote set-url origin https://dev.tildefriends.net/YOUR_USERNAME/tildefriends.git`
 
 - Make your changes
 

docs/documentation.md

@@ -11,9 +11,3 @@ See <contributing.md>.
 ## FAQ / Troubleshooting
 
 See <faq.md>.
-
-## Guide
-
-This document will be phased out and integrated into the new documentation.
-
-See <.guide.md>.

docs/faq.md

@@ -7,3 +7,10 @@ See <running.md>.
 ### The compiler throws an error and I can't build the binary
 
 See <building.md>.
+
+### Where is my database located ?
+
+TODO
+
+
+

docs/guidelines/documentation-guidelines.md

@@ -1,7 +1,6 @@
 # Documentation guidelines
 
 This document defines the rules used to write documentation in order to make it more consistent.
-
 This documentation is a living document and so are it's rules; you are free to propose changes but in the meantime, please stick to them.
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119/).
@@ -9,7 +8,6 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
 ## File naming
 
 Files SHOULD be named using [kebab-case](https://www.freecodecamp.org/news/snake-case-vs-camel-case-vs-pascal-case-vs-kebab-case-whats-the-difference/#kebab-case).
-
 Their names should be meaningful and SHOULD not conflict with other files in other directories:
 
 > Example: this document is named `docs/guidelines/documentation-guidelines.md` instead of `docs/guidelines/documentation.md` because it could cause confusion with `docs/documentation.md`.
@@ -49,16 +47,29 @@ The documentation should therefore be acessible and usefule to most people inter
 
     You MAY use one line per sentence.
 
-2. Lines ending with an `inline code block` SHOULD NOT end with a period.
+2. Lines ending with an `inline code block` or hyperlinks SHOULD NOT end with a period to make copy-pasting easier.
 
-> Example: To build in docker, `docker build .`
+    > Example: To build in docker, `$ docker build .`
 
-NB: this does not apply to file names or other text that are not meant to be copy-pasted.
+    NB: this does not apply to file names or other text that are not meant to be copy-pasted.
 
-> Example: this document is named `docs/guidelines/documentation-guidelines.md` instead of `docs/guidelines/documentation.md` because it could cause confusion with `docs/documentation.md`.
+    > Example: this document is named `docs/guidelines/documentation-guidelines.md` instead of `docs/guidelines/documentation.md` because it could cause confusion with `docs/documentation.md`.
+
+3. Commands SHOULD start with a caret: (is that the tehnical term ?)
+
+    - `$` if the command should be run as the current user 
+    - `#` if the command should be run as root
+
+    > Example: To build in docker, `$ docker build .`
 
 More TODO
 
 ## License
 
 As per the rest of the code in this repository, the documentation is shared under the [MIT](https://opensource.org/licenses/MIT/) license.
+
+## Changelog
+
+### v1 (2024-05-12)
+
+First version; 3 new guidelines.

docs/in-depth.md

@@ -0,0 +1,37 @@
+# Tilde Friends in depth
+
+## Philosophy
+
+Tilde Friends is a platform for making, running, and sharing web applications.
+
+<!-- When you visit Tilde Friends in a web browser, you are presented with a
+terminal interface, typically with a big text output box covering most of the
+page and an input box at the bottom, into which text or commands can be
+entered. A script runs to produce text output and consume user input.
+
+The script is a Tilde Friends application, and it runs on the server, which
+means that unlike client-side JavaScript, it can have the ability to read and
+write files on the server or create network connections to other machines.
+Unlike node.js or other server-side runtime environments, applications are
+limited for security reasons to not interfere with each other or bring the
+entire server down.
+
+Above the terminal, an "Edit" link brings a visitor to the source code for the
+current Tilde Friends application, which they can then edit, save as their own,
+and run. -->
+
+## Architecture
+
+Tilde Friends is a C++ application with a JavaScript runtime that provides restricted access to filesystem, network, and other system resources.
+The core process runs a core set of scripts that implement a web server, typically starting a new process for each visitor's session which runs scripts for the active application and stopping it when the visitor leaves.
+
+Only the core process has access to most system resources, but session processes can be given accesss through the core process.
+
+Service processes are identical to session processes, but they are not tied to a user session.
+
+```text
+/-------\         /-------------\         /--------------\
+| C app | <-----> | Server-side | <-----> | Client-side  |
+|       |  tfrpc  | JS runtime  |         | JS (Browser) |
+\-------/         \-------------/         \--------------/
+```

docs/running.md

@@ -6,10 +6,10 @@ The binaries should appear at `out/debug/tildefriends` and `out/release/tildefri
 
 For Android, iOS and Windows: TODO
 
-You can now start the server by running `./out/debug/tildefriends` or `./out/release/tildefriends`.
+You can now start the server by running `$ ./out/debug/tildefriends` or `$ ./out/release/tildefriends`.
 
 By default, running the built `tildefriends` executable will start a web server
-at <http://localhost:12345/>. `tildefriends -h` lists further options.
+at <http://localhost:12345/>. `$ tildefriends -h` lists further options.
 
 ## How to use TF