amfora
amfora copied to clipboard
makew0rld
Wiki: Docs, Tutorials
The wiki has started!
Amfora is growing, and its feature-set is becoming larger and less obvious when casually browsing. I feel that the README is also becoming a bit cluttered. Some documentation or tutorials on specific features should be created to resolve this, and then linked in the README.
Documentation Topics
- [x] Basic navigation
- Mention link numbers!! You can access links > 10 by pressing space, typing the number, then Enter.
- [x] Client certs
- [x] Move this off the README
- [x] How to add to config
- [x] How to generate on Windows
- [x] Expiry dates?
- [x]
[url-handlers]config section - [x]
[[mediatype-handlers]]config section(s) (#121) - [x] Proxying
- Links to existing proxy software
- [x] Subscriptions (#61)
- [x] Write gemlog post after release
- [x] Bookmarks
Readme changes
- [ ] Table of contents
- [x] Collapse the Building From Source section with
<details>and<summary>
Other
- [x] Mirror wiki on Gemini - put script in
contrib/ - [x] Link to GitHub and Gemini version of wiki on new tab page.
How about using GitHub's wiki system and moving all documentation to it? I'd be willing to write about the parts that I have a decent grasp on.
I was thinking about that last night! A GitHub wiki seems like the way to go. It's clone-able, so I don't feel tied in.
As for you contributing, that sounds great! Thanks. I think I'd like to write the opening sections myself, but you're welcome to add on.
@lokesh-krishna I would be happy to have you create and write sections, I take back what I said about starting them. I've been tied up with code (#61) and also day-to-day life. Let me know if you can!
I've created the Wiki, with a dummy first page. That way you can open PRs to add to it.
Hey,
It would be an honor.
I've already begun and should hopefully have the basics ready by tomorrow!
Here is what I have so far: Amfora WIki
I have a few doubts though so lemme know when you'll be available on IRC and we can maybe discuss things?
Thanks! I'm happy to add that as it is and then make my own changes, but I'll come online this afternoon (EST) and we can talk.
Your page was added with some small changes, and the sections it contained were removed from the README.
Added sections on URL-handlers and proxying (which includes the few proxies that I know of).
Thanks! Unfortunately I think this is just starting to look like a big README. I want to split this up into different pages to make it more readable, and to allow a user to focus on the areas they want. But I'm not sure exactly what the pages would be. Any ideas? I'll think about it more as well.
Once we figure that out, I can add these new sections.
Other things:
- It's helpful if you sync your wiki with mine, as I made some small changes when I added your homepage
- Aren't the proxies X-to-Gemini, not Gemini-to-X?
Any ideas? I'll think about it more as well.
I like the Polybar wiki's organization a lot and think their categorization with a home page and then separate pages for compiling, configuration and theming would be a good fit for Amfora too.
It's helpful if you sync your wiki with mine, as I made some small changes when I added your homepage
Right, I did add yours as a remote but forgot to sync. If you settle upon an organization scheme then would it be too much to ask if I could be a collaborator for just the wiki? GitHub has made things needlessly unwieldy otherwise.
Aren't the proxies X-to-Gemini, not Gemini-to-X?
I'm pretty confused about this myself. I based this choice upon Drew's Kineto which is described as a HTTP to Gemini proxy. It lets you serve a Gemini capsule over HTTP. So I figured these proxies that make a HTTP site available on Gemini would be Gemini to X proxies.
I would love to be corrected if I'm getting this wrong.
The polybar wiki organization is not super clear to me, but seems decent. For Amfora I think having a general configuration page is good, but I don't want to end up putting everything in there, like URL handlers and proxies. Maybe just at the top pages that require configuration just link back to config page? Like polybar does here.
As for specific pages, I think if you look at the opening comment in this issue and go off that that'd be good. Each top-level checkbox should have it's own page. Maybe with a different name though, like instead of it being named url-handlers, it could be called "Opening non-gemini URLs" or something.
If you settle upon an organization scheme then would it be too much to ask if I could be a collaborator for just the wiki? GitHub has made things needlessly unwieldy otherwise.
You've been invited as a collaborator. Once you accept, you should be able to edit the wiki yourself. Please let me know here when you add/edit things, but you're welcome to go ahead and do it.
I based this choice upon Drew's Kineto which is described as a HTTP to Gemini proxy. It lets you serve a Gemini capsule over HTTP. So I figured these proxies that make a HTTP site available on Gemini would be Gemini to X proxies.
I realize it's more complicated than I thought, because both portals and proxies are biderectional. Portals take HTTP requests from the user and make Gemini requests, and then translate the Gemini responses into HTTP. Proxies are vice-versa. I would still consider proxies to be X-to-Gemini, since most of the flow of content is the response, which starts out as protocol X, and then is turned into Gemini.
For Amfora I think having a general configuration page is good, but I don't want to end up putting everything in there, like URL handlers and proxies. Maybe just at the top pages that require configuration just link back to config page?
Yup, that sounds good. I'll go with that then :)
You've been invited as a collaborator.
Thank you so, so much! I'm honoured! I definitely mean for everything to be reviewed by you first. Can we do branches on the wiki? That way nothing would get on the main branch until you approved it.
I would still consider proxies to be X-to-Gemini, since most of the flow of content is the response, which starts out as protocol X, and then is turned into Gemini.
This is all I needed. I just kept getting confused.
Can we do branches on the wiki? That way nothing would get on the main branch until you approved it.
Thanks, good idea. You should be able to, let me know if you have any issues.
Let me know when you've reorganized and pushed the URL-handlers and proxying sections, and I'll take a look. Thanks!
I've pushed my changes to the proxy-and-handlers branch. Could you please review them?
Thank you, merged. You can look at the branch history and the master branch history for changes I made.
Some things for the future:
- Don't start the page with a H1 heading like
# Proxying, GitHub does this for us - Page titles can't have hyphens in them apparently. So
Handling Non-Gemini URLsbecameHandling Other URL Schemes
It seems to me like there's now an overlap between the documentation in the config file and in the Wiki. The recently added pages are nice, but it seems like they mostly just copy what's said in the config file. But I think they're good for bringing attention to the feature, and for providing extra info, like links to proxies. But I don't want to maintain docs in two separate places. Thoughts on how to reconcile this?
I think all projects have this redundancy though it's usually in the form of an online wiki and an offline man page. I don't think Amfora is complex enough (yet) to need a man page and I love that you can just copy over the default config file and know everything you need to configure Amfora. I wouldn't want the information to disappear from the default config file.
Maybe we could add more information to the wiki? I am limited by my knowledge but if you were willing to share any notes or make the additions yourself then the wiki could address more involved workflows, additional context and edge cases. An example of this would be the page on subscription giving a brief overview of all supported formats with their advantages and shortcomings. The config file meanwhile would just provide the bare minimum.
Eventually though I think we might need a man page, judging by all that's in store and I would love to be a part of it.
EDIT: Having gone through #142, I can definitely see the need for a man page arising soon. We would need documentation for all that the infobar is capable of but the default config would grow too cluttered if all of it was added there. I strongly believe that all programs should ship with comprehensive offline documentation though so...
Thoughts on how to reconcile this?
Default config file has the bare minimum, comprehensive man page, wiki which at least matches the man page in covering features and configuration with maybe additional context and links to relevant projects (such as proxies).
I love that you can just copy over the default config file and know everything you need to configure Amfora. I wouldn't want the information to disappear from the default config file.
Agreed. It would be simpler for me to just maintain everything in the wiki and link to it in the config file, but I think having it all there is much nicer for users.
Maybe we could add more information to the wiki? [...] The config file meanwhile would just provide the bare minimum.
This makes sense to me. I was more wondering about how write the info that's already in the config. Like so far it's been rewritten into prose sentences, but would it be better to just paste the config in there? Like so:
# Allows setting the commands to run for various URL schemes.
# E.g. to open FTP URLs with FileZilla set the following key:
# ftp = 'filezilla'
# You can set any scheme to "off" or "" to disable handling it, or
# just leave the key unset.
#
# DO NOT use this for setting the HTTP command.
# Use the http setting in the "a-general" section above.
#
# NOTE: These settings are overrided by the ones in the proxies section.
# Note the use of single quotes, so that backslashes will not be escaped.
# This is a special key that defines the handler for all URL schemes for which
# no handler is defined.
other = 'off'
And then additional info can be written afterwards in sentences.
EDIT: Having gone through #142, I can definitely see the need for a man page arising soon. We would need documentation for all that the infobar is capable of but the default config would grow too cluttered if all of it was added there.
I'm not a huge fan of man pages, and I'm not sure if it's really needed here. Why can't the instructions for the info bar just be added to the config? [theme] is already a large section and I don't think it's an issue.
Default config file has the bare minimum, comprehensive man page, wiki which at least matches the man page in covering features and configuration with maybe additional context and links to relevant projects (such as proxies).
I was thinking config file with relevant info and short explanation, and wiki with more info, context, example setups, etc.
And then additional info can be written afterwards in sentences.
This is good. Would be make it easier to update both too if they share the same base. We could just drop the comments and use code blocks for the actual config stuff?
I'm not a huge fan of man pages, and I'm not sure if it's really needed here.
I just like that they provide an entirely offline yet entirely complete source of documentation. However, if you mean for the config file to still cover everything then I think there's no need for one.
I was thinking config file with relevant info and short explanation, and wiki with more info, context, example setups, etc.
Let's go ahead with this then?
Would be make it easier to update both too if they share the same base.
That's what I was thinking, yeah.
We could just drop the comments and use code blocks for the actual config stuff?
Basically I was just thinking to copy the minimal info in the config file into the wiki as a TOML code block, and then write extra info on the wiki outside of that. Is that what you understood?
However, if you mean for the config file to still cover everything then I think there's no need for [a man page.]
Yep, I like just having that single offline source for info.
Let's go ahead with this then?
Sounds good!
Unrelated, but I'm planning to mirror the wiki on my capsule with a script that uses git pull and md2gemini, and then I can link to it on the new tab page :smile:. I've added this as a checkbox to the top.
Basically I was just thinking to copy the minimal info in the config file into the wiki as a TOML code block, and then write extra info on the wiki outside of that. Is that what you understood?
So all the info in the config file that is in the form of comments would remain as comments within the TOML code block? I was thinking the comments could be moved out of the code block but leaving it in would sure make it even easier to keep both updated.
Yep, that's what I was thinking. It also makes it obvious to the user what information is in the config and what is not. I will update the wiki to do this with existing pages.
@lokesh-krishna I've added a full page on the Subscriptions feature, would be happy to have you take a look, and maybe try out the feature too! It's in master. Let me know if you need a binary.
That's a comprehensive implementation with a comprehensive wiki page to go along with it :)
I just touched up a couple of lines, added a missing word. Hope that's alright.
Testing it out now.
EDIT:
Tried it out and love the implementation. The only suggestion that I have is to link to the wiki in about:subscriptions right after you mention it.
Glad you like both the code and page! Thanks for the fixes. And yes, I'm planning on linking the wiki page. Just want to get the wiki running on Gemini first, so I can link to both versions.
The wiki is now on Gemini! And it's in the new tab page, as of 507c6e8.
gemini://makeworld.gq/amfora-wiki/
I will keep this open as more sections will need to be added over time, but I'm removing it from the v1.7.0 milestone as all the docs I wanted for that release are done.
Wiki is done for v1.8.0, but this page will need to be updated to remove the "not released yet!" notice at the top.
Things to add for v1.9.0 that don't have issues:
- [x] Note/page about bookmarks file and format
- [x] Mention search engine change in changelog
- [x] Put link to Amfora theme in release notes
- [x] Put config change for #207 in release notes
- [x] Mention rare potential issues with custom config, bookmarks, or subscriptions - see #255
Todo for v1.10.0 release
- [ ] Remove warning from top of Source Code Highlighting wiki page
- [ ] Update Client Certificates page for #115, fixed in eab0a6a
- [ ] Add info about
AMFORA_SOCKS5to wiki