avatar.txt

**********************************************************************
FGHI                                FIDONET GLOBAL HYPERTEXT INTERFACE
**********************************************************************
Status:         draft
Revision:       initial complete draft
Title:          Fidonet avatars
Author:         Mithgol the Webmaster   (aka Sergey Sokoloff, 2:50/88)
Revision Date:  10 Jan 2017
-+--------------------------------------------------------------------
Contents:
   1. Status of this document
   2. Introduction
   3. Key words to indicate requirement levels
   4. Kludges
   5. The AVATAR kludge
   6. The GIF kludge
   7. The GRAVATAR kludge
   8. The AVAKEY kludge
   Appendix A. Known implementations
-+--------------------------------------------------------------------

1. Status of this document
-+------------------------

  This document is a draft of a Fidonet Standards Proposal (FSP).

  This document specifies an optional Fidonet standard
  that can be used in the Fidonet community.

  Implementation of the standard defined in this document is not
  mandatory, but all implementations are expected to adhere
  to this standard.

  Distribution of this document is unlimited, 
  provided that its text is not altered without notice.

2. Introduction
-+-------------

  Fidonet avatars are pictures that serve as graphical representations
  of individual authors of echomail and netmail messages in Fidonet.

  This document specifies a simple kludge-based method of declaring
  an avatar to represent the message's author.

3. Key words to indicate requirement levels
-+-----------------------------------------

  The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY",
  and "OPTIONAL" in this document are to be interpreted as described
  in FTA-1006 (based on RFC 2119).

4. Kludges
-+--------

  Kludges (also known as klugde lines or control paragraphs) are
  special lines embedded in the text body of a Fidonet message.
  Sometimes kludges are used to support some new addressing and other
  control information, sometimes they contain pieces of auxiliary
  information about the message's author (location, ICQ UIN,
  Jabber ID, real name, current music, mood, etc.) See technical
  details in FTS-4000.

  Kludges defined in the following sections are REQUIRED to have
  the following four common characteristics:

  1) Such kludge MUST NOT be preceded (immediately or otherwise)
     by any of the common (i.e. non-kludge) lines of the message.
     In other words, a set of kludges precedes the rest of the
     message's body, and an echoprocessor (a tosser) MAY collect
     and store these kludges separately, for example, in subfields
     of a JAM message header, in a Squish message control block
     (see FSP-1037), etc.

  2) Each kludge line MUST start with a single SOH character (Ctrl+A,
     ASCII 1).

  3) That SOH character MUST immediately be followed by the kludge's
     name and a colon and a RECOMMENDED OPTIONAL whitespace character.

  4) The rest of the line contains that kludge's value.

5. The AVATAR kludge
-+------------------

  The name of this kludge is "AVATAR" (case-insensitive,
  without quotes).

  The value of this kludge is the URL of the avatar designated
  for the message where the kludge appears.

  That URL, however, MAY be preceded by one or more (space-separated)
  OPTIONAL hints.

  If such hint is a natural number, it SHOULD be interpreted as the
  size (in bytes) of the avatar's file. The number MAY immediately be
  followed by a metric postfix; for example, "k" (without quotes)
  means kilobytes (1k = 1024 bytes), "M" (without quotes) means
  megabytes (1M = 1024k), "G" (without quotes) means gigabytes (1G =
  1024M). That makes a hint shorter and easier to fit in the kludge
  before the URL.

  If such hint is a pair of natural numbers separated by "x" or "X"
  character (without quotes), these numbers SHOULD be interpreted as
  the width and the height (in pixels) of the avatar. For example,
  300x50 avatar is 300 pixels wide, 50 pixels high.

  (Fidonet browsers MAY resize avatars; however, they MAY use hints
  to choose an avatar of the necessary size when several avatar URLs
  are available, as explained below.)

  If several different hints of the same type are given (for example,
  "400x55 256x256" or "14k 8M"), these hints MUST be ignored. Even if
  several equal hints of the same type are given (for example, "400x55
  400x55" or "14k 14k"), these hints SHOULD be ignored.

  Several AVATAR kludges MAY appear in the same message. They MUST
  contain different URLs of essentially the same avatar image (though
  the image MAY be resized and/or cropped for different width and
  height) and thus a Fidonet browser MUST be able to choose any of
  the given URLs without getting a different avatar.

  In other words, the browser's choice of an avatar's source URL can
  be based on the browser's support of URL schemes, on availability
  of the resources designated by URLs (Internet servers or services,
  Fidonet systems, Fidonet echomail or file areas), on given hints,
  etc. This standard permits any URL scheme to be given in the kludge,
  for example,

  *) "http:" or "https:" scheme for WWW-hosted avatars,

  *) "ftp:" scheme for FTP-hosted avatars,

  *) "magnet:" or "ed2k:" scheme for avatars
     accessible via file exchange,

  *) "freq:" scheme for avatars accessible via Fidonet file requests,

  *) "faqserv:" scheme for avatars accessible in automated Fidonet
     netmail replies sent by so called "FAQ servers",

  *) "fecho:" scheme for avatars posted in Fidonet file echoes,

  *) "area:" scheme for avatars posted in Fidonet echomail areas.
     By the way, an avatar and a kludge-containing message MAY
     reside in different echomail areas (for example, if there is
     some special echomail area for posting UUE-encoded avatars).

  Note 1: this list of examples is not an exhaustive list.

  Note 2: the latter four schemes (area, fecho, faqserv, freq) are
  defined in the FGHI URL standard. Available here:

  https://github.com/Mithgol/FGHI-URL/blob/master/FidoURL.txt

  Note 3: if some Fidonet browser does not support an URL's scheme,
  it MAY ignore the AVATAR kludge with that URL.

6. The GIF kludge
-+---------------

  The name of this kludge is "GIF" (case-insensitive, without quotes).

  The value of this kludge is a name of the avatar's file. The name is
  given without its extension, and that extension is always ".GIF"
  (without quotes). It is implied that the file is available via
  file request from the message's author's system.

  For example, if the message's author's address is 2:9999/88, then
  the following two kludges are equivalent:

      ^aGIF: SYSOP88

      ^aAVATAR: freq://2:9999/88/SYSOP88.GIF

  where "^a" represents the SOH character and "freq://" is
  an URL scheme for file requests (defined in the FGHI URL standard).

  This kludge is defined for this standard to be backwards-compatible
  with the earlier versions of GoldED where this kludge was actually
  supported.

  If several GIF kludges with different values coexist in the same
  message, these kludges MUST be ignored. Even if several GIF kludges
  of equal values coexist in the same message, these kludges SHOULD be
  ignored.

  When AVATAR and GIF kludges coexist in the same message, the browser
  MAY choose between them as if the GIF kludge was an equivalent
  AVATAR kludge.

7. The GRAVATAR kludge
-+--------------------

  The name of this kludge is "GRAVATAR" (case-insensitive,
  without quotes).

  The value of this kludge is a 32-digit hexadecimal number. It is
  the MD5 hash of a lowercase e-mail address. For example, if that
  address is "SomeExample@example.org", then the number is the output
  of the following PHP code:

     echo md5( strtolower( "SomeExample@example.org" ) );

  There MUST be no whitespace before and after such e-mail address
  when it is given to the MD5 hash calculator.

  To make use of this kludge, the message's author has to register his
  e-mail address on http://gravatar.com/ and publish his avatar there.
  The e-mail address (unlike the avatar) does not become public
  because only the hash is published (as the kludge's value) in Fido.

  Then a Fidonet browser can use the published hash to get the avatar
  as explained at http://gravatar.com/site/implement/images/

  For example, the following two kludges MAY be equivalent:

     ^aGRAVATAR: somehash

     ^aAVATAR: https://secure.gravatar.com/avatar/somehash?s=200&r=x

  (where "^a" represents the SOH character and "somehash" represents
  some actual 32-digit hexadecimal number).

  The value of the "s" parameter in that URL SHOULD be varied to fetch
  an avatar of the necessary size ("s=200" means 200x200 avatar,
  "s=333" means 333x333 avatar, etc.). Examples:

  *) a Fidonet browser MAY request 20x20 avatars to represent authors
     in a list of subjects of messages and a 200x200 avatar
     to represent an author in a larger (multi-line) heading
     of an individual message;

  *) some JavaScript of a WebBBS MAY use window.devicePixelRatio
     as a multiplier to get larger avatars for mobile devices with
     greater pixel density (such as Apple's Retina display).

  The value of the "r" parameter SHOULD be used to specify one of the
  following ratings to request images up to and including that rating:

  r=g: suitable for display on all websites with any audience type;

  r=pg: may contain rude gestures, provocatively dressed individuals,
        the lesser swear words, or mild violence;

  r=r: may contain such things as harsh profanity, intense violence,
       nudity, or hard drug use;

  r=x: may contain hardcore sexual imagery or extremely disturbing
       violence.

  If several GRAVATAR kludges with different values coexist
  in the same message, these kludges MUST be ignored. Even if several
  GRAVATAR kludges of equal values coexist in the same message,
  these kludges SHOULD be ignored.

  When GRAVATAR and AVATAR and/or GIF kludges coexist in the same
  message, the browser MAY choose between them as if the GRAVATAR
  kludge was an equivalent AVATAR kludge.

8. The AVAKEY kludge
-+------------------

  The name of this kludge is "AVAKEY" (case-insensitive,
  without quotes).

  The value of this kludge is a list of keywords separated by
  "|" characters (without quotes). These keywords MUST correspond
  to the avatar designated for the message where the kludge appears.

  These keywords are useful when all of the avatar's URLs point to
  some resources that are not immediately available and thus
  the avatar itself is not immediately available to display. Examples:

  *) a file exchange URL when the file's sources (seeds) are offline;

  *) an Internet URL when the reader's device is offline;

  *) a file request URL when the destination node is offline.

  In such situation the Fidonet browser MAY temporarily display some
  other avatar recently used by the same author in the same echomail
  area (or in netmail), provided that the other avatar was used with
  the same keyword.

  If only one AVAKEY kludge is present in the message, the keywords
  SHOULD be used in the order of appearance. For example, the kludge

      ^aAVAKEY: smiling|very happy|seaside|default

  (where "^a" represents the SOH character) means that the most recent
  of available avatars with the "smiling" keyword is used; if no such
  avatars are available, then the most recent "very happy" avatar, and
  so on.

  If several AVAKEY kludges are present in the message, the keywords'
  order SHOULD NOT be taken into account. For example, the kludges

      ^aAVAKEY: smiling|very happy
      ^aAVAKEY: seaside|default

  (where "^a" represents the SOH character) mean that the most recent
  avatar marked with at least one of the four keywords ("smiling",
  "very happy", "seaside" and "default") is used.

  If the AVAKEY kludge is not present in the message, than the keyword
  "default" (without quotes) MUST be assumed for the avatar if one or
  more of the other kludges (AVATAR, GIF, GRAVATAR) designate some
  avatar's URL. It works both ways:

  1) if the avatar for such message is not immediately available,
     the Fidonet browser MAY temporarily display the most recent
     of available avatars used with the keyword "default",

  2) when the Fidonet browser looks for the avatars used with
     the keyword "default", the browser MUST also find avatars
     designated in the messages with missing AVAKEY kludges.

Appendix A. Known implementations
-+-------------------------------

  By the time of this writing there are several implementation of the
  draft editions of this standard.

  Reference implementation (free open source):

  https://github.com/Mithgol/node-fidonet-jam

  Application-level implementations written by the standard's author:

  *) Fido2RSS https://github.com/Mithgol/fido2rss

  *) fido2twi https://github.com/Mithgol/node-fido2twi

  *) PhiDo https://github.com/Mithgol/phido

  *) twi2fido https://github.com/Mithgol/node-twi2fido/

  These implementations do not implement the last section of this
  standard (the AVAKEY kludge).

**********************************************************************
EOTD                                               END OF THE DOCUMENT
**********************************************************************