PonyMirrors/ponysay
1
0
Fork 0
mirror of https://github.com/erkin/ponysay.git synced 2024-11-22 04:27:58 +01:00
Code Issues Projects Releases Packages Wiki Activity

metadata specifications

Browse source
This commit is contained in:
Mattias Andrée 2012-10-31 02:20:42 +01:00
parent a5018169ed
commit b272e6d235
1 changed files with 295 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

301
manuals/ponysay.texinfo
View file

@ -69,6 +69,7 @@ Texts. A copy of the license is included in the section entitled
* Advanced usage:: Advanced usage of @command{ponysay}.
* Environment variables:: Getting more from @command{ponysay} with environment variables.
* Optional features:: Get the most out of @command{ponysay} with optional features.
* Pony metadata:: Metadata tags in the pony files.
* Limitations:: Known limitations that may not be that easy to overcome.
* Problems and requests:: Report issues and making requests.
* Dependencies:: Ponysay's dependencies.
@ -751,6 +752,294 @@ for cache space.
@node Pony metadata
@chapter Pony metadata
@cindex pony metadata
@cindex metadata
@cindex tags, metadata
@cindex comments, metadata
@cindex pony tags, metadata
@cindex pony comments, metadata
Pony files can contain metadata tags and a multiline comment.
The following are the standard tags (comma separated lists may
have whitespace surrounding the comma [@code{,}]):
@table @var
@item GROUP NAME
@vindex @var{GROUP NAME}
If a pony file contains multiple ponies, it @emph{should} have a @var{GROUP NAME}
tag. The tag is a comma seperated list of the recognised names of the ponies as a
groups, if the list is empty the tag value must be @code{(none)}. An officiallity
tag should be added to each name.
@item NAME
@vindex @var{NAME}
Every pony file should have this tag, one entry for each pony on the file.
The value of the tag @emph{must} be the pony's most common name as used on
the TV show (or other source). If the pony's name have not been mentioned
the value must be @code{(not mentioned)}.
@item OTHER NAMES
@vindex @var{OTHER NAMES}
If a pony in the pony file has other names then the one in @var{NAME} it @emph{should}
have this take for this pony. Any pony in the file (in case of multiple ponies) that
do not need this tag should use the value @code{(none)}.
The tag is a comma seperated list of alternative (to @var{NAME} names for the pony,
each name should have an officiallity tag.
@item APPEARANCE
@vindex @var{APPEARANCE}
This tag specifies in which episode the pony first appeared. It reasonable to specify
it even for ponies that appears in every episode.
For uniformity the format @code{S%sE%e %t[ %P]} is recommended; @code{[ ]} denotes
and optional part, optional in the sence that it does not apply the every episode,
but it @emph{should} be used if applyable. @code{%s} is the series (season) number
in two digits, @code{%e} is the episode number in two digits. @code{%t} is the
episode title and should use the standardised title format for the used format
however without surrounding quotes if the used language has that, in the unlike
event that @code{[} or @code{]} is present in the title it should be backslashed
(@code{\[}, @code{\]}). @code{%P} is the part in the format @code{[Part %p]}, where
@code{[ ]} @i{does not} denote and optional part but rather is verbatim, and
@code{%p} is the part number in one digit (well, if the part number is not 10 or higher).
The standard way to format titles in American English is the same as in British English,
however it is not fully standardised. Capitalisation of the first word, and all other words,
except for articles, prepositions, conjunctions, and forms of `to be' is recommended.
Be aware that MLP:FiM episodes use American spelling which include a rather uncommon
why to write for examples abbrevations (like for example Mr. instread of Mr), this may
however not be the case for non-MLP:FiM episodes. And if there are not series (season)
the series number defaults to 1, however other numbers and tags (which the part number
is) may be added if required.
@item KIND
@vindex @var{KIND}
This tag decribes what kind of pony a pony is, it is a comma seperated lower case list,
and it cannot be empty, by it can be (but shouldn't) skipped for every pony in the image.
Every fitting value should be used, however a alicorn (also known as alacord or winged
unicorn) should have the values @code{pegasus}, @code{unicorn}, @code{pony}, but not
@code{alicorn}. Earth ponies should have the value @code{pony} but not @code{earth} or
@code{earth pony}.
The standard values are (you may use other ones if fitting): @code{unicorn}, @code{pegasus},
@code{pony}, @code{changeling}, @code{crystal}, @code{seapony}, @code{animal}
(applies to Spike) and @code{item} (applies to Tom and Pinkamina's imaginare friends).
@item GROUP
@vindex @var{GROUP}
This tag decribes which groups a pony classifies under, it is a comma seperated lower case
list, and it cannot be empty, by it can be (but shouldn't) skipped for every pony in the
image.
The standard values are (you may use other ones if fitting):
@itemize @bullet
@item @code{mare}
Adult female pony
@item @code{stallion}
Adult male pony
@item @code{filly}
Female pony child
@item @code{colt}
Male pony child
@item @code{dragon}
Dragon (Spike and the other dragons)
@item @code{mane}
The mane characters (also known as main characters [unponified] or protagonists)
@item @code{wildlife}
Wildlife, for example timberwolfs
@item @code{pet}
A ponies' pet, Spike does not count because Twilight does not play with him during
pony–pet play dates.
@item @code{villain}
Villains, normally minons to antagonists. Applies to changelings.
@item @code{antagonist} (applies to: nightmare moon, gilda, discord, chrysalis)
Antagonists are also known as archvillians or archenemies.
Nightmare Moon, Discord and Chrysalis are such, but Gilda also counts as one.
@item @code{deuteragonist} (applies to: the cutiemark cruisers)
Deuteragonists are secondary characters, these are (as of series 2) only the Cutiemark
Cruisers. The requirement is that thay are somewhat regular characters with dedicated
episodes, but are not protagonists.
@item @code{tritagonist} (applies to: celestia, luna, cadance, shining armor, spike)
Important characters (excluding Derpy Hooves) that are neither protagonists,
deuteragonists nor antagonists.
@item @code{background}
Background characters are not characters that are neither protagonists, deuteragonist,
tritagonist, antagonist nor pets. They do not need to be strictly background characters,
for example Big Mac and Cheerilee classifies under this group, as they are not too
important to be considered tritagonists (as of series 2).
@item @code{voiced} (only used together with background)
Only @code{background} characters can be @code{voiced}. The additional requirement is
that they have said something (ponies comics can also be voiced).
@item @code{imaginary}
Imaginary ponies (or other animal).
@end itemize
@item BALLOON
@vindex @var{BALLOON}
For each balloon in the file (a pony file can have more than one balloon, but
that is not common) their should one tag entry. There are four values that
can be used: top (the common setup, the balloon is at the top of the image),
bottom (the balloon is at the bottom of the image), right (the balloon is neither
at the top or at the bottom of the image, but is placed to the right of the pony)
and inside (the balloon is somewhere as inside the image.)
@item LINK ON
@vindex @var{LINK ON}
Files with only one pony @emph{should not} use this tag. Specifies to which pony
the link is connected, it is a number, starting from 1.
If a file contains Fluttershy and Pinkie (in that order, i.e. Pinkie is to the
right of or below Fluttershy) and the link is connected to Pinkie, than the value
should be 2.
In the rare case that the file contains multiple links (and multi ponies), the
metadata should contains multiple entries of this tag, one entry for each link
sorted in the order of the linkes placement in the image, in the same way
ponies are ordered.
@item LINK
@vindex @var{LINK}
In the rare case that the file contains multiple links the metadata should contains
multiple entries of this tag, one entry for each link sorted in the order of the
linkes placement in the image, in the same way ponies are ordered.
The value for this tag must be either @code{regular} or @code{mirrored}. @code{regular}
applies to linkes with NNE–SSW (@code{\}) direction. @code{mirrored} applies to linkes
with NNW–SSE (@code{/}) direction, in version 2.9.1 only @file{rainbowdrag} uses this.
@item COAT
@vindex @var{COAT}
The name of the colour (as best estimated by you), in lowercase, that the pony's coat
have. If the creature is (for example) a dragon, the colour of the scales is used.
Common colour names are preferable. Only one colour should be named, but the name may
describe a colour combination.
@item MANE
@vindex @var{MANE}
The name of the colour (as best estimated by you), in lowercase, that the pony's mane
have. Common colour names are preferable. Only one colour should be named, but the name
may describe a colour combination.
@item EYE
@vindex @var{EYE}
The name of the colour (as best estimated by you), in lowercase, that the pony's eyes
have. Common colour names are preferable. Only one colour should be named, but the name
may describe a colour combination.
@item AURA
@vindex @var{AURA}
The name of the colour (as best estimated by you), in lowercase, that the pony's magic
aura have. Common colour names are preferable. Only one colour should be named, but the
name may describe a colour combination.
The magic aura is the colourisation around items that are affected by magic.
If the pony file have multiple ponies, some with magicial abilities and some without,
the ponies without magicial abilies should use the value @code{(no magic)}. If the pony
has magicial abilies but without an aura, use the value @code{(invisible)}.
Only humans [here we must call ourself humnas rather than ponies, otherwise the sentance
does not make sense) can se the magic aura, describe the colour that we humans see, not
ponies and other creatures in the TV Show [proof, see S01E11 Winter Wrap Up and S02E25-26
A Canterlot Wedding].
@item DISPLAY
@vindex @var{DISPLAY}
This tag describes how a pony is places in the image. The standard values are: @code{full}
(full body), @code{head} (just the head), @code{down} (upside down), @code{left} (pony is
looking to our left), @code{right} (pony is looking to our right), @code{front} (pony is
looking at us). @code{front} can be combined with @code{left} and @code{right}, but
@code{left} and @code{right} nor @code{full} and @code{head} cannot be combined.
@item WIDTH
@vindex @var{WIDTH}
The width of the pony image measured in text columns.
@item HEIGHT
@vindex @var{HEIGHT}
The height of the pony image measured in text lines, this include the balloon
(occupies one line) even if it the first line with nothing else on that line.
@item BALLOON TOP
@vindex @var{BALLOON TOP}
The number of lines at the beginning of the pony image that should be skipped
if the balloon is not printed.
@item BALLOON BOTTOM
@vindex @var{BALLOON BOTTOM}
The number of lines at the end of the pony image that should be skipped if the
balloon is not printed.
@item MASTER
@vindex @var{MASTER}
This tag refers to the pony file that is not named with extra attributes. For example,
all files where Shining Armour is the (sole) speaking pony the this tag should be
@code{shiningarmor}, except for in @file{shiningarmor.pony} where this tag may be omitted.
@item SOURCE
@vindex @var{SOURCE}
This tag specifies from where the pony image (not the file itself) originates.
If the source is unknown the value should be @code{(unknown)}, if a GitHub user
draw it the the value should be that user inside square brackets (in case of
multiple artists, the tag is comma seperated list). Otherwise the source
should be specified in any reasonable manner.
In order the claim authorship (the GitHub user value) it image must have been
written from scratch (using templates is okay) or must be a major edit of another
image. Just converting (including fixing the colours) an image (for example from
the Internet or a screenshot) with or without removing the background is not enough.
@item MEDIA
@vindex @var{MEDIA}
This tag @emph{must not} be used for MLP:FiM ponies, but only for extraponies.
It specifies the media from where the pony (not the image) originates.
@item LICENSE
@vindex @var{LICENSE}
Which licence applies to the image? Full name and version should be used.
In case of multiple license there should be one entry for each license.
Omit this tag is the license is not known.
The are two special cases here where this is no license. In which case it
either uses regular copyright, in which case use the value @code{(regular)},
or everyone is the copyright holder (for example Public Domain), in which
case use the value @code{(public)}.
@item FREE
@vindex @var{FREE}
Is the image fully free? (For example Linux-libre is fully free, but not regular Linux.)
The value @emph{must} either be @code{yes} or @code{no}, or the tag must be omitted.
@b{This is the most important tag} is it helps us build a fully free version that can
be officially distributed on GNU endorsed GNU/Linux distributions (GNU/Linux-libre).
@end table
Duplicate tags should be ordered in the order of the pony they describe from top-left
to bottom-right in the image. It is important that if there are for example three ponies
the image then all used tags that depends on the number of ponies in the image is used
three times.
@cindex officiallity tag
`Officiallity tag' refers the an annotation added to a tag value's list element.
If the value is unofficial the string @code{(unofficial)} is appended (preferable with
leading whitespace) to the element. If it is official the appended string is of the
format @code{(unofficial, %c)} (the brackets are verbatim), where @code{%c} is a
comment. For example Chrysalis' name has not been mentioned in the show, however it
is used in the manuscript, therefore a pony file with Chrysalis should have the
(partial) metadata:
@example
NAME: (not mentioned)
OTHER NAMES: Chrysalis (official, in manuscript)
@end example
@node Limitations
@chapter Limitations
@cindex limitations
@ -1509,7 +1798,7 @@ To perform an uninstallation of old files run @command{make uninstall-old}.
@menu
* Pony anatomy:: Anatomy of pony files.
* Pony metadata:: Metadata in pony files.
* Pony metadata extension:: Metadata in pony files.
* Pony quote infrastructure:: Pony quote infrastructure.
* Balloon style files:: Balloon style files.
* Printing in TTY with KMS:: Printing in TTY with KMS support.
@ -1554,8 +1843,8 @@ the balloon) itself was printed by @command{cowsay} and is not defined in the co
files.
@node Pony metadata
@section Pony metadata
@node Pony metadata extension
@section Pony metadata extension
@cindex pony metadata
@cindex metadata
@cindex tags, metadata
@ -1576,9 +1865,9 @@ end in the same way direct follow by the pony image starting from the next line.
A metadata tag consists of a tag name in upper case and a tag value, with a colon
(@code{:}), optionally with regular spaces or tab spaces. Multiple tag names can
be used multiple times or can be completely skipped. There are only a few tags,
namely @var{BALLOON TOP}, @var{BALLOON BOTTOM}, @var{FREE}, that absolutely should
not be used muliple tag; a general rule is that a tag desribing a pony should be
duplicated exact as many times as there are ponies in the image.
namely @var{BALLOON TOP}, @var{BALLOON BOTTOM}, @var{MASTER}, @var{FREE}, that
absolutely should not be used muliple tag; a general rule is that a tag desribing
a pony should be duplicated exact as many times as there are ponies in the image.
Any line that does not conform to the format of a tag line is a part of the comment
field. Leading line breaks in the comment field is ignored.