|author||Florent Le Coz <email@example.com>||2014-06-11 02:37:11 +0200|
|committer||Florent Le Coz <firstname.lastname@example.org>||2014-06-11 02:37:11 +0200|
Rewrite the whole IID usage
IRC users and channels are now distinguished by the separator used in the IID (% or !). ref #2468
Diffstat (limited to 'doc')
1 files changed, 26 insertions, 10 deletions
diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md
index 605fb96..38a4718 100644
@@ -101,11 +101,12 @@ signal again or if a 2 seconds delay has passed.
IRC entities are represented by XMPP JIDs. The domain part of the JID is
-the domain served by biboumi, and the local part depends on the concerned
+the domain served by biboumi (the part after the `@`, biboumi.example.com in
+the examples), and the local part (the part before the `@`) depends on the
-IRC channels and IRC users JIDs have a localpart formed like this:
-`name`, the `'%'` separator and the `irc_server`.
+IRC channels have a local part formed like this:
If the IRC channel you want to adress starts with the `'#'` character (or an
other character, announced by the IRC server, like `'&'`, `'+'` or `'!'`),
@@ -113,12 +114,16 @@ then you must include it in the JID. Some other gateway implementations, as
well as some IRC clients, do not require them to be started by one of these
characters, adding an implicit `'#'` in that case. Biboumi does not do that
because this gets confusing when trying to understand the difference between
-the channels *#foo*, and *##foo*.
+the channels *#foo*, and *##foo*. Note that biboumi does not use the
+presence of these special characters to identify an IRC channel, only the
+presence of the separator `%` is used for that.
-The name part can also be empty (for example `%irc.example.com`), in that
+The channel name can also be empty (for example `%irc.example.com`), in that
case this represents the virtual channel provided by biboumi. See *Connect
to an IRC server* for more details.
+IRC users have a local part formed like this:
On XMPP, the node part of the JID can only be lowercase. On the other hand,
IRC nicknames are case-insensitive, this means that the nicknames toto,
@@ -131,7 +136,7 @@ Examples:
irc.example.com IRC server, and this is served by the biboumi instance on
- `email@example.com` is the IRC user named toto, or
+ `firstname.lastname@example.org` is the IRC user named toto, or
`email@example.com` is the IRC server irc.example.com.
@@ -139,9 +144,20 @@ Examples:
`%firstname.lastname@example.org` is the virtual channel provided by
biboumi, for the IRC server irc.example.com.
-If compiled with Libidn, an IRC user has a bare JID representing the
-“hostname” provided by the IRC server. This JID can only be used to set IRC
-modes (for example to ban a user based on its IP), or to identify user.
+Note: Some JIDs are valid but make no sense in the context of
+ `!email@example.com` is the empty-string nick on the
+ irc.example.com server. It makes no sense to try to send messages to it.
+ `#firstname.lastname@example.org`, or any other JID that does not contain an
+ IRC server is invalid. Any message to that kind of JID will trigger an
+ error, or will be ignored.
+If compiled with Libidn, an IRC channel participant has a bare JID
+representing the “hostname” provided by the IRC server. This JID can only
+be used to set IRC modes (for example to ban a user based on its IP), or to
+identify user. It cannot be used to contact that user using biboumi.
### Join an IRC channel