feat(ssb): show the name of the tab if the screen is large enough

- instruction for writing apps
- add NOTES.md to .gitignore

.dockerignore

@@ -1,4 +1,5 @@
 .svn
-db.sqlite
+db.*
 out/**/*.o
 out/**/*.d
+NOTES.md

.gitignore

@@ -8,3 +8,4 @@ out
 *.swo
 *.swp
 .zsign_cache/
+NOTES.md

.markdownlint.yaml

@@ -1,2 +1,5 @@
 default: true
+MD010: false # Ignore tabs in code blocks
 MD013: false # Don't wrap lines by default
+MD046: 
+  style: "fenced" # Force fenced code blocks

.prettierignore

@@ -12,3 +12,8 @@ deps
 apps/ssb/tribute.esm.js
 apps/api/app.js
 **/emojis.json
+
+# only markdownlint should deal with the documentation
+docs/**/*.md
+
+NOTES.md

LICENSE

@@ -1,4 +1,4 @@
-Copyright 2014 Cory McWilliams
+Copyright 2014-2024 Cory McWilliams
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

README.md

@@ -4,46 +4,19 @@ Tilde Friends is a tool for making and sharing.
 
 A public instance lives at https://www.tildefriends.net/.
 
-It is both a peer-to-peer social network client, participating in Secure
-Scuttlebutt, as well as a platform for writing and running web applications.
+It is both a peer-to-peer social network client, participating in Secure Scuttlebutt, as well as a platform for writing and running web applications.
 
 ## Goals
 
 1. Make it easy and fun to run all sorts of web applications.
 2. Provide security that is easy to understand and protects your data.
-3. Make creating and sharing web applications accessible to anyone with a
-   browser.
-
-## Building
-
-Builds on Linux (x86_64 and aarch64), MacOS, OpenBSD, and Haiku. Builds for
-all of those host platforms plus mingw64, iOS, and android.
-
-1. Requires openssl (`libssl-dev`, in debian-speak). All other dependencies
-   are kept up to date in the tree.
-2. To build, run `make debug` or `make release`. An executable will be
-   generated in a subdirectory of `out/`.
-3. It's possible to build for Android, iOS, and Windows on Linux, if you have
-   the right dependencies in the right places. `make windebug winrelease
-iosdebug-ipa iosrelease-ipa release-apk`.
-4. To build in docker, `docker build .`.
-5. `make format` will normalize formatting to the coding standard.
-
-## Running
-
-By default, running the built `tildefriends` executable will start a web server
-at <http://localhost:12345/>. `tildefriends -h` lists further options.
-
-The first user to create an account and log in will be granted administrative
-privileges. Further administration can be done at
-<http://localhost:12345/~core/admin/>.
+3. Make creating and sharing web applications accessible to anyone with a browser.
 
 ## Documentation
 
-Docs are a work in progress:
-<https://www.tildefriends.net/~cory/wiki/#test-wiki/tf-app-quick-reference>.
+Docs are a work in progress in the `docs` folder, or alternatively in Tilde Friends: <https://www.tildefriends.net/~cory/wiki/#test-wiki/tf-app-quick-reference>.
 
 ## License
 
-All code unless otherwise noted in is provided under the
-[MIT](https://opensource.org/licenses/MIT) license.
+All code, documentation and assets unless otherwise noted in is provided under the
+[MIT](https://opensource.org/licenses/MIT/) license.

apps/ssb/tf-app.js

@@ -339,6 +339,13 @@ class TfElement extends LitElement {
 		};
 
 		let tabs = html`
+			<style>
+				@media only screen and (max-width: 650px) {
+					.hide-on-small-screens {
+						display: none;
+					}
+				}
+			</style>
 			<div class="w3-bar w3-theme-l1">
 				${Object.entries(k_tabs).map(
 					([k, v]) => html`
@@ -351,6 +358,7 @@ class TfElement extends LitElement {
 							@click=${() => self.set_tab(v)}
 						>
 							${k}
+							<span class="hide-on-small-screens">${v}</span>
 						</button>
 					`
 				)}

docs/.guide.md

@@ -1,4 +1,6 @@
-# Philosophy
+# Tilde Friends
+
+## Philosophy
 
 Tilde Friends is a platform for making, running, and sharing web applications.
 
@@ -18,7 +20,7 @@ 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
+## Architecture
 
 Tilde Friends is a C++ application with a JavaScript runtime that provides
 restricted access to filesystem, network, and other system resources. The core
@@ -135,16 +137,18 @@ Sets the browser window/tab title.
 
 Reconfigures the terminal layout, potentially into multiple split panes.
 
-    terminal.split([
-    	{
+```javascript
+terminal.split(
+    [{
         type: "horizontal",
         children: [
             {name: "left", basis: "2in", grow: 0, shrink: 0},
             {name: "middle", grow: 1},
             {name: "right", basis: "2in", grow: 0, shrink: 0},
         ],
-    	},
-    ]);
+    }]
+);
+```
 
 #### terminal.select(name)
 

docs/apps/quickstart.md

@@ -0,0 +1,50 @@
+# Writing Tilde Friends applications7
+
+TODO
+
+## Creating your environment
+
+1. Open an existing application (ie: `identity`);
+2. Open the editing panel;
+3. Save the app under a new name (ie `/~YOUR_USERNAME/my-app/`);
+4. Go back to the main menu and open your new app;
+5. You can now edit your app, save it and see changes in the real time.
+
+## Project structure
+
+An application has a `app.js` file that gets run when a user enters the app.
+This file contains a function (typically called `main()`) that's considered the entry point.
+
+Paste this in `app.js`:
+
+```javascript
+async function main() {
+	let ids = await ssb.getIdentities();
+	await app.setDocument(`
+		<body style="font-family: sans-serif; color: white">
+			<h1>Hello world!</h1>
+		</body>
+	</body>`);
+}
+
+main();
+```
+
+Save the app, and you should now be seeing `Hello world!` on the screen.
+
+
+## Components
+
+Once your app grows to a certain size, you'll want to introduce components.
+In Tilde Friends, the de facto standard is [Lit](TODO).
+Althogh you an use any framework you want, you're encouraged to use Lit as you can reuse
+
+First, add lit-all-min.js into your project.
+
+TODO
+
+<!-- mention shadow dom -->
+
+TODO: tfrpc
+
+TODO: sharing apps

docs/building.md

@@ -0,0 +1,76 @@
+# How to build Tilde Friends
+
+> Disclaimer: this documentation has been written by a Linux user and has not been reviewed by other people on other platforms. The procedure may vary slightly depending on your operating system.
+
+Builds **on** Linux (`x86_64` and `aarch64`), MacOS, OpenBSD, and Haiku.
+
+Builds **for** all of those host platforms plus `mingw64`, iOS, and android.
+
+Dependencies:
+
+- `openssl` (`libssl-dev`, in debian-speak)
+
+Dependencies for Android:
+
+- TODO
+
+Dependencies for iOS:
+
+- TODO
+
+Dependencies for Windows:
+
+- TODO
+
+> All other dependencies are kept up to date as git submodules.
+
+1. Clone the repository with the submodules: `git clone --recursive https://dev.tildefriends.net/cory/tildefriends.git`
+
+2. Run `make -j $(nproc) debug` or `make -j $(nproc) release`
+
+If you're unsure whether you should choose `debug` or `release`, stick to `release`.
+
+> `-j $(nproc)` will start a compiler for every CPU thread, which will dramatically reduce the time needed to compile Tilde Friends.
+
+An executable will be generated in a subdirectory of `out/`
+
+It's possible to build for Android, iOS, and Windows on Linux, if you have the right dependencies in the right places. Run `make -j $(nproc) windebug winrelease iosdebug-ipa iosrelease-ipa release-apk`
+
+To build in docker, `docker build .`
+
+<!-- On NixOS: TODO -->
+<!-- Add shell.nix and nix derivs first -->
+
+Now that you have a binary, head over to <running.md>.
+
+## Troubleshooting
+
+### The compiler throws an error and I can't build the binary
+
+Open `GNUMakefile` and edit the CFLAGS environment variable around line 50.
+
+For example given this error:
+
+```text
+src/http.c: In function 'tf_http_get_cookie':
+src/http.c:1089:128: error: check of 'name' for NULL after already dereferencing it [-Werror=analyzer-deref-before-check]
+```
+
+Add:
+
+```diff
+CFLAGS += \
+	-std=gnu11 \
+	-Wall \
+	-Wextra \
+	-Wno-unused-parameter \
++	-Wno-analyzer-deref-before-check \
+	-MMD \
+	-MP \
+	-ffunction-sections \
+	-fdata-sections \
+	-fno-exceptions \
+	-g
+```
+
+Now the compiler will ignore this error and *should* continue building anyways.

docs/contributing.md

@@ -0,0 +1,42 @@
+# How to contribute
+
+- Fork this repository
+
+- Clone your repository
+
+Alternatively, you can change the `origin` remote on your existing clone:
+
+`git remote set-url origin https://dev.tildefriends.net/YOUR_USERNAME/tildefriends.git`
+
+- Make your changes
+
+  - I want to edit C code !
+
+    TODO
+
+  - I want to edit JavaScript code !
+
+    TODO
+
+  - I want to write documentation !
+
+    Great! Before you do, have a look at the [documentation guidelines](guidelines/documentation-guidelines.md) to learn how to write consistent documentation.
+
+    In all cases:
+
+    - Make sure that your commit messages are descriptive.
+    <!-- - hi -->
+
+- Format your changes:
+
+If you've edited C code: run `make format`
+
+If you've edited JavaScript code or the documentation: run `npm run format`
+
+- Open a pull request
+
+TODO
+
+- Get your changes reviewed and merged
+
+TODO

docs/documentation.md

@@ -0,0 +1,19 @@
+# Tilde Friends documentation
+
+## Building
+
+See <building.md>.
+
+## Contibuting
+
+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

@@ -0,0 +1,9 @@
+# Troubleshooting
+
+## I started tildefriends. Now what ?
+
+See <running.md>.
+
+### The compiler throws an error and I can't build the binary
+
+See <building.md>.

docs/guidelines/c-guidelines.md

@@ -0,0 +1 @@
+TODO

docs/guidelines/documentation-guidelines.md

@@ -0,0 +1,64 @@
+# 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/).
+
+## 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`.
+
+## Documentation
+
+When writing documentation, the author should have in mind it's target audience: people with varying technical skills and backgrounds, fluency in peer-to-peer-specific terms and mental ability.
+The documentation should therefore be acessible and usefule to most people interested in building, using and contributing to Tilde Friends.
+
+### Terminology
+
+`Tilde Friends` refers to the projectas a whole. This can be abbreviated to `TF`.
+
+`tildefriends` refers to the program.
+
+### Style guide
+
+1. Lines SHOULD NOT be wrapped, to allow clients to dynamically wrap them however they want:
+
+    ```text
+    This is not very pleasant to read because
+    the text
+    is manually wrapped, but the size of the
+    screen is
+    smaller than the size the text is wrapped
+    at. I
+    need to write even more useless text here
+    so I get
+    my point across. Also hi! If you're here
+    that
+    means you're either going to contribute to
+    Tilde
+    Friends, or that you're reviewing my
+    stupid
+    changes. Either way, you're awesome!
+    ```
+
+    You MAY use one line per sentence.
+
+2. Lines ending with an `inline code block` SHOULD NOT end with a period.
+
+> 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.
+
+> 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`.
+
+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.

docs/guidelines/javascript-guidelines.md

@@ -0,0 +1 @@
+TODO

docs/running.md

@@ -0,0 +1,50 @@
+# Running Tilde Friends
+
+> Disclaimer: this documentation has been written by a Linux user and has not been reviewed by other people on other platforms. The procedure may vary slightly depending on your operating system.
+
+The binaries should appear at `out/debug/tildefriends` and `out/release/tildefriends`.
+
+For Android, iOS and Windows: TODO
+
+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.
+
+## How to use TF
+
+### Initial setup
+
+Now you have a Tilde Friends instance running. The first thing you'll want to do is create your account. Click "login" in the top right corner, then "Register".
+Enter your username and password.
+
+> The first user to create an account and log in will be granted administrative privileges.
+> Further administration can be done at <http://localhost:12345/~core/admin/>
+
+Next, create a Scuttlebutt identity by pressing the "Create an identity" button.
+This will create a pair of keys that are used to sign your messages with.
+
+Because of the way Scuttlebutt is designed, you cannot log into your account without your keys. 
+Tilde Friends locks your keys behind a password, but if you were to destroy your database, the keys would be gone forever, and with it your possibility to send messages using this account. Click on the `identity` app and under "Identities", export your newly created identity.
+
+You'll be prompted with a dialog box saying "This app is requesting the following permission:ssb_id_export".
+This is because applications are not trusted to have access to your keys by default.
+Click on "Allow" and you'll see a list of 12 words. You need to write those down in a password manager or on a piece of paperand keep it private and secure.
+
+> Warning: Nobody needs to know these 12 words. Anybody that has access to those keys can post messages as you, see your private messages and documents and much more.
+
+Now that your keys are safe, we can start connecting to the outside world.
+
+### Replication
+
+You've probably noticed asdtring of random characters by now. This is your public key, a unique identifier for your account you can share to anyone. If you go back to the home menu and into the `ssb` app, you can click on your public key. This will lead you to your profile, which is empty at the time. Edit it and enter your name.
+
+TODO: joining a room
+
+TODO: initial sync
+
+TODO: send messages
+
+TODO: how messages spread to friends
+
+TODO: other apps

package.json

@@ -1,9 +1,9 @@
 {
 	"name": "tildefriends",
 	"scripts": {
-		"lint": "npm run prettier && npm run markdown",
-		"prettier": "prettier --cache --write --check .",
-		"markdown": "npx markdownlint-cli 'docs/**/*.md' -f"
+		"format": "npm run prettier && npm run markdown",
+		"prettier": "npx prettier --cache --write --check .",
+		"markdown": "npx markdownlint-cli --fix 'docs/**/*.md'"
 	},
 	"author": "Cory McWilliams",
 	"license": "MIT",