.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SVG::Metadata 3"
.TH SVG::Metadata 3 "2005-08-22" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
SVG::Metadata \- Perl module to capture metadata info about an SVG file
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use SVG::Metadata;
.Ve
.PP
.Vb 1
\& my $svgmeta = new SVG::Metadata;
.Ve
.PP
.Vb 4
\& $svgmeta->parse($filename)
\&     or die "Could not parse $filename: " . $svgmeta->errormsg();
\& $svgmeta2->parse($filename2)
\&     or die "Could not parse $filename: " . $svgmeta->errormsg();
.Ve
.PP
.Vb 4
\& # Do the files have the same metadata (author, title, license)?
\& if (! $svgmeta->compare($svgmeta2) ) {
\&    print "$filename is different than $filename2\en";
\& }
.Ve
.PP
.Vb 3
\& if ($svgmeta->title() eq '') {
\&     $svgmeta->title('Unknown');
\& }
.Ve
.PP
.Vb 3
\& if ($svgmeta->author() eq '') {
\&     $svgmeta->author('Unknown');
\& }
.Ve
.PP
.Vb 3
\& if ($svgmeta->license() eq '') {
\&     $svgmeta->license('Unknown');
\& }
.Ve
.PP
.Vb 5
\& if (! $svgmeta->keywords()) {
\&     $svgmeta->addKeyword('unsorted');
\& } elsif ($svgmeta->hasKeyword('unsorted') && $svgmeta->keywords()>1) {
\&     $svgmeta->removeKeyword('unsorted');
\& }
.Ve
.PP
.Vb 1
\& print $svgmeta->to_text();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a way of extracting, browsing and using \s-1RDF\s0
metadata embedded in an \s-1SVG\s0 file.
.PP
The \s-1SVG\s0 spec itself does not provide any particular mechanisms for
handling metadata, but instead relies on embedded, namespaced \s-1RDF\s0
sections, as per \s-1XML\s0 philosophy.  Unfortunately, many \s-1SVG\s0 tools don't
support the concept of \s-1RDF\s0 metadata; indeed many don't support the idea
of embedded \s-1XML\s0 \*(L"islands\*(R" at all.  Some will even ignore and drop the
rdf data entirely when encountered.
.PP
The motivation for this module is twofold.  First, it provides a
mechanism for accessing this metadata from the \s-1SVG\s0 files.  Second, it
provides a means of validating \s-1SVG\s0 files to detect if they have the
metadata.
.PP
The motivation for this script is primarily for the Open Clip Art
Library (http://www.openclipart.org), as a way of filtering out
submissions that lack metadata from being included in the official
distributions.  A secondary motivation is to serve as a testing tool for
\&\s-1SVG\s0 editors like Inkscape (http://www.inkscape.org).
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.Sh "\fInew()\fP"
.IX Subsection "new()"
Creates a new SVG::Metadata object.  Optionally, can pass in arguments
\&'title', 'author', 'license', etc..
.PP
.Vb 2
\& my $svgmeta = new SVG::Metadata;
\& my $svgmeta = new SVG::Metadata(title=>'My title', author=>'Me', license=>'Public Domain');
.Ve
.Sh "\fIauthor()\fP"
.IX Subsection "author()"
Alias for \fIcreator()\fR
.Sh "\fIkeywords_to_rdf()\fP"
.IX Subsection "keywords_to_rdf()"
Generates an rdf:Bag based on the data structure of keywords.
This can then be used to populate the subject section of the metadata.
I.e.:
.PP
.Vb 1
\&    $svgobj->subject($svg->keywords_to_rdf());
.Ve
.PP
See:
  http://www.w3.org/TR/rdf\-schema/#ch_bag
  http://www.w3.org/TR/rdf\-syntax\-grammar/#section\-Syntax\-list\-element
  http://dublincore.org/documents/2002/05/15/dcq\-rdf\-xml/#sec2
.Sh "\fIerrormsg()\fP"
.IX Subsection "errormsg()"
Returns the last encountered error message.  Most of the error messages
are encountered during file parsing.
.PP
.Vb 1
\&    print $svgmeta->errormsg();
.Ve
.Sh "parse($filename)"
.IX Subsection "parse($filename)"
Extracts \s-1RDF\s0 metadata out of an existing \s-1SVG\s0 file.
.PP
.Vb 1
\&    $svgmeta->parse($filename) || die "Error: " . $svgmeta->errormsg();
.Ve
.PP
This routine looks for a field in the rdf:RDF section of the document
named 'ns:Work' and then attempts to load the following keys from it:
\&'dc:title', 'dc:rights'\->'ns:Agent', and 'ns:license'.  If any are
missing, it
.PP
The \f(CW$filename\fR parameter can be a filename, or a text string containing
the \s-1XML\s0 to parse, or an open 'IO::Handle', or a \s-1URL\s0.
.PP
Returns false if there was a problem parsing the file, and sets an
error message appropriately.  The conditions under which it will return
false are as follows:
.PP
.Vb 9
\&   * No 'filename' parameter given.
\&   * Filename does not exist.
\&   * Document is not parseable XML.
\&   * No rdf:RDF element was found in the document, and the try harder
\&     option was not set.
\&   * The rdf:RDF element did not have a ns:Work sub-element, and the
\&     try_harder option was not set.
\&   * Strict validation mode was turned on, and the document didn't
\&     strictly comply with one or more of its extra criteria.
.Ve
.Sh "\fItitle()\fP"
.IX Subsection "title()"
Gets or sets the title.
.PP
.Vb 2
\&    $svgmeta->title('My Title');
\&    print $svgmeta->title();
.Ve
.Sh "\fIdescription()\fP"
.IX Subsection "description()"
Gets or sets the description
.Sh "\fIsubject()\fP"
.IX Subsection "subject()"
Gets or sets the subject.  Note that the \fIparse()\fR routine pulls the
keywords out of the subject and places them in the keywords
collection, so \fIsubject()\fR will normally return undef.  If you assign to
\&\fIsubject()\fR it will override the internal \fIkeywords()\fR mechanism, but this
may later be discarded again in favor of the keywords, if \fIto_rdf()\fR is
called, either directly or indirectly via \fIto_svg()\fR.
.Sh "\fIpublisher()\fP"
.IX Subsection "publisher()"
Gets or sets the publisher name.  E.g., 'Open Clip Art Library'
.Sh "\fIpublisher_url()\fP"
.IX Subsection "publisher_url()"
Gets or sets the web \s-1URL\s0 for the publisher.  E.g., 'http://www.openclipart.org'
.Sh "\fIcreator()\fP"
.IX Subsection "creator()"
Gets or sets the creator.
.PP
.Vb 2
\&    $svgmeta->creator('Bris Geek');
\&    print $svgmeta->creator();
.Ve
.Sh "\fIcreator_url()\fP"
.IX Subsection "creator_url()"
Gets or sets the \s-1URL\s0 for the creator.
.Sh "\fIauthor()\fP"
.IX Subsection "author()"
Alias for \fIcreator()\fR \- does the same thing
.PP
.Vb 2
\&    $svgmeta->author('Bris Geek');
\&    print $svgmeta->author();
.Ve
.Sh "\fIowner()\fP"
.IX Subsection "owner()"
Gets or sets the owner.
.PP
.Vb 2
\&    $svgmeta->owner('Bris Geek');
\&    print $svgmeta->owner();
.Ve
.Sh "\fIowner_url()\fP"
.IX Subsection "owner_url()"
Gets or sets the owner \s-1URL\s0 for the item
.Sh "\fIlicense()\fP"
.IX Subsection "license()"
Gets or sets the license.
.PP
.Vb 2
\&    $svgmeta->license('Public Domain');
\&    print $svgmeta->license();
.Ve
.Sh "\fIlicense_date()\fP"
.IX Subsection "license_date()"
Gets or sets the date that the item was licensed
.Sh "\fIlanguage()\fP"
.IX Subsection "language()"
Gets or sets the language for the metadata.  This should be in the
two-letter lettercodes, such as 'en', etc.
.Sh "\fIretain_xml()\fP"
.IX Subsection "retain_xml()"
Gets or sets the \s-1XML\s0 retention option, which (if true) will cause any
subsequent call to \fIparse()\fR to retain the \s-1XML\s0.  You have to turn this
on if you want \fIto_svg()\fR to work later.
.Sh "\fIstrict_validation()\fP"
.IX Subsection "strict_validation()"
Gets or sets the strict validation option, which (if true) will cause
subsequent calls to \fIparse()\fR to be pickier about how things are
structured and possibly set an error and return undef when it
otherwise would succeed.
.Sh "\fItry_harder()\fP"
.IX Subsection "try_harder()"
Gets or sets the try harder option option, which causes subsequent
calls to \fIparse()\fR to try to return a valid Metadata object even if it
can't find any metadata at all.  The resulting object may contain
mostly empty fields.
.PP
Parse will still fail and return undef if the input file does not
exist or cannot be parsed as \s-1XML\s0, but otherwise it will attempt to
return an object.
.PP
If you set both this option and the strict validation option at the
same time, the Undefined Behavior Fairy will come and zap you with a
frap ray blaster and take away your cookie.
.Sh "\fIkeywords()\fP"
.IX Subsection "keywords()"
Gets or sets an array of keywords.  Keywords are a categorization
mechanism, and can be used, for example, to sort the files topically.
.ie n .Sh "addKeyword($kw1 [, $kw2 ...])"
.el .Sh "addKeyword($kw1 [, \f(CW$kw2\fP ...])"
.IX Subsection "addKeyword($kw1 [, $kw2 ...])"
Adds one or more a new keywords.  Note that the keywords are stored
internally as a set, so only one copy of a given keyword will be stored.
.PP
.Vb 2
\&    $svgmeta->addKeyword('Fruits and Vegetables');
\&    $svgmeta->addKeyword('Fruit','Vegetable','Animal','Mineral');
.Ve
.Sh "removeKeyword($kw)"
.IX Subsection "removeKeyword($kw)"
Removes a given keyword
.PP
.Vb 1
\&    $svgmeta->removeKeyword('Fruits and Vegetables');
.Ve
.PP
Return value:  The keyword removed.
.Sh "hasKeyword($kw)"
.IX Subsection "hasKeyword($kw)"
Returns true if the metadata includes the given keyword
.Sh "compare($meta2)"
.IX Subsection "compare($meta2)"
Compares this metadata to another metadata for equality.
.PP
Two \s-1SVG\s0 file metadata objects are considered equivalent if they
have exactly the same author, title, and license.  Keywords can
vary, as can the \s-1SVG\s0 file itself.
.Sh "\fIto_text()\fP"
.IX Subsection "to_text()"
Creates a plain text representation of the metadata, suitable for
debuggery, emails, etc.  Example output:
.PP
.Vb 4
\& Title:    SVG Road Signs
\& Author:   John Cliff
\& License:  http://web.resource.org/cc/PublicDomain
\& Keywords: unsorted
.Ve
.PP
Return value is a string containing the title, author, license, and
keywords, each value on a separate line.  The text always ends with
a newline character.
.Sh "esc_ents($text)"
.IX Subsection "esc_ents($text)"
Escapes '<', '>', and '&' and single and double quote
characters to avoid causing rdf to become invalid.
.Sh "\fIto_rdf()\fP"
.IX Subsection "to_rdf()"
Generates an \s-1RDF\s0 snippet to describe the item.  This includes the
author, title, license, etc.  The text always ends with a newline
character.
.Sh "\fIto_svg()\fP"
.IX Subsection "to_svg()"
Returns the \s-1SVG\s0 with the updated metadata embedded.  This can only be
done if \fIparse()\fR was called with the retain_xml option.  Note that the
code's layout can change a little, especially in terms of whitespace,
but the semantics \s-1SHOULD\s0 be the same, except for the updated metadata.
.SH "PREREQUISITES"
.IX Header "PREREQUISITES"
\&\f(CW\*(C`XML::Twig\*(C'\fR
.SH "AUTHOR"
.IX Header "AUTHOR"
Bryce Harrington <bryce@bryceharrington.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2004 Bryce Harrington.
All Rights Reserved.
.PP
This script is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
perl, XML::Twig