.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .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. \*(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- .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" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" 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 "EBook::Tools 3pm" .TH EBook::Tools 3pm "2019-08-08" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" EBook::Tools \- Object class for manipulating and generating E\-books .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides an object interface and a number of related procedures intended to create or modify documents centered around the International Digital Publishing Forum (\s-1IDPF\s0) standards, currently both \s-1OEBPS\s0 v1.2 and \s-1OPS/OPF\s0 v2.0. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use EBook::Tools qw(split_metadata system_tidy_xml); \& $EBook::Tools::tidysafety = 2; \& \& my $opffile = split_metadata(\*(Aqebook.html\*(Aq); \& my $otheropffile = \*(Aqalternate.opf\*(Aq; \& my $retval = system_tidy_xml($opffile,\*(Aqtidy\-backup.xml\*(Aq); \& my $ebook = EBook::Tools\->new($opffile); \& $ebook\->fix_opf20; \& $ebook\->fix_misc; \& $ebook\->print; \& $ebook\->save; \& \& $ebook\->init($otheropffile); \& $ebook\->fix_oeb12; \& $ebook\->gen_epub; .Ve .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" .SS "Perl Modules" .IX Subsection "Perl Modules" .IP "Archive::Zip" 4 .IX Item "Archive::Zip" .PD 0 .IP "Data::UUID (or \s-1OSSP::UUID\s0)" 4 .IX Item "Data::UUID (or OSSP::UUID)" .IP "Date::Manip" 4 .IX Item "Date::Manip" .PD Note that Date::Manip will die on \s-1MS\s0 Windows system unless the \&\s-1TZ\s0 environment variable is set in a specific manner. See: .Sp http://search.cpan.org/perldoc?Date::Manip#TIME_ZONES .IP "File::MimeInfo" 4 .IX Item "File::MimeInfo" .PD 0 .IP "HTML::Parser" 4 .IX Item "HTML::Parser" .IP "Lingua::EN::NameParse" 4 .IX Item "Lingua::EN::NameParse" .IP "Tie::IxHash" 4 .IX Item "Tie::IxHash" .IP "Time::Local" 4 .IX Item "Time::Local" .IP "URI::Escape" 4 .IX Item "URI::Escape" .IP "XML::Twig" 4 .IX Item "XML::Twig" .PD .SS "Other Programs" .IX Subsection "Other Programs" .IP "Tidy" 4 .IX Item "Tidy" The command \*(L"tidy\*(R" needs to be available, and ideally on the path. If it isn't on the path, package variable \*(L"$tidycmd\*(R" can be set to its absolute path. If tidy cannot be found, \*(L"\fBsystem_tidy_xml()\fR\*(R" and \&\*(L"\fBsystem_tidy_xhtml()\fR\*(R" will be nonfunctional. .SH "CONFIGURABLE PACKAGE VARIABLES" .IX Header "CONFIGURABLE PACKAGE VARIABLES" .ie n .IP "%bisacsubjects" 4 .el .IP "\f(CW%bisacsubjects\fR" 4 .IX Item "%bisacsubjects" A mapping of lowercase \s-1BISAC\s0 codes and text descriptions to standard capitalized text descriptions. As \s-1BISG\s0 claims copyright on this and does not allow the lists to be redistributed, this list must be downloaded and cached locally via \f(CW\*(C`ebook dlbisac\*(C'\fR before it is available. .Sp Running the unit tests will cause this to happen automatically. .ie n .IP "%bisactolc" 4 .el .IP "\f(CW%bisactolc\fR" 4 .IX Item "%bisactolc" An extremely incomplete mapping of lowercase \s-1BISAC\s0 codes and text descriptions to Library of Congress standard subjects. .ie n .IP "%booktypes" 4 .el .IP "\f(CW%booktypes\fR" 4 .IX Item "%booktypes" A hash mapping all-lowercase terms to a standard vocabulary to be used in elements. .ie n .IP "%dcelements12" 4 .el .IP "\f(CW%dcelements12\fR" 4 .IX Item "%dcelements12" A tied IxHash mapping an all-lowercase list of Dublin Core metadata element names to the capitalization dictated by the \s-1OEB 1.2\s0 specification, used by the \fBfix_oeb12()\fR and \fBfix_oeb12_dcmeta()\fR methods. Changing the tags in this list will change the tags recognized and placed inside the element. .Sp Order is preserved and significant \*(-- fix_oeb12 will output \s-1DC\s0 metadata elements in the same order as in this hash, though order for tags of the same name is preserved from the input file. .ie n .IP "%dcelements20" 4 .el .IP "\f(CW%dcelements20\fR" 4 .IX Item "%dcelements20" A tied IxHash mapping an all-lowercase list of Dublin Core metadata element names to the all-lowercase form dictated by the \s-1OPF 2.0\s0 specification (which means it maps the all-lowercase tags to themselves). It is used by the \fBfix_opf20()\fR and \fBfix_opf20_dcmeta()\fR methods. Changing the tags in this list will change the tags recognized and placed directly under the element. .Sp Order is preserved and significant \*(-- fix_opf20 will output \s-1DC\s0 metadata elements in the same order as in this hash, though order for tags of the same name is preserved from the input file. .ie n .IP "%lcsubjects" 4 .el .IP "\f(CW%lcsubjects\fR" 4 .IX Item "%lcsubjects" An extremely incomplete mapping of lowercase terms to Library of Congress subject classifications. This is used for automatic normalization of subject elements. Every value in the hash has a lowercase representation of itself as a key in addition to any aliases. .Sp This \s-1MUST NOT\s0 contain mappings from \s-1BISAC\s0 codes or descriptors to Library of Congress subjects. Use \f(CW%bisactolc\fR for that. .ie n .IP "%nonxmlentity2char" 4 .el .IP "\f(CW%nonxmlentity2char\fR" 4 .IX Item "%nonxmlentity2char" This is the \f(CW%entity2char\fR conversion map from HTML::Entities with the 5 pre-defined \s-1XML\s0 entities (amp, gt, lt, quot, apos) removed. This is used during by \*(L"\fBinit()\fR\*(R" to sanitize the \s-1OPF\s0 file data before parsing. This hash can be modified to allow and convert other non-standard entities to unicode characters. See HTML::Entities for details. .ie n .IP "%publishermap" 4 .el .IP "\f(CW%publishermap\fR" 4 .IX Item "%publishermap" A hash mapping known variants of publisher names to a canonical form, used by \*(L"\fBfix_publisher()\fR\*(R", and thus also indirectly by \&\*(L"\fBfix_misc()\fR\*(R". .Sp Keys should be entered in lowercase. The hash can also be set empty to prevent \fBfix_publisher()\fR from taking any action at all. .ie n .IP "%referencetypes" 4 .el .IP "\f(CW%referencetypes\fR" 4 .IX Item "%referencetypes" A hash mapping valid \s-1OPF 2.0\s0 reference types to themselves, along with common variants to standard types. .ie n .IP "%relatorcodes" 4 .el .IP "\f(CW%relatorcodes\fR" 4 .IX Item "%relatorcodes" A hash mapping the \s-1MARC\s0 Relator Codes (see: http://www.loc.gov/marc/relators/relacode.html) to their descriptive names. .ie n .IP "%sexcodes" 4 .el .IP "\f(CW%sexcodes\fR" 4 .IX Item "%sexcodes" A hash normalizing subject tags for erotic fiction, as used by StoriesOnline, \s-1ASSTR,\s0 and Literotica, among others. .Sp Unlike the other mappings, this one is *not* lowercased, and the keys are case-sensitive. The hash maps only to the canonical base code, but subject normalization will also add a prefix, defaulting to the \&\s-1BISAC\s0 format of '\s-1FICTION /\s0 Erotica / '. .ie n .IP "%strangenames" 4 .el .IP "\f(CW%strangenames\fR" 4 .IX Item "%strangenames" .PD 0 .ie n .IP "%strangefileas" 4 .el .IP "\f(CW%strangefileas\fR" 4 .IX Item "%strangefileas" .PD Hashes mapping mapping known incorrect outputs of name normalization to correct format. The first handles the main name display, the second the file-as output. .ie n .IP "$tidycmd" 4 .el .IP "\f(CW$tidycmd\fR" 4 .IX Item "$tidycmd" The tidy executable name. This has to be a fully qualified pathname if tidy isn't on the path. Defaults to 'tidy'. .ie n .IP "$tidyxhtmlerrors" 4 .el .IP "\f(CW$tidyxhtmlerrors\fR" 4 .IX Item "$tidyxhtmlerrors" The name of the error output file from \fBsystem_tidy_xhtml()\fR. Defaults to 'tidyxhtml\-errors.txt' .ie n .IP "$tidyxmlerrors" 4 .el .IP "\f(CW$tidyxmlerrors\fR" 4 .IX Item "$tidyxmlerrors" The name of the error output file from \fBsystem_tidy_xml()\fR. Defaults to \&'tidyxml\-errors.txt' .ie n .IP "$tidysafety" 4 .el .IP "\f(CW$tidysafety\fR" 4 .IX Item "$tidysafety" The safety level to use when running tidy (default is 1). Potential values are: .RS 4 .ie n .IP """$tidysafety < 1"":" 4 .el .IP "\f(CW$tidysafety < 1\fR:" 4 .IX Item "$tidysafety < 1:" No checks performed, no error files kept, works like a clean tidy \-m .Sp This setting is \s-1DANGEROUS\s0! .ie n .IP """$tidysafety == 1"":" 4 .el .IP "\f(CW$tidysafety == 1\fR:" 4 .IX Item "$tidysafety == 1:" Overwrites original file if there were no errors, but even if there were warnings. Keeps a log of errors, but not warnings. .ie n .IP """$tidysafety == 2"":" 4 .el .IP "\f(CW$tidysafety == 2\fR:" 4 .IX Item "$tidysafety == 2:" Overwrites original file if there were no errors, but even if there were warnings. Keeps a log of both errors and warnings. .ie n .IP """$tidysafety == 3"":" 4 .el .IP "\f(CW$tidysafety == 3\fR:" 4 .IX Item "$tidysafety == 3:" Overwrites original file only if there were no errors or warnings. Keeps a log of both errors and warnings. .ie n .IP "$tidysafety = 4>:" 4 .el .IP "\f(CW$tidysafety \fR= 4>:" 4 .IX Item "$tidysafety = 4>:" Never overwrites original file. Keeps a log of both errors and warnings. .RE .RS 4 .RE .ie n .IP "%validspecs" 4 .el .IP "\f(CW%validspecs\fR" 4 .IX Item "%validspecs" A hash mapping valid specification strings to themselves, primarily used to undefine unrecognized values. Default valid values are '\s-1OEB12\s0' and '\s-1OPF20\s0'. .SH "CONSTRUCTORS AND INITIALIZATION" .IX Header "CONSTRUCTORS AND INITIALIZATION" .ie n .SS """new($filename)""" .el .SS "\f(CWnew($filename)\fP" .IX Subsection "new($filename)" Instantiates a new EBook::Tools object. If \f(CW$filename\fR is specified, it will also immediately initialize itself via the \f(CW\*(C`init\*(C'\fR method. .ie n .SS """init($filename)""" .el .SS "\f(CWinit($filename)\fP" .IX Subsection "init($filename)" Initializes the object from an existing \s-1OPF\s0 file. If \f(CW$filename\fR is specified and exists, the \s-1OEB\s0 object will be set to read and write to that file before attempting to initialize. Otherwise, if the object currently points to an \s-1OPF\s0 file it will use that name. If there is no \&\s-1OPF\s0 filename data, and \f(CW$filename\fR was not specified, it will make a last-ditch attempt to find an \s-1OPF\s0 file first by looking in META\-INF/container.xml, and if nothing is found there, by looking in the current directory for a single \s-1OPF\s0 file. .PP If no such files or found (or more than one is found), the initialization croaks. .ie n .SS """init_blank(%args)""" .el .SS "\f(CWinit_blank(%args)\fP" .IX Subsection "init_blank(%args)" Initializes an object containing nothing more than the basic \s-1OPF\s0 framework, suitable for adding new documents when creating an e\-book from scratch. .PP \fIArguments\fR .IX Subsection "Arguments" .PP \&\f(CW\*(C`init_blank\*(C'\fR takes up to three optional named arguments: .ie n .IP """opffile""" 4 .el .IP "\f(CWopffile\fR" 4 .IX Item "opffile" This specifies the \s-1OPF\s0 filename to use. If not specified, defaults to \&'content.opf' .ie n .IP """author""" 4 .el .IP "\f(CWauthor\fR" 4 .IX Item "author" This specifies the content of the initial dc:creator element. If not specified, defaults to \*(L"Unknown Author\*(R". .ie n .IP """title""" 4 .el .IP "\f(CWtitle\fR" 4 .IX Item "title" This specifies the content of the initial dc:title element. If not specified, defaults to \*(L"Unknown Title\*(R". .PP \fIExample\fR .IX Subsection "Example" .PP .Vb 2 \& init_blank(\*(Aqopffile\*(Aq => \*(Aqnewfile.opf\*(Aq, \& \*(Aqtitle\*(Aq => \*(AqThe Great Unknown\*(Aq); .Ve .SH "ACCESSOR METHODS" .IX Header "ACCESSOR METHODS" The following methods return data deeper in the structure than the auto-accessors, but still do not modify any object data or files. .ie n .SS """adult()""" .el .SS "\f(CWadult()\fP" .IX Subsection "adult()" Returns the text of the Mobipocket-specific element, if it exists. Expected values are 'yes' and undef. .ie n .SS """contributor_list()""" .el .SS "\f(CWcontributor_list()\fP" .IX Subsection "contributor_list()" Returns a list containing the text of all dc:contributor elements (case-insensitive) or undef if none are found. .PP In scalar context, returns the first contributor, not the last. .ie n .SS """coverimage()""" .el .SS "\f(CWcoverimage()\fP" .IX Subsection "coverimage()" Returns the href to the cover image, or undef if none is found. .PP Checks the following in order: .ie n .IP "" 4 .el .IP "" 4 .IX Item "" .PD 0 .IP "" 4 .IX Item "" .ie n .IP " (as href)" 4 .el .IP " (as href)" 4 .IX Item " (as href)" .ie n .IP " (as item id)" 4 .el .IP " (as item id)" 4 .IX Item " (as item id)" .PD .ie n .SS """date_list(%args)""" .el .SS "\f(CWdate_list(%args)\fP" .IX Subsection "date_list(%args)" Returns the text of all dc:date elements (case-insensitive) matching the specified attributes. .PP In scalar context, returns the first match, not the last. .PP Returns undef if no matches are found. .PP \fIArguments\fR .IX Subsection "Arguments" .IP "\(bu" 4 \&\f(CW\*(C`id\*(C'\fR \- 'id' attribute that must be matched exactly for the result to be added to the list .IP "\(bu" 4 \&\f(CW\*(C`event\*(C'\fR 'opf:event' or 'event' attribute that must be matched exactly for the result to be added to the list .PP If both arguments are specified a value is added to the list if it matches either one (i.e. the logic is \s-1OR\s0). .ie n .SS """description()""" .el .SS "\f(CWdescription()\fP" .IX Subsection "description()" Returns the description of the e\-book, if set, or undef otherwise. .ie n .SS """element_list(%args)""" .el .SS "\f(CWelement_list(%args)\fP" .IX Subsection "element_list(%args)" Returns a list containing the text values of all elements matching the specified criteria. .PP \fIArguments\fR .IX Subsection "Arguments" .IP "\(bu" 4 \&\f(CW\*(C`cond\*(C'\fR .Sp The XML::Twig search condition used to find the elements. Typically this is just the \s-1GI\s0 (tag) of the element you wish to find, but it can also be a \f(CW\*(C`qr//\*(C'\fR expression, coderef, or anything else that XML::Twig can work with. See the XML::Twig documentation for details. .Sp If this is not specified, an error is added and the method returns undef. .IP "\(bu" 4 \&\f(CW\*(C`id\*(C'\fR (optional) .Sp \&'id' attribute that must be matched exactly for the result to be added to the list .IP "\(bu" 4 \&\f(CW\*(C`scheme\*(C'\fR (optional) .Sp \&'opf:scheme' or 'scheme' attribute that must be matched exactly for the result to be added to the list .IP "\(bu" 4 \&\f(CW\*(C`event\*(C'\fR (optional) .Sp \&'opf:event' or 'event' attribute that must be matched exactly for the result to be added to the list .PP If more than one of the arguments \f(CW\*(C`id\*(C'\fR, \f(CW\*(C`scheme\*(C'\fR, or \f(CW\*(C`event\*(C'\fR are specified a value is added to the list if it matches any one (i.e. the logic is \s-1OR\s0). .ie n .SS """errors()""" .el .SS "\f(CWerrors()\fP" .IX Subsection "errors()" Returns an arrayref containing any generated error messages. .ie n .SS """identifier()""" .el .SS "\f(CWidentifier()\fP" .IX Subsection "identifier()" Returns the text of the dc:identifier element pointed to by the \&'unique\-identifier' attribute of the root 'package' element, or undef if it could not be located. .ie n .SS """isbn_list(%args)""" .el .SS "\f(CWisbn_list(%args)\fP" .IX Subsection "isbn_list(%args)" Returns a list of all ISBNs matching the specified attributes. See \&\*(L"\fBtwigelt_is_isbn()\fR\*(R" for a detailed description of how the \s-1ISBN\s0 elements are found. .PP Returns undef if no matches are found. .PP In scalar context returns the first match, not the last. .PP See also \*(L"isbns(%args)\*(R". .PP \fIArguments\fR .IX Subsection "Arguments" .IP "\(bu" 4 \&\f(CW\*(C`id\*(C'\fR (optional) .Sp \&'id' attribute that must be matched exactly for the result to be added to the list .IP "\(bu" 4 \&\f(CW\*(C`scheme\*(C'\fR (optional) .Sp \&'opf:scheme' or 'scheme' attribute that must be matched exactly for the result to be added to the list .PP If both arguments are specified a value is added to the list if it matches either one (i.e. the logic is \s-1OR\s0). .ie n .SS """isbns(%args)""" .el .SS "\f(CWisbns(%args)\fP" .IX Subsection "isbns(%args)" Returns all of the \s-1ISBN\s0 identifiers matching the specificied attributes as a list of hashrefs, with one hash per \s-1ISBN\s0 identifier presented in the order that the identifiers are found. The hash keys are 'id' (containing the value of the 'id' attribute), 'scheme' (containing the value of either the 'opf:scheme' or 'scheme' attribute, whichever is found first), and 'isbn' (containing the text of the element). .PP If no entries are found, returns undef. .PP In scalar context returns the first match, not the last. .PP See also \*(L"isbn_list(%args)\*(R". .PP \fIArguments\fR .IX Subsection "Arguments" .PP \&\f(CW\*(C`isbns()\*(C'\fR takes two optional named arguments: .IP "\(bu" 4 \&\f(CW\*(C`id\*(C'\fR \- 'id' attribute that must be matched exactly for the result to be added to the list .IP "\(bu" 4 \&\f(CW\*(C`scheme\*(C'\fR \- 'opf:scheme' or 'scheme' attribute that must be matched exactly for the result to be added to the list .PP If both arguments are specified a value is added to the list if it matches either one (i.e. the logic is \s-1OR\s0). .ie n .SS """languages()""" .el .SS "\f(CWlanguages()\fP" .IX Subsection "languages()" Returns a list containing the text of all dc:language (case-insensitive) entries, or undef if none are found. .PP In scalar context returns the first match, not the last. .ie n .SS """manifest(%args)""" .el .SS "\f(CWmanifest(%args)\fP" .IX Subsection "manifest(%args)" Returns all of the items in the manifest as a list of hashrefs, with one hash per manifest item in the order that they appear, where the hash keys are 'id', 'href', and 'media\-type', each returning the appropriate attribute, if any. .PP In scalar context, returns the first match, not the last. .PP \fIArguments\fR .IX Subsection "Arguments" .PP \&\f(CW\*(C`manifest()\*(C'\fR takes four optional named arguments: .IP "\(bu" 4 \&\f(CW\*(C`id\*(C'\fR \- 'id' attribute to match .IP "\(bu" 4 \&\f(CW\*(C`href\*(C'\fR \- 'href' attribute to match .IP "\(bu" 4 \&\f(CW\*(C`mtype\*(C'\fR \- 'media\-type' attribute to match .IP "\(bu" 4 \&\f(CW\*(C`logic\*(C'\fR \- logic to use (valid values are 'and' or 'or', default: 'and') .PP If any of the named arguments are specified, \f(CW\*(C`manifest()\*(C'\fR will return only items matching the specified criteria. This is an exact case-sensitive match, but it can (especially in the case of mtype) still return multiple elements. .PP \fIReturn values\fR .IX Subsection "Return values" .PP Returns undef if there is no element directly underneath , or if contains no items. .PP \fISee also\fR .IX Subsection "See also" .PP \&\*(L"\fBmanifest_hrefs()\fR\*(R", \*(L"\fBspine()\fR\*(R" .PP \fIExample\fR .IX Subsection "Example" .PP .Vb 3 \& @manifest = $ebook\->manifest(id => \*(Aqncx\*(Aq, \& mtype => \*(Aqtext/xml\*(Aq, \& logic => \*(Aqor\*(Aq); .Ve .ie n .SS """manifest_hrefs()""" .el .SS "\f(CWmanifest_hrefs()\fP" .IX Subsection "manifest_hrefs()" Returns a list of all of the hrefs in the current \s-1OPF\s0 manifest, or the empty list if none are found. .PP In scalar context returns the first href, not the last. .PP See also: \f(CW\*(C`manifest()\*(C'\fR, \f(CW\*(C`spine_idrefs()\*(C'\fR .ie n .SS """opf_namespace()""" .el .SS "\f(CWopf_namespace()\fP" .IX Subsection "opf_namespace()" Some \s-1OPF\s0 generators explicity assign 'opf:' in the gi as a prefix on \&\s-1OPF\s0 elements. This makes later parsing more complex and is unnecessary, so this is stripped before any parsing takes place. .ie n .SS """opfdir()""" .el .SS "\f(CWopfdir()\fP" .IX Subsection "opfdir()" Returns the full filesystem path to the directory where the \s-1OPF\s0 metadata file will be stored, or undef if either the top-level directory or the \s-1OPF\s0 subdirectory is not found. .ie n .SS """opffile()""" .el .SS "\f(CWopffile()\fP" .IX Subsection "opffile()" Returns the name of the file where the \s-1OPF\s0 metadata will be stored or undef if no value is found.. .ie n .SS """opfpath()""" .el .SS "\f(CWopfpath()\fP" .IX Subsection "opfpath()" Returns the full filesystem path to the file where the \s-1OPF\s0 metadata will be stored or undef if either the top level directory or the \s-1OPF\s0 filename is not found. .ie n .SS """primary_author()""" .el .SS "\f(CWprimary_author()\fP" .IX Subsection "primary_author()" Finds the primary author of the book, defined as the first \&'dc:creator' entry (case-insensitive) where either the attribute opf:role=\*(L"aut\*(R" or role=\*(L"aut\*(R", or the first 'dc:creator' entry if no entries with either attribute can be found. Entries must actually have text to be considered. .PP In list context, returns a two-item list, the first of which is the text of the entry (the author name), and the second element of which is the value of the 'opf:file\-as' or 'file\-as' attribute (where \&'opf:file\-as' is given precedence if both are present). .PP In scalar context, returns the text of the entry (the author name). .PP If no entries are found, returns undef. .PP Uses \*(L"\fBtwigelt_is_author()\fR\*(R" in the first half of the search. .PP \fIExample\fR .IX Subsection "Example" .PP .Vb 2 \& my ($fileas, $author) = $ebook\->primary_author; \& my $author = $ebook\->primary_author; .Ve .ie n .SS """print_errors()""" .el .SS "\f(CWprint_errors()\fP" .IX Subsection "print_errors()" Prints the current list of errors to \s-1STDERR.\s0 .ie n .SS """print_warnings()""" .el .SS "\f(CWprint_warnings()\fP" .IX Subsection "print_warnings()" Prints the current list of warnings to \s-1STDERR.\s0 .ie n .SS """print_opf()""" .el .SS "\f(CWprint_opf()\fP" .IX Subsection "print_opf()" Prints the \s-1OPF\s0 file to the default filehandle .ie n .SS """publishers()""" .el .SS "\f(CWpublishers()\fP" .IX Subsection "publishers()" Returns a list containing the text of all dc:publisher (case-insensitive) entries, or undef if none are found. .PP In scalar context returns the first match, not the last. .ie n .SS """retailprice()""" .el .SS "\f(CWretailprice()\fP" .IX Subsection "retailprice()" Returns a two-scalar list, the first scalar being the text of the Mobipocket-specific <\s-1SRP\s0> element, if it exists, and the second being the 'Currency' attribute of that element, if it exists. .PP In scalar context, returns just the text (price). .PP Returns undef if the \s-1SRP\s0 element is not found. .ie n .SS """review()""" .el .SS "\f(CWreview()\fP" .IX Subsection "review()" Returns the text of the Mobipocket-specific element, if it exists. Returns undef if one is not found. .ie n .SS """rights(\*(Aqid\*(Aq => \*(Aqidentifier\*(Aq)""" .el .SS "\f(CWrights(\*(Aqid\*(Aq => \*(Aqidentifier\*(Aq)\fP" .IX Subsection "rights(id => identifier)" Returns a list containing the text of all of dc:rights or dc:copyrights (case-insensitive) entries in the e\-book, or undef if none are found. .PP In scalar context returns the first match, not the last. .PP If the optional named argument 'id' is specified, it will only return entries where the id attribute matches the specified identifier. Although this still returns a list, if more than one entry is found, a warning is logged. .PP Note that dc:copyrights is not a valid Dublin Core element \*(-- it is included only because some broken Mobipocket books use it. .ie n .SS """search_knownuids()""" .el .SS "\f(CWsearch_knownuids()\fP" .IX Subsection "search_knownuids()" Searches the \s-1OPF\s0 twig for the first dc:identifier (case-insensitive) element with an \s-1ID\s0 matching known \s-1UID\s0 IDs. .PP Returns the \s-1ID\s0 if a match is found, undef otherwise .ie n .SS """search_knownuidschemes()""" .el .SS "\f(CWsearch_knownuidschemes()\fP" .IX Subsection "search_knownuidschemes()" Searches descendants of the \s-1OPF\s0 twig element for the first or subelement with the attribute \&'scheme' or 'opf:scheme' matching a known list of schemes for unique IDs .PP \&\s-1NOTE:\s0 this is \s-1NOT\s0 a case-insensitive search! If you have to deal with really bizarre input, make sure that you run \*(L"\fBfix_oeb12()\fR\*(R" or \&\*(L"\fBfix_opf20()\fR\*(R" before calling \*(L"\fBfix_packageid()\fR\*(R" or \*(L"\fBfix_misc()\fR\*(R". .PP Returns the \s-1ID\s0 if a match is found, undef otherwise. .ie n .SS """spec()""" .el .SS "\f(CWspec()\fP" .IX Subsection "spec()" Returns the version of the \s-1OEB\s0 specification currently in use. Valid values are \f(CW\*(C`OEB12\*(C'\fR and \f(CW\*(C`OPF20\*(C'\fR. This value will default to undef until \f(CW\*(C`fix_oeb12\*(C'\fR or \f(CW\*(C`fix_opf20\*(C'\fR is called, as there is no way for the object to know what specification is being conformed to (if any) until it attempts to enforce it. .ie n .SS """spine()""" .el .SS "\f(CWspine()\fP" .IX Subsection "spine()" Returns all of the manifest items referenced in the spine as a list of hashrefs, with one hash per manifest item in the order that they appear, where the hash keys are 'id', 'href', and 'media\-type', each returning the appropriate attribute, if any. .PP In scalar context, returns the first item, not the last. .PP Returns undef if there is no element directly underneath , or if contains no itemrefs. If exists, but does not, or a spine itemref exists but points an \s-1ID\s0 not found in the manifest, \fBspine()\fR logs an error and returns undef. .PP See also: \*(L"\fBspine_idrefs()\fR\*(R", \*(L"\fBmanifest()\fR\*(R" .ie n .SS """spine_idrefs()""" .el .SS "\f(CWspine_idrefs()\fP" .IX Subsection "spine_idrefs()" Returns a list of all of the idrefs in the current \s-1OPF\s0 spine, or the empty list if none are found. .PP In scalar context, returns the first idref, not the last. .PP See also: \*(L"\fBspine()\fR\*(R", \*(L"\fBmanifest_hrefs()\fR\*(R" .ie n .SS """subject_list()""" .el .SS "\f(CWsubject_list()\fP" .IX Subsection "subject_list()" Returns a list containing the text of all dc:subject elements or undef if none are found. .PP In scalar context, returns the first subject, not the last. .ie n .SS """title()""" .el .SS "\f(CWtitle()\fP" .IX Subsection "title()" Returns the title of the e\-book, or undef if no dc:title element (case-insensitive) exists. If a dc:title element exists, but contains no text, returns an empty string. .ie n .SS """twig()""" .el .SS "\f(CWtwig()\fP" .IX Subsection "twig()" Returns the raw XML::Twig object used to store the \s-1OPF\s0 metadata. .PP Although this twig can be manipulated via the standard XML::Twig methods, doing so requires caution and is not recommended. In particular, changing the root element from here will cause the EBook::Tools internal twig and twigroot attributes to become unlinked and the result of any subsequent action is not defined. .ie n .SS """twigcheck()""" .el .SS "\f(CWtwigcheck()\fP" .IX Subsection "twigcheck()" Croaks showing the calling location unless \f(CW$self\fR has both a twig and a twigroot, and the twigroot is . Used as a sanity check for methods that use twig or twigroot. .ie n .SS """twigroot()""" .el .SS "\f(CWtwigroot()\fP" .IX Subsection "twigroot()" Returns the raw XML::Twig root element used to store the \s-1OPF\s0 metadata. .PP This twig element can be manipulated via the standard XML::Twig::Elt methods, but care should be taken not to attempt to cut this element from its twig as doing so will cause the EBook::Tools internal twig and twigroot attributes to become unlinked and the result of any subsequent action is not defined. .ie n .SS """warnings()""" .el .SS "\f(CWwarnings()\fP" .IX Subsection "warnings()" Returns an arrayref containing any generated warning messages. .SH "MODIFIER METHODS" .IX Header "MODIFIER METHODS" Unless otherwise specified, all modifier methods return undef if an error was added to the error list, and true otherwise (even if a warning was added to the warning list). .ie n .SS """add_document($href,$id,$mediatype)""" .el .SS "\f(CWadd_document($href,$id,$mediatype)\fP" .IX Subsection "add_document($href,$id,$mediatype)" Adds a document to the \s-1OPF\s0 manifest and spine, creating and if necessary. To add an item only to the \s-1OPF\s0 manifest, see \&\fBadd_item()\fR. .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP "$href" 4 .el .IP "\f(CW$href\fR" 4 .IX Item "$href" The href to the document in question. Usually, this is just a filename (or relative path and filename) of a file in the current working directory. If you are planning to eventually generate a .epub book, all hrefs \s-1MUST\s0 be in or below the current working directory. .Sp The method returns undef if \f(CW$href\fR is not defined or empty. .ie n .IP "$id" 4 .el .IP "\f(CW$id\fR" 4 .IX Item "$id" The \s-1XML ID\s0 to use. If not specified, defaults to the href with invalid characters removed. .Sp This must be unique not only to the manifest list, but to every element in the \s-1OPF\s0 file. If a duplicate \s-1ID\s0 exists, the method sets an error and returns undef. .ie n .IP "$mediatype (optional)" 4 .el .IP "\f(CW$mediatype\fR (optional)" 4 .IX Item "$mediatype (optional)" The mime type of the document. If not specified, will attempt to autodetect the mime type, and if that fails, will default to \&'application/xhtml+xml'. .ie n .SS """add_error(@errors)""" .el .SS "\f(CWadd_error(@errors)\fP" .IX Subsection "add_error(@errors)" Adds \f(CW@errors\fR to the list of object errors. Each member of \&\f(CW@errors\fR should be a string containing the entire text of the error, with no ending newline. .PP \&\s-1SEE ALSO:\s0 \*(L"\fBadd_warning()\fR\*(R", \*(L"\fBclear_errors()\fR\*(R", \*(L"\fBclear_warnerr()\fR\*(R" .ie n .SS """add_identifier(%args)""" .el .SS "\f(CWadd_identifier(%args)\fP" .IX Subsection "add_identifier(%args)" Creates a new dc:identifier element containing the specified text, id, and scheme. .PP If a element exists underneath , the identifier element will be created underneath the in \s-1OEB 1.2\s0 format, otherwise the title element is created underneath in \s-1OPF 2.0\s0 format. .PP Returns the twig element containing the new identifier. .PP \fIArguments\fR .IX Subsection "Arguments" .PP \&\f(CW\*(C`add_identifier()\*(C'\fR takes three named arguments, one mandatory, two optional. .IP "\(bu" 4 \&\f(CW\*(C`text\*(C'\fR \- the text of the identifier. This is mandatory, and the method croaks if it is not present. .IP "\(bu" 4 \&\f(CW\*(C`scheme\*(C'\fR \- 'opf:scheme' or 'scheme' attribute to be added (optional) .IP "\(bu" 4 \&\f(CW\*(C`id\*(C'\fR \- 'id' attribute to be added. If this is specified, and the id is already in use, a warning will be added but the method will continue, removing the id attribute from the element that previously contained it. .ie n .SS """add_item($href,$id,$mediatype)""" .el .SS "\f(CWadd_item($href,$id,$mediatype)\fP" .IX Subsection "add_item($href,$id,$mediatype)" Adds a document to the \s-1OPF\s0 manifest (but not spine), creating if necessary. To add an item only to both the \s-1OPF\s0 manifest and spine, see \fBadd_document()\fR. .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP "$href" 4 .el .IP "\f(CW$href\fR" 4 .IX Item "$href" The href to the document in question. Usually, this is just a filename (or relative path and filename) of a file in the current working directory. If you are planning to eventually generate a .epub book, all hrefs \s-1MUST\s0 be in or below the current working directory. .ie n .IP "$id" 4 .el .IP "\f(CW$id\fR" 4 .IX Item "$id" The \s-1XML ID\s0 to use. If not specified, defaults to the href with all nonword characters removed. .Sp This must be unique not only to the manifest list, but to every element in the \s-1OPF\s0 file. If a duplicate \s-1ID\s0 exists, the method sets an error and returns undef. .ie n .IP "$mediatype (optional)" 4 .el .IP "\f(CW$mediatype\fR (optional)" 4 .IX Item "$mediatype (optional)" The mime type of the document. If not specified, will attempt to autodetect the mime type, and if that fails, will set an error and return undef. .SS "add_metadata(%args)" .IX Subsection "add_metadata(%args)" Creates a metadata element with the specified text, attributes, and parent. .PP If a element exists underneath , the language element will be created underneath the and any standard attributes will be created in \s-1OEB 1.2\s0 format, otherwise the element is created underneath in \s-1OPF 2.0\s0 format. .PP Returns 1 on success, returns undef if no gi or if no text was specified. .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP """gi""" 4 .el .IP "\f(CWgi\fR" 4 .IX Item "gi" The generic identifier (tag) of the metadata element to alter or create. If not specified, the method sets an error and returns undef. .ie n .IP """parent""" 4 .el .IP "\f(CWparent\fR" 4 .IX Item "parent" The generic identifier (tag) of the parent to use for any newly created element. If not specified, defaults to 'dc\-metadata' if \&'dc\-metadata' exists underneath 'metadata', and 'metadata' otherwise. .Sp A newly created element will be created under the first element found with this gi. A modified element will be moved under the first element found with this gi. .Sp Newly created elements will use \s-1OPF 2.0\s0 attribute names if the parent is 'metadata' and \s-1OEB 1.2\s0 attribute names otherwise. .ie n .IP """text""" 4 .el .IP "\f(CWtext\fR" 4 .IX Item "text" This specifies the element text to set. If not specified, the method sets an error and returns undef. .ie n .IP """id"" (optional)" 4 .el .IP "\f(CWid\fR (optional)" 4 .IX Item "id (optional)" This specifies the \s-1ID\s0 to set on the element. If set and the \s-1ID\s0 is already in use, a warning is logged and the \s-1ID\s0 is removed from the other location and assigned to the element. .ie n .IP """fileas"" (optional)" 4 .el .IP "\f(CWfileas\fR (optional)" 4 .IX Item "fileas (optional)" This specifies the file-as attribute to set on the element. .ie n .IP """role"" (optional)" 4 .el .IP "\f(CWrole\fR (optional)" 4 .IX Item "role (optional)" This specifies the role attribute to set on the element. .ie n .IP """scheme"" (optional)" 4 .el .IP "\f(CWscheme\fR (optional)" 4 .IX Item "scheme (optional)" This specifies the scheme attribute to set on the element. .PP \fIExample\fR .IX Subsection "Example" .PP .Vb 6 \& $retval = $ebook\->add_metadata(gi => \*(AqAuthorNonstandard\*(Aq, \& text => \*(AqElement Text\*(Aq, \& id => \*(Aqcustomid\*(Aq, \& fileas => \*(AqText, Element\*(Aq, \& role => \*(Aqxxx\*(Aq, \& scheme => \*(Aqcode\*(Aq); .Ve .ie n .SS """add_subject(%args)""" .el .SS "\f(CWadd_subject(%args)\fP" .IX Subsection "add_subject(%args)" Creates a new dc:subject element containing the specified text, code, and id. .PP If a element exists underneath , the subject element will be created underneath the in \s-1OEB 1.2\s0 format, otherwise the title element is created underneath in \s-1OPF 2.0\s0 format. .PP Returns the twig element containing the new subject. .PP \fIArguments\fR .IX Subsection "Arguments" .PP \&\f(CW\*(C`add_subject()\*(C'\fR takes four named arguments, one mandatory, three optional. .IP "\(bu" 4 \&\f(CW\*(C`text\*(C'\fR \- the text of the subject. This is mandatory, and the method croaks if it is not present. .IP "\(bu" 4 \&\f(CW\*(C`scheme\*(C'\fR (optional) \- 'opf:scheme' or 'scheme' attribute to be added. Be warned that neither the \s-1OEB 1.2\s0 nor the \s-1OPF 2.0\s0 specifications allow a scheme to be added to this element, so if this is specified, the resulting \s-1OPF\s0 file will fail to validate against either standard. .IP "\(bu" 4 \&\f(CW\*(C`basiccode\*(C'\fR (optional) \- 'BASICCode' attribute to be added. Be warned that this is a Mobipocket-specific attribute that does not exist in either the \s-1OEB 1.2\s0 nor the \s-1OPF 2.0\s0 specifications, so if this is specified, the resulting \s-1OPF\s0 file will fail to validate against either standard. .IP "\(bu" 4 \&\f(CW\*(C`id\*(C'\fR (optional) \- 'id' attribute to be added. If this is specified, and the id is already in use, a warning will be added but the method will continue, removing the id attribute from the element that previously contained it. .ie n .SS """add_warning(@newwarning)""" .el .SS "\f(CWadd_warning(@newwarning)\fP" .IX Subsection "add_warning(@newwarning)" Joins \f(CW@newwarning\fR to a single string and adds it to the list of object warnings. The warning should not end with a newline newline. .PP \&\s-1SEE ALSO:\s0 \*(L"\fBadd_error()\fR\*(R", \*(L"\fBclear_warnings()\fR\*(R", \*(L"\fBclear_warnerr()\fR\*(R" .ie n .SS """clear_errors()""" .el .SS "\f(CWclear_errors()\fP" .IX Subsection "clear_errors()" Clear the current list of errors .ie n .SS """clear_warnerr()""" .el .SS "\f(CWclear_warnerr()\fP" .IX Subsection "clear_warnerr()" Clear both the error and warning lists .ie n .SS """clear_warnings()""" .el .SS "\f(CWclear_warnings()\fP" .IX Subsection "clear_warnings()" Clear the current list of warnings .ie n .SS """delete_meta_filepos()""" .el .SS "\f(CWdelete_meta_filepos()\fP" .IX Subsection "delete_meta_filepos()" Deletes metadata elements with the attribute 'filepos' underneath the given parent element .PP These are secondary metadata elements included in the output from mobi2html may that are not used. .ie n .SS """delete_subject(%args)""" .el .SS "\f(CWdelete_subject(%args)\fP" .IX Subsection "delete_subject(%args)" Deletes dc:subject and dc:Subject elements based on text content or the id, scheme, or basiccode attributes. Matches are case-sensitive. .PP Specifying multiple arguments will delete subject matching any of them. .PP This has the same potential arguments as add_subject. .PP Returns the count of elements deleted. .ie n .SS """fix_creators()""" .el .SS "\f(CWfix_creators()\fP" .IX Subsection "fix_creators()" Normalizes creator and contributor names and file-as attributes .PP Names are normalized to 'First Last' format, while file-as attributes are normalized to 'Last, First' format. .PP This can damage some unusual names that do not match standard capitalization formats, so it is not made part of \*(L"\fBfix_misc()\fR\*(R". .ie n .SS """fix_dates()""" .el .SS "\f(CWfix_dates()\fP" .IX Subsection "fix_dates()" Standardizes all elements via \fBfix_datestring()\fR. Adds a warning to the object for each date that could not be fixed. .PP Called from \*(L"\fBfix_misc()\fR\*(R". .ie n .SS """fix_guide()""" .el .SS "\f(CWfix_guide()\fP" .IX Subsection "fix_guide()" Fixes problems related to the \s-1OPF\s0 guide elements, specifically: .IP "\(bu" 4 Ensures the guide element exists .IP "\(bu" 4 Moves all reference elements directly underneath the guide element .IP "\(bu" 4 Finds nonstandard reference types and either converts them to standard or prefaces them with 'other.' .IP "\(bu" 4 Finds reference elements with a href with only an anchor portion and assigns them to the first spine href. This only works if the spine is in working condition, so it may be wise to run \&\*(L"\fBfix_spine()\fR\*(R" before \f(CW\*(C`fix_guide()\*(C'\fR if the input is expected to be very badly broken. .PP Logs a warning if a reference href is found that does not appear in the manifest. .ie n .SS """fix_languages(%args)""" .el .SS "\f(CWfix_languages(%args)\fP" .IX Subsection "fix_languages(%args)" Checks through the elements (case-insensitive) and removes any duplicates. If no elements are found, one is created. .PP \&\s-1TODO:\s0 Also convert language names to \s-1IANA\s0 language and region codes. .PP \fIArguments\fR .IX Subsection "Arguments" .IP "\(bu" 4 \&\f(CW\*(C`default\*(C'\fR .Sp The default language string to use when creating a new language element. If not specified, defaults to 'en'. .ie n .SS """fix_links()""" .el .SS "\f(CWfix_links()\fP" .IX Subsection "fix_links()" Checks through the links in the manifest and checks them for anything they might link to, adding anything missing to the manifest. .PP A warning is added for every manifest item missing a href. .PP If no element exists directly underneath the root, or contains no items, the method logs a warning and returns undef. Otherwise, it returns 1. .ie n .SS """fix_manifest()""" .el .SS "\f(CWfix_manifest()\fP" .IX Subsection "fix_manifest()" Finds all elements and moves them underneath , creating if necessary. .PP Logs a warning but continues if it finds an with a missing id or href attribute. If both id and href attributes are missing, logs a warning, skips moving the item entirely (unless it was already underneath , in which case it is moved to preserve its sort order along all other items under ), but otherwise continues. .ie n .SS """fix_metastructure_basic()""" .el .SS "\f(CWfix_metastructure_basic()\fP" .IX Subsection "fix_metastructure_basic()" Verifies that exists (creating it if necessary), and moves it to be the first child of . If additional elements exist, their children are moved into the first one found and then the extras are deleted. .PP Used in \*(L"\fBfix_metastructure_oeb12()\fR\*(R", \*(L"\fBfix_packageid()\fR\*(R", and \&\*(L"set_primary_author(%args)\*(R". .ie n .SS """fix_metastructure_oeb12()""" .el .SS "\f(CWfix_metastructure_oeb12()\fP" .IX Subsection "fix_metastructure_oeb12()" Verifies the existence of , , and , creating them as needed, and making sure that is a child of , while and are children of . .PP Used in \*(L"\fBfix_oeb12()\fR\*(R" and \*(L"\fBfix_mobi()\fR\*(R". .ie n .SS """fix_misc()""" .el .SS "\f(CWfix_misc()\fP" .IX Subsection "fix_misc()" Fixes miscellaneous potential problems in \s-1OPF\s0 data. Specifically, this is a shortcut to calling \*(L"\fBdelete_meta_filepos()\fR\*(R", \&\*(L"\fBfix_packageid()\fR\*(R", \*(L"\fBfix_dates()\fR\*(R", \*(L"\fBfix_languages()\fR\*(R", \&\*(L"\fBfix_publisher()\fR\*(R", \*(L"\fBfix_manifest()\fR\*(R", \*(L"\fBfix_spine()\fR\*(R", \&\*(L"\fBfix_subjects()\fR\*(R", \*(L"\fBfix_type()\fR\*(R", \*(L"\fBfix_guide()\fR\*(R", and \&\*(L"\fBfix_links()\fR\*(R". .PP \&\*(L"\fBfix_creators()\fR\*(R" is not run from this, as it carries a risk of taking a correct name and making it incorrect. .PP The objective here is that you can run either \f(CW\*(C`fix_misc()\*(C'\fR and either \&\*(L"\fBfix_oeb12()\fR\*(R" or \*(L"\fBfix_opf20()\fR\*(R" and a perfectly valid \s-1OPF\s0 file will result from only two calls. .ie n .SS """fix_mobi()""" .el .SS "\f(CWfix_mobi()\fP" .IX Subsection "fix_mobi()" Manipulates the twig to fix Mobipocket-specific issues .IP "\(bu" 4 Force the \s-1OEB 1.2\s0 structure (although not the namespace, \s-1DTD,\s0 or capitalization), so that and are guaranteed to exist. .IP "\(bu" 4 Find and move all Mobi-specific elements to .IP "\(bu" 4 If no element exists, creates one for a utf\-8 ebook .PP Note that the forced creation of will cause the \s-1OPF\s0 file to become noncompliant with \s-1IDPF\s0 specifications. .ie n .SS """fix_oeb12()""" .el .SS "\f(CWfix_oeb12()\fP" .IX Subsection "fix_oeb12()" Modifies the \s-1OPF\s0 data to conform to the \s-1OEB 1.2\s0 standard .PP Specifically, this involves: .IP "\(bu" 4 adding the \s-1OEB 1.2\s0 doctype .IP "\(bu" 4 removing \s-1OPF 2.0\s0 version and namespace attributes .IP "\(bu" 4 setting the \s-1OEB 1.2\s0 namespace on .IP "\(bu" 4 moving all of the dc-metadata elements underneath an element with tag , which itself is forced to be underneath , which is created if it doesn't exist. .IP "\(bu" 4 moving any remaining tags underneath , again forced to be under .IP "\(bu" 4 making the dc-metadata tags conform to the \s-1OEB\s0 v1.2 capitalization .ie n .SS """fix_oeb12_dcmetatags()""" .el .SS "\f(CWfix_oeb12_dcmetatags()\fP" .IX Subsection "fix_oeb12_dcmetatags()" Makes a case-insensitive search for tags matching a known list of \s-1DC\s0 metadata elements and corrects the capitalization to the \s-1OEB 1.2\s0 standard. Also corrects 'dc:Copyrights' to 'dc:Rights'. See global variable \f(CW$dcelements12\fR. .PP The \*(L"\fBfix_oeb12()\fR\*(R" method does this also, but \fBfix_oeb12_dcmetatags()\fR is usable separately for the case where you want \s-1DC\s0 metadata elements with consistent tag names, but don't want them moved from wherever they are. .ie n .SS """fix_opf20()""" .el .SS "\f(CWfix_opf20()\fP" .IX Subsection "fix_opf20()" Modifies the \s-1OPF\s0 data to conform to the \s-1OPF 2.0\s0 standard .PP Specifically, this involves: .IP "\(bu" 4 moving all of the dc-metadata and x\-metadata elements directly underneath .IP "\(bu" 4 removing the and elements themselves .IP "\(bu" 4 lowercasing the dc-metadata tags (and fixing dc:copyrights to dc:rights) .IP "\(bu" 4 setting namespaces on dc-metata \s-1OPF\s0 attributes .IP "\(bu" 4 setting version and xmlns attributes on .IP "\(bu" 4 setting xmlns:dc and xmlns:opf on .ie n .SS """fix_opf20_dcmetatags()""" .el .SS "\f(CWfix_opf20_dcmetatags()\fP" .IX Subsection "fix_opf20_dcmetatags()" Makes a case-insensitive search for tags matching a known list of \s-1DC\s0 metadata elements and corrects the capitalization to the \s-1OPF 2.0\s0 standard. Also corrects 'dc:copyrights' to 'dc:rights'. See package variable \f(CW%dcelements20\fR. .PP The \*(L"\fBfix_opf20()\fR\*(R" method does this also, but \&\f(CW\*(C`fix_opf20_dcmetatags()\*(C'\fR is usable separately for the case where you want \s-1DC\s0 metadata elements with consistent tag names, but don't want them moved from wherever they are. .ie n .SS """fix_packageid()""" .el .SS "\f(CWfix_packageid()\fP" .IX Subsection "fix_packageid()" Checks the element for the attribute 'unique\-identifier', makes sure that it is mapped to a valid dc:identifier subelement, and if not, searches those subelements for an identifier to assign, or creates one if nothing can be found. .PP Requires that exist. Croaks if it doesn't. Run \&\*(L"\fBfix_oeb12()\fR\*(R" or \*(L"\fBfix_opf20()\fR\*(R" before calling this if the input might be very broken. .ie n .SS """fix_publisher()""" .el .SS "\f(CWfix_publisher()\fP" .IX Subsection "fix_publisher()" Standardizes publisher names in all dc:publisher entities, mapping known variants of a publisher's name to a canonical form via package variable \f(CW%publishermap\fR. .PP Publisher entries with no text are deleted. .ie n .SS """fix_spine()""" .el .SS "\f(CWfix_spine()\fP" .IX Subsection "fix_spine()" Fixes problems with the \s-1OPF\s0 spine, specifically: .IP "Moves all elements underneath , creating if necessary." 4 .IX Item "Moves all elements underneath , creating if necessary." .ie n .SS """fix_subjects()""" .el .SS "\f(CWfix_subjects()\fP" .IX Subsection "fix_subjects()" Deletes empty and duplicate subject elements and normalizes existing subject text against the known Library of Congress mappings. .PP If \f(CW$self\fR\->{erotic} is true, then the book will be treated as a work of erotic fiction and the subjects will go through preprocessing against the \f(CW%sexcodes\fR package variable, normalizing matches and prepending '\s-1FICTION /\s0 Erotica / ' (with a trailing space). .PP This method is called as a component of \f(CW\*(C`fix_misc()\*(C'\fR. .ie n .SS """fix_type()""" .el .SS "\f(CWfix_type()\fP" .IX Subsection "fix_type()" Normalizes elements against a limited list based on book types listed in Wikipedia. .ie n .SS """gen_epub(%args)""" .el .SS "\f(CWgen_epub(%args)\fP" .IX Subsection "gen_epub(%args)" Creates a .epub format e\-book. This will create (or overwrite) the files 'mimetype' and 'META\-INF/container.xml' in the current directory, creating the subdirectory META-INF as needed. .PP A \s-1NCX\s0 file will also be created if missing. .PP \fIArguments\fR .IX Subsection "Arguments" .PP This method can take two optional named arguments. .ie n .IP """filename""" 4 .el .IP "\f(CWfilename\fR" 4 .IX Item "filename" The filename of the .epub output file. If not specified, takes the base name of the opf file and adds a .epub extension. .ie n .IP """dir""" 4 .el .IP "\f(CWdir\fR" 4 .IX Item "dir" The directory to output the .epub file. If not specified, uses the current working directory. If a specified directory does not exist, it will be created, or the method will croak. .PP \fIExample\fR .IX Subsection "Example" .PP .Vb 2 \& gen_epub(filename => \*(Aqmybook.epub\*(Aq, \& dir => \*(Aq../epub_books\*(Aq); .Ve .ie n .SS """gen_epub_files()""" .el .SS "\f(CWgen_epub_files()\fP" .IX Subsection "gen_epub_files()" Generates the \f(CW\*(C`mimetype\*(C'\fR and \f(CW\*(C`META\-INF/container.xml\*(C'\fR files expected by a .epub container, but does not actually generate the .epub file itself. This will be called automatically by \f(CW\*(C`gen_epub\*(C'\fR. .PP The \s-1OPF\s0 will be normalized to the \s-1OPF 2.0\s0 format. .PP If no \s-1NCX\s0 element exists, it will also be created. .ie n .SS """gen_ncx($filename)""" .el .SS "\f(CWgen_ncx($filename)\fP" .IX Subsection "gen_ncx($filename)" Creates a NCX-format table of contents from the package unique-identifier, the dc:title, dc:creator, and spine elements, and then add the \s-1NCX\s0 entry to the manifest if it is not already referenced. .PP Adds an error and fails if any of those cannot be found. The first available dc:title is taken, but will prioritize dc:creator elements with opf:role=\*(L"aut\*(R" over those with no role attribute (see \&\fBtwigelt_is_author()\fR for details). .PP \&\s-1WARNING:\s0 This method \s-1REQUIRES\s0 that the e\-book be in \s-1OPF 2.0\s0 format to function correctly. Call \fBfix_opf20()\fR before calling \fBgen_ncx()\fR. \&\fBgen_ncx()\fR will log an error and fail if \f(CW$self\fR{spec} is not set to \&\s-1OPF20.\s0 .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP "$filename : The filename to save to. If not specified, will use 'toc.ncx'." 4 .el .IP "\f(CW$filename\fR : The filename to save to. If not specified, will use 'toc.ncx'." 4 .IX Item "$filename : The filename to save to. If not specified, will use 'toc.ncx'." .PP This method will overwrite any existing file. .PP Returns a twig containing the \s-1NCX XML,\s0 or undef on failure. .ie n .SS """save()""" .el .SS "\f(CWsave()\fP" .IX Subsection "save()" Saves the \s-1OPF\s0 file to disk. Existing files are backed up to filename.backup. .ie n .SS """set_adult($bool)""" .el .SS "\f(CWset_adult($bool)\fP" .IX Subsection "set_adult($bool)" Sets the Mobipocket-specific element, creating or deleting it as necessary. If \f(CW$bool\fR is true, the text is set to 'yes'. If it is defined but false, any existing elements are deleted. If it is undefined, the method immediately returns. .PP If a new element has to be created, \*(L"fix_metastructure_oeb12\*(R" is called to ensure that exists and the element is created under , as Mobipocket elements are not recognized by Mobipocket's software when placed directly under .ie n .SS """set_cover(%args)""" .el .SS "\f(CWset_cover(%args)\fP" .IX Subsection "set_cover(%args)" Sets a cover image .PP In \s-1OPF 2.0,\s0 this is done by setting both a element and a guide element (though some readers will also extract the first image found in the \&\s-1HTML\s0 of the element, which this method will not handle). .PP In \s-1OEB 1.2,\s0 this is done by setting the tag. .PP If the filename is not currently listed as an item in the manifest, it is added. .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP """href""" 4 .el .IP "\f(CWhref\fR" 4 .IX Item "href" The filename of the image file to use. This is mandatory. .ie n .IP """id""" 4 .el .IP "\f(CWid\fR" 4 .IX Item "id" The id attribute to assign to its item element .ie n .IP """spec""" 4 .el .IP "\f(CWspec\fR" 4 .IX Item "spec" The specification to use, either \s-1OEB12\s0 or \s-1OPF20.\s0 If this is left undefined, the current spec state will be checked, and if that is undefined, it will default to \s-1OPF20.\s0 .ie n .SS """set_date(%args)""" .el .SS "\f(CWset_date(%args)\fP" .IX Subsection "set_date(%args)" Sets the date metadata for a given event. If more than one dc:date or dc:Date element is present with the specified event attribute, sets the first. If no dc:date element is present with the specified event attribute, a new element is created. .PP If a element exists underneath , the date element will be created underneath the in \s-1OEB 1.2\s0 format, otherwise the title element is created underneath in \s-1OPF 2.0\s0 format. .PP Returns 1 on success, logs an error and returns undef if no text or event was specified. .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP """text""" 4 .el .IP "\f(CWtext\fR" 4 .IX Item "text" This specifies the description to use as the text of the element. If not specified, the method sets an error and returns undef. .ie n .IP """event""" 4 .el .IP "\f(CWevent\fR" 4 .IX Item "event" This optionally specifies the event attribute for the date. This attribute is not valid in \s-1OPF 3.0\s0 (which only allows publication date in this element) and should no longer be used. .ie n .IP """id"" (optional)" 4 .el .IP "\f(CWid\fR (optional)" 4 .IX Item "id (optional)" This specifies the \s-1ID\s0 to set on the element. If set and the \s-1ID\s0 is already in use, a warning is logged and the \s-1ID\s0 is removed from the other location and assigned to the element. .SS "set_description(%args)" .IX Subsection "set_description(%args)" Sets the text and optionally \s-1ID\s0 of the first dc:description element found (case-insensitive). Creates the element if one did not exist. If a element exists underneath , the description element will be created underneath the in \&\s-1OEB 1.2\s0 format, otherwise the title element is created underneath in \s-1OPF 2.0\s0 format. .PP Returns 1 on success, returns undef if no publisher was specified. .PP \fIArguments\fR .IX Subsection "Arguments" .PP \&\f(CW\*(C`set_description()\*(C'\fR takes one required and one optional named argument .ie n .IP """text""" 4 .el .IP "\f(CWtext\fR" 4 .IX Item "text" This specifies the description to use as the text of the element. If not specified, the method returns undef. .ie n .IP """id"" (optional)" 4 .el .IP "\f(CWid\fR (optional)" 4 .IX Item "id (optional)" This specifies the \s-1ID\s0 to set on the element. If set and the \s-1ID\s0 is already in use, a warning is logged and the \s-1ID\s0 is removed from the other location and assigned to the element. .PP \fIExample\fR .IX Subsection "Example" .PP .Vb 2 \& $retval = $ebook\->set_description(\*(Aqtext\*(Aq => \*(AqA really good book\*(Aq, \& \*(Aqid\*(Aq => \*(Aqmydescid\*(Aq); .Ve .ie n .SS """set_erotic($bool)""" .el .SS "\f(CWset_erotic($bool)\fP" .IX Subsection "set_erotic($bool)" If \f(CW$bool\fR is true, \f(CW\*(C`$self\-\*(C'\fR{erotic}> is set to 1, otherwise this is set to 0. .PP This will enable or disable special handling for erotic books, most notably in subject normalization. .PP This is not related in any way to \f(CW\*(C`set_adult\*(C'\fR which is a Mobipocket-specific flag. .PP Returns 1 if no argument is given, 0 otherwise. .ie n .SS """set_language(%args)""" .el .SS "\f(CWset_language(%args)\fP" .IX Subsection "set_language(%args)" Sets the text and optionally the \s-1ID\s0 of the first dc:language element found (case-insensitive). Creates the element if one did not exist. If a element exists underneath , the language element will be created underneath the in \s-1OEB 1.2\s0 format, otherwise the title element is created underneath in \s-1OPF 2.0\s0 format. .PP Returns 1 on success, returns undef if no text was specified. .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP """text""" 4 .el .IP "\f(CWtext\fR" 4 .IX Item "text" This specifies the language set as the text of the element. If not specified, the method sets an error and returns undef. This should be an \s-1IANA\s0 language code, and it will be lowercased before it is set. .ie n .IP """id"" (optional)" 4 .el .IP "\f(CWid\fR (optional)" 4 .IX Item "id (optional)" This specifies the \s-1ID\s0 to set on the element. If set and the \s-1ID\s0 is already in use, a warning is logged and the \s-1ID\s0 is removed from the other location and assigned to the element. .PP \fIExample\fR .IX Subsection "Example" .PP .Vb 2 \& $retval = $ebook\->set_language(\*(Aqtext\*(Aq => \*(Aqen\-us\*(Aq, \& \*(Aqid\*(Aq => \*(Aqlangid\*(Aq); .Ve .SS "set_meta(%args)" .IX Subsection "set_meta(%args)" Sets a element in the element area. .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP """name""" 4 .el .IP "\f(CWname\fR" 4 .IX Item "name" The name attribute to use when finding or creating \s-1OPF 2.0\s0 elements. Either this or the property attribute (below) must be specified, but specifying both is an error. .ie n .IP """content""" 4 .el .IP "\f(CWcontent\fR" 4 .IX Item "content" The value of the content attribute to set on \s-1OPF 2.0\s0 elements. If this value is empty or undefined, but \f(CW\*(C`name\*(C'\fR is provided and matches an existing element, that element will be deleted. .ie n .IP """property""" 4 .el .IP "\f(CWproperty\fR" 4 .IX Item "property" The property attribute to use when finding or creating \s-1OPF 3.0\s0 elements. Either this or \f(CW\*(C`name\*(C'\fR (above) must be specified, but specifying both is an error. .ie n .IP """refines""" 4 .el .IP "\f(CWrefines\fR" 4 .IX Item "refines" The refines attribute to use when finding or creating \s-1OPF 3.0\s0 elements. .ie n .IP """scheme""" 4 .el .IP "\f(CWscheme\fR" 4 .IX Item "scheme" The scheme attribute to use when creating or updating \s-1OPF 3.0\s0 elements. .ie n .IP """text""" 4 .el .IP "\f(CWtext\fR" 4 .IX Item "text" The text set on \s-1OPF 3.0\s0 elements. If this value is empty or undefined, but \f(CW\*(C`property\*(C'\fR is provided and the combination of \&\f(CW\*(C`property\*(C'\fR and \f(CW\*(C`refines\*(C'\fR matches an existing element, that element will be deleted. .ie n .IP """lang""" 4 .el .IP "\f(CWlang\fR" 4 .IX Item "lang" The xml:lang attribute to set. This is valid on both \s-1OPF 2\s0 and \s-1OPF 3\s0 elements. .SS "set_metadata(%args)" .IX Subsection "set_metadata(%args)" Sets the text and optionally the \s-1ID\s0 of the first specified element type found (case-insensitive). Creates the element if one did not exist (with the exact capitalization specified). .PP If a element exists underneath , the language element will be created underneath the and any standard attributes will be created in \s-1OEB 1.2\s0 format, otherwise the element is created underneath in \s-1OPF 2.0\s0 format. .PP Returns 1 on success, returns undef if no gi or if no text was specified. .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP """gi""" 4 .el .IP "\f(CWgi\fR" 4 .IX Item "gi" The generic identifier (tag) of the metadata element to alter or create. If not specified, the method sets an error and returns undef. .ie n .IP """parent""" 4 .el .IP "\f(CWparent\fR" 4 .IX Item "parent" The generic identifier (tag) of the parent to use for any newly created element. If not specified, defaults to 'dc\-metadata' if \&'dc\-metadata' exists underneath 'metadata', and 'metadata' otherwise. .Sp A newly created element will be created under the first element found with this gi. A modified element will be moved under the first element found with this gi. .Sp Newly created elements will use \s-1OPF 2.0\s0 attribute names if the parent is 'metadata' and \s-1OEB 1.2\s0 attribute names otherwise. .ie n .IP """text""" 4 .el .IP "\f(CWtext\fR" 4 .IX Item "text" This specifies the element text to set. If not specified, the method sets an error and returns undef. .ie n .IP """id"" (optional)" 4 .el .IP "\f(CWid\fR (optional)" 4 .IX Item "id (optional)" This specifies the \s-1ID\s0 to set on the element. If set and the \s-1ID\s0 is already in use, a warning is logged and the \s-1ID\s0 is removed from the other location and assigned to the element. .ie n .IP """fileas"" (optional)" 4 .el .IP "\f(CWfileas\fR (optional)" 4 .IX Item "fileas (optional)" This specifies the file-as attribute to set on the element. .ie n .IP """role"" (optional)" 4 .el .IP "\f(CWrole\fR (optional)" 4 .IX Item "role (optional)" This specifies the role attribute to set on the element. .ie n .IP """scheme"" (optional)" 4 .el .IP "\f(CWscheme\fR (optional)" 4 .IX Item "scheme (optional)" This specifies the scheme attribute to set on the element. .PP \fIExample\fR .IX Subsection "Example" .PP .Vb 6 \& $retval = $ebook\->set_metadata(gi => \*(AqAuthorNonstandard\*(Aq, \& text => \*(AqElement Text\*(Aq, \& id => \*(Aqcustomid\*(Aq, \& fileas => \*(AqText, Element\*(Aq, \& role => \*(Aqxxx\*(Aq, \& scheme => \*(Aqcode\*(Aq); .Ve .SS "set_opffile($filename)" .IX Subsection "set_opffile($filename)" Sets the filename used to store the \s-1OPF\s0 metadata. .PP Returns 1 on success; sets an error message and returns undef if no filename was specified. .SS "set_retailprice(%args)" .IX Subsection "set_retailprice(%args)" Sets the Mobipocket-specific <\s-1SRP\s0> element (Suggested Retail Price), creating or deleting it as necessary. .PP If a new element has to be created, \*(L"fix_metastructure_oeb12\*(R" is called to ensure that exists and the element is created under , as Mobipocket elements are not recognized by Mobipocket's software when placed directly under .PP \fIArguments\fR .IX Subsection "Arguments" .IP "\(bu" 4 \&\f(CW\*(C`text\*(C'\fR .Sp The price to set as the text of the element. If this is undefined, the method sets an error and returns undef. If it is set but false, any existing <\s-1SRP\s0> element is deleted. .IP "\(bu" 4 \&\f(CW\*(C`currency\*(C'\fR (optional) .Sp The value to set on the 'Currency' attribute. If not provided, defaults to '\s-1USD\s0' (\s-1US\s0 Dollars) .SS "set_primary_author(%args)" .IX Subsection "set_primary_author(%args)" Sets the text, id, file-as, and role attributes of the primary author element (see \*(L"\fBprimary_author()\fR\*(R" for details on how this is found), or if no primary author exists, creates a new element containing the information. .PP This method calls \*(L"\fBfix_metastructure_basic()\fR\*(R" to enforce the presence of the element. When creating a new element, the method will use the \s-1OEB 1.2\s0 element name and create the element underneath if an existing element is found underneath . If no existing element is found, the new element will be created with the \s-1OPF 2.0\s0 element name directly underneath . Regardless, it is probably a good idea to call \&\*(L"\fBfix_oeb12()\fR\*(R" or \*(L"\fBfix_opf20()\fR\*(R" after calling this method to ensure a consistent scheme. .PP \fIArguments\fR .IX Subsection "Arguments" .PP Three optional named arguments can be passed: .IP "\(bu" 4 \&\f(CW\*(C`text\*(C'\fR .Sp Specifies the author text to set. If omitted and a primary author element exists, the text will be left as is; if omitted and a primary author element cannot be found, an error message will be generated and the method will return undef. .IP "\(bu" 4 \&\f(CW\*(C`fileas\*(C'\fR .Sp Specifies the 'file\-as' attribute to set. If omitted and a primary author element exists, any existing attribute will be left untouched; if omitted and a primary author element cannot be found, the newly created element will not have this attribute. .IP "\(bu" 4 \&\f(CW\*(C`id\*(C'\fR .Sp Specifies the 'id' attribute to set. If this is specified, and the id is already in use, a warning will be added but the method will continue, removing the id attribute from the element that previously contained it. .Sp If this is omitted and a primary author element exists, any existing id will be left untouched; if omitted and a primary author element cannot be found, the newly created element will not have an id set. .PP If called with no arguments, the only effect this method has is to enforce that either an 'opf:role' or 'role' attribute is set to 'aut' on the primary author element. .PP \fIReturn values\fR .IX Subsection "Return values" .PP Returns 1 if successful, returns undef and sets an error message if the author argument is missing and no primary author element was found. .ie n .SS """set_publisher(%args)""" .el .SS "\f(CWset_publisher(%args)\fP" .IX Subsection "set_publisher(%args)" Sets the text and optionally the \s-1ID\s0 of the first dc:publisher element found (case-insensitive). Creates the element if one did not exist. If a element exists underneath , the publisher element will be created underneath the in \s-1OEB 1.2\s0 format, otherwise the title element is created underneath in \s-1OPF 2.0\s0 format. .PP Returns 1 on success, returns undef if no publisher was specified. .PP \fIArguments\fR .IX Subsection "Arguments" .PP \&\f(CW\*(C`set_publisher()\*(C'\fR takes one required and one optional named argument .ie n .IP """text""" 4 .el .IP "\f(CWtext\fR" 4 .IX Item "text" This specifies the publisher name to set as the text of the element. If not specified, the method returns undef. .ie n .IP """id"" (optional)" 4 .el .IP "\f(CWid\fR (optional)" 4 .IX Item "id (optional)" This specifies the \s-1ID\s0 to set on the element. If set and the \s-1ID\s0 is already in use, a warning is logged and the \s-1ID\s0 is removed from the other location and assigned to the element. .PP \fIExample\fR .IX Subsection "Example" .PP .Vb 2 \& $retval = $ebook\->set_publisher(\*(Aqtext\*(Aq => \*(AqMy Publishing House\*(Aq, \& \*(Aqid\*(Aq => \*(Aqmypubid\*(Aq); .Ve .SS "set_review(%args)" .IX Subsection "set_review(%args)" Sets the text and optionally \s-1ID\s0 of the first element found (case-insensitive), creating the element if one did not exist. .PP This is a Mobipocket-specific element and if it needs to be created it will always be created under with \&\*(L"\fBfix_metastructure_oeb12()\fR\*(R" called to ensure that exists. .PP Returns 1 on success, returns undef if no review text was specified .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP """text""" 4 .el .IP "\f(CWtext\fR" 4 .IX Item "text" This specifies the description to use as the text of the element. If not specified, the method returns undef. .ie n .IP """id"" (optional)" 4 .el .IP "\f(CWid\fR (optional)" 4 .IX Item "id (optional)" This specifies the \s-1ID\s0 to set on the element. If set and the \s-1ID\s0 is already in use, a warning is logged and the \s-1ID\s0 is removed from the other location and assigned to the element. .PP \fIExample\fR .IX Subsection "Example" .PP .Vb 2 \& $retval = $ebook\->set_review(\*(Aqtext\*(Aq => \*(AqThis book is perfect!\*(Aq, \& \*(Aqid\*(Aq => \*(Aqrevid\*(Aq); .Ve .ie n .SS """set_rights(%args)""" .el .SS "\f(CWset_rights(%args)\fP" .IX Subsection "set_rights(%args)" Sets the text of the first dc:rights or dc:copyrights element found (case-insensitive). If the element found has the gi of dc:copyrights, it will be changed to dc:rights. This is to correct certain noncompliant Mobipocket files. .PP Creates the element if one did not exist. If a element exists underneath , the title element will be created underneath the in \s-1OEB 1.2\s0 format, otherwise the title element is created underneath in \s-1OPF 2.0\s0 format. .PP Returns 1 on success, returns undef if no rights string was specified. .PP \fIArguments\fR .IX Subsection "Arguments" .IP "\(bu" 4 \&\f(CW\*(C`text\*(C'\fR .Sp This specifies the text of the element. If not specified, the method returns undef. .IP "\(bu" 4 \&\f(CW\*(C`id\*(C'\fR (optional) .Sp This specifies the \s-1ID\s0 to set on the element. If set and the \s-1ID\s0 is already in use, a warning is logged but the method continues anyway. .ie n .SS """set_spec($spec)""" .el .SS "\f(CWset_spec($spec)\fP" .IX Subsection "set_spec($spec)" Sets the \s-1OEB\s0 specification to match when modifying \s-1OPF\s0 data. Allowable values are '\s-1OEB12\s0', '\s-1OPF20\s0', and '\s-1MOBI12\s0'. .PP Returns 1 if successful; returns undef and sets an error message if an unknown specification was set. .ie n .SS """set_timestamp()""" .el .SS "\f(CWset_timestamp()\fP" .IX Subsection "set_timestamp()" Sets the element to the current timestamp and removes duplicate or nonstandard timestamps. .ie n .SS """set_title(%args)""" .el .SS "\f(CWset_title(%args)\fP" .IX Subsection "set_title(%args)" Sets the text or id of the first dc:title element found (case-insensitive). Creates the element if one did not exist. If a element exists underneath , the title element will be created underneath the in \s-1OEB 1.2\s0 format, otherwise the title element is created underneath in \s-1OPF 2.0\s0 format. .PP \fIArguments\fR .IX Subsection "Arguments" .PP \&\fBset_title()\fR takes two optional named arguments. If neither is specified, the method will do nothing. .IP "\(bu" 4 \&\f(CW\*(C`text\*(C'\fR .Sp This specifies the text of the element. If not specified, and no title element is found, an error will be set and the method will return undef \*(-- \fBset_title()\fR will refuse to create a dc:title element with no text. .IP "\(bu" 4 \&\f(CW\*(C`id\*(C'\fR .Sp This specifies the \s-1ID\s0 to set on the element. If set and the \s-1ID\s0 is already in use, a warning is logged but the method continues anyway. .ie n .SS """set_type(%args)""" .el .SS "\f(CWset_type(%args)\fP" .IX Subsection "set_type(%args)" Sets the text and optionally the \s-1ID\s0 of the first dc:type element found (case-insensitive). Creates the element if one did not exist. If a element exists underneath , the publisher element will be created underneath the in \s-1OEB 1.2\s0 format, otherwise the title element is created underneath in \s-1OPF 2.0\s0 format. .PP Returns 1 on success, returns undef if no publisher was specified. .PP \fIArguments\fR .IX Subsection "Arguments" .PP \&\f(CW\*(C`set_type()\*(C'\fR takes one required and one optional named argument .ie n .IP """text""" 4 .el .IP "\f(CWtext\fR" 4 .IX Item "text" This specifies the publisher name to set as the text of the element. If not specified, the method returns undef. .ie n .IP """id"" (optional)" 4 .el .IP "\f(CWid\fR (optional)" 4 .IX Item "id (optional)" This specifies the \s-1ID\s0 to set on the element. If set and the \s-1ID\s0 is already in use, a warning is logged and the \s-1ID\s0 is removed from the other location and assigned to the element. .PP \fIExample\fR .IX Subsection "Example" .PP .Vb 2 \& $retval = $ebook\->set_type(\*(Aqtext\*(Aq => \*(AqShort Story\*(Aq, \& \*(Aqid\*(Aq => \*(Aqmytypeid\*(Aq); .Ve .SH "PROCEDURES" .IX Header "PROCEDURES" All procedures are exportable, but none are exported by default. All procedures can be exported by using the \*(L":all\*(R" tag. .ie n .SS """_lc""" .el .SS "\f(CW_lc\fP" .IX Subsection "_lc" Wrapper for CORE::lc to get around the fact that builtins can't be used in dispatch tables prior to Perl 5.16. .PP \&\s-1WARNING:\s0 this procedure may disappear once Perl 5.16 is standard on all systems in common use! For that reason, this is not exportable. .ie n .SS """_uc""" .el .SS "\f(CW_uc\fP" .IX Subsection "_uc" Wrapper for CORE::uc to get around the fact that builtins can't be used in dispatch tables prior to Perl 5.16. .PP \&\s-1WARNING:\s0 this procedure may disappear once Perl 5.16 is standard on all systems in common use! For that reason, this is not exportable. .ie n .SS """capitalize($string)""" .el .SS "\f(CWcapitalize($string)\fP" .IX Subsection "capitalize($string)" Capitalizes the first letter of each word in \f(CW$string\fR. .PP Returns the corrected string. .ie n .SS """clean_filename($string)""" .el .SS "\f(CWclean_filename($string)\fP" .IX Subsection "clean_filename($string)" Takes an input string and cleans out any characters that would not be valid in a filename. .PP Returns the cleaned string. .ie n .SS """create_epub_container($opffile)""" .el .SS "\f(CWcreate_epub_container($opffile)\fP" .IX Subsection "create_epub_container($opffile)" Creates the \s-1XML\s0 file META\-INF/container.xml pointing to the specified \s-1OPF\s0 file. .PP Creates the META-INF directory if necessary. Will destroy any non-directory file named '\s-1META\-INF\s0' in the current directory. If META\-INF/container.xml already exists, it will rename that file to META\-INF/container.xml.backup. .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP "$opffile" 4 .el .IP "\f(CW$opffile\fR" 4 .IX Item "$opffile" The \s-1OPF\s0 filename (and path, if necessary) to use in the container. If not specified, looks for a sole \s-1OPF\s0 file in the current working directory. Fails if more than one is found. .PP \fIReturn values\fR .IX Subsection "Return values" .IP "Returns a twig representing the container data if successful, undef otherwise" 4 .IX Item "Returns a twig representing the container data if successful, undef otherwise" .ie n .SS """create_epub_mimetype()""" .el .SS "\f(CWcreate_epub_mimetype()\fP" .IX Subsection "create_epub_mimetype()" Creates a file named 'mimetype' in the current working directory containing 'application/epub+zip' (no trailing newline) .PP Destroys and overwrites that file if it exists. .PP Returns the mimetype string if successful, undef otherwise. .ie n .SS """debug($level,@message)""" .el .SS "\f(CWdebug($level,@message)\fP" .IX Subsection "debug($level,@message)" Prints a debugging message to \f(CW\*(C`STDERR\*(C'\fR if package variable \f(CW$debug\fR is greater than or equal to \f(CW$level\fR. A trailing newline is appended, and should not be part of \f(CW@message\fR. .PP Returns true or dies. .ie n .SS """excerpt_line($text)""" .el .SS "\f(CWexcerpt_line($text)\fP" .IX Subsection "excerpt_line($text)" Takes as an argument a list of text pieces that will be joined. If the joined length is less than 70, all of the joined text is returned. .PP If the joined length is greater than 70, the return string is the first 30 characters followed by \f(CW\*(Aq [...] \*(Aq\fR followed by the last 30 characters. .ie n .SS """find_in_path($pattern,@extradirs)""" .el .SS "\f(CWfind_in_path($pattern,@extradirs)\fP" .IX Subsection "find_in_path($pattern,@extradirs)" Searches through \f(CW$ENV{PATH}\fR (and optionally any additional directories specified in \f(CW@extradirs\fR) for the first regular file matching \f(CW$pattern\fR. \f(CW$pattern\fR itself can take two forms: if passed a \f(CW\*(C`qr//\*(C'\fR regular expression, that expression is used directly. If passed any other string, that string will be used for a case-insensitive exact match where the extension '.bat', '.com', or \&'.exe' is optional (i.e. the final pattern will be \&\f(CW\*(C`qr/^ $pattern (\e.bat|\e.com|\e.exe)? $/ix\*(C'\fR). .PP Returns the first match found, or undef if there were no matches or if no pattern was specified. .ie n .SS """find_links($filename)""" .el .SS "\f(CWfind_links($filename)\fP" .IX Subsection "find_links($filename)" Searches through a file for href and src attributes, and returns a list of unique links with any named anchors removed (e.g. 'myfile.html#part7' returns as just 'myfile.html'). If no links are found, or the file does not exist, returns undef. .PP Does not check to see if the links are local. Requires that links be surrounded by double quotes, not single or left bare. Assumes that any link will not be broken across multiple lines, so it will (for example) fail to find: .PP .Vb 2 \& .Ve .PP though it can find: .PP .Vb 2 \& .Ve .PP This also does not distinguish between local files and remote links. .ie n .SS """find_opffile()""" .el .SS "\f(CWfind_opffile()\fP" .IX Subsection "find_opffile()" Attempts to locate an \s-1OPF\s0 file, first by calling \&\*(L"\fBget_container_rootfile()\fR\*(R" to check the contents of \&\f(CW\*(C`META\-INF/container.xml\*(C'\fR, and then by looking for a single file with the extension \f(CW\*(C`.opf\*(C'\fR in the current working directory. .PP Returns the filename of the \s-1OPF\s0 file, or undef if nothing was found. .ie n .SS """fix_datestring($datestring)""" .el .SS "\f(CWfix_datestring($datestring)\fP" .IX Subsection "fix_datestring($datestring)" Takes a date string and attempts to convert it to the limited subset of \s-1ISO8601\s0 allowed by the \s-1OPF\s0 standard (\s-1YYYY,\s0 YYYY-MM, or YYYY-MM-DD). .PP In the special case of finding \s-1MM/DD/YYYY,\s0 it assumes that it was a Mobipocket-mangled date, and not only converts it, but will strip the day information if the day is '01', and both the month and day information if both month and day are '01'. This is because Mobipocket Creator enforces a complete \s-1MM/DD/YYYY\s0 even if the month and day aren't known, and it is common practice to use 01 for an unknown value. .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP "$datestring" 4 .el .IP "\f(CW$datestring\fR" 4 .IX Item "$datestring" A date string in a format recognizable by Date::Manip .PP \fIReturns \f(CI$fixeddate\fI\fR .IX Subsection "Returns $fixeddate" .ie n .IP "$fixeddate : the corrected string, or undef on failure" 4 .el .IP "\f(CW$fixeddate\fR : the corrected string, or undef on failure" 4 .IX Item "$fixeddate : the corrected string, or undef on failure" .ie n .SS """get_container_rootfile($container)""" .el .SS "\f(CWget_container_rootfile($container)\fP" .IX Subsection "get_container_rootfile($container)" Opens and parses an OPS/epub container, extracting the 'full\-path' attribute of element 'rootfile' .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP "$container" 4 .el .IP "\f(CW$container\fR" 4 .IX Item "$container" The \s-1OPS\s0 container to parse. Defaults to 'META\-INF/container.xml' .PP \fIReturn values\fR .IX Subsection "Return values" .IP "Returns a string containing the rootfile on success, undef on failure." 4 .IX Item "Returns a string containing the rootfile on success, undef on failure." .ie n .SS """hashvalue_key_self(\e%hash, $modifier)""" .el .SS "\f(CWhashvalue_key_self(\e%hash, $modifier)\fP" .IX Subsection "hashvalue_key_self(%hash, $modifier)" Takes as an argument a hash reference and an optional modifier and inserts a new key for every value in that hash if no such key already exists. .PP If the modifer is set to 'lc' or 'uc', the value is either lowercased or uppercased respectively before it is used as a key. .PP Croaks if the first argument is not a hashref, or if an invalid modifier string is used. .ie n .SS """hexstring($bindata)""" .el .SS "\f(CWhexstring($bindata)\fP" .IX Subsection "hexstring($bindata)" Takes as an argument a scalar containing a sequence of binary bytes. Returns a string converting each octet of the data to its two-digit hexadecimal equivalent. There is no leading \*(L"0x\*(R" on the string. .ie n .SS """print_memory($label)""" .el .SS "\f(CWprint_memory($label)\fP" .IX Subsection "print_memory($label)" Checks /proc/$PID/statm and prints out a line to \s-1STDERR\s0 showing the current memory usage. This is a debugging tool that will likely fail to do anything useful on a system without a /proc system compatible with Linux. .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP "$label" 4 .el .IP "\f(CW$label\fR" 4 .IX Item "$label" If defined, will be output along with the memory usage. .PP Returns 1 on success, undef otherwise. .ie n .SS """split_metadata($metahtmlfile, $metafile)""" .el .SS "\f(CWsplit_metadata($metahtmlfile, $metafile)\fP" .IX Subsection "split_metadata($metahtmlfile, $metafile)" Takes a psuedo-HTML containing one or more ... blocks and splits out the metadata blocks into an \s-1XML\s0 file ready to be used as an \s-1OPF\s0 document. The input \s-1HTML\s0 file is rewritten without the metadata. .PP If \f(CW$metafile\fR (or the temporary HTML-only file created during the split) already exists, it will be moved to filename.backup. .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP "$metahtmlfile" 4 .el .IP "\f(CW$metahtmlfile\fR" 4 .IX Item "$metahtmlfile" The filename of the pseudo-HTML file .ie n .IP "$metafile (optional)" 4 .el .IP "\f(CW$metafile\fR (optional)" 4 .IX Item "$metafile (optional)" The filename to write out any extracted metadata. If not specified, will default to the basename of \f(CW$metahtmlfile\fR with '.opf' appended. .PP Returns the filename the metadata was written to, or undef if no metadata was found. .ie n .SS """split_pre($htmlfile,$outfilebase)""" .el .SS "\f(CWsplit_pre($htmlfile,$outfilebase)\fP" .IX Subsection "split_pre($htmlfile,$outfilebase)" Splits 
...
blocks out of a source \s-1HTML\s0 file into their own separate \s-1HTML\s0 files including required headers. Each block will be written to its own file following the naming format \&\f(CW\*(C`$outfilebase\-###.html\*(C'\fR, where ### is a three-digit number beginning at 001 and incrementing for each block found. If \f(CW$outfilebase\fR is not specified, it defaults to the basename of \f(CW$htmlfile\fR with \&\*(L"\-pre\-###.html\*(R" appended. The .PP Returns a list containing all filenames created. .ie n .SS """strip_script(%args)""" .el .SS "\f(CWstrip_script(%args)\fP" .IX Subsection "strip_script(%args)" Strips any blocks out of a \s-1HTML\s0 file. .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP """infile""" 4 .el .IP "\f(CWinfile\fR" 4 .IX Item "infile" Specifies the input file. If not specified, the sub croaks. .ie n .IP """outfile""" 4 .el .IP "\f(CWoutfile\fR" 4 .IX Item "outfile" Specifies the output file. If not specified, it defaults to \f(CW\*(C`infile\*(C'\fR (i.e. the input file is overwritten). .ie n .IP """noscript""" 4 .el .IP "\f(CWnoscript\fR" 4 .IX Item "noscript" If set to true, the sub will strip blocks as well. .ie n .SS """system_result($caller,$retval,@syscmd)""" .el .SS "\f(CWsystem_result($caller,$retval,@syscmd)\fP" .IX Subsection "system_result($caller,$retval,@syscmd)" Checks the result of a system call and croak on failure with an appropriate message. For this to work, it \s-1MUST\s0 be used as the line immediately following the system command. .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP "$caller" 4 .el .IP "\f(CW$caller\fR" 4 .IX Item "$caller" The calling function (used in output message) .ie n .IP "$retval" 4 .el .IP "\f(CW$retval\fR" 4 .IX Item "$retval" The return value of the system command .ie n .IP "@syscmd" 4 .el .IP "\f(CW@syscmd\fR" 4 .IX Item "@syscmd" The array passed to the system call .PP \fIReturn Values\fR .IX Subsection "Return Values" .PP Returns 0 on success .PP Croaks on failure. .ie n .SS """system_tidy_xhtml($infile,$outfile)""" .el .SS "\f(CWsystem_tidy_xhtml($infile,$outfile)\fP" .IX Subsection "system_tidy_xhtml($infile,$outfile)" Runs tidy on a \s-1XHTML\s0 file semi-safely (using a secondary file) .PP Converts \s-1HTML\s0 to \s-1XHTML\s0 if necessary .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP "$infile" 4 .el .IP "\f(CW$infile\fR" 4 .IX Item "$infile" The filename to tidy .ie n .IP "$outfile" 4 .el .IP "\f(CW$outfile\fR" 4 .IX Item "$outfile" The filename to use for tidy output if the safety condition to overwrite the input file isn't met. .Sp Defaults to \f(CW\*(C`infile\-tidy.ext\*(C'\fR if not specified. .PP \fIGlobal variables used\fR .IX Subsection "Global variables used" .ie n .IP "$tidycmd" 4 .el .IP "\f(CW$tidycmd\fR" 4 .IX Item "$tidycmd" the location of the tidy executable .ie n .IP "$tidyxhtmlerrors" 4 .el .IP "\f(CW$tidyxhtmlerrors\fR" 4 .IX Item "$tidyxhtmlerrors" the filename to use to output errors .ie n .IP "$tidysafety" 4 .el .IP "\f(CW$tidysafety\fR" 4 .IX Item "$tidysafety" the safety factor to use (see \s-1CONFIGURABLE GLOBAL VARIABLES,\s0 above) .PP \fIReturn Values\fR .IX Subsection "Return Values" .PP Returns the return value from tidy .IP "0 \- no errors" 4 .IX Item "0 - no errors" .PD 0 .IP "1 \- warnings only" 4 .IX Item "1 - warnings only" .IP "2 \- errors" 4 .IX Item "2 - errors" .IP "Dies horribly if the return value is unexpected" 4 .IX Item "Dies horribly if the return value is unexpected" .PD .ie n .SS """system_tidy_xml($infile,$outfile)""" .el .SS "\f(CWsystem_tidy_xml($infile,$outfile)\fP" .IX Subsection "system_tidy_xml($infile,$outfile)" Runs tidy on an \s-1XML\s0 file semi-safely (using a secondary file) .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP "$infile" 4 .el .IP "\f(CW$infile\fR" 4 .IX Item "$infile" The filename to tidy .ie n .IP "$outfile (optional)" 4 .el .IP "\f(CW$outfile\fR (optional)" 4 .IX Item "$outfile (optional)" The filename to use for tidy output if the safety condition to overwrite the input file isn't met. .Sp Defaults to \f(CW\*(C`infile\-tidy.ext\*(C'\fR if not specified. .PP \fIGlobal variables used\fR .IX Subsection "Global variables used" .ie n .IP "$tidycmd" 4 .el .IP "\f(CW$tidycmd\fR" 4 .IX Item "$tidycmd" the name of the tidy executable .ie n .IP "$tidyxmlerrors" 4 .el .IP "\f(CW$tidyxmlerrors\fR" 4 .IX Item "$tidyxmlerrors" the filename to use to output errors .ie n .IP "$tidysafety" 4 .el .IP "\f(CW$tidysafety\fR" 4 .IX Item "$tidysafety" the safety factor to use (see \s-1CONFIGURABLE GLOBAL VARIABLES,\s0 above) .PP \fIReturn values\fR .IX Subsection "Return values" .PP Returns the return value from tidy .IP "0 \- no errors" 4 .IX Item "0 - no errors" .PD 0 .IP "1 \- warnings only" 4 .IX Item "1 - warnings only" .IP "2 \- errors" 4 .IX Item "2 - errors" .IP "Dies horribly if the return value is unexpected" 4 .IX Item "Dies horribly if the return value is unexpected" .PD .ie n .SS """trim""" .el .SS "\f(CWtrim\fP" .IX Subsection "trim" Removes any whitespace characters from the beginning or end of every string in \f(CW@list\fR (also works on scalars). .PP .Vb 6 \& trim; # trims $_ inplace \& $new = trim; # trims (and returns) a copy of $_ \& trim $str; # trims $str inplace \& $new = trim $str; # trims (and returns) a copy of $str \& trim @list; # trims @list inplace \& @new = trim @list; # trims (and returns) a copy of @list .Ve .PP This was shamelessly copied from japhy's example at perlmonks.org: .PP http://www.perlmonks.org/?node_id=36684 .PP If needed for large lists, it would probably be better to use String::Strip. .ie n .SS """twigelt_create_uuid($gi)""" .el .SS "\f(CWtwigelt_create_uuid($gi)\fP" .IX Subsection "twigelt_create_uuid($gi)" Creates an unlinked element with the specified gi (tag), and then assigns it the id and scheme attributes '\s-1UUID\s0'. .PP \fIArguments\fR .IX Subsection "Arguments" .ie n .IP "$gi : The gi (tag) to use for the element" 4 .el .IP "\f(CW$gi\fR : The gi (tag) to use for the element" 4 .IX Item "$gi : The gi (tag) to use for the element" Default: 'dc:identifier' .PP Returns the element. .ie n .SS """twigelt_detect_duplicate($element1, $element2)""" .el .SS "\f(CWtwigelt_detect_duplicate($element1, $element2)\fP" .IX Subsection "twigelt_detect_duplicate($element1, $element2)" Takes two twig elements and returns 1 if they have the same \s-1GI\s0 (tag), text, and attributes, but are not actually the same element. The \s-1GI\s0 comparison is case-insensitive. The others are case-sensitive. .PP Returns 0 otherwise. .PP Croaks if passed anything but twig elements. .ie n .SS """twigelt_fix_oeb12_atts($element)""" .el .SS "\f(CWtwigelt_fix_oeb12_atts($element)\fP" .IX Subsection "twigelt_fix_oeb12_atts($element)" Checks the attributes in a twig element to see if they match \s-1OPF\s0 names with an opf: namespace, and if so, removes the namespace. Used by the \&\fBfix_oeb12()\fR method. .PP Takes as a sole argument a twig element. .PP Returns that element with the modified attributes, or undef if the element didn't exist. Returns an unmodified element if both att and opf:att exist. .ie n .SS """twigelt_fix_opf20_atts($element)""" .el .SS "\f(CWtwigelt_fix_opf20_atts($element)\fP" .IX Subsection "twigelt_fix_opf20_atts($element)" Checks the attributes in a twig element to see if they match \s-1OPF\s0 names, and if so, prepends the \s-1OPF\s0 namespace. Used by the \fBfix_opf20()\fR method. .PP Takes as a sole argument a twig element. .PP Returns that element with the modified attributes, or undef if the element didn't exist. .ie n .SS """twigelt_is_author($element)""" .el .SS "\f(CWtwigelt_is_author($element)\fP" .IX Subsection "twigelt_is_author($element)" Takes as an argument a twig element. Returns true if the element is a dc:creator (case-insensitive) with either a opf:role=\*(L"aut\*(R" or role=\*(L"aut\*(R" attribute defined. Returns undef otherwise, and also if the element has no text. .PP Croaks if fed no argument, or fed an argument that isn't a twig element. .PP Intended to be used as a twig search condition. .PP \fIExample\fR .IX Subsection "Example" .PP .Vb 1 \& my @elements = $ebook\->twigroot\->descendants(\e&twigelt_is_author); .Ve .ie n .SS """twigelt_is_isbn($element)""" .el .SS "\f(CWtwigelt_is_isbn($element)\fP" .IX Subsection "twigelt_is_isbn($element)" Takes as an argument a twig element. Returns true if the element is a dc:identifier (case-insensitive) where any of the id, opf:scheme, or scheme attributes start with 'isbn', '\-isbn', 'eisbn', or 'e\-isbn' (again case-insensitive). .PP Returns undef otherwise, and also if the element has no text. .PP Croaks if fed no argument, or fed an argument that isn't a twig element. .PP Intended to be used as a twig search condition. .PP \fIExample\fR .IX Subsection "Example" .PP .Vb 1 \& my @elements = $ebook\->twigroot\->descendants(\e&twigelt_is_isbn); .Ve .ie n .SS """twigelt_is_knownuid($element)""" .el .SS "\f(CWtwigelt_is_knownuid($element)\fP" .IX Subsection "twigelt_is_knownuid($element)" Takes as an argument a twig element. Returns true if the element is a dc:identifier (case-insensitive) element with an \f(CW\*(C`id\*(C'\fR attribute matching the known IDs of proper unique identifiers suitable for a package-id (also case-insensitive). Returns undef otherwise. .PP Croaks if fed no argument, or fed an argument that isn't a twig element. .PP Intended to be used as a twig search condition. .PP \fIExample\fR .IX Subsection "Example" .PP .Vb 1 \& my @elements = $ebook\->twigroot\->descendants(\e&twigelt_is_knownuid); .Ve .ie n .SS """usedir($dir)""" .el .SS "\f(CWusedir($dir)\fP" .IX Subsection "usedir($dir)" Changes the current working directory to the one specified, creating it if necessary. .PP Returns the current working directory before the change. If no directory is specified, returns the current working directory without changing anything. .PP Croaks on any failure. .ie n .SS """userconfigdir()""" .el .SS "\f(CWuserconfigdir()\fP" .IX Subsection "userconfigdir()" Returns the directory in which user configuration files and helper programs are expected to be found, creating that directory if it does not exist. Typically, this directory is \f(CW"$ENV{HOME}/.ebooktools"\fR, but on MSWin32 systems if that directory does not already exist, \&\f(CW"$ENV{USERPROFILE}/ApplicationData/EBook\-Tools"\fR is returned (and potentially created) instead. .PP If \f(CW$ENV{HOME}\fR (and \f(CW$ENV{USERPROFILE}\fR on MSWin32) are either not set or do not point to a directory, the sub returns undef. .ie n .SS """ymd_validate($year,$month,$day)""" .el .SS "\f(CWymd_validate($year,$month,$day)\fP" .IX Subsection "ymd_validate($year,$month,$day)" Make sure month and day have valid values. Return the passed values if they are, return 3 undefs if not. Testing of month or day can be skipped by passing undef in that spot. .SH "BUGS AND LIMITATIONS" .IX Header "BUGS AND LIMITATIONS" .IP "\(bu" 4 \&\fBfix_links()\fR could be improved to download remote URIs instead of ignoring them. .IP "\(bu" 4 \&\fBfix_links()\fR needs to check the links under .IP "\(bu" 4 \&\fBfix_links()\fR needs to be redone with HTML::TreeBuilder or Mojo::DOM to avoid the weakness with newlines between attribute names and values .IP "\(bu" 4 Need to implement \fBfix_tours()\fR that should collect the related elements and delete the parent if none are found. Empty elements aren't allowed. .IP "\(bu" 4 \&\fBfix_languages()\fR needs to convert language names into \s-1IANA\s0 language codes. .IP "\(bu" 4 \&\fBset_language()\fR should add a warning if the text isn't a valid \&\s-1IANA\s0 language code. .IP "\(bu" 4 \&\s-1NCX\s0 generation only generates from the spine. It should be possible to use a \s-1TOC\s0 html file for generation instead. In the long term, it should be possible to generate one from the headers and anchors in arbitrary \s-1HTML\s0 files. .IP "\(bu" 4 It might be better to use sysread / index / substr / syswrite in &split_metadata to handle the split in 10k chunks, to avoid massive memory usage on large files. .Sp This may not be worth the effort, since the average size for most books is less than 500k, and the largest books are rarely over 10M. .IP "\(bu" 4 The only generator is currently for .epub books. \s-1PDF,\s0 PalmDoc, Mobipocket, Plucker, and iSiloX are eventually planned. .IP "\(bu" 4 Although I like keeping warnings associated with the ebook object, it may be better to throw exceptions on errors and catch them later. This probably won't be implemented until it bites someone who complains, though. .IP "\(bu" 4 Unit tests are incomplete .SH "AUTHOR" .IX Header "AUTHOR" Zed Pobre .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright 2008\-2013 Zed Pobre .PP Licensed to the public under the terms of the \s-1GNU GPL,\s0 version 2