[chore] Go back to using `name` for attachment alt text for now, add note in docs (#4559)v0.20.2

# Description

> If this is a code change, please include a summary of what you've coded, and link to the issue(s) it closes/implements.
>
> If this is a documentation change, please briefly describe what you've changed and why.

This pull request switches us back to using the `name` property instead of the `summary` property for media descriptions for now, as using `summary` was causing accessibility issues with folks on *key, *oma, and Iceshrimp instances not being able to see GtS alt text, as those softwares (as of their latest releases I think) only look for `name`.

Also updates the docs to add a note there on our intention to switch to using the HTML `summary` property instead of / in addition to `name` from v0.21.0 onwards.

closes https://codeberg.org/superseriousbusiness/gotosocial/issues/4524

## Checklist

Please put an x inside each checkbox to indicate that you've read and followed it: `[ ]` -> `[x]`

If this is a documentation change, only the first checkbox must be filled (you can delete the others if you want).

- [x] I/we have read the [GoToSocial contribution guidelines](https://codeberg.org/superseriousbusiness/gotosocial/src/branch/main/CONTRIBUTING.md).
- [x] I/we have discussed the proposed changes already, either in an issue on the repository, or in the Matrix chat.
- [x] I/we have not leveraged AI to create the proposed changes.
- [x] I/we have performed a self-review of added code.
- [x] I/we have written code that is legible and maintainable by others.
- [x] I/we have commented the added code, particularly in hard-to-understand areas.
- [x] I/we have made any necessary changes to documentation.
- [ ] I/we have added tests that cover new code.
- [x] I/we have run tests and they pass locally with the changes.
- [x] I/we have run `go fmt ./...` and `golangci-lint run`.

Reviewed-on: https://codeberg.org/superseriousbusiness/gotosocial/pulls/4559
Reviewed-by: Daenney <daenney@noreply.codeberg.org>
Co-authored-by: tobi <tobi.smethurst@protonmail.com>
Co-committed-by: tobi <tobi.smethurst@protonmail.com>

4 files changed, 18 insertions, 7 deletions

diff --git a/docs/federation/posts.md b/docs/federation/posts.md
index 45a4fb7cd..7c92c297d 100644
--- a/docs/federation/posts.md
+++ b/docs/federation/posts.md
@@ -9,7 +9,14 @@ GoToSocial sends media attachments in the `attachment` property of posts using t
 - `Audio` - any audio type (mp3, flac, wma, etc).
 - `Document` - fallback for any other / unknown type.
 
-Attachments sent from GoToSocial include the MIME `mediaType`, the `url` of the full-sized version of the media file, and the `summary` property, which can be interpreted by remote instance's as a short description / alt text for the attachment.
+Attachments sent from GoToSocial include the MIME `mediaType`, the `url` of the full-sized version of the media file, and the `name` property, which can be interpreted by remote instance's as a short description / alt text for the attachment.
+
+!!! warning
+    According to ActivityStreams, `name` is "A simple, human-readable, plain-text name for the object" ([Link](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-name)). On the other hand, `summary` should be "A natural language summarization of the object encoded as HTML" ([Link](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-summary)).
+
+    In light of `summary`'s better suitability as description / alt text, in future GoToSocial will switch to either using *only* the `summary` property instead of the `name` property, or will use *both* the `name` and `summary` properties (exact implementation tbd). This change will likely be introduced in version 0.21.0 of the software.
+    
+    This means the `summary` property transmitted by GoToSocial in v0.21.0 onwards will likely contain things like HTML `<br>` elements instead of newlines, escaped HTML characters, etc. Receiving instances should account for this when interpreting `summary` as alt text.
 
 Types `Image` and `Video` will also include the `http://joinmastodon.org/ns#blurhash` property so that remotes can generate a colorful hash of the image. If an audio file included an embedded cover art image, then the `Audio` type will also include a blurhash. See the [Mastodon blurhash docs](https://docs.joinmastodon.org/spec/activitypub/#blurhash).
 
@@ -40,7 +47,7 @@ Here's an example of a `Note` with one attachment:
         0.5
       ],
       "mediaType": "image/jpeg",
-      "summary": "Black and white image of some 50's style text saying: Welcome On Board",
+      "name": "Black and white image of some 50's style text saying: Welcome On Board",
       "type": "Image",
       "url": "http://localhost:8080/fileserver/01F8MH17FWEB39HZJ76B6VXSKF/attachment/original/01F8MH6NEM8D7527KZAECTCR76.jpg"
     }
diff --git a/docs/locales/zh/federation/posts.md b/docs/locales/zh/federation/posts.md
index 798c07daa..49afc815d 100644
--- a/docs/locales/zh/federation/posts.md
+++ b/docs/locales/zh/federation/posts.md
@@ -40,7 +40,7 @@ GoToSocial 发送的附件包含 MIME 类型（`mediaType`）、媒体文件的�
         0.5
       ],
       "mediaType": "image/jpeg",
-      "summary": "Black and white image of some 50's style text saying: Welcome On Board",
+      "name": "Black and white image of some 50's style text saying: Welcome On Board",
       "type": "Image",
       "url": "http://localhost:8080/fileserver/01F8MH17FWEB39HZJ76B6VXSKF/attachment/original/01F8MH6NEM8D7527KZAECTCR76.jpg"
     }
diff --git a/internal/typeutils/internaltoas.go b/internal/typeutils/internaltoas.go
index 6255ee8e2..d08c3c935 100644
--- a/internal/typeutils/internaltoas.go
+++ b/internal/typeutils/internaltoas.go
@@ -1145,8 +1145,12 @@ func (c *Converter) attachAttachments(
 		}
 		ap.AppendURL(attachmentable, imageURL)
 
-		// `summary` ie., media description / alt text
-		ap.AppendSummary(attachmentable, a.Description)
+		// `name` ie., media description / alt text
+		//
+		// TODO: Change this to `summary` when there's
+		// wider support for this across fedi. See:
+		// https://codeberg.org/superseriousbusiness/gotosocial/issues/4524
+		ap.AppendName(attachmentable, a.Description)
 
 		// `blurhash`
 		ap.SetBlurhash(attachmentable, a.Blurhash)
diff --git a/internal/typeutils/internaltoas_test.go b/internal/typeutils/internaltoas_test.go
index 970e16cfa..943910f00 100644
--- a/internal/typeutils/internaltoas_test.go
+++ b/internal/typeutils/internaltoas_test.go
@@ -656,7 +656,7 @@ func (suite *InternalToASTestSuite) TestStatusWithTagsToASWithIDs() {
         0.5
       ],
       "mediaType": "image/jpeg",
-      "summary": "Black and white image of some 50's style text saying: Welcome On Board",
+      "name": "Black and white image of some 50's style text saying: Welcome On Board",
       "type": "Image",
       "url": "http://localhost:8080/fileserver/01F8MH17FWEB39HZJ76B6VXSKF/attachment/original/01F8MH6NEM8D7527KZAECTCR76.jpg"
     }
@@ -776,7 +776,7 @@ func (suite *InternalToASTestSuite) TestStatusWithTagsToASFromDB() {
         0.5
       ],
       "mediaType": "image/jpeg",
-      "summary": "Black and white image of some 50's style text saying: Welcome On Board",
+      "name": "Black and white image of some 50's style text saying: Welcome On Board",
       "type": "Image",
       "url": "http://localhost:8080/fileserver/01F8MH17FWEB39HZJ76B6VXSKF/attachment/original/01F8MH6NEM8D7527KZAECTCR76.jpg"
     }