Fossil SCM
Improvements to chat documentation.
Commit
e525317e631889f7ede29698cf10ab6f32cc4282e1f60237e3b89111ef2fd70d
Parent
9d24a2849018c58…
1 file changed
+67
-31
+67
-31
| --- www/chat.md | ||
| +++ www/chat.md | ||
| @@ -2,46 +2,44 @@ | ||
| 2 | 2 | |
| 3 | 3 | ## Introduction |
| 4 | 4 | |
| 5 | 5 | As of version 2.14 (and prerelease versions after about 2020-12-25), |
| 6 | 6 | Fossil supports a developer chatroom feature. The chatroom provides an |
| 7 | -ephemeral discussion forum for insiders. Design goals include: | |
| 7 | +ephemeral discussion venue for insiders. Design goals include: | |
| 8 | 8 | |
| 9 | 9 | * **Simple but functional** → Fossil chat is designed to provide a |
| 10 | 10 | convenient real-time communication mechanism for geographically |
| 11 | - distributed developers. It is not intended as a replace or | |
| 11 | + dispersed developers. Fossil chat is emphatically *not* intended | |
| 12 | + as a replacement or | |
| 12 | 13 | competitor for IRC, Slack, Discord, Telegram, Google Hangouts, etc. |
| 13 | 14 | |
| 14 | - * **Low administrative overhead** → | |
| 15 | - There is nothing new to set up or configure. | |
| 15 | + * **Low administration** → | |
| 16 | + There is no additional set up or configuration. | |
| 16 | 17 | Simply enable the [C capability](/setup_ucap_list) for users |
| 17 | 18 | whom you want to give access to the chatroom. |
| 18 | 19 | |
| 19 | 20 | * **Ephemeral** → |
| 20 | 21 | Chat messages do not sync to peer repositories. And they are |
| 21 | 22 | automatically deleted after a configurable delay (default: 7 days). |
| 22 | - | |
| 23 | -Fossil chat is designed to provide a communication venue for discussion | |
| 24 | -that does *not* become part of the permanent record for the project. | |
| 25 | -For persist and syncable discussion, use the [Forum](./forum.wiki). | |
| 23 | + They can be deleted at any time without impacting any other part | |
| 24 | + of the system. | |
| 26 | 25 | |
| 27 | 26 | Fossil chat is designed for use by insiders - people with check-in |
| 28 | -privileges or higher. It is not intended as a general-urpose gathering | |
| 29 | -place for random passers-by on the internet. (It could be used for that, | |
| 30 | -in theory, but its feature set is not designed with that use case in mind.) | |
| 31 | - | |
| 32 | -Fossil chat is designed for transient, ephemerial, real-time discussion. | |
| 33 | -The conversation is local to a single repository and is not synced or | |
| 34 | -retained long-term. | |
| 35 | - | |
| 36 | -Fossil chat is specific to a single repository. It is only really useful | |
| 37 | -if you configure a [common server repository](./server/) that all chat | |
| 38 | -participants can connect to. | |
| 27 | +privileges or higher. It is not intended as a general-purpose gathering | |
| 28 | +place for random passers-by on the internet. | |
| 29 | +Fossil chat is seeks to provide a communication venue for discussion | |
| 30 | +that does *not* become part of the permanent record for the project. | |
| 31 | +For persist and durable discussion, use the [Forum](./forum.wiki). | |
| 32 | +Because the conversation is intended to be ephemeral, the chat messages | |
| 33 | +are local to a single repository. Chat content does not sync. | |
| 34 | + | |
| 39 | 35 | |
| 40 | 36 | ## Setup |
| 41 | 37 | |
| 42 | -To activate Fossil chat, simply add the [C capability](/setup_ucap_list) | |
| 38 | +A Fossil repository must be functioning as a [server](./server/) in order | |
| 39 | +for chat to work. | |
| 40 | +To activate chat, simply add the [C capability](/setup_ucap_list) | |
| 43 | 41 | to every user who is authorized to participate. Anyone who can read chat |
| 44 | 42 | can also post to chat. |
| 45 | 43 | |
| 46 | 44 | Setup ("s") and Admin ("a") users always have access to chat, without needing |
| 47 | 45 | the "C" capability. A common configuration is to add the "C" capability |
| @@ -58,12 +56,12 @@ | ||
| 58 | 56 | |
| 59 | 57 | For users with appropriate permissions simply browse to the |
| 60 | 58 | [/chat](/help?cmd=/chat) to start up a chat session. The default |
| 61 | 59 | skin includes a "Chat" entry on the menu bar on wide screens for |
| 62 | 60 | people with chat privilege. There is also a "Chat" option on |
| 63 | -the [Sitemap page](/sitemap) (which is linked to the hamburger menu | |
| 64 | -of many skins). | |
| 61 | +the [Sitemap page](/sitemap), which means that chat will appears | |
| 62 | +as an option under the hamburger menu for many [skins](./customskin.md). | |
| 65 | 63 | |
| 66 | 64 | Message text is delivered verbatim. There is no markup. However, |
| 67 | 65 | the chat system does try to identify and tag hyperlinks, as follows: |
| 68 | 66 | |
| 69 | 67 | * Any word that begins with "http://" or "https://" is assumed |
| @@ -74,21 +72,52 @@ | ||
| 74 | 72 | [Markdown](/md_rules) understand hyperlinks) then that text |
| 75 | 73 | is tagged. |
| 76 | 74 | |
| 77 | 75 | Apart from adding hyperlink anchor tags to bits of text that look |
| 78 | 76 | like hyperlinks, no changes are made to the input text. |
| 77 | + | |
| 78 | +## Aural Alerts | |
| 79 | + | |
| 80 | +If you have a local clone and checkout for a remote Fossil repository | |
| 81 | +and that remote repository supports chat, | |
| 82 | +then you can bring up a chat window for that remote repository | |
| 83 | +that will beep whenever new content arrives. This must be done from a | |
| 84 | +terminal window. | |
| 85 | +Change directories to a working checkout of the local clone and type: | |
| 86 | + | |
| 87 | +> fossil chat | |
| 88 | + | |
| 89 | +This command will bring up a chat window in your default web-browser | |
| 90 | +(similar to the way the "[fossil ui](/help?cmd=ui)" does). The | |
| 91 | +chat will be for the remote repository, the repository whose URL shows | |
| 92 | +when you type the "[fossil remote](/help?cmd=remote)" command. In | |
| 93 | +addition to bring up the chat window, this command will also | |
| 94 | +send a single "bel" character (U+0007) to standard error of the terminal | |
| 95 | +whenever new messages arrive in the chat window. On most systems, | |
| 96 | +the terminal windows will emit an "beep" whenever they receive the U+0007 | |
| 97 | +character. This works out-of-the-box for Mac and Windows, but on some | |
| 98 | +flavors of Linux, you might need to enable terminal beeps in your system | |
| 99 | +preferences. | |
| 100 | + | |
| 101 | +In theory, it should be possible to get a web-browser to make an alert | |
| 102 | +sound whenever new content arrives in the chat window. However, the | |
| 103 | +Fossil developers have been unable to figure out how to do that. | |
| 104 | +Web-browsers make it very difficult to play sounds that are | |
| 105 | +not the direct result of a user-click, probably to prevent | |
| 106 | +advertisements from pestering users with a cacophony of alerts. | |
| 107 | + | |
| 79 | 108 | |
| 80 | 109 | ## Implementation Details |
| 81 | 110 | |
| 82 | -*(This section is informational only. You do not need to understand | |
| 83 | -how Fossil chat works in order to use it. But many developers prefer | |
| 84 | -to know what is happening "under the hood".)* | |
| 111 | +*You do not need to understand how Fossil chat works in order to use it. | |
| 112 | +But many developers prefer to know how their tools work. | |
| 113 | +This section is provided for the benefit of those curious developers.* | |
| 85 | 114 | |
| 86 | 115 | The [/chat](/help?cmd=/chat) webpage downloads a small amount of |
| 87 | 116 | HTML and a few KB of javascript to run the chat session. The |
| 88 | 117 | javascript uses XMLHttpRequest (XHR) to download chat content, |
| 89 | -post not content, or delete historical message. The following | |
| 118 | +post new content, or delete historical messages. The following | |
| 90 | 119 | web interfaces are used by the XHR: |
| 91 | 120 | |
| 92 | 121 | * **/chat-poll** → |
| 93 | 122 | Download chat content as JSON. |
| 94 | 123 | Chat messages are number sequentially. |
| @@ -101,18 +130,25 @@ | ||
| 101 | 130 | Sends a new chat message to the server. |
| 102 | 131 | |
| 103 | 132 | * **/chat-delete** → |
| 104 | 133 | Delete a chat message. |
| 105 | 134 | |
| 106 | -The Fossil chat design uses the traditional "hanging GET" or | |
| 135 | + * **/chat-ping** → | |
| 136 | + An HTTP request to this page on the loopback IP address causes | |
| 137 | + a single U+0007 "bel" character to be sent to standard error of | |
| 138 | + the controlling terminal. This is used to implement | |
| 139 | + aural alerts with the "[fossil chat](/help?cmd=chat)" command. | |
| 140 | + | |
| 141 | +Fossil chat uses the venerable "hanging GET" or | |
| 107 | 142 | "[long polling](wikipedia:/wiki/Push_technology#Long_polling)" |
| 108 | -to wait for new chat messages. This is done because that technique works | |
| 109 | -easily with CGI and SCGI, which are the usual mechanisms for setting up | |
| 110 | -a Fossil server. More advanced techniques such as | |
| 143 | +technique to recieve asynchronous notification of new messages. | |
| 144 | +This is done because long polling works well with CGI and SCGI, | |
| 145 | +which are the usual mechanisms for setting up a Fossil server. | |
| 146 | +More advanced notification techniques such as | |
| 111 | 147 | [Server-sent events](wikipedia:/wiki/Server-sent_events) and especially |
| 112 | 148 | [WebSockets](wikipedia:/wiki/WebSocket) might seem more appropriate for |
| 113 | -a chat system, but those technologies are not readily compatible with CGI. | |
| 149 | +a chat system, but those technologies are not compatible with CGI. | |
| 114 | 150 | |
| 115 | 151 | Chat messages are stored on the server-side in the CHAT table of |
| 116 | 152 | the repository. |
| 117 | 153 | |
| 118 | 154 | ~~~ |
| 119 | 155 |
| --- www/chat.md | |
| +++ www/chat.md | |
| @@ -2,46 +2,44 @@ | |
| 2 | |
| 3 | ## Introduction |
| 4 | |
| 5 | As of version 2.14 (and prerelease versions after about 2020-12-25), |
| 6 | Fossil supports a developer chatroom feature. The chatroom provides an |
| 7 | ephemeral discussion forum for insiders. Design goals include: |
| 8 | |
| 9 | * **Simple but functional** → Fossil chat is designed to provide a |
| 10 | convenient real-time communication mechanism for geographically |
| 11 | distributed developers. It is not intended as a replace or |
| 12 | competitor for IRC, Slack, Discord, Telegram, Google Hangouts, etc. |
| 13 | |
| 14 | * **Low administrative overhead** → |
| 15 | There is nothing new to set up or configure. |
| 16 | Simply enable the [C capability](/setup_ucap_list) for users |
| 17 | whom you want to give access to the chatroom. |
| 18 | |
| 19 | * **Ephemeral** → |
| 20 | Chat messages do not sync to peer repositories. And they are |
| 21 | automatically deleted after a configurable delay (default: 7 days). |
| 22 | |
| 23 | Fossil chat is designed to provide a communication venue for discussion |
| 24 | that does *not* become part of the permanent record for the project. |
| 25 | For persist and syncable discussion, use the [Forum](./forum.wiki). |
| 26 | |
| 27 | Fossil chat is designed for use by insiders - people with check-in |
| 28 | privileges or higher. It is not intended as a general-urpose gathering |
| 29 | place for random passers-by on the internet. (It could be used for that, |
| 30 | in theory, but its feature set is not designed with that use case in mind.) |
| 31 | |
| 32 | Fossil chat is designed for transient, ephemerial, real-time discussion. |
| 33 | The conversation is local to a single repository and is not synced or |
| 34 | retained long-term. |
| 35 | |
| 36 | Fossil chat is specific to a single repository. It is only really useful |
| 37 | if you configure a [common server repository](./server/) that all chat |
| 38 | participants can connect to. |
| 39 | |
| 40 | ## Setup |
| 41 | |
| 42 | To activate Fossil chat, simply add the [C capability](/setup_ucap_list) |
| 43 | to every user who is authorized to participate. Anyone who can read chat |
| 44 | can also post to chat. |
| 45 | |
| 46 | Setup ("s") and Admin ("a") users always have access to chat, without needing |
| 47 | the "C" capability. A common configuration is to add the "C" capability |
| @@ -58,12 +56,12 @@ | |
| 58 | |
| 59 | For users with appropriate permissions simply browse to the |
| 60 | [/chat](/help?cmd=/chat) to start up a chat session. The default |
| 61 | skin includes a "Chat" entry on the menu bar on wide screens for |
| 62 | people with chat privilege. There is also a "Chat" option on |
| 63 | the [Sitemap page](/sitemap) (which is linked to the hamburger menu |
| 64 | of many skins). |
| 65 | |
| 66 | Message text is delivered verbatim. There is no markup. However, |
| 67 | the chat system does try to identify and tag hyperlinks, as follows: |
| 68 | |
| 69 | * Any word that begins with "http://" or "https://" is assumed |
| @@ -74,21 +72,52 @@ | |
| 74 | [Markdown](/md_rules) understand hyperlinks) then that text |
| 75 | is tagged. |
| 76 | |
| 77 | Apart from adding hyperlink anchor tags to bits of text that look |
| 78 | like hyperlinks, no changes are made to the input text. |
| 79 | |
| 80 | ## Implementation Details |
| 81 | |
| 82 | *(This section is informational only. You do not need to understand |
| 83 | how Fossil chat works in order to use it. But many developers prefer |
| 84 | to know what is happening "under the hood".)* |
| 85 | |
| 86 | The [/chat](/help?cmd=/chat) webpage downloads a small amount of |
| 87 | HTML and a few KB of javascript to run the chat session. The |
| 88 | javascript uses XMLHttpRequest (XHR) to download chat content, |
| 89 | post not content, or delete historical message. The following |
| 90 | web interfaces are used by the XHR: |
| 91 | |
| 92 | * **/chat-poll** → |
| 93 | Download chat content as JSON. |
| 94 | Chat messages are number sequentially. |
| @@ -101,18 +130,25 @@ | |
| 101 | Sends a new chat message to the server. |
| 102 | |
| 103 | * **/chat-delete** → |
| 104 | Delete a chat message. |
| 105 | |
| 106 | The Fossil chat design uses the traditional "hanging GET" or |
| 107 | "[long polling](wikipedia:/wiki/Push_technology#Long_polling)" |
| 108 | to wait for new chat messages. This is done because that technique works |
| 109 | easily with CGI and SCGI, which are the usual mechanisms for setting up |
| 110 | a Fossil server. More advanced techniques such as |
| 111 | [Server-sent events](wikipedia:/wiki/Server-sent_events) and especially |
| 112 | [WebSockets](wikipedia:/wiki/WebSocket) might seem more appropriate for |
| 113 | a chat system, but those technologies are not readily compatible with CGI. |
| 114 | |
| 115 | Chat messages are stored on the server-side in the CHAT table of |
| 116 | the repository. |
| 117 | |
| 118 | ~~~ |
| 119 |
| --- www/chat.md | |
| +++ www/chat.md | |
| @@ -2,46 +2,44 @@ | |
| 2 | |
| 3 | ## Introduction |
| 4 | |
| 5 | As of version 2.14 (and prerelease versions after about 2020-12-25), |
| 6 | Fossil supports a developer chatroom feature. The chatroom provides an |
| 7 | ephemeral discussion venue for insiders. Design goals include: |
| 8 | |
| 9 | * **Simple but functional** → Fossil chat is designed to provide a |
| 10 | convenient real-time communication mechanism for geographically |
| 11 | dispersed developers. Fossil chat is emphatically *not* intended |
| 12 | as a replacement or |
| 13 | competitor for IRC, Slack, Discord, Telegram, Google Hangouts, etc. |
| 14 | |
| 15 | * **Low administration** → |
| 16 | There is no additional set up or configuration. |
| 17 | Simply enable the [C capability](/setup_ucap_list) for users |
| 18 | whom you want to give access to the chatroom. |
| 19 | |
| 20 | * **Ephemeral** → |
| 21 | Chat messages do not sync to peer repositories. And they are |
| 22 | automatically deleted after a configurable delay (default: 7 days). |
| 23 | They can be deleted at any time without impacting any other part |
| 24 | of the system. |
| 25 | |
| 26 | Fossil chat is designed for use by insiders - people with check-in |
| 27 | privileges or higher. It is not intended as a general-purpose gathering |
| 28 | place for random passers-by on the internet. |
| 29 | Fossil chat is seeks to provide a communication venue for discussion |
| 30 | that does *not* become part of the permanent record for the project. |
| 31 | For persist and durable discussion, use the [Forum](./forum.wiki). |
| 32 | Because the conversation is intended to be ephemeral, the chat messages |
| 33 | are local to a single repository. Chat content does not sync. |
| 34 | |
| 35 | |
| 36 | ## Setup |
| 37 | |
| 38 | A Fossil repository must be functioning as a [server](./server/) in order |
| 39 | for chat to work. |
| 40 | To activate chat, simply add the [C capability](/setup_ucap_list) |
| 41 | to every user who is authorized to participate. Anyone who can read chat |
| 42 | can also post to chat. |
| 43 | |
| 44 | Setup ("s") and Admin ("a") users always have access to chat, without needing |
| 45 | the "C" capability. A common configuration is to add the "C" capability |
| @@ -58,12 +56,12 @@ | |
| 56 | |
| 57 | For users with appropriate permissions simply browse to the |
| 58 | [/chat](/help?cmd=/chat) to start up a chat session. The default |
| 59 | skin includes a "Chat" entry on the menu bar on wide screens for |
| 60 | people with chat privilege. There is also a "Chat" option on |
| 61 | the [Sitemap page](/sitemap), which means that chat will appears |
| 62 | as an option under the hamburger menu for many [skins](./customskin.md). |
| 63 | |
| 64 | Message text is delivered verbatim. There is no markup. However, |
| 65 | the chat system does try to identify and tag hyperlinks, as follows: |
| 66 | |
| 67 | * Any word that begins with "http://" or "https://" is assumed |
| @@ -74,21 +72,52 @@ | |
| 72 | [Markdown](/md_rules) understand hyperlinks) then that text |
| 73 | is tagged. |
| 74 | |
| 75 | Apart from adding hyperlink anchor tags to bits of text that look |
| 76 | like hyperlinks, no changes are made to the input text. |
| 77 | |
| 78 | ## Aural Alerts |
| 79 | |
| 80 | If you have a local clone and checkout for a remote Fossil repository |
| 81 | and that remote repository supports chat, |
| 82 | then you can bring up a chat window for that remote repository |
| 83 | that will beep whenever new content arrives. This must be done from a |
| 84 | terminal window. |
| 85 | Change directories to a working checkout of the local clone and type: |
| 86 | |
| 87 | > fossil chat |
| 88 | |
| 89 | This command will bring up a chat window in your default web-browser |
| 90 | (similar to the way the "[fossil ui](/help?cmd=ui)" does). The |
| 91 | chat will be for the remote repository, the repository whose URL shows |
| 92 | when you type the "[fossil remote](/help?cmd=remote)" command. In |
| 93 | addition to bring up the chat window, this command will also |
| 94 | send a single "bel" character (U+0007) to standard error of the terminal |
| 95 | whenever new messages arrive in the chat window. On most systems, |
| 96 | the terminal windows will emit an "beep" whenever they receive the U+0007 |
| 97 | character. This works out-of-the-box for Mac and Windows, but on some |
| 98 | flavors of Linux, you might need to enable terminal beeps in your system |
| 99 | preferences. |
| 100 | |
| 101 | In theory, it should be possible to get a web-browser to make an alert |
| 102 | sound whenever new content arrives in the chat window. However, the |
| 103 | Fossil developers have been unable to figure out how to do that. |
| 104 | Web-browsers make it very difficult to play sounds that are |
| 105 | not the direct result of a user-click, probably to prevent |
| 106 | advertisements from pestering users with a cacophony of alerts. |
| 107 | |
| 108 | |
| 109 | ## Implementation Details |
| 110 | |
| 111 | *You do not need to understand how Fossil chat works in order to use it. |
| 112 | But many developers prefer to know how their tools work. |
| 113 | This section is provided for the benefit of those curious developers.* |
| 114 | |
| 115 | The [/chat](/help?cmd=/chat) webpage downloads a small amount of |
| 116 | HTML and a few KB of javascript to run the chat session. The |
| 117 | javascript uses XMLHttpRequest (XHR) to download chat content, |
| 118 | post new content, or delete historical messages. The following |
| 119 | web interfaces are used by the XHR: |
| 120 | |
| 121 | * **/chat-poll** → |
| 122 | Download chat content as JSON. |
| 123 | Chat messages are number sequentially. |
| @@ -101,18 +130,25 @@ | |
| 130 | Sends a new chat message to the server. |
| 131 | |
| 132 | * **/chat-delete** → |
| 133 | Delete a chat message. |
| 134 | |
| 135 | * **/chat-ping** → |
| 136 | An HTTP request to this page on the loopback IP address causes |
| 137 | a single U+0007 "bel" character to be sent to standard error of |
| 138 | the controlling terminal. This is used to implement |
| 139 | aural alerts with the "[fossil chat](/help?cmd=chat)" command. |
| 140 | |
| 141 | Fossil chat uses the venerable "hanging GET" or |
| 142 | "[long polling](wikipedia:/wiki/Push_technology#Long_polling)" |
| 143 | technique to recieve asynchronous notification of new messages. |
| 144 | This is done because long polling works well with CGI and SCGI, |
| 145 | which are the usual mechanisms for setting up a Fossil server. |
| 146 | More advanced notification techniques such as |
| 147 | [Server-sent events](wikipedia:/wiki/Server-sent_events) and especially |
| 148 | [WebSockets](wikipedia:/wiki/WebSocket) might seem more appropriate for |
| 149 | a chat system, but those technologies are not compatible with CGI. |
| 150 | |
| 151 | Chat messages are stored on the server-side in the CHAT table of |
| 152 | the repository. |
| 153 | |
| 154 | ~~~ |
| 155 |