Commit e1ebe43907cde443a21772e2f96d567a5b5e2509
Update About page
- Document description field - Document bare link for image - Clarify that other properties are okay - Remove bias about number of properties to use Fix %ugtF1WpFFu3e4fTjP+yI96+UI/F9/L2noH8IRQ8uSr0=.sha256cel committed on 10/6/2017, 8:50:11 PM
Parent: 404d138845253f2aee74e3c0032fd9273c8762f9
Files changed
| tmpl/docs/message-types/about.md | changed |
| tmpl/docs/message-types/about.md | |||
|---|---|---|---|
| @@ -1,16 +1,15 @@ | |||
| 1 | 1 … | ## About | |
| 2 | 2 … | ||
| 3 | 3 … | About-messages set attributes about someone or something. | |
| 4 | -They can be used to set a name or picture for users, files, or messages. | ||
| 5 | -However, they're most commonly published about users. | ||
| 4 … | +They can be used to set a name, picture, description, or other property for users, files, or messages. | ||
| 6 | 5 … | ||
| 7 | -About messages do not have to have both `name` and `image`, and, in fact, it's recommended that they only have one or the other. | ||
| 8 | -Why? | ||
| 9 | -Because then a `vote` on the message can be more specific. | ||
| 6 … | +An About message may set one property or multiple. | ||
| 7 … | +If the message sets only one property, then a reply or `vote` on the message can be more specific. | ||
| 8 … | +If there are multiple properties to assign, combining them into one About message can reduce data overhead. | ||
| 10 | 9 … | ||
| 11 | 10 … | ```js | |
| 12 | -{ type: 'about', about: Link, name: String, image: BlobLink } | ||
| 11 … | +{ type: 'about', about: Link, name: String, image: BlobLink, description: String } | ||
| 13 | 12 … | ``` | |
| 14 | 13 … | ||
| 15 | 14 … | ### Names | |
| 16 | 15 … | ||
| @@ -18,20 +17,28 @@ | |||
| 18 | 17 … | Each user can choose a name for themselves and for others, and conflicts are allowed. | |
| 19 | 18 … | ||
| 20 | 19 … | Its up to your application to decide which names to use. | |
| 21 | 20 … | Generally speaking, names by followed users are trusted, and the local user gets to override all decisions. | |
| 21 … | +Self-given names may also be prioritized. | ||
| 22 | 22 … | ||
cel %Zh4ZUalmnandohrNdmRr2ekhP5q/cd2L683EMCt/zys=.sha256 · 11/23/2017, 8:59:57 PM test cel %W2CWvjyxn25s3WfoJqkG0oItK7/OgjHI9V6oLmxqzHg=.sha256 · 11/23/2017, 10:59:22 PM test reply | |||
| 23 | -A common rule for names is to allow `A-z0-9._-`, and not allow a trailing `.`. | ||
| 23 … | +An application may apply a rule for names, such as to allow `A-z0-9._-`, and not allow a trailing `.`. | ||
| 24 | 24 … | ||
| 25 | 25 … | ### Images | |
| 26 | 26 … | ||
| 27 | 27 … | For images, a common size is 512x512. | |
| 28 | 28 … | Square images are recommended but not required. | |
| 29 | 29 … | ||
| 30 | -Some recommended (but not required) attributes on the `image` link: | ||
| 30 … | +Some recommended attributes on the `image` link: | ||
| 31 | 31 … | ||
| 32 | 32 … | - `width` in pixels | |
| 33 | 33 … | - `height` in pixels | |
| 34 | 34 … | - `name` a string filename | |
| 35 | 35 … | - `size` in bytes | |
| 36 | 36 … | - `type` a mimetype | |
| 37 | 37 … | ||
| 38 … | +The image field may also be a plain blob id instead of a link object, but it is better to include the full object so that clients can make use of the metadata. | ||
| 39 … | + | ||
| 40 … | +### Description | ||
| 41 … | + | ||
| 42 … | +A description may be a markdown string describing the referenced entity. A client may show description data for a user on their profile page. | ||
| 43 … | + | ||
| 44 … | +If the description field is present, there may also be a [`mentions` field](/docs/message-types/post.html) associated with it. | ||
Built with git-ssb-web