commit refs/heads/master mark :1 committer Ben Finney 1258762084 +1100 data 55 Add reStructuredText source for specification document. M 644 inline specification.txt data 10211 ##################### Personal Avatar 0.3.0 ##################### .. title:: Personal Avatar (aka Pavatar) Specification 0.3.0 :Updated: 2006-12-18 :Copyright: © 2006 Jeena Paradies :This version: http://pavatar.com/spec/pavatar-0.3.0 :Latest version: http://pavatar.com/spec :Previous versions: | http://pavatar.com/spec/pavatar-0.2.0 | http://jeenaparadies.net/specs/pavatar-0.1.2 | http://jeenaparadies.net/specs/pavatar-0.1.1 | http://jeenaparadies.net/specs/pavatar-0.1.0 :Editors: `Jeena Paradies `_ ---- .. rubric:: Abstract The Personal Avatar (short Pavatar) system is a way to use small personalized images to standardize a providers profile picture through various websites when leaving comments and other content. Providers are able to host their Personal Avatars themselves. .. rubric:: Status of This Document This is the 18 December 2006 Candidate Recommendation of the Personal Avatar. This Candidate Recommendation was published to indicate that the document is believed to be stable and to encourage implementation by the developer community. Comments are welcome, please write to . .. role:: abbr .. role:: var(emphasis) .. contents:: Table of Contents :depth: 2 .. sectnum:: ---- Definitions =========== Provider `Provider` is the person who leaves a comment, post, annotation or similar content on a publishers page and possesses the Personal Avatar. The provider and the consumer **may** be the same. Providers website A `providers website` **must** be a valid :abbr:`HTTP (HyperText Transfer Protocol)` :abbr:`URL (Uniform Resource Locator)` according to `[RFC 1738]`_, which the provider has specified as his website. Personal Avatar A `Personal Avatar` is a picture stored on the provider's website conforming to the Personal Avatar conformance requirements described in `Personal Avatar Conformance Requirements`_. Consumer The `consumer` provides the service for the provider to act. The consumer and the provider **may** be the same. The Personal Avatar implementation (short: `implementation`) This is the `implementation` running the provider's service dealing the Personal Avatars. Now `Now` refers to the time the HTTP request is finished. The key words **must**, **must not**, **required**, **shall**, **shall not**, **should**, **should not**, **recommended**, **may**, and **optional** in this document are to be interpreted as described in `[RFC 2119]`_. .. _[RFC 1738]: http://www.faqs.org/rfcs/rfc1738.html .. _[RFC 2119]: http://www.faqs.org/rfcs/rfc2119.html ---- Personal Avatar Conformance Requirements ======================================== Technical Definition -------------------- A valid Personal Avatar **must** be a 80x80 pixel sized image in GIF (`[GIF89a]`_), PNG (`[PNG]`_) or JPEG ([ISO/IEC IS 10918-1], [ISO/IEC IS 14495-1], [ISO/IEC IS 15444-1]) format. A valid Personal Avatar **must not** exceed the size of 409600 Bit (the octuple size of an uncompressed 80x80pixel big picture with 8-bit color depth). A valid Personal Avatar **must** be publicly accessible through a valid HTTP URL (`[RFC 1738]`_). This URL **must** be used to reference the Personal Avatar (see `Autodiscovery`_). The Personal Avatar URL **must** have the correct ``Content-Type`` header. .. _[GIF89a]: http://www.w3.org/Graphics/GIF/spec-gif89a.txt .. _[PNG]: http://www.w3.org/TR/PNG/ Refusing Personal Avatar Requests --------------------------------- The provider **may** restrict access to the Personal Avatar. The provider **must** act accordingly to HTTP, e.g. **should** response with a 403 HTTP status code, if access is denied. It is **recommended** to use the keyword "**none**" of the HTTP-Header ``X-Pavatar`` as described in `HTTP Header`_ to refuse the delivery of the Personal Avatar completely. ---- Autodiscovery ============= The URL of the Personal Avatar **must** be offered by the provider in one or more of the following ways to the consumer, the use of `HTTP Header`_ and `Link Element`_ is **recommended**. The consumer **must** accept all three ways. HTTP Header ----------- If chosen, a reference to a Personal Avatar **must** be returned with a ``X-Pavatar`` HTTP header, for example:: X-Pavatar: http://example.com/path/to/my-own_pavatar.png The value of the ``X-Pavatar`` header **must** be the absolute URL of the Personal Avatar or the keyword "**none**". The server response **must not** include more than one such header. Link Element ------------ If chosen, an HTML or XHTML Personal Avatar enabled page **must** contain a ```` element. It **must** have one of the following forms: HTML .. parsed-literal:: XHTML .. parsed-literal:: The URL in the "``href``" attribute **must** be a valid and absolute HTTP URL according to `[RFC 1738]`_ or the keyword "**none**". Direct URL ---------- (the favicon.ico way) If chosen, there **must** be a file named ":var:`pavatar.png`" on the providers server. The URL for this file **must** conform to the following form. The EBNF keywords used here are similar to the ones used in `[RFC 1738]`_. .. parsed-literal:: hostport = host [ ":" port ] hsegment = \*[ uchar | ";" | ":" | "@" | "&" | "=" ] **puri = "http://" hostport \*[ "/" hsegment ] "/pavatar.png"** Example in Pseudocode ~~~~~~~~~~~~~~~~~~~~~ 1. IF the last ``hsegmet`` ends with a slash: GOTO 3 2. Remove the first ``hsegment`` 3. Append ":var:`pavatar.png`" to the result 4. IF success (i.e. a 2xx answer to an HEAD request) EXIT(SUCCESS) 5. ELSE remove all ``hsegments`` 6. Append ":var:`pavatar.png`" to the result 7. IF success (i.e. a 2xx answer to an HEAD request) EXIT(SUCCESS) 8. EXIT(FAILURE) Precedence ---------- The `HTTP Header`_ method **must** have the highest precedence, the `Direct URL`_ method the lowest. ---- Dealing with Personal Avatars ============================= The implementation **should** ensure to use as little traffic as possible to deal with Personal Avatars (e.g., use conditional get HTTP headers like ``If-Modified-Since``). Autodiscovery Algorithm ----------------------- Personal Avatar implementations, given a publisher's website URL, **should** follow the following steps to find the Personal Avatar URL (*obs.* if the implementation finds the keyword "**none**" instead of a valid URL it **must** abbort the autodiscovery because there will be no Personal Avatar at all): 1. Examine the HTTP headers of the response. If there are any ``X-Pavatar`` headers then the first such header's value **should** be used as the Personal Avatar resource. Clients **must** examine the HTTP headers if they are able to. If for some reason the HTTP headers are not available to the implementation then this step **may** be skipped, however, implementers **should** be aware that this will reduce the usefulness of their application as link elements cannot be used for resources that are neither HTML nor XHTML, and HTTP headers are defined to override link elements when they differ. 2. If there is no ``X-Pavatar`` HTTP Header, search the entity body for the first match of the following regular expression: .. parsed-literal:: If the regular expression matched, clients **must** decode the allowed HTML entities (``&`` for ``&``, ``<`` for ``<``, ``>`` for ``>``, and ``"`` for ``"``). 3. If no ``X-Pavatar`` HTTP Header and no ```` could be found the implementation **shall** check first if there is a Personal Avatar in the publisher's website directory. If not, it **shall** check if there is a Personal Avatar in the publisher's website document root. Manipulating ------------ The implementation **may** manipulate the cached Personal Avatar if necessary, e.g. changes in width and height, colors, etc. but it **must** respect the visual identity of the provider and therefore avoid *destructive* transformations of the Personal Avatar, such as those that fundamentally alter the content of the image. Caching ------- The implementation **should** cache **all** Personal Avatars it wants to serve. It **should not** serve them remotely. Updating Cached Personal Avatars -------------------------------- The implementation **may** check regularly for changed Personal Avatars using the information given in the ``Cache-Control`` or ``Expires`` headers. If the publisher's website doesn't send these headers, it is **recommended** that it checks weekly for changes. The implementation **should** remember URLs for which the `autodiscovery algorithm`_ didn't find a Personal Avatar and not check them for changes until the provider posts something new. ---- Appendix ======== This chapter is informative. Useragents are not required to implement the properties of this chapter in order to conform to the Personal Avatar specification. Optimization ------------ Clients **may** optimize the search. For example: 1. The client **may** initally only send an HTTP HEAD request in the hope that the header will be found and the content will not have to be fetched. 2. Since ```` elements may only appear in the document's head, clients **may** abort when the strings ```` or ```` are seen (e.g. if the client reads the content one line at a time). 3. Since the Personal Avatar links are most likely to appear near the top of the document, clients **may** abort the search after passing a certain size threshold. Clients **may** similarly use the HTTP Content-Range header to only fetch the first few kilobytes of the target URI. Support of Conformance to Arbitrary Rules ----------------------------------------- The implementation **may** include an automatic denial-of-publish mechanism if the Personal Avatar is unknown to the system. It **may** include a notification mechanism in case of an automatic denial-of-publish. .. Local variables: coding: utf-8 mode: rst End: vim: fileencoding=utf-8 filetype=rst : commit refs/heads/master mark :2 committer Ben Finney 1258762110 +1100 data 49 Add GNU Makefile for building HTML documentation. from :1 M 755 inline Makefile data 939 #! /usr/bin/make -f # # GNU Makefile for Pavatar documentation. # # Copyright © 2009 Ben Finney # This work is hereby placed in the public domain. To the extent that # placing a work in the public domain is not legally possible, the # copyright holder hereby grants to all recipients of this work all # rights and freedoms that would otherwise be restricted by copyright. DOCUMENT_NAMES = specification RST_SUFFIX = .txt HTML_SUFFIX = .html STYLESHEET_SUFFIX = .css html_docs = $(addsuffix ${HTML_SUFFIX},${DOCUMENT_NAMES}) RST2HTML = rst2html RST2HTML_OPTS = --no-toc-backlinks --initial-header-level 2 .PHONY: all all: doc .PHONY: doc doc: ${html_docs} %${HTML_SUFFIX}: RST2HTML_OPTS += --link-stylesheet %${HTML_SUFFIX}: RST2HTML_OPTS += --stylesheet $(patsubst %${HTML_SUFFIX},%${STYLESHEET_SUFFIX},$@) %${HTML_SUFFIX}: %${RST_SUFFIX} %${STYLESHEET_SUFFIX} $(RST2HTML) ${RST2HTML_OPTS} $< > $@ commit refs/heads/master mark :3 committer Ben Finney 1258762139 +1100 data 32 Ignore autogenerated HTML files. from :2 M 644 inline .bzrignore data 7 *.html commit refs/heads/master mark :4 committer Ben Finney 1258766653 +1100 data 24 Fix trailing whitespace. from :3 M 644 inline specification.txt data 10207 ##################### Personal Avatar 0.3.0 ##################### .. title:: Personal Avatar (aka Pavatar) Specification 0.3.0 :Updated: 2006-12-18 :Copyright: © 2006 Jeena Paradies :This version: http://pavatar.com/spec/pavatar-0.3.0 :Latest version: http://pavatar.com/spec :Previous versions: | http://pavatar.com/spec/pavatar-0.2.0 | http://jeenaparadies.net/specs/pavatar-0.1.2 | http://jeenaparadies.net/specs/pavatar-0.1.1 | http://jeenaparadies.net/specs/pavatar-0.1.0 :Editors: `Jeena Paradies `_ ---- .. rubric:: Abstract The Personal Avatar (short Pavatar) system is a way to use small personalized images to standardize a providers profile picture through various websites when leaving comments and other content. Providers are able to host their Personal Avatars themselves. .. rubric:: Status of This Document This is the 18 December 2006 Candidate Recommendation of the Personal Avatar. This Candidate Recommendation was published to indicate that the document is believed to be stable and to encourage implementation by the developer community. Comments are welcome, please write to . .. role:: abbr .. role:: var(emphasis) .. contents:: Table of Contents :depth: 2 .. sectnum:: ---- Definitions =========== Provider `Provider` is the person who leaves a comment, post, annotation or similar content on a publishers page and possesses the Personal Avatar. The provider and the consumer **may** be the same. Providers website A `providers website` **must** be a valid :abbr:`HTTP (HyperText Transfer Protocol)` :abbr:`URL (Uniform Resource Locator)` according to `[RFC 1738]`_, which the provider has specified as his website. Personal Avatar A `Personal Avatar` is a picture stored on the provider's website conforming to the Personal Avatar conformance requirements described in `Personal Avatar Conformance Requirements`_. Consumer The `consumer` provides the service for the provider to act. The consumer and the provider **may** be the same. The Personal Avatar implementation (short: `implementation`) This is the `implementation` running the provider's service dealing the Personal Avatars. Now `Now` refers to the time the HTTP request is finished. The key words **must**, **must not**, **required**, **shall**, **shall not**, **should**, **should not**, **recommended**, **may**, and **optional** in this document are to be interpreted as described in `[RFC 2119]`_. .. _[RFC 1738]: http://www.faqs.org/rfcs/rfc1738.html .. _[RFC 2119]: http://www.faqs.org/rfcs/rfc2119.html ---- Personal Avatar Conformance Requirements ======================================== Technical Definition -------------------- A valid Personal Avatar **must** be a 80x80 pixel sized image in GIF (`[GIF89a]`_), PNG (`[PNG]`_) or JPEG ([ISO/IEC IS 10918-1], [ISO/IEC IS 14495-1], [ISO/IEC IS 15444-1]) format. A valid Personal Avatar **must not** exceed the size of 409600 Bit (the octuple size of an uncompressed 80x80pixel big picture with 8-bit color depth). A valid Personal Avatar **must** be publicly accessible through a valid HTTP URL (`[RFC 1738]`_). This URL **must** be used to reference the Personal Avatar (see `Autodiscovery`_). The Personal Avatar URL **must** have the correct ``Content-Type`` header. .. _[GIF89a]: http://www.w3.org/Graphics/GIF/spec-gif89a.txt .. _[PNG]: http://www.w3.org/TR/PNG/ Refusing Personal Avatar Requests --------------------------------- The provider **may** restrict access to the Personal Avatar. The provider **must** act accordingly to HTTP, e.g. **should** response with a 403 HTTP status code, if access is denied. It is **recommended** to use the keyword "**none**" of the HTTP-Header ``X-Pavatar`` as described in `HTTP Header`_ to refuse the delivery of the Personal Avatar completely. ---- Autodiscovery ============= The URL of the Personal Avatar **must** be offered by the provider in one or more of the following ways to the consumer, the use of `HTTP Header`_ and `Link Element`_ is **recommended**. The consumer **must** accept all three ways. HTTP Header ----------- If chosen, a reference to a Personal Avatar **must** be returned with a ``X-Pavatar`` HTTP header, for example:: X-Pavatar: http://example.com/path/to/my-own_pavatar.png The value of the ``X-Pavatar`` header **must** be the absolute URL of the Personal Avatar or the keyword "**none**". The server response **must not** include more than one such header. Link Element ------------ If chosen, an HTML or XHTML Personal Avatar enabled page **must** contain a ```` element. It **must** have one of the following forms: HTML .. parsed-literal:: XHTML .. parsed-literal:: The URL in the "``href``" attribute **must** be a valid and absolute HTTP URL according to `[RFC 1738]`_ or the keyword "**none**". Direct URL ---------- (the favicon.ico way) If chosen, there **must** be a file named ":var:`pavatar.png`" on the providers server. The URL for this file **must** conform to the following form. The EBNF keywords used here are similar to the ones used in `[RFC 1738]`_. .. parsed-literal:: hostport = host [ ":" port ] hsegment = \*[ uchar | ";" | ":" | "@" | "&" | "=" ] **puri = "http://" hostport \*[ "/" hsegment ] "/pavatar.png"** Example in Pseudocode ~~~~~~~~~~~~~~~~~~~~~ 1. IF the last ``hsegmet`` ends with a slash: GOTO 3 2. Remove the first ``hsegment`` 3. Append ":var:`pavatar.png`" to the result 4. IF success (i.e. a 2xx answer to an HEAD request) EXIT(SUCCESS) 5. ELSE remove all ``hsegments`` 6. Append ":var:`pavatar.png`" to the result 7. IF success (i.e. a 2xx answer to an HEAD request) EXIT(SUCCESS) 8. EXIT(FAILURE) Precedence ---------- The `HTTP Header`_ method **must** have the highest precedence, the `Direct URL`_ method the lowest. ---- Dealing with Personal Avatars ============================= The implementation **should** ensure to use as little traffic as possible to deal with Personal Avatars (e.g., use conditional get HTTP headers like ``If-Modified-Since``). Autodiscovery Algorithm ----------------------- Personal Avatar implementations, given a publisher's website URL, **should** follow the following steps to find the Personal Avatar URL (*obs.* if the implementation finds the keyword "**none**" instead of a valid URL it **must** abbort the autodiscovery because there will be no Personal Avatar at all): 1. Examine the HTTP headers of the response. If there are any ``X-Pavatar`` headers then the first such header's value **should** be used as the Personal Avatar resource. Clients **must** examine the HTTP headers if they are able to. If for some reason the HTTP headers are not available to the implementation then this step **may** be skipped, however, implementers **should** be aware that this will reduce the usefulness of their application as link elements cannot be used for resources that are neither HTML nor XHTML, and HTTP headers are defined to override link elements when they differ. 2. If there is no ``X-Pavatar`` HTTP Header, search the entity body for the first match of the following regular expression: .. parsed-literal:: If the regular expression matched, clients **must** decode the allowed HTML entities (``&`` for ``&``, ``<`` for ``<``, ``>`` for ``>``, and ``"`` for ``"``). 3. If no ``X-Pavatar`` HTTP Header and no ```` could be found the implementation **shall** check first if there is a Personal Avatar in the publisher's website directory. If not, it **shall** check if there is a Personal Avatar in the publisher's website document root. Manipulating ------------ The implementation **may** manipulate the cached Personal Avatar if necessary, e.g. changes in width and height, colors, etc. but it **must** respect the visual identity of the provider and therefore avoid *destructive* transformations of the Personal Avatar, such as those that fundamentally alter the content of the image. Caching ------- The implementation **should** cache **all** Personal Avatars it wants to serve. It **should not** serve them remotely. Updating Cached Personal Avatars -------------------------------- The implementation **may** check regularly for changed Personal Avatars using the information given in the ``Cache-Control`` or ``Expires`` headers. If the publisher's website doesn't send these headers, it is **recommended** that it checks weekly for changes. The implementation **should** remember URLs for which the `autodiscovery algorithm`_ didn't find a Personal Avatar and not check them for changes until the provider posts something new. ---- Appendix ======== This chapter is informative. Useragents are not required to implement the properties of this chapter in order to conform to the Personal Avatar specification. Optimization ------------ Clients **may** optimize the search. For example: 1. The client **may** initally only send an HTTP HEAD request in the hope that the header will be found and the content will not have to be fetched. 2. Since ```` elements may only appear in the document's head, clients **may** abort when the strings ```` or ```` are seen (e.g. if the client reads the content one line at a time). 3. Since the Personal Avatar links are most likely to appear near the top of the document, clients **may** abort the search after passing a certain size threshold. Clients **may** similarly use the HTTP Content-Range header to only fetch the first few kilobytes of the target URI. Support of Conformance to Arbitrary Rules ----------------------------------------- The implementation **may** include an automatic denial-of-publish mechanism if the Personal Avatar is unknown to the system. It **may** include a notification mechanism in case of an automatic denial-of-publish. .. Local variables: coding: utf-8 mode: rst End: vim: fileencoding=utf-8 filetype=rst : commit refs/heads/master mark :5 committer Ben Finney 1258768854 +1100 data 40 Use proper headings markup for headings. from :4 M 644 inline specification.txt data 10214 ##################### Personal Avatar 0.3.0 ##################### .. title:: Personal Avatar (aka Pavatar) Specification 0.3.0 :Updated: 2006-12-18 :Copyright: © 2006 Jeena Paradies :This version: http://pavatar.com/spec/pavatar-0.3.0 :Latest version: http://pavatar.com/spec :Previous versions: | http://pavatar.com/spec/pavatar-0.2.0 | http://jeenaparadies.net/specs/pavatar-0.1.2 | http://jeenaparadies.net/specs/pavatar-0.1.1 | http://jeenaparadies.net/specs/pavatar-0.1.0 :Editors: `Jeena Paradies `_ ---- Abstract ======== The Personal Avatar (short Pavatar) system is a way to use small personalized images to standardize a providers profile picture through various websites when leaving comments and other content. Providers are able to host their Personal Avatars themselves. Status of This Document ======================= This is the 18 December 2006 Candidate Recommendation of the Personal Avatar. This Candidate Recommendation was published to indicate that the document is believed to be stable and to encourage implementation by the developer community. Comments are welcome, please write to . .. role:: abbr .. role:: var(emphasis) .. contents:: Table of Contents :depth: 2 .. sectnum:: ---- Definitions =========== Provider `Provider` is the person who leaves a comment, post, annotation or similar content on a publishers page and possesses the Personal Avatar. The provider and the consumer **may** be the same. Providers website A `providers website` **must** be a valid :abbr:`HTTP (HyperText Transfer Protocol)` :abbr:`URL (Uniform Resource Locator)` according to `[RFC 1738]`_, which the provider has specified as his website. Personal Avatar A `Personal Avatar` is a picture stored on the provider's website conforming to the Personal Avatar conformance requirements described in `Personal Avatar Conformance Requirements`_. Consumer The `consumer` provides the service for the provider to act. The consumer and the provider **may** be the same. The Personal Avatar implementation (short: `implementation`) This is the `implementation` running the provider's service dealing the Personal Avatars. Now `Now` refers to the time the HTTP request is finished. The key words **must**, **must not**, **required**, **shall**, **shall not**, **should**, **should not**, **recommended**, **may**, and **optional** in this document are to be interpreted as described in `[RFC 2119]`_. .. _[RFC 1738]: http://www.faqs.org/rfcs/rfc1738.html .. _[RFC 2119]: http://www.faqs.org/rfcs/rfc2119.html ---- Personal Avatar Conformance Requirements ======================================== Technical Definition -------------------- A valid Personal Avatar **must** be a 80x80 pixel sized image in GIF (`[GIF89a]`_), PNG (`[PNG]`_) or JPEG ([ISO/IEC IS 10918-1], [ISO/IEC IS 14495-1], [ISO/IEC IS 15444-1]) format. A valid Personal Avatar **must not** exceed the size of 409600 Bit (the octuple size of an uncompressed 80x80pixel big picture with 8-bit color depth). A valid Personal Avatar **must** be publicly accessible through a valid HTTP URL (`[RFC 1738]`_). This URL **must** be used to reference the Personal Avatar (see `Autodiscovery`_). The Personal Avatar URL **must** have the correct ``Content-Type`` header. .. _[GIF89a]: http://www.w3.org/Graphics/GIF/spec-gif89a.txt .. _[PNG]: http://www.w3.org/TR/PNG/ Refusing Personal Avatar Requests --------------------------------- The provider **may** restrict access to the Personal Avatar. The provider **must** act accordingly to HTTP, e.g. **should** response with a 403 HTTP status code, if access is denied. It is **recommended** to use the keyword "**none**" of the HTTP-Header ``X-Pavatar`` as described in `HTTP Header`_ to refuse the delivery of the Personal Avatar completely. ---- Autodiscovery ============= The URL of the Personal Avatar **must** be offered by the provider in one or more of the following ways to the consumer, the use of `HTTP Header`_ and `Link Element`_ is **recommended**. The consumer **must** accept all three ways. HTTP Header ----------- If chosen, a reference to a Personal Avatar **must** be returned with a ``X-Pavatar`` HTTP header, for example:: X-Pavatar: http://example.com/path/to/my-own_pavatar.png The value of the ``X-Pavatar`` header **must** be the absolute URL of the Personal Avatar or the keyword "**none**". The server response **must not** include more than one such header. Link Element ------------ If chosen, an HTML or XHTML Personal Avatar enabled page **must** contain a ```` element. It **must** have one of the following forms: HTML .. parsed-literal:: XHTML .. parsed-literal:: The URL in the "``href``" attribute **must** be a valid and absolute HTTP URL according to `[RFC 1738]`_ or the keyword "**none**". Direct URL ---------- (the favicon.ico way) If chosen, there **must** be a file named ":var:`pavatar.png`" on the providers server. The URL for this file **must** conform to the following form. The EBNF keywords used here are similar to the ones used in `[RFC 1738]`_. .. parsed-literal:: hostport = host [ ":" port ] hsegment = \*[ uchar | ";" | ":" | "@" | "&" | "=" ] **puri = "http://" hostport \*[ "/" hsegment ] "/pavatar.png"** Example in Pseudocode ~~~~~~~~~~~~~~~~~~~~~ 1. IF the last ``hsegmet`` ends with a slash: GOTO 3 2. Remove the first ``hsegment`` 3. Append ":var:`pavatar.png`" to the result 4. IF success (i.e. a 2xx answer to an HEAD request) EXIT(SUCCESS) 5. ELSE remove all ``hsegments`` 6. Append ":var:`pavatar.png`" to the result 7. IF success (i.e. a 2xx answer to an HEAD request) EXIT(SUCCESS) 8. EXIT(FAILURE) Precedence ---------- The `HTTP Header`_ method **must** have the highest precedence, the `Direct URL`_ method the lowest. ---- Dealing with Personal Avatars ============================= The implementation **should** ensure to use as little traffic as possible to deal with Personal Avatars (e.g., use conditional get HTTP headers like ``If-Modified-Since``). Autodiscovery Algorithm ----------------------- Personal Avatar implementations, given a publisher's website URL, **should** follow the following steps to find the Personal Avatar URL (*obs.* if the implementation finds the keyword "**none**" instead of a valid URL it **must** abbort the autodiscovery because there will be no Personal Avatar at all): 1. Examine the HTTP headers of the response. If there are any ``X-Pavatar`` headers then the first such header's value **should** be used as the Personal Avatar resource. Clients **must** examine the HTTP headers if they are able to. If for some reason the HTTP headers are not available to the implementation then this step **may** be skipped, however, implementers **should** be aware that this will reduce the usefulness of their application as link elements cannot be used for resources that are neither HTML nor XHTML, and HTTP headers are defined to override link elements when they differ. 2. If there is no ``X-Pavatar`` HTTP Header, search the entity body for the first match of the following regular expression: .. parsed-literal:: If the regular expression matched, clients **must** decode the allowed HTML entities (``&`` for ``&``, ``<`` for ``<``, ``>`` for ``>``, and ``"`` for ``"``). 3. If no ``X-Pavatar`` HTTP Header and no ```` could be found the implementation **shall** check first if there is a Personal Avatar in the publisher's website directory. If not, it **shall** check if there is a Personal Avatar in the publisher's website document root. Manipulating ------------ The implementation **may** manipulate the cached Personal Avatar if necessary, e.g. changes in width and height, colors, etc. but it **must** respect the visual identity of the provider and therefore avoid *destructive* transformations of the Personal Avatar, such as those that fundamentally alter the content of the image. Caching ------- The implementation **should** cache **all** Personal Avatars it wants to serve. It **should not** serve them remotely. Updating Cached Personal Avatars -------------------------------- The implementation **may** check regularly for changed Personal Avatars using the information given in the ``Cache-Control`` or ``Expires`` headers. If the publisher's website doesn't send these headers, it is **recommended** that it checks weekly for changes. The implementation **should** remember URLs for which the `autodiscovery algorithm`_ didn't find a Personal Avatar and not check them for changes until the provider posts something new. ---- Appendix ======== This chapter is informative. Useragents are not required to implement the properties of this chapter in order to conform to the Personal Avatar specification. Optimization ------------ Clients **may** optimize the search. For example: 1. The client **may** initally only send an HTTP HEAD request in the hope that the header will be found and the content will not have to be fetched. 2. Since ```` elements may only appear in the document's head, clients **may** abort when the strings ```` or ```` are seen (e.g. if the client reads the content one line at a time). 3. Since the Personal Avatar links are most likely to appear near the top of the document, clients **may** abort the search after passing a certain size threshold. Clients **may** similarly use the HTTP Content-Range header to only fetch the first few kilobytes of the target URI. Support of Conformance to Arbitrary Rules ----------------------------------------- The implementation **may** include an automatic denial-of-publish mechanism if the Personal Avatar is unknown to the system. It **may** include a notification mechanism in case of an automatic denial-of-publish. .. Local variables: coding: utf-8 mode: rst End: vim: fileencoding=utf-8 filetype=rst : commit refs/heads/master mark :6 committer Ben Finney 1258813293 +1100 data 65 Make field structure of version references so they render better. from :5 M 644 inline specification.txt data 10236 ##################### Personal Avatar 0.3.0 ##################### .. title:: Personal Avatar (aka Pavatar) Specification 0.3.0 :Updated: 2006-12-18 :Copyright: © 2006 Jeena Paradies :Versions: :This: http://pavatar.com/spec/pavatar-0.3.0 :Latest: http://pavatar.com/spec :Previous: | http://pavatar.com/spec/pavatar-0.2.0 | http://jeenaparadies.net/specs/pavatar-0.1.2 | http://jeenaparadies.net/specs/pavatar-0.1.1 | http://jeenaparadies.net/specs/pavatar-0.1.0 :Editors: `Jeena Paradies `_ ---- Abstract ======== The Personal Avatar (short Pavatar) system is a way to use small personalized images to standardize a providers profile picture through various websites when leaving comments and other content. Providers are able to host their Personal Avatars themselves. Status of This Document ======================= This is the 18 December 2006 Candidate Recommendation of the Personal Avatar. This Candidate Recommendation was published to indicate that the document is believed to be stable and to encourage implementation by the developer community. Comments are welcome, please write to . .. role:: abbr .. role:: var(emphasis) .. contents:: Table of Contents :depth: 2 .. sectnum:: ---- Definitions =========== Provider `Provider` is the person who leaves a comment, post, annotation or similar content on a publishers page and possesses the Personal Avatar. The provider and the consumer **may** be the same. Providers website A `providers website` **must** be a valid :abbr:`HTTP (HyperText Transfer Protocol)` :abbr:`URL (Uniform Resource Locator)` according to `[RFC 1738]`_, which the provider has specified as his website. Personal Avatar A `Personal Avatar` is a picture stored on the provider's website conforming to the Personal Avatar conformance requirements described in `Personal Avatar Conformance Requirements`_. Consumer The `consumer` provides the service for the provider to act. The consumer and the provider **may** be the same. The Personal Avatar implementation (short: `implementation`) This is the `implementation` running the provider's service dealing the Personal Avatars. Now `Now` refers to the time the HTTP request is finished. The key words **must**, **must not**, **required**, **shall**, **shall not**, **should**, **should not**, **recommended**, **may**, and **optional** in this document are to be interpreted as described in `[RFC 2119]`_. .. _[RFC 1738]: http://www.faqs.org/rfcs/rfc1738.html .. _[RFC 2119]: http://www.faqs.org/rfcs/rfc2119.html ---- Personal Avatar Conformance Requirements ======================================== Technical Definition -------------------- A valid Personal Avatar **must** be a 80x80 pixel sized image in GIF (`[GIF89a]`_), PNG (`[PNG]`_) or JPEG ([ISO/IEC IS 10918-1], [ISO/IEC IS 14495-1], [ISO/IEC IS 15444-1]) format. A valid Personal Avatar **must not** exceed the size of 409600 Bit (the octuple size of an uncompressed 80x80pixel big picture with 8-bit color depth). A valid Personal Avatar **must** be publicly accessible through a valid HTTP URL (`[RFC 1738]`_). This URL **must** be used to reference the Personal Avatar (see `Autodiscovery`_). The Personal Avatar URL **must** have the correct ``Content-Type`` header. .. _[GIF89a]: http://www.w3.org/Graphics/GIF/spec-gif89a.txt .. _[PNG]: http://www.w3.org/TR/PNG/ Refusing Personal Avatar Requests --------------------------------- The provider **may** restrict access to the Personal Avatar. The provider **must** act accordingly to HTTP, e.g. **should** response with a 403 HTTP status code, if access is denied. It is **recommended** to use the keyword "**none**" of the HTTP-Header ``X-Pavatar`` as described in `HTTP Header`_ to refuse the delivery of the Personal Avatar completely. ---- Autodiscovery ============= The URL of the Personal Avatar **must** be offered by the provider in one or more of the following ways to the consumer, the use of `HTTP Header`_ and `Link Element`_ is **recommended**. The consumer **must** accept all three ways. HTTP Header ----------- If chosen, a reference to a Personal Avatar **must** be returned with a ``X-Pavatar`` HTTP header, for example:: X-Pavatar: http://example.com/path/to/my-own_pavatar.png The value of the ``X-Pavatar`` header **must** be the absolute URL of the Personal Avatar or the keyword "**none**". The server response **must not** include more than one such header. Link Element ------------ If chosen, an HTML or XHTML Personal Avatar enabled page **must** contain a ```` element. It **must** have one of the following forms: HTML .. parsed-literal:: XHTML .. parsed-literal:: The URL in the "``href``" attribute **must** be a valid and absolute HTTP URL according to `[RFC 1738]`_ or the keyword "**none**". Direct URL ---------- (the favicon.ico way) If chosen, there **must** be a file named ":var:`pavatar.png`" on the providers server. The URL for this file **must** conform to the following form. The EBNF keywords used here are similar to the ones used in `[RFC 1738]`_. .. parsed-literal:: hostport = host [ ":" port ] hsegment = \*[ uchar | ";" | ":" | "@" | "&" | "=" ] **puri = "http://" hostport \*[ "/" hsegment ] "/pavatar.png"** Example in Pseudocode ~~~~~~~~~~~~~~~~~~~~~ 1. IF the last ``hsegmet`` ends with a slash: GOTO 3 2. Remove the first ``hsegment`` 3. Append ":var:`pavatar.png`" to the result 4. IF success (i.e. a 2xx answer to an HEAD request) EXIT(SUCCESS) 5. ELSE remove all ``hsegments`` 6. Append ":var:`pavatar.png`" to the result 7. IF success (i.e. a 2xx answer to an HEAD request) EXIT(SUCCESS) 8. EXIT(FAILURE) Precedence ---------- The `HTTP Header`_ method **must** have the highest precedence, the `Direct URL`_ method the lowest. ---- Dealing with Personal Avatars ============================= The implementation **should** ensure to use as little traffic as possible to deal with Personal Avatars (e.g., use conditional get HTTP headers like ``If-Modified-Since``). Autodiscovery Algorithm ----------------------- Personal Avatar implementations, given a publisher's website URL, **should** follow the following steps to find the Personal Avatar URL (*obs.* if the implementation finds the keyword "**none**" instead of a valid URL it **must** abbort the autodiscovery because there will be no Personal Avatar at all): 1. Examine the HTTP headers of the response. If there are any ``X-Pavatar`` headers then the first such header's value **should** be used as the Personal Avatar resource. Clients **must** examine the HTTP headers if they are able to. If for some reason the HTTP headers are not available to the implementation then this step **may** be skipped, however, implementers **should** be aware that this will reduce the usefulness of their application as link elements cannot be used for resources that are neither HTML nor XHTML, and HTTP headers are defined to override link elements when they differ. 2. If there is no ``X-Pavatar`` HTTP Header, search the entity body for the first match of the following regular expression: .. parsed-literal:: If the regular expression matched, clients **must** decode the allowed HTML entities (``&`` for ``&``, ``<`` for ``<``, ``>`` for ``>``, and ``"`` for ``"``). 3. If no ``X-Pavatar`` HTTP Header and no ```` could be found the implementation **shall** check first if there is a Personal Avatar in the publisher's website directory. If not, it **shall** check if there is a Personal Avatar in the publisher's website document root. Manipulating ------------ The implementation **may** manipulate the cached Personal Avatar if necessary, e.g. changes in width and height, colors, etc. but it **must** respect the visual identity of the provider and therefore avoid *destructive* transformations of the Personal Avatar, such as those that fundamentally alter the content of the image. Caching ------- The implementation **should** cache **all** Personal Avatars it wants to serve. It **should not** serve them remotely. Updating Cached Personal Avatars -------------------------------- The implementation **may** check regularly for changed Personal Avatars using the information given in the ``Cache-Control`` or ``Expires`` headers. If the publisher's website doesn't send these headers, it is **recommended** that it checks weekly for changes. The implementation **should** remember URLs for which the `autodiscovery algorithm`_ didn't find a Personal Avatar and not check them for changes until the provider posts something new. ---- Appendix ======== This chapter is informative. Useragents are not required to implement the properties of this chapter in order to conform to the Personal Avatar specification. Optimization ------------ Clients **may** optimize the search. For example: 1. The client **may** initally only send an HTTP HEAD request in the hope that the header will be found and the content will not have to be fetched. 2. Since ```` elements may only appear in the document's head, clients **may** abort when the strings ```` or ```` are seen (e.g. if the client reads the content one line at a time). 3. Since the Personal Avatar links are most likely to appear near the top of the document, clients **may** abort the search after passing a certain size threshold. Clients **may** similarly use the HTTP Content-Range header to only fetch the first few kilobytes of the target URI. Support of Conformance to Arbitrary Rules ----------------------------------------- The implementation **may** include an automatic denial-of-publish mechanism if the Personal Avatar is unknown to the system. It **may** include a notification mechanism in case of an automatic denial-of-publish. .. Local variables: coding: utf-8 mode: rst End: vim: fileencoding=utf-8 filetype=rst : commit refs/heads/master mark :7 committer Jeena Paradies 1258711768 +0100 data 36 added the check your pavatar script M 644 inline check_your_pavatar.rb data 6980 #!/usr/bin/ruby -w # This is a Pavatar check script written in ruby by Jeena Paradies # I hereby place this script into the public domain. # # This is version 0.2 and it could include some bugs I haven't found yet. # Because the program is licensed free of charge, there is no warranty # for the program, but it works for me, try it if you want. # # If you have some questions contact me: pavatar@jeenaparadies.net # include some libraries require 'cgi' require 'uri' require 'net/http' require 'image_size' # see http://www.rubycgi.org/archive/ class Pavatar # content types defined by the spec http://pavatar.com/spec#technical-definition @@content_types = ['image/png', 'image/jpeg', 'image/gif'] # fetch the pavatar url on initialize def initialize url @url = url @purl = URI.parse(@url) # check for the first real pavatar url and save it into a class variable if (@pavatar = xHeader).nil? and (@pavatar = link).nil? and (@pavatar = path).nil? @pavatar = favicon end end # Autodiscovery methods # get url from header if there is one def xHeader begin res = FetchHelper.head(@url) res['X-Pavatar'] unless res['X-Pavatar'].nil? rescue end end # get url from if there is one def link begin res = FetchHelper.get(@url) pavatar = //.match(res.body) pavatar[1] unless pavatar.nil? rescue end end # look in users path if there is a pavatar def path begin # to discover the given directory is a little bit tricky in ruby path = @purl.path.to_s unless path[-1..-1] == '/' path = File.dirname(path) unless path == '.' or path == '/' path << '/' end end if path == '.' path = '/' end url = 'http://' + @purl.host.to_s + path + 'pavatar.png' # if would be ok to look on the header here but Apache has a problem with # head requests so we use a get request to workaround it res = FetchHelper.get(url) # some people redirect to a 404 page and send status 200 so we need to check the content type url unless res['content-type'].nil? or not @@content_types.include?(res['content-type']) rescue end end # look in users home directory if there is a pavatar def favicon begin url = 'http://' + @purl.host.to_s + '/pavatar.png' # same problem with apache here res = FetchHelper.get(url) url unless res['content-type'].nil? or not @@content_types.include?(res['content-type']) rescue end end # url getter def get_url @pavatar end # get a whole html string to show a pavatar def get_html (attr = '') attr = ' ' + attr unless attr.length > 0 '' end end # helps us handle redirections module FetchHelper def FetchHelper.head(url_str, limit = 10) # stop if there is a loop raise ArgumentError, 'HTTP redirect too deep' if limit == 0 url = URI.parse(url_str) path = File.dirname(url.path.to_s) response = nil Net::HTTP.start(url.host, url.port) { |http| response = http.head( path == '.' ? '/' : url.path.to_s ) } case response when Net::HTTPSuccess then response when Net::HTTPRedirection then FetchHelper.head(response['location'], limit - 1) else response.error! end end def FetchHelper.get(url_str, limit = 10) raise ArgumentError, 'HTTP redirect too deep.' if limit == 0 response = Net::HTTP.get_response(URI.parse(url_str)) case response when Net::HTTPSuccess then response when Net::HTTPRedirection then FetchHelper.get(response['location'], limit - 1) else response.error! end end def FetchHelper.validate(url, what) begin uri = URI.parse(url) if uri.class != URI::HTTP raise ArgumentError, "Only HTTP protocol addresses can be used in the #{what} URL." end rescue URI::InvalidURIError raise ArgumentError, "The format of the #{what} URL is not valid." end end end # ------------------------------------- # HTML output # ------------------------------------- cgi = CGI.new url = cgi['hp'] # print our HTML header print "Content-type: text/html\r\n\r\n" print < Check your Pavatar!

Check your Pavatar!

Your homepage:

HTML types = { 'PNG' => 'image/png', 'GIF' => 'image/gif', 'JPEG' => 'image/jpeg' } unless cgi['hp'].length == 0 then begin FetchHelper.validate(url, 'homepage') pavatar_url = Pavatar.new(cgi['hp']) raise ArgumentError, "No pavatar here." if pavatar_url.get_url.nil? or pavatar_url.get_url == "none" FetchHelper.validate(pavatar_url.get_url, 'Pavatar') pavatar = FetchHelper.get(pavatar_url.get_url) raise ArgumentError, "File size too big (#{(pavatar.body.to_s.size * 8)}) max: 409600." if (pavatar.body.to_s.size * 8) > 409600 img = ImageSize.new(pavatar.body) raise ArgumentError, "Width is not 80px but #{img.get_width}px." unless img.get_width == 80 raise ArgumentError, "Height is not 80px but #{img.get_height}px." unless img.get_height == 80 raise ArgumentError, "False image type: #{img.get_type} #{pavatar_url.get_url}." unless types.has_key? img.get_type print pavatar_url.get_html('alt="My Pavatar"') rescue Exception => e print "Error:
#{e}\r\n" end end print <

HTML commit refs/heads/master mark :8 committer Ben Finney 1258848526 +1100 data 29 Merge from pavatar.upstream/. from :6 merge :7 M 644 inline check_your_pavatar.rb data 6980 #!/usr/bin/ruby -w # This is a Pavatar check script written in ruby by Jeena Paradies # I hereby place this script into the public domain. # # This is version 0.2 and it could include some bugs I haven't found yet. # Because the program is licensed free of charge, there is no warranty # for the program, but it works for me, try it if you want. # # If you have some questions contact me: pavatar@jeenaparadies.net # include some libraries require 'cgi' require 'uri' require 'net/http' require 'image_size' # see http://www.rubycgi.org/archive/ class Pavatar # content types defined by the spec http://pavatar.com/spec#technical-definition @@content_types = ['image/png', 'image/jpeg', 'image/gif'] # fetch the pavatar url on initialize def initialize url @url = url @purl = URI.parse(@url) # check for the first real pavatar url and save it into a class variable if (@pavatar = xHeader).nil? and (@pavatar = link).nil? and (@pavatar = path).nil? @pavatar = favicon end end # Autodiscovery methods # get url from header if there is one def xHeader begin res = FetchHelper.head(@url) res['X-Pavatar'] unless res['X-Pavatar'].nil? rescue end end # get url from if there is one def link begin res = FetchHelper.get(@url) pavatar = //.match(res.body) pavatar[1] unless pavatar.nil? rescue end end # look in users path if there is a pavatar def path begin # to discover the given directory is a little bit tricky in ruby path = @purl.path.to_s unless path[-1..-1] == '/' path = File.dirname(path) unless path == '.' or path == '/' path << '/' end end if path == '.' path = '/' end url = 'http://' + @purl.host.to_s + path + 'pavatar.png' # if would be ok to look on the header here but Apache has a problem with # head requests so we use a get request to workaround it res = FetchHelper.get(url) # some people redirect to a 404 page and send status 200 so we need to check the content type url unless res['content-type'].nil? or not @@content_types.include?(res['content-type']) rescue end end # look in users home directory if there is a pavatar def favicon begin url = 'http://' + @purl.host.to_s + '/pavatar.png' # same problem with apache here res = FetchHelper.get(url) url unless res['content-type'].nil? or not @@content_types.include?(res['content-type']) rescue end end # url getter def get_url @pavatar end # get a whole html string to show a pavatar def get_html (attr = '') attr = ' ' + attr unless attr.length > 0 '' end end # helps us handle redirections module FetchHelper def FetchHelper.head(url_str, limit = 10) # stop if there is a loop raise ArgumentError, 'HTTP redirect too deep' if limit == 0 url = URI.parse(url_str) path = File.dirname(url.path.to_s) response = nil Net::HTTP.start(url.host, url.port) { |http| response = http.head( path == '.' ? '/' : url.path.to_s ) } case response when Net::HTTPSuccess then response when Net::HTTPRedirection then FetchHelper.head(response['location'], limit - 1) else response.error! end end def FetchHelper.get(url_str, limit = 10) raise ArgumentError, 'HTTP redirect too deep.' if limit == 0 response = Net::HTTP.get_response(URI.parse(url_str)) case response when Net::HTTPSuccess then response when Net::HTTPRedirection then FetchHelper.get(response['location'], limit - 1) else response.error! end end def FetchHelper.validate(url, what) begin uri = URI.parse(url) if uri.class != URI::HTTP raise ArgumentError, "Only HTTP protocol addresses can be used in the #{what} URL." end rescue URI::InvalidURIError raise ArgumentError, "The format of the #{what} URL is not valid." end end end # ------------------------------------- # HTML output # ------------------------------------- cgi = CGI.new url = cgi['hp'] # print our HTML header print "Content-type: text/html\r\n\r\n" print < Check your Pavatar!

Check your Pavatar!

Your homepage:

HTML types = { 'PNG' => 'image/png', 'GIF' => 'image/gif', 'JPEG' => 'image/jpeg' } unless cgi['hp'].length == 0 then begin FetchHelper.validate(url, 'homepage') pavatar_url = Pavatar.new(cgi['hp']) raise ArgumentError, "No pavatar here." if pavatar_url.get_url.nil? or pavatar_url.get_url == "none" FetchHelper.validate(pavatar_url.get_url, 'Pavatar') pavatar = FetchHelper.get(pavatar_url.get_url) raise ArgumentError, "File size too big (#{(pavatar.body.to_s.size * 8)}) max: 409600." if (pavatar.body.to_s.size * 8) > 409600 img = ImageSize.new(pavatar.body) raise ArgumentError, "Width is not 80px but #{img.get_width}px." unless img.get_width == 80 raise ArgumentError, "Height is not 80px but #{img.get_height}px." unless img.get_height == 80 raise ArgumentError, "False image type: #{img.get_type} #{pavatar_url.get_url}." unless types.has_key? img.get_type print pavatar_url.get_html('alt="My Pavatar"') rescue Exception => e print "Error:
#{e}\r\n" end end print <

HTML