Start tutorials with transports on irc. #6

Merged
southerntofu merged 1 commits from :docs into main 7 months ago

This PR creates the following,

[1] Section 'Tutorials': Section for tutorials related to JoinJabber.
[2] Category 'Transports': Category for tutorials that fall under transports.
[3] Content 'IRC Transport': First tutorial entry on how to connect to IRC from Jabber via Biboumi.

This PR creates the following, [1] Section 'Tutorials': Section for tutorials related to JoinJabber. [2] Category 'Transports': Category for tutorials that fall under transports. [3] Content 'IRC Transport': First tutorial entry on how to connect to IRC from Jabber via Biboumi.
raghavgururajan added 1 commit 7 months ago
raghavgururajan force-pushed docs from 75b5f3e5b4 to 384179ca02 7 months ago
raghavgururajan force-pushed docs from 384179ca02 to a2ba9ac72b 7 months ago
raghavgururajan force-pushed docs from a2ba9ac72b to b152166bcf 7 months ago
raghavgururajan force-pushed docs from b152166bcf to c8969a23bf 7 months ago
southerntofu reviewed 7 months ago
## HowTo
1. [How to connect to IRC from Jabber?](https://joinjabber.org/docs/howto/irc)
Poster
Owner

Could you maybe use an internal link here? This way it will work with .onion address (and others in the future)

Could you maybe use an [internal link](https://www.getzola.org/documentation/content/linking/#internal-links) here? This way it will work with .onion address (and others in the future)
southerntofu marked this conversation as resolved
southerntofu reviewed 7 months ago
# Jabber <-> IRC
Here it's shown how to connect to IRC from Jabber, via Biboumi (an IRC transport for Jabber).
Poster
Owner

Could you maybe add a paragraph to describe IRC and compare it with Jabber? Maybe add a link to biboumi website?

Could you maybe add a paragraph to describe IRC and compare it with Jabber? Maybe add a link to biboumi website?
southerntofu marked this conversation as resolved
southerntofu reviewed 7 months ago
The syntax for connecting to IRC channel is:
`#channel%irc.network.tld@irc.transport.tld`
Poster
Owner

Are there public biboumi instances? Or maybe we can explicit that irc.transport.tld is a service often provided by Jabber servers? If you have time, it would be nice also to check what servers we recommend have a IRC gateway so we can advertise the list here (otherwise we can do it later!)

Are there public biboumi instances? Or maybe we can explicit that `irc.transport.tld` is a service often provided by Jabber servers? If you have time, it would be nice also to check what servers we recommend have a IRC gateway so we can advertise the list here (otherwise we can do it later!)
southerntofu marked this conversation as resolved
southerntofu reviewed 7 months ago
Repeat 1 and 3, for different channel but same network and transport.
Repeat 1 to 3, for different channel, network and transport.
Poster
Owner

So maybe if we have a short sentence explaining what an IRC network is (eg. like a MUC server), we don't need a list? Just something like "Just like you're used to joining a Jabber chat by joining chat@muc.server", here you would join chat%irc.server@biboumi.server, where chat is the chatroom you'd like to join on the IRC network irc.server."

Then we can add another point about authentication but i think most people who need it are already familiar with it so it could be a separate point to keep the "one-shot tutorial" super simple. Do you agree?

So maybe if we have a short sentence explaining what an IRC network is (eg. like a MUC server), we don't need a list? Just something like "Just like you're used to joining a Jabber chat by joining chat@muc.server", here you would join chat%irc.server@biboumi.server, where chat is the chatroom you'd like to join on the IRC network irc.server." Then we can add another point about authentication but i think most people who need it are already familiar with it so it could be a separate point to keep the "one-shot tutorial" super simple. Do you agree?
southerntofu marked this conversation as resolved
southerntofu reviewed 7 months ago
Repeat 3 to 7, if joining different channel on different network via same transport.
Repeat 1 to 7, if joining different channel on different network via different transport.
Poster
Owner

Maybe make it clear this only needs to be done once and then you can use any Jabber client in which the IRC chat will appear as a classical Jabber chat.

Maybe make it clear this only needs to be done once and then you can use any Jabber client in which the IRC chat will appear as a classical Jabber chat.
southerntofu marked this conversation as resolved
raghavgururajan force-pushed docs from c8969a23bf to 2896d96f48 7 months ago

@southerntofu

Thanks so much for your feed-back. I have now made some changes. If there are still things that can be improved upon, I can do it some other time or I'll let others to contribute. :-)

@southerntofu Thanks so much for your feed-back. I have now made some changes. If there are still things that can be improved upon, I can do it some other time or I'll let others to contribute. :-)
raghavgururajan changed title from Start docs with how-to on irc. to Start tutorials with transports on irc. 7 months ago

Thanks a lot @raghavgururajan ! Just a few more changes before merging (and we'll keep improving after)

  • _index.md is for sections (pages with children pages), please use index.md for a simple page
  • could the IRC client page we're writing be in its own "client" subsection? so then we can add a server guide
  • not sure, but maybe rename "tutorials" "guide" ? "documentation" would be less clear but maybe we're not having only tutorials in this section in the future? <-- if you think tutorials is fine keep it that way ;)
Thanks a lot @raghavgururajan ! Just a few more changes before merging (and we'll keep improving after) - `_index.md` is for sections (pages with children pages), please use `index.md` for a simple page - could the IRC client page we're writing be in its own "client" subsection? so then we can add a server guide - not sure, but maybe rename "tutorials" "guide" ? "documentation" would be less clear but maybe we're not having only tutorials in this section in the future? <-- if you think tutorials is fine keep it that way ;)
raghavgururajan force-pushed docs from 2896d96f48 to 59ea801129 7 months ago
raghavgururajan force-pushed docs from 59ea801129 to ea77a84346 7 months ago

@southerntofu

I have made the changes.

Regarding tutorials|guides|docs, I think tutorials is aptly named.

Regarding separate clients directory, we'll re-work the index when we have more content.

:-)

@southerntofu I have made the changes. Regarding tutorials|guides|docs, I think tutorials is aptly named. Regarding separate clients directory, we'll re-work the index when we have more content. :-)
raghavgururajan added 1 commit 7 months ago
raghavgururajan force-pushed docs from 5309678435 to ea77a84346 7 months ago
southerntofu reviewed 7 months ago
# Tutorials
1. **[Transports](@/tutorials/transports/index.md)**
Poster
Owner

This file needs to be _index.md because it's a parent to other pages (section).

This file needs to be _index.md because it's a parent to other pages (section).
southerntofu marked this conversation as resolved
southerntofu reviewed 7 months ago
In Jabber realm, transports are the means to connect to different protocols.
1. **[IRC](@/tutorials/transports/irc/index.md)**
Poster
Owner

This file needs to be _index.md because it's a parent to other pages (section).

This file needs to be _index.md because it's a parent to other pages (section).
southerntofu marked this conversation as resolved

Two small changes and we're ready to merge :)

Two small changes and we're ready to merge :)
raghavgururajan force-pushed docs from ea77a84346 to ce963859e0 7 months ago
raghavgururajan force-pushed docs from ce963859e0 to 39cd528538 7 months ago

@southerntofu

Done! :-)

@southerntofu Done! :-)
raghavgururajan force-pushed docs from 39cd528538 to b02c4fa686 7 months ago
raghavgururajan force-pushed docs from b02c4fa686 to 41f71b2f87 7 months ago
southerntofu approved these changes 7 months ago
southerntofu merged commit eaaa38086f into main 7 months ago

Thanks it's been merged!

For future reference, i missed in review that you need TOML frontmatter in pages/sections, as done in b549daa340

That's because zola doesn't yet support empty frontmatter

Thanks it's been merged! For future reference, i missed in review that you need TOML frontmatter in pages/sections, as done in b549daa3404570aad0fb0acf6d3f7fcd2d49377c That's because zola doesn't yet support [empty frontmatter](https://github.com/getzola/zola/issues/374)
raghavgururajan deleted branch docs 7 months ago

Reviewers

southerntofu approved these changes 7 months ago
The pull request has been merged as eaaa38086f.
Sign in to join this conversation.
No reviewers
No Milestone
No Assignees
2 Participants
Notifications
Due Date

No due date set.

Dependencies

This pull request currently doesn't have any dependencies.

Loading…
There is no content yet.