====================
ISBN-13 improvements
====================

:authors: Vidar Langseid
:Version: 0.2


This spesification addresses certain limitations in the ISBN-13 implemenation
in eZ Publish. Some  improvents could also be applied to the ISBN-10
implemenation but such improvements are not evaluated and addressed in this
specification since ISBN-10 now is obseleted by the industry.

Change to the ISBN datatype on the class level
===============================================
When adding new ISBN datatypes to a class, "ISBN-13 format" should be enabled
by default

Changes to the ISBN datatype on the object level
===============================================

Autoconverting from ISBN-10 to ISBN-13
--------------------------------------
If user enters an ISBN number in ISBN-10 format AND "ISBN-13 format" is enabled
for the attribute, the system should automaticly convert it to ISBN-13

Entring ISBN-13 values with or without hyphens '-'
--------------------------------------------------
Current implementation accepts hyphens everywhere. This should be changed.
When entering ISBN-13 numbers, user may choose if he wants to include the
hyphens or not. The system should automatically correct misplaced hyphens
without any warnings.

Placement of hyphens
--------------------
An ISBN-13 number typically looks like:
978-824-73-0904-6

The hyphens separates the different fields:
- Prefix element
- Registration group element
- Registrant element
- Publication element
- Check digit

The Prefix element have a fixed length of 3 digits, while the Check digit have
a fixed length of 1 digit. The other elements may vary in length.
The algoritm for finding the element lengths and to place the hyphens are
specified here:
"http://www.isbn-international.org/en/download/2005 ISBN Users' Manual
International Edition.pdf"

Deriving the registration group and internal structure
------------------------------------------------------
Each registration group element belongs to a country or area and may have their
own rules for the internal structure for Registrant and Publication element.

This need to be calculated based on the distribution of ranges each region has.
The different ranges need to be stored in order to calculate the correct
placement to each hyphens in the internal structure. The ranges may be updated
and should be checked on a regular basis with the International ISBN Agency and
updated in eZ Publish. The different ranges will be stored in the database and
accessible from the setup as a setting for all ISBN datatypes.

ISBN-13 numbers stored in database
----------------------------------
In current implementation, ISBN-13 numbers are stored in database in the same
way as user entered them (with or without hyphens). This must be changed

The number should be stored in the database with the hyphens at the correct
place.
For instance: 978-82-573-0904-6

Storing the ISBN-13 number without hyphens or with hyphens at incorrect
possitions should NOT happend.

Viewing ISBN-13 numbers with or without hyphens
-----------------------------------------------
As stated previously in this spec, ISBN-13 numbers should be stored with
hyphens in the database. However it must be possible and convenient to view the
ISBN-13 number both with and without hyphens from a template.

This template code should display the ISBN-13 number with hyphens:
{$attribute.content.value}
For backwards compatibility, this should also work:
{$attribute.data_text}

This template code should display the ISBN-13 number without hyphens:
{$attribute.content.value_without_hyphens}

For the record: The view template for the ISBN datatype should continue showing
the "ISBN" prefix:
ISBN 978-82-573-0904-6


Script to convert ISBN-10 data to ISBN-13
=========================================
A script should be made to convert ISBN-10 to ISBN-13

convert2isbn13.php [--class-id=CLASSID] [--attribute-id=ATTRIBUTEID]
[--all-classes]

CLASSID and ATTRIBUTEID may be either be numeric number or attribute identifier
(string)

If only --class-id paramter is given, all ISBN attributes in that class will be
converted.

If --attribute-id is given, that attribute will be converted to ISBN-13

If both --class-id and --attribute-id is given, the script should check that
attribute-id is truely a attribute in the class spesified by class-id.

If only --attribute-id is given and this is given as identfier(string) and not
number, the script should ensure that multiple attributes with the same
identifier does not exists in the system.

If --all-classes is given, all ISBN attributes in database will be converted

If --force is given, attribute will be converted even though "ISBN-13 format"
is not enabled for the attribute. Script will then enable "ISBN-13 format" for
the attribute

If you run the script and try to convert a datatype where "ISBN-13 format" is
not enabled, the script should warn about this. The script should also abort
execution unless the "--force" option is given

After converting an attribute, script must ensure that "ISBN-13 format" is
enabled for the attribute at the class level.

The script should not create new versions of the objects it alters. Instead,
ISBN values for all versions of the object should be converted. This will
ensure that all ISBN values in the database is stored correctly and
consistently.

If the script is run on a attribute which is already converted to ISBN-13, it
should ensure that hyphens are stored at the correct place. Earlier versions of
eZ Publish don't ensure this so running this script would be mandatory when
users using ISBN-13 are upgrading their eZ Publish installation.

If you enable the "ISBN-13 format" on a attribute which contains numbers in
ISBN-10 format, this scripts needs to be run.

Please not that there is no script to convert ISBN-13 numbers back to ISBN-10.
This is considered a no-issues since ISBN-10 should not be used anymore,
according to international standards.


Documentation issues
====================
Documentation of the convert2isbn13.php needs to be written
Documentation of ISBN-13 datatype must inform about:
 - convert2isbn13.php needs to be run after "ISBN-13 format" is enabled
 - if "ISBN-13 format" is disabled, there is no script available for converting
   all data back to ISBN-10 format
 - Documentation should explain how to get data from a template
   ({$attribute.content.value_without_hyphens} and {$attribute.content.value})

