Rewrite the help, and some of the README

README.md

@@ -8,29 +8,32 @@ Nostr stands for "Notes and Other Stuff Transmitted by Relays."
 
 [^1] and Mastodon, Gab, Post, Gettr, Farcaster, Truth social, BlueSky, Locals, Minds, Spoutable, etc, etc....
 
+### Points of Difference
+
+The following features make gossip different than most other nostr clients so far:
+
+- Gossip follows people wherever they post, dynamically detects where events might be, and dynamically connects, subscribes, and disconnects to various relays as needed to get those events.
+- Gossip handles private keys securely.
+- Gossip avoids complex HTML/CSS/JavaScript web rendering, preferring to render with OpenGL (or similar), and also avoids web fetch technologies, preferring to use simple HTTP GETs and WebSocket upgrade. This avoids web security issues like XSS vulnerabilities, JavaScript attack vectors, CORS issues, cookie issues, etc, etc. The downside is that it isn't as pretty as web-based clients.
+
 ## Status
 
 Gossip is currently alpha-quality code. Given most nostr clients are also alpha quality code, I no longer recommend against its usage. Feel free to use it as it is, just be aware that there are still serious shortcomings.
 
-Also, the GUI sucks. It looks horrible. And isn't smartly designed. But form follows function, and only after the function is sufficiently complete will I work on the GUI. Also, the GUI tech may still change entirely if egui isn't up to the challenge. So don't be put off too much by the ugliness. We will have hinted fonts and full color emoji support one way or another as a high priority.
+Also, the GUI sucks. It looks horrible. And isn't smartly designed. But form follows function, and only after the function is sufficiently complete will I work on the GUI.
-
-### Features
-
-I'm no longer listing features as the list is getting to long and hard to keep up to date.
 
 ### Missing Critical Features
 
+- [ ] Making it much easier to get started
 - [ ] Setting your metadata and syncing it with the network.
 - [ ] Syncing the relays you use with the network
 - [ ] Encrypted Private Messaging
-- [ ] Seeing who other people follow (contact lists)
+- [ ] Choosing to hide replies (anybody can reply so they can be spammy)
-- [ ] Quoting and/or boosting posts
-- [ ] Choosing not to see replies and/or reactions to your own posts by people you didn't directly follow
 - [ ] Muting people
 
 ## Getting Started
 
-In particular, **Gossip is HARD to get started** because there is no way to tell it a set of relays to pull from, and right from the start it doesn't have enough data to figure out what to do. You can however do this to get it started:
+**Gossip is HARD to get started** because there is no way to tell it a set of relays to pull from, and right from the start it doesn't have enough data to figure out what to do. You can however do this to get it started:
 
 - On page `You`, add your key (public or private)
 - On page `Relays` add a relay that you post to (or several), and tick off "Post Here" (otherwise it won't pull your data from there). Remember to press "SAVE CHANGES" at the bottom of that page.
@@ -66,26 +69,28 @@ In particular, **Gossip is HARD to get started** because there is no way to tell
 We intend to support the following features/NIPs:
 
 - [x] NIP-01 - Basic protocol flow description
-- [ ] NIP-02 - Contact List and Petnames
+- [x] NIP-02 - Contact List and Petnames
-- [ ] NIP-04 - Encrypted Direct Message: I doesn't believe this is a good idea to do encrypted messaging this way, as it leaks metadata and has a cryptographic weakness. But it is in common enough usage.
+- [ ] NIP-04 - Encrypted Direct Message
-- [ ] NIP-05 - Mapping Nostr keys to DNS-based internet identifiers (partial)
+- [x] NIP-05 - Mapping Nostr keys to DNS-based internet identifiers
-- [ ] NIP-08 - Handling Mentions
+- [x] NIP-08 - Handling Mentions
-- [x] NIP-09 - Event Deletion
+- [ ] NIP-09 - Event Deletion
 - [x] NIP-10 - Conventions for clients' use of e and p tags in text events
-- [ ] NIP-11 - Relay Information Document (partial)
+- [x] NIP-11 - Relay Information Document
 - [ ] NIP-12 - Generic Tag Queries
 - [x] NIP-13 - Proof of Work
 - [ ] NIP-14 - Subject tag in text events (partial)
 - [x] NIP-15 - End of Stored Events Notice
 - [ ] NIP-16 - Event Treatment
-- [ ] NIP-19 - bech32-encoded entities (keys, not elsewise)
+- [x] NIP-19 - bech32-encoded entities
 - [x] NIP-20 - Command Results
 - [ ] NIP-22 - Event created_at Limits
-- [ ] NIP-25 - Reactions (viewing, not yet creating)
+- [x] NIP-25 - Reactions
 - [ ] NIP-26 - Delegated Event Signing
 - [ ] NIP-28 - Public Chat
+- [ ] NIP-33 - Parameterized Replaceable Events
 - [ ] NIP-36 - Sensitive Content
 - [ ] NIP-40 - Expiration Timestamp
+- [ ] NIP-42 - Authentication of clients to relays
 
 We do not intend to support the following features/NIPs:
 
@@ -93,29 +98,6 @@ We do not intend to support the following features/NIPs:
 - NIP-06 - Basic key derivation from mnemonic seed phrase. This is probably not applicable anyways.
 - NIP-07 - window.nostr capability for web browsers. This is not applicable.
 
-### other features worth mentioning
-
-- [x] configurable look-back time
-- [x] dark/light mode
-- [x] secure handling of private keys by zeroing memory and marking them Weak if displayed or exported
-- [x] exporting/importing of private keys with a passphrase
-- [ ] multiple identities
-- [ ] user management of relays (read/write), including ranking (partial, no ranking ui yet)
-- [ ] choose to load from another relay with a button press
-- [ ] choose what kinds of posts to want to see.
-- [ ] block lists, word filters, etc.
-- [ ] mute a specific post
-- [x] dismiss a specific post without blocking for future sessions
-- [ ] follow people privately or publicly (currently entirely private, not synced)
-
-### What Gossip Isn't
-
-Gossip doesn't use web technology (except for Websockets and HTTP GET). There is no JavaScript, no HTML parsing, no automatic fetch of other resources in order to draw the page, and no HTML/CSS-based layout. Because of this, there are no suprises, no XSS vulnerabilities, no JavaScript attack vectors, no CORS errors, and especially no fetching of page-referenced resources that you never intended to fetch.
-
-On the flip side, we have (currently) shitty fonts, no color emojis, and we render many frames per second which has a computation cost.
-
-This is a trade off that works for the developer, who wants a reliable, secure and privacy-oriented client, not necessarily a flashy one.
-
 ## Building and Installing
 
 ### Step 1 - Install Rust

src/ui/help/mod.rs

@@ -1,4 +1,5 @@
 use super::{GossipUi, Page};
+use crate::feed::FeedKind;
 use eframe::egui;
 use egui::{Context, RichText, ScrollArea, Ui};
 
@@ -7,7 +8,7 @@ mod stats;
 
 pub(super) fn update(app: &mut GossipUi, ctx: &Context, _frame: &mut eframe::Frame, ui: &mut Ui) {
     ui.horizontal(|ui| {
-        ui.selectable_value(&mut app.page, Page::HelpHelp, "Help");
+        ui.selectable_value(&mut app.page, Page::HelpHelp, "Getting Started");
         ui.separator();
         ui.selectable_value(&mut app.page, Page::HelpStats, "Stats");
         ui.separator();
@@ -18,7 +19,7 @@ pub(super) fn update(app: &mut GossipUi, ctx: &Context, _frame: &mut eframe::Fra
 
     if app.page == Page::HelpHelp {
         ui.add_space(24.0);
-        ui.heading("Help");
+        ui.heading("Help - Getting Started");
 
         ScrollArea::vertical().show(ui, |ui| {
 
@@ -26,6 +27,81 @@ pub(super) fn update(app: &mut GossipUi, ctx: &Context, _frame: &mut eframe::Fra
             ui.separator();
             ui.add_space(10.0);
 
+            ui.horizontal_wrapped(|ui| {
+                ui.label(RichText::new("Quickstart").heading());
+            });
+
+            ui.add_space(10.0);
+            ui.label("If you have used other clients, here is the procedure to get up and running on gossip:");
+            ui.add_space(10.0);
+
+            ui.label("• Setup your Identity");
+            ui.indent("quickstartaddkey", |ui| {
+                ui.horizontal_wrapped(|ui| {
+                    ui.label("On the");
+                    if ui.link("You").clicked() {
+                        app.set_page(Page::You);
+                    }
+                    ui.label("page, add your key (public or private). If you supply your private key you will be able to post, but this is not necessary to use gossip as a viewing tool. You can even supply somebody else's public key and see what they see (sneaky you!)");
+                });
+            });
+            ui.label("• Setup the relays you write to");
+            ui.indent("quickstartrelays", |ui| {
+                ui.horizontal_wrapped(|ui| {
+                    ui.label("On the");
+                    if ui.link("Relays").clicked() {
+                        app.set_page(Page::Relays);
+                    }
+                    ui.label("page, add a relay that you post to (or several), and tick off \"Post Here\" (otherwise it won't pull your data from there). Remember to press \"SAVE CHANGES\" at the bottom of that page.");
+                });
+            });
+            ui.label("• Follow yourself");
+            ui.indent("quickstartfollowyou", |ui| {
+                ui.horizontal_wrapped(|ui| {
+                    ui.label("On the");
+                    if ui.link("People > Follow Someone New").clicked() {
+                        app.set_page(Page::PeopleFollow);
+                    }
+                    ui.label("page, follow yourself (specify your public key AND one of the relays you added in the previous step. If you don't add the relay, gossip can't help you).");
+                });
+            });
+            ui.label("• Restart");
+            ui.indent("quickstartrestart", |ui| {
+                ui.horizontal_wrapped(|ui| {
+                    ui.label("Sorry, this insufficiency will be remedied eventually. After following somebody it doesn't rewrite the general feed subscription, but restarting does.");
+                });
+            });
+            ui.label("• Browse your feed and explore threads");
+            ui.indent("quickstartfeedthreads", |ui| {
+                ui.horizontal_wrapped(|ui| {
+                    ui.label("On the");
+                    if ui.link("Feed > Following").clicked() {
+                        app.set_page(Page::Feed(FeedKind::General));
+                    }
+                    ui.label("page, look at your posts (by default only the last 12 hours show up) and their replies (by clicking the right arrow on the right side of post to give the thread), which will give gossip some data to launch from. Hopefully you have some replies. But if not, no worry, the next step helps too.");
+                });
+            });
+            ui.label("• Pull your Contacts List");
+            ui.indent("quickstartpullcontacts", |ui| {
+                ui.horizontal_wrapped(|ui| {
+                    ui.label("On the");
+                    if ui.link("People > Followed").clicked() {
+                        app.set_page(Page::PeopleList);
+                    }
+                    ui.label("page, press [Pull Overwrite] to pull down the people you follow. Metadata is not automatically gathered for them yet (but will be in the future).");
+                });
+            });
+            ui.label("• Click Avatars to explore people");
+            ui.indent("quickstartclickavatars", |ui| {
+                ui.horizontal_wrapped(|ui| {
+                    ui.label("Click any of these people's avatars to get to their page, where you can update their metadata or view their posts. If you don't get any data for a person, it may be because there is no good way for nostr to know where they post to. This problem goes away after using gossip for awhile, and it remains an outstanding issue to solve.");
+                });
+            });
+
+            ui.add_space(10.0);
+            ui.separator();
+            ui.add_space(10.0);
+
             ui.horizontal_wrapped(|ui| {
                 ui.label(RichText::new("Gossip follows people").heading());
                 ui.label(RichText::new("at relays").heading().italics());
@@ -35,50 +111,43 @@ pub(super) fn update(app: &mut GossipUi, ctx: &Context, _frame: &mut eframe::Fra
             ui.horizontal_wrapped(|ui| {
                 ui.label("Gossip follows people at whichever relays they post to,");
                 ui.label(RichText::new("not").strong());
-                ui.label("whichever relays you post to. This is a core concept. As the nostr network expands, it will be increasingly unlikely that the person you want to follow posts to the same relays that you do. And it will become increasingly untenable for event mirroring to be occuring on all those relays. Most clients will eventually need to work this way, except for clients that intend to be bound to a local community of relays.");
+                ui.label("some list of relays you choose to read from. This is a core concept. As the nostr network expands, it will be increasingly unlikely that the person you want to follow posts to the same relays that you do. And it will become increasingly untenable for event mirroring to be occuring on all those relays. Most clients will eventually need to work this way, except for clients that intend to be bound to a local community of relays.");
+            });
+
+            ui.add_space(10.0);
+            ui.horizontal_wrapped(|ui| {
+                ui.label("Think of it like a web browser. Web browsers fetch resources that other resources (pages) refer to, and they can get them from any URL on the Internet. Gossip can find people and events at relays it has never heard of before if other events reference them as being there.");
             });
 
             ui.add_space(10.0);
             ui.horizontal_wrapped(|ui| {
                 ui.label("The upshot of this is that when you follow someone, you will need to supply their public key");
-                ui.label(RichText::new("and their relays").italics());
+                ui.label(RichText::new("and their relays.").italics());
-            });
+                ui.label("You do this at the");
-
-            ui.add_space(10.0);
-            ui.label("NIP-05 (used in the reverse for user discovery) makes this easy, since it specifies how users can share their public key and their relays via a webserver that they control. For example, you can follow me at `mike@mikedilger.com`. That's all you need to type in. Gossip will go to mikedilger.com, fetch the `.well-known/nostr.json` file, find the entry for `mike` and find the relays for that public key. Then it will go to those relays and pull my recent posts into your feed.");
-            ui.add_space(10.0);
-
-            ui.label("Other ways of following people include pasting their public key (hex or bech32 format) and typing in a relay URL which should start with 'ws'.  NOTE: use CTRL-V to paste, other forms of pasting (X11 middle click) won't work.");
-            ui.add_space(10.0);
-
-            ui.horizontal_wrapped(|ui| {
-                ui.label("To get started, go to the");
                 if ui.link("People > Follow Someone New").clicked() {
                     app.set_page(Page::PeopleFollow);
                 }
-                ui.label("page and add people to follow. If you don't know anybody, you can follow me at NIP-05 DNS ID mike@mikedilger.com and you can find other people through me (posts I reply to or quote).");
+                ui.label("page.");
             });
-            ui.add_space(10.0);
-
-            ui.label("Gossip currently does not fetch your following list from nostr. Nor does it publish the list of follows you configure on gossip so you don't have to worry about it clobbering anything (but this will change).");
 
             ui.add_space(10.0);
-            ui.separator();
+            ui.label("There are multiple ways to supply this information:");
-            ui.add_space(10.0);
+            ui.label("\n• Fetching your Contact List (kind 3 event)");
-
+            ui.indent("helpfollowcontactlist", |ui| {
-            ui.heading("Driving the Feed");
+                ui.label("If you have used other clients and have published your contact list, after you setup your identity (next section) you can pull in your contact list. However, it probably won't include URLs for your contacts.");
-            ui.add_space(10.0);
+            });
-
+            ui.label("\n• nprofile");
-            ui.label("Recent events from people you follow should show up on the main [Feed > Following] page in reverse chronological order, without replies or context. If you want to see the context of a post, press the right-arrow on the right hand side of the feed to move to the [Feed > Thread] page. This page should show the full context, and when you enter the thread page it will ask relays questions in order to fill in the thread. But often it is missing posts and can't quite get the full context. In fact, there are cases where the post you clicked on isn't even there. Future development on Gossip will likely improve this greatly.");
+            ui.indent("helpfollownprofile1", |ui| {
-            ui.add_space(10.0);
+                ui.label("An nprofile string is bech32 encoded information about a person that includes their public key as well as one or more relays that they post to. As strings, they can be anywhere: on other social media, in emails, on webpages, as QR codes, etc. NOTE: as of this writing gossip does not support nprofile, but it should soon.");
-
+            });
-            ui.label("One dirty hack that helps: As events come in, they often refer to other events that have not come in yet. If you want to query the relays for these missing events, you can by pressing the QM (Query Missing) button on the feed page. Usually some but not all missing events can be found this way. But it is older code and newer event processing may have already superceded it's abilities by the time you read this. Still, worth a shot.");
+            ui.label("\n• NIP-05 (in reverse)");
-
+            ui.indent("helpfollownip05", |ui| {
-            ui.add_space(10.0);
+                ui.label("NIP-05 specifies a nostr.json file on a webserver which contains a person's name and public key, but now also can contain the relays they post to. I find it very easy and natural to follow `mike@mikedilger.com` - that is all you have to type. Using just this email-like address (email not being involved, we call it a dns id or a nip05 identifier), gossip will go to mikedilger.com, fetch the `.well-known/nostr.json` file, find the entry for `mike` and find the relays for that public key. Then it will go to those relays and pull my recent posts into your feed. Unfortunately as of this writing, I've only encountered one other person who has put relays into their nostr.json file. But I hope it (or something functionally equivalent) catches on eventually.");
-            ui.label("There is a [Feed > Replies] page where you can see replies to your own posts, with descendants (but not ancestors)");
+            });
-
+            ui.label("\n• Typing them both in");
-            ui.add_space(10.0);
+            ui.indent("helpfollowtype", |ui| {
-            ui.label("Finally there is a [Feed > Person] page where you can see posts made by a person. To get there, click an avatar, then click [VIEW THEIR FEED].");
+                ui.label("Entering both a key (either bech32 or hex) as well as at least one relay URL. NOTE: as of this writing, gossip only takes one relay URL when you add a person to follow.");
+            });
 
             ui.add_space(10.0);
             ui.separator();
@@ -92,20 +161,36 @@ pub(super) fn update(app: &mut GossipUi, ctx: &Context, _frame: &mut eframe::Fra
                 if ui.link("You").clicked() {
                     app.set_page(Page::You);
                 }
-                ui.label("page you can setup your identity. If you are new, you should just press \"Generate\" and you are good to go. Otherwise you can import a private key in hex or bech32 format, although it isn't very secure to cut-n-paste and display your private key, so it will mark your key security as \"weak\". Eventually you'll be able to import your password-protected private key from a nostr relay.");
+                ui.label("page you can setup your identity. If you are new, you should just press \"Generate\" and you are good to go. Otherwise you can import a private key in hex or bech32 format, although it isn't very secure to cut-n-paste and display your private key, so it will mark your key security as \"weak\". Hopefully one day soon you'll be able to import a password-protected private key exported from a different client.");
             });
             ui.add_space(10.0);
 
-            ui.label("After generating or importing your key, gossip will save it encrypted under a password. You will need this password to unlock it every time you start gossip. Gossip handles keys securely by never displaying them and zeroing memory used for private keys and passwords before freeing it (unless you explicitly request it to be exported).");
+            ui.label("After generating or importing your key, gossip will save it encrypted under a password. You will need this password to unlock it every time you start gossip. Gossip handles keys securely, never writes them to disk, never displays them (unless you request it to) and zeroing memory that was used for private keys or passwords before freeing it.");
             ui.add_space(10.0);
 
-            ui.label("If you are just trying Gossip out and not intending to post or react to posts yet, you can just import your public key. This way you'll be able to sync your following list (when that work is committed), and see your replies, but you won't be able to post or react to posts.");
+            ui.label("If you are just trying Gossip out and not intending to post or react to posts yet, you can just import your public key. This way you'll be able to sync your following list, view your feed and see your replies, but you won't be able to post or react to posts.");
             ui.add_space(10.0);
 
             ui.add_space(10.0);
             ui.separator();
             ui.add_space(10.0);
 
+            ui.heading("The Feeds");
+            ui.add_space(10.0);
+
+            ui.label("Recent events from people you follow should show up on the main [Feed > Following] page in reverse chronological order, without replies or context. If you want to see the context of a post, press the right-arrow on the right hand side of the feed to move to the [Feed > Thread] page. This page should show the full context, and when you enter the thread page it will ask relays questions in order to fill in the thread. But it doesn't always work smoothly.  Sometimes it is missing posts and can't quite get the full context. In fact, there are cases where the post you clicked on isn't even there (known bug). Future development on Gossip will likely improve this greatly.");
+            ui.add_space(10.0);
+
+            ui.label("There is a [Feed > Replies] page where you can see replies to your own posts as well as mentions of you.");
+
+            ui.add_space(10.0);
+            ui.label("Finally there is a [Feed > Person] page where you can see posts made by a person. To get there, click an avatar, then click [VIEW THEIR FEED].");
+
+            ui.add_space(10.0);
+            ui.separator();
+            ui.add_space(10.0);
+
+
             ui.heading("Configuring your Relays");
             ui.add_space(10.);
 
@@ -117,11 +202,11 @@ pub(super) fn update(app: &mut GossipUi, ctx: &Context, _frame: &mut eframe::Fra
                 if ui.link("Relays").clicked() {
                     app.set_page(Page::Relays);
                 }
-                ui.label("page and tick a half dozen relays that you intend to post to. If your webserver serves a nostr.json file, you can follow NIP-05 and use the same relays in that file.");
+                ui.label("page and tick the relays that you intend to post to. If your webserver serves a nostr.json file, you can make the relays that you post to match the contents of the relay portion of that file.");
             });
             ui.add_space(10.0);
 
-            ui.label("Gossip currently does not synchronize this list of relays on the nostr network, so it will not get data you use with other clients. Nor will it clobber that data. The list is local and independent (but this will change).");
+            ui.label("Gossip currently does not synchronize this list of relays on the nostr network, so it will not get relay data you use with other clients. The list is local and independent, but this is expected to change.");
 
             ui.add_space(10.0);
             ui.separator();
@@ -136,14 +221,20 @@ pub(super) fn update(app: &mut GossipUi, ctx: &Context, _frame: &mut eframe::Fra
             ui.label("To reply, press the reply icon at the bottom of the post you want to reply to. That post will be copied to the top of the page to make it clear what you are replying to. Type your reply and press Send.");
             ui.add_space(10.0);
 
-            ui.label("To react, you can click the heart. Other kinds of reactions are not yet implemented. You can see other people's reactions below the posts.");
+            ui.label("To quote another post, press the quote icon at the bottom of the post you want to reply to, and a bech32 note string will be added into the edit box.  That will be replaced with the reference to the post you quoted when you press Send.");
             ui.add_space(10.0);
 
-            ui.label("Quoting and Boosting content are not yet implemented.");
+            ui.label("To tag someone, start typing their name into the @username box to the right of the posting box, then press the [@] button below to get a pulldown of matches. Pick the match you wish, and it will add a bech32 npub string to the edit box.  That will be replaced with a tag of the person you are tagging when you press Send.");
+
+            ui.label("To react, you can click the heart. Other kinds of reactions are not yet implemented. You can see other people's reactions below the posts. If you don't like reactions, you can disable this in the settings.");
             ui.add_space(10.0);
 
             ui.add_space(10.0);
 
+            ui.heading("Things You Can't Do ... Yet");
+            ui.add_space(10.0);
+
+            ui.label("We don't yet support editing or publishing your metadata, pulling or publishing your relays, encrypted direct messages, seeing other people's contact lists, seeing your follower count, hiding replies (which could always be spammy), muting people, marking sensitive content, expiration timestamps, delegated event signing, subject tags, or note deletion. But we intend to do all of that. We also don't support chat.");
         });
     } else if app.page == Page::HelpStats {
         stats::update(app, ctx, _frame, ui);

src/ui/people/follow.rs

@@ -7,9 +7,8 @@ use egui::{Context, TextEdit, Ui};
 pub(super) fn update(app: &mut GossipUi, _ctx: &Context, _frame: &mut eframe::Frame, ui: &mut Ui) {
     ui.add_space(30.0);
 
-    ui.heading("NOTICE: Gossip doesn't update the filters when you follow someone yet, so you have to restart the client to fetch their events. Will fix soon.");
+    ui.label("NOTICE: Gossip doesn't update the filters when you follow someone yet, so you have to restart the client to fetch their events. Will fix soon.
-
+");
-    ui.heading("NOTICE: Gossip is not synchronizing with data on the nostr relays. This is a separate list and it won't overwrite anything.");
 
     ui.label("NOTICE: use CTRL-V to paste (middle/right click wont work)");