From 72414d039a9dc081f63d7627c58e1cf70e97c011 Mon Sep 17 00:00:00 2001 From: Florent Rougon Date: Sat, 30 Dec 2017 12:23:34 +0100 Subject: [PATCH] Docs/README.add-ons: update regarding /addon/authors and /addon/maintainers With FlightGear commit 4d36082, the contents of /addon/authors (resp. /addon/maintainers) in addon-metadata.xml files is now structured. It may contain an arbitrary number of 'author' (resp. 'maintainer') child nodes, each of which contains subnodes 'name', 'email' and 'url' ('name' being mandatory, 'email' and 'url' being optional). This commit updates Docs/README.add-ons regarding this change in the syntax for addon-metadata.xml files, as well as the related modifications to the add-on Nasal interface. --- Docs/README.add-ons | 78 +++++++++++++++++++++++++++++++++++++-------- 1 file changed, 65 insertions(+), 13 deletions(-) diff --git a/Docs/README.add-ons b/Docs/README.add-ons index 316f9cc9a..847a58130 100644 --- a/Docs/README.add-ons +++ b/Docs/README.add-ons @@ -117,12 +117,26 @@ add-on called “Flying Turtle” distributed by Joe User: Flying Turtle 1.0.0rc2 - - Joe user <optional_address@example.com> - Jane Maintainer <jane@example.com> + + + Joe User + optional_address@example.com + http://joe.example.com/foobar/ + + + + Jane Maintainer + jane@example.com + https://jane.example.com/ + - - Jane Maintainer <jane@example.com> + + + + Jane Maintainer + jane@example.com + https://jane.example.com/ + @@ -213,10 +227,26 @@ Authors and maintainers Nodes: /addon/authors and /addon/maintainers Authors are people who contributed significantly to the add-on. -Maintainers are people currently in charge of maintaining the add-on. -These fields are free-form, therefore contents such as “Joe User and -others” is allowed. However, please stick to the format used in the -above example if possible. +Maintainers are people currently in charge of maintaining it. + +It is possible to declare any number of authors and any number of +maintainers---the example above shows only one maintainer for shortness, +but this is not a restriction. + +For each author and maintainer, you can give a name, an email address +and a URL. The name must be non-empty, but the email address and URL +need not be specified or may be left empty, which is equivalent. +Obviously, if no email address nor URL is given for any maintainer, it +is highly desirable that /addon/urls/support contains a usable URL for +contacting the add-on maintainers. + +The data in children nodes of /addon/maintainers may refer either to +real persons or to more abstract entities such as mailing-lists. In case +of a real person, the corresponding URL, if specified, is expected to be +the person's home page. On the other hand, if a declared “maintainer” is +a mailing-list, a good use for the 'url' field is to indicate the +address of a web page from which people can subscribe to the +mailing-list. Short and long descriptions =========================== @@ -427,8 +457,15 @@ code easy access to add-on metadata, for instance like this: print(myAddon.id); print(myAddon.name); print(myAddon.version.str()); - print(myAddon.authors); - print(myAddon.maintainers); + + foreach (var author; myAddon.authors) { + print(author.name, author.email, author.url); + } + + foreach (var maintainer; myAddon.maintainers) { + print(maintainer.name, maintainer.email, maintainer.url); + } + print(myAddon.shortDescription); print(myAddon.longDescription); print(myAddon.licenseDesignation); @@ -481,8 +518,9 @@ Read-only data members (attributes) of addons.Addon objects: name the add-on “pretty name” (string) version the add-on version (instance of addons.AddonVersion, ghost) - authors the add-on authors (string) - maintainers the add-on maintainers (string) + authors the add-on authors (vector of addons.Author ghosts) + maintainers the add-on maintainers (vector of addons.Maintainer + ghosts) shortDescription the add-on short description (string) longDescription the add-on long description (string) licenseDesignation licensing terms: "GNU GPL version 2 or later", @@ -530,6 +568,20 @@ Member functions (methods) of addons.AddonVersion objects: greaterThan(addons.AddonVersion other) | greaterThanOrEqual(addons.AddonVersion other) | +Read-only data members (attributes) of addons.Author objects: + + name author name (non-empty string) + email email address of the author (string) + url home page of the author (string) + +Read-only data members (attributes) of addons.Maintainer objects: + + name maintainer name (non-empty string) + email email address of the maintainer (string) + url home page of the maintainer, if a person; if the + maintainer is a mailing-list, the URL can point + to a web page from which people can subscribe to + that mailing-list (string) Footnotes ---------