Fossil SCM
Minor editorial improvements to chat documentation
Commit
9428699039c6f7d1d7dc776ef1f4b983c83891628693e983530aad6637928d94
Parent
f2ec37e45e1ed2c…
1 file changed
+16
-16
+16
-16
| --- www/chat.md | ||
| +++ www/chat.md | ||
| @@ -18,11 +18,11 @@ | ||
| 18 | 18 | In an existing [server setup](./server/), |
| 19 | 19 | simply enable the [C capability](/setup_ucap_list) for users |
| 20 | 20 | whom you want to give access to the chatroom. |
| 21 | 21 | |
| 22 | 22 | * **Ephemeral** → |
| 23 | - Chat messages do not sync to peer repositories. And they are | |
| 23 | + Chat messages do not sync to peer repositories, and they are | |
| 24 | 24 | automatically deleted after a configurable delay (default: 7 days). |
| 25 | 25 | Individual messages or the entire conversation |
| 26 | 26 | can be deleted at any time without impacting any other part |
| 27 | 27 | of the system. |
| 28 | 28 | |
| @@ -29,11 +29,11 @@ | ||
| 29 | 29 | Fossil chat is designed for use by insiders - people with check-in |
| 30 | 30 | privileges or higher. It is not intended as a general-purpose gathering |
| 31 | 31 | place for random passers-by on the internet. |
| 32 | 32 | Fossil chat seeks to provide a communication venue for discussion |
| 33 | 33 | that does *not* become part of the permanent record for the project. |
| 34 | -For persist and durable discussion, use the [Forum](./forum.wiki). | |
| 34 | +For persistent and durable discussion, use the [Forum](./forum.wiki). | |
| 35 | 35 | Because the conversation is intended to be ephemeral, the chat messages |
| 36 | 36 | are local to a single repository. Chat content does not sync. |
| 37 | 37 | |
| 38 | 38 | |
| 39 | 39 | ## Setup |
| @@ -55,27 +55,27 @@ | ||
| 55 | 55 | the amount of time that chat messages are retained before being purged |
| 56 | 56 | from the repository database. |
| 57 | 57 | |
| 58 | 58 | ## Usage |
| 59 | 59 | |
| 60 | -For users with appropriate permissions simply browse to the | |
| 60 | +For users with appropriate permissions, simply browse to the | |
| 61 | 61 | [/chat](/help?cmd=/chat) to start up a chat session. The default |
| 62 | 62 | skin includes a "Chat" entry on the menu bar on wide screens for |
| 63 | 63 | people with chat privilege. There is also a "Chat" option on |
| 64 | -the [Sitemap page](/sitemap), which means that chat will appears | |
| 64 | +the [Sitemap page](/sitemap), which means that chat will appear | |
| 65 | 65 | as an option under the hamburger menu for many [skins](./customskin.md). |
| 66 | 66 | |
| 67 | 67 | Message text is delivered verbatim. There is no markup. However, |
| 68 | 68 | the chat system does try to identify and tag hyperlinks, as follows: |
| 69 | 69 | |
| 70 | 70 | * Any word that begins with "http://" or "https://" is assumed |
| 71 | 71 | to be a hyperlink and is tagged. |
| 72 | 72 | |
| 73 | - * Text within `[...]` is parsed and it if is a valid hyperlink | |
| 73 | + * Text within `[...]` is parsed, and it if is a valid hyperlink | |
| 74 | 74 | target (according to the way that [Fossil Wiki](/wiki_rules) or |
| 75 | - [Markdown](/md_rules) understand hyperlinks) then that text is | |
| 76 | - tagged. Note that only URLs and fossil-internal constructs such | |
| 75 | + [Markdown](/md_rules) understand hyperlinks), then that text is | |
| 76 | + tagged. Note that only URLs and Fossil-internal constructs such | |
| 77 | 77 | as checkin hashes and wiki pages names are recognized here, not |
| 78 | 78 | constructs such as `[URL | label]` or `[label](URL)`. |
| 79 | 79 | |
| 80 | 80 | Apart from adding hyperlink anchor tags to bits of text that look |
| 81 | 81 | like hyperlinks, no changes are made to the input text. |
| @@ -85,20 +85,20 @@ | ||
| 85 | 85 | files may be dragged and dropped onto that element. Files are not |
| 86 | 86 | automatically sent - selection of a file can be cancelled using the |
| 87 | 87 | Cancel button which appears only when a file is selected. When the |
| 88 | 88 | Send button is pressed, any pending text is submitted along with the |
| 89 | 89 | selected file. Image files sent this way will, by default, appear |
| 90 | -inline in messages but each user may toggle that via the settings | |
| 90 | +inline in messages, but each user may toggle that via the settings | |
| 91 | 91 | popup menu, such that images instead appear as downloadable links. |
| 92 | 92 | Non-image files always appear in messages as download links. |
| 93 | 93 | |
| 94 | 94 | ### Deletion of Messages |
| 95 | 95 | |
| 96 | 96 | Any user may *locally* delete a given message by clicking on the "tab" |
| 97 | 97 | at the top of the message and clicking the button which appears. Such |
| 98 | -deletions are local-only and the messages will reappear if the page | |
| 99 | -page is reloaded. Admin users may additionally choose to globally | |
| 98 | +deletions are local-only, and the messages will reappear if the page | |
| 99 | +is reloaded. Admin users may additionally choose to globally | |
| 100 | 100 | delete a message from the chat record, which deletes it not only from |
| 101 | 101 | their own browser but also propagates the removal to all connected |
| 102 | 102 | clients the next time they poll for new messages. |
| 103 | 103 | |
| 104 | 104 | ## Implementation Details |
| @@ -112,22 +112,22 @@ | ||
| 112 | 112 | javascript uses XMLHttpRequest (XHR) to download chat content, post |
| 113 | 113 | new content, or delete historical messages. The following web |
| 114 | 114 | interfaces are used by the XHR: |
| 115 | 115 | |
| 116 | 116 | * **/chat-poll** → |
| 117 | - Download chat content as JSON. | |
| 118 | - Chat messages are number sequentially. | |
| 117 | + Downloads chat content as JSON. | |
| 118 | + Chat messages are numbered sequentially. | |
| 119 | 119 | The client tells the server the largest chat message it currently |
| 120 | - holds and the server sends back subsequent messages. If there | |
| 120 | + holds, and the server sends back subsequent messages. If there | |
| 121 | 121 | are no subsequent messages, the /chat-poll page blocks until new |
| 122 | 122 | messages are available. |
| 123 | 123 | |
| 124 | 124 | * **/chat-send** → |
| 125 | 125 | Sends a new chat message to the server. |
| 126 | 126 | |
| 127 | 127 | * **/chat-delete** → |
| 128 | - Delete a chat message. | |
| 128 | + Deletes a chat message. | |
| 129 | 129 | |
| 130 | 130 | Fossil chat uses the venerable "hanging GET" or |
| 131 | 131 | "[long polling](wikipedia:/wiki/Push_technology#Long_polling)" |
| 132 | 132 | technique to recieve asynchronous notification of new messages. |
| 133 | 133 | This is done because long polling works well with CGI and SCGI, |
| @@ -168,11 +168,11 @@ | ||
| 168 | 168 | |
| 169 | 169 | On the server-side, message text is stored exactly as entered by the |
| 170 | 170 | users. The /chat-poll page queries the CHAT table and constructs a |
| 171 | 171 | JSON reply described in the [/chat-poll |
| 172 | 172 | documentation](/help?cmd=/chat-poll). The message text is translated |
| 173 | -into HTML prior to being converted into JSON so that the text can be | |
| 173 | +into HTML before being converted to JSON so that the text can be | |
| 174 | 174 | safely added to the display using assignment to `innerHTML`. Though |
| 175 | 175 | `innerHTML` assignment is generally considered unsafe, it is only so |
| 176 | 176 | with untrusted content from untrusted sources. The chat content goes |
| 177 | -through sanitation steps which eliminate any potential security | |
| 177 | +through sanitization steps which eliminate any potential security | |
| 178 | 178 | vulnerabilities of assigning that content to `innerHTML`. |
| 179 | 179 |
| --- www/chat.md | |
| +++ www/chat.md | |
| @@ -18,11 +18,11 @@ | |
| 18 | In an existing [server setup](./server/), |
| 19 | simply enable the [C capability](/setup_ucap_list) for users |
| 20 | whom you want to give access to the chatroom. |
| 21 | |
| 22 | * **Ephemeral** → |
| 23 | Chat messages do not sync to peer repositories. And they are |
| 24 | automatically deleted after a configurable delay (default: 7 days). |
| 25 | Individual messages or the entire conversation |
| 26 | can be deleted at any time without impacting any other part |
| 27 | of the system. |
| 28 | |
| @@ -29,11 +29,11 @@ | |
| 29 | Fossil chat is designed for use by insiders - people with check-in |
| 30 | privileges or higher. It is not intended as a general-purpose gathering |
| 31 | place for random passers-by on the internet. |
| 32 | Fossil chat seeks to provide a communication venue for discussion |
| 33 | that does *not* become part of the permanent record for the project. |
| 34 | For persist and durable discussion, use the [Forum](./forum.wiki). |
| 35 | Because the conversation is intended to be ephemeral, the chat messages |
| 36 | are local to a single repository. Chat content does not sync. |
| 37 | |
| 38 | |
| 39 | ## Setup |
| @@ -55,27 +55,27 @@ | |
| 55 | the amount of time that chat messages are retained before being purged |
| 56 | from the repository database. |
| 57 | |
| 58 | ## Usage |
| 59 | |
| 60 | For users with appropriate permissions simply browse to the |
| 61 | [/chat](/help?cmd=/chat) to start up a chat session. The default |
| 62 | skin includes a "Chat" entry on the menu bar on wide screens for |
| 63 | people with chat privilege. There is also a "Chat" option on |
| 64 | the [Sitemap page](/sitemap), which means that chat will appears |
| 65 | as an option under the hamburger menu for many [skins](./customskin.md). |
| 66 | |
| 67 | Message text is delivered verbatim. There is no markup. However, |
| 68 | the chat system does try to identify and tag hyperlinks, as follows: |
| 69 | |
| 70 | * Any word that begins with "http://" or "https://" is assumed |
| 71 | to be a hyperlink and is tagged. |
| 72 | |
| 73 | * Text within `[...]` is parsed and it if is a valid hyperlink |
| 74 | target (according to the way that [Fossil Wiki](/wiki_rules) or |
| 75 | [Markdown](/md_rules) understand hyperlinks) then that text is |
| 76 | tagged. Note that only URLs and fossil-internal constructs such |
| 77 | as checkin hashes and wiki pages names are recognized here, not |
| 78 | constructs such as `[URL | label]` or `[label](URL)`. |
| 79 | |
| 80 | Apart from adding hyperlink anchor tags to bits of text that look |
| 81 | like hyperlinks, no changes are made to the input text. |
| @@ -85,20 +85,20 @@ | |
| 85 | files may be dragged and dropped onto that element. Files are not |
| 86 | automatically sent - selection of a file can be cancelled using the |
| 87 | Cancel button which appears only when a file is selected. When the |
| 88 | Send button is pressed, any pending text is submitted along with the |
| 89 | selected file. Image files sent this way will, by default, appear |
| 90 | inline in messages but each user may toggle that via the settings |
| 91 | popup menu, such that images instead appear as downloadable links. |
| 92 | Non-image files always appear in messages as download links. |
| 93 | |
| 94 | ### Deletion of Messages |
| 95 | |
| 96 | Any user may *locally* delete a given message by clicking on the "tab" |
| 97 | at the top of the message and clicking the button which appears. Such |
| 98 | deletions are local-only and the messages will reappear if the page |
| 99 | page is reloaded. Admin users may additionally choose to globally |
| 100 | delete a message from the chat record, which deletes it not only from |
| 101 | their own browser but also propagates the removal to all connected |
| 102 | clients the next time they poll for new messages. |
| 103 | |
| 104 | ## Implementation Details |
| @@ -112,22 +112,22 @@ | |
| 112 | javascript uses XMLHttpRequest (XHR) to download chat content, post |
| 113 | new content, or delete historical messages. The following web |
| 114 | interfaces are used by the XHR: |
| 115 | |
| 116 | * **/chat-poll** → |
| 117 | Download chat content as JSON. |
| 118 | Chat messages are number sequentially. |
| 119 | The client tells the server the largest chat message it currently |
| 120 | holds and the server sends back subsequent messages. If there |
| 121 | are no subsequent messages, the /chat-poll page blocks until new |
| 122 | messages are available. |
| 123 | |
| 124 | * **/chat-send** → |
| 125 | Sends a new chat message to the server. |
| 126 | |
| 127 | * **/chat-delete** → |
| 128 | Delete a chat message. |
| 129 | |
| 130 | Fossil chat uses the venerable "hanging GET" or |
| 131 | "[long polling](wikipedia:/wiki/Push_technology#Long_polling)" |
| 132 | technique to recieve asynchronous notification of new messages. |
| 133 | This is done because long polling works well with CGI and SCGI, |
| @@ -168,11 +168,11 @@ | |
| 168 | |
| 169 | On the server-side, message text is stored exactly as entered by the |
| 170 | users. The /chat-poll page queries the CHAT table and constructs a |
| 171 | JSON reply described in the [/chat-poll |
| 172 | documentation](/help?cmd=/chat-poll). The message text is translated |
| 173 | into HTML prior to being converted into JSON so that the text can be |
| 174 | safely added to the display using assignment to `innerHTML`. Though |
| 175 | `innerHTML` assignment is generally considered unsafe, it is only so |
| 176 | with untrusted content from untrusted sources. The chat content goes |
| 177 | through sanitation steps which eliminate any potential security |
| 178 | vulnerabilities of assigning that content to `innerHTML`. |
| 179 |
| --- www/chat.md | |
| +++ www/chat.md | |
| @@ -18,11 +18,11 @@ | |
| 18 | In an existing [server setup](./server/), |
| 19 | simply enable the [C capability](/setup_ucap_list) for users |
| 20 | whom you want to give access to the chatroom. |
| 21 | |
| 22 | * **Ephemeral** → |
| 23 | Chat messages do not sync to peer repositories, and they are |
| 24 | automatically deleted after a configurable delay (default: 7 days). |
| 25 | Individual messages or the entire conversation |
| 26 | can be deleted at any time without impacting any other part |
| 27 | of the system. |
| 28 | |
| @@ -29,11 +29,11 @@ | |
| 29 | Fossil chat is designed for use by insiders - people with check-in |
| 30 | privileges or higher. It is not intended as a general-purpose gathering |
| 31 | place for random passers-by on the internet. |
| 32 | Fossil chat seeks to provide a communication venue for discussion |
| 33 | that does *not* become part of the permanent record for the project. |
| 34 | For persistent and durable discussion, use the [Forum](./forum.wiki). |
| 35 | Because the conversation is intended to be ephemeral, the chat messages |
| 36 | are local to a single repository. Chat content does not sync. |
| 37 | |
| 38 | |
| 39 | ## Setup |
| @@ -55,27 +55,27 @@ | |
| 55 | the amount of time that chat messages are retained before being purged |
| 56 | from the repository database. |
| 57 | |
| 58 | ## Usage |
| 59 | |
| 60 | For users with appropriate permissions, simply browse to the |
| 61 | [/chat](/help?cmd=/chat) to start up a chat session. The default |
| 62 | skin includes a "Chat" entry on the menu bar on wide screens for |
| 63 | people with chat privilege. There is also a "Chat" option on |
| 64 | the [Sitemap page](/sitemap), which means that chat will appear |
| 65 | as an option under the hamburger menu for many [skins](./customskin.md). |
| 66 | |
| 67 | Message text is delivered verbatim. There is no markup. However, |
| 68 | the chat system does try to identify and tag hyperlinks, as follows: |
| 69 | |
| 70 | * Any word that begins with "http://" or "https://" is assumed |
| 71 | to be a hyperlink and is tagged. |
| 72 | |
| 73 | * Text within `[...]` is parsed, and it if is a valid hyperlink |
| 74 | target (according to the way that [Fossil Wiki](/wiki_rules) or |
| 75 | [Markdown](/md_rules) understand hyperlinks), then that text is |
| 76 | tagged. Note that only URLs and Fossil-internal constructs such |
| 77 | as checkin hashes and wiki pages names are recognized here, not |
| 78 | constructs such as `[URL | label]` or `[label](URL)`. |
| 79 | |
| 80 | Apart from adding hyperlink anchor tags to bits of text that look |
| 81 | like hyperlinks, no changes are made to the input text. |
| @@ -85,20 +85,20 @@ | |
| 85 | files may be dragged and dropped onto that element. Files are not |
| 86 | automatically sent - selection of a file can be cancelled using the |
| 87 | Cancel button which appears only when a file is selected. When the |
| 88 | Send button is pressed, any pending text is submitted along with the |
| 89 | selected file. Image files sent this way will, by default, appear |
| 90 | inline in messages, but each user may toggle that via the settings |
| 91 | popup menu, such that images instead appear as downloadable links. |
| 92 | Non-image files always appear in messages as download links. |
| 93 | |
| 94 | ### Deletion of Messages |
| 95 | |
| 96 | Any user may *locally* delete a given message by clicking on the "tab" |
| 97 | at the top of the message and clicking the button which appears. Such |
| 98 | deletions are local-only, and the messages will reappear if the page |
| 99 | is reloaded. Admin users may additionally choose to globally |
| 100 | delete a message from the chat record, which deletes it not only from |
| 101 | their own browser but also propagates the removal to all connected |
| 102 | clients the next time they poll for new messages. |
| 103 | |
| 104 | ## Implementation Details |
| @@ -112,22 +112,22 @@ | |
| 112 | javascript uses XMLHttpRequest (XHR) to download chat content, post |
| 113 | new content, or delete historical messages. The following web |
| 114 | interfaces are used by the XHR: |
| 115 | |
| 116 | * **/chat-poll** → |
| 117 | Downloads chat content as JSON. |
| 118 | Chat messages are numbered sequentially. |
| 119 | The client tells the server the largest chat message it currently |
| 120 | holds, and the server sends back subsequent messages. If there |
| 121 | are no subsequent messages, the /chat-poll page blocks until new |
| 122 | messages are available. |
| 123 | |
| 124 | * **/chat-send** → |
| 125 | Sends a new chat message to the server. |
| 126 | |
| 127 | * **/chat-delete** → |
| 128 | Deletes a chat message. |
| 129 | |
| 130 | Fossil chat uses the venerable "hanging GET" or |
| 131 | "[long polling](wikipedia:/wiki/Push_technology#Long_polling)" |
| 132 | technique to recieve asynchronous notification of new messages. |
| 133 | This is done because long polling works well with CGI and SCGI, |
| @@ -168,11 +168,11 @@ | |
| 168 | |
| 169 | On the server-side, message text is stored exactly as entered by the |
| 170 | users. The /chat-poll page queries the CHAT table and constructs a |
| 171 | JSON reply described in the [/chat-poll |
| 172 | documentation](/help?cmd=/chat-poll). The message text is translated |
| 173 | into HTML before being converted to JSON so that the text can be |
| 174 | safely added to the display using assignment to `innerHTML`. Though |
| 175 | `innerHTML` assignment is generally considered unsafe, it is only so |
| 176 | with untrusted content from untrusted sources. The chat content goes |
| 177 | through sanitization steps which eliminate any potential security |
| 178 | vulnerabilities of assigning that content to `innerHTML`. |
| 179 |