idml 0.1.0

data/reference-docs/spec/01_abstract/00_index.md

@@ -0,0 +1,3 @@
+# 1 Abstract
+
+IDML is an XML representation of an In  Design document or components. This document describes the structure of IDML files, the XML schema for IDML validation, and provides examples of IDML file content. This document has been updated for IDML version 8.0, which corresponds to InDesign CS6. For the list of content updates in this version, refer to 'Appendix E. Update List of IDML 8.0' .

data/reference-docs/spec/02_introduction/00_index.md

@@ -0,0 +1,11 @@
+# 2 Introduction
+
+IDML is an XML-based format that is capable of fully describing an In  Design document, and is the interchange format for Adobe In  Design CS4 documents. By using an XML representation of text and graphic frames, stories, and other aspects of an In  Design layout, IDML gives you a way to create and modify In  Design documents using tools outside the In  Design application.
+
+Like its precursor INX, IDML is a Document Object Model (DOM) representation of In  Design documents, and is based on the In  Design scripting object model. INX stands for 'In  Design Interchange' and was introduced in In  Design CS2 to support the ability to save documents for use in a previous version. INX will continue to be used for backward compatibility for In  Design versions prior to In  Design CS4; IDML will be used for backward compatibility between In  Design CS4 and future versions.
+
+It was quite difficult to write or edit the INX format, as it was designed to be written and consumed by In  Design alone. IDML addresses requests by third party developers and system integrators to make INX more readable and to make it easier to change and assemble In  Design documents using XML tools. By using IDML, you can realize gains in performance, convenience, and flexibility.
+
+IDML is also like INX in that In  Design uses the format for a variety of other purposes, such as library items, In  Design snippets (standalone document fragments saved using IDML markup), and In  Copy assignments and stories.
+
+It is important to note that while IDML is an XML format, you do not necessarily need to make use of In  Design's XML features in an IDML document. In fact, we expect that some users will prefer to keep all XML processing outside of In  Design for a variety of reasons, including performance and the limitations of the implementation of XML in In  Design.

data/reference-docs/spec/03_terminology/00_index.md

@@ -0,0 +1,7 @@
+# 3 Terminology
+
+When you open an IDML document in In  Design, the XML elements in the document are converted to objects-both objects in the resulting In  Design document and objects in the InDesign scripting object model. Because of this, we need to be very careful when using certain
+
+terms in this specification. When we say 'object,' for example, are we referring to the XML element or the In  Design object that the XML element corresponds to after the IDML file has been opened? The same question applies to the XML attributes and elements that specify properties of In  Design objects.
+
+In this specification, we'll use the phrase XML element when we're specifically referring to an element in an IDML file, and we'll use XML attribute to refer to an attribute of an XML element. When we use the terms object and property , we're referring to an entity in an In  Design document (and in the In  Design scripting document object model).

data/reference-docs/spec/04_inx_idml_and_in_design_scripting/00_index.md

@@ -0,0 +1,48 @@
+# 4 INX, IDML, and In  Design Scripting
+
+INX, the precursor to IDML, was introduced to give In  Design the ability to save a document for use in a previous version. Rather than write a complicated and error-prone binary file conversion plug-in, we decided to use In  Design's scripting features. When In  Design exports to INX or IDML, we serialize objects and properties from the scripting DOM of an In  Design document to an XML file. When we open an INX or IDML document, In  Design constructs layout objects, sets preferences, enters text, and applies formatting to produce an In  Design document.
+
+IDML will continue to be built on and reflect the scripting DOM view of the In  Design object model. The scripting system provides several vital benefits:
+
+- A high-level isolation from the details and changes in the low-level In  Design object model.
+- Well-documented and easily understood architecture for extending the object model and the file format to add third-party data. There is also an existing policy and procedure for developers to register their objects and attributes to ensure that the object names they add are unique within the scripting DOM.
+- Significant level of object and property parameter validation and error checking.
+- High level versioning support and a well-defined mechanism for adding, deleting, or modifying items.
+
+IDML differs from the scripting DOM in the following ways:
+
+- Scripting events (methods) are not included in IDML document.
+- IDML requires that some elements and attributes appear in certain order, while scripting DOM can be viewed as random access.
+- Some objects and properties that are included in IDML may not be available in scripting object models for Apple  Script, Java  Script, VBScript, and vice versa.
+- In some cases, property values that are the same as default values are not written out to IDML.
+
+The following example shows the close connection between scripting and IDML:
+
+## Script (Java  Script):
+
+```
+//Where my  Rectangle is a reference to a rectangle: my Rectangle.stroke  Weight = .5; my Rectangle.corner  Option = Corner Options.bevel  Corner; IDML: <Rectangle Stroke  Weight=".5" Corner Option="Bevel  Corner" .../>
+```
+
+Given the close connection of IDML to In  Design scripting, the In  Design scripting documentation and example scripts provide a great way to learn about the format. The scripting object model is also exposed to scripting clients, and can be viewed from script editors (such as the Adobe Extend  Script Toolkit) for any of the supported scripting languages.
+
+
+## Table of Contents
+- [4.1 Dynamic Object Model](4_1_dynamic_object_model.md)
+- [4.2 IDML and Third Party Data](4_2_idml_and_third_party_data.md)
+
+
+## 4.1 Dynamic Object Model
+
+It is important to note that In  Design's scripting object model is dynamic, and changes based on the active set of plug-ins. If you add plug-ins that support In  Design scripting, objects, properties, enumerations, and methods can appear in the scripting object model, and new objects and properties may appear in the exported IDML. In addition, removing or disabling plug-ins can change the scripting object model and, therefore, the XML elements written to an IDML file.
+
+
+## 4.2 IDML and Third Party Data
+
+IDML supports the inclusion of new scripting objects and properties added by In  Design plug-ins. Because IDML is built on the In  Design scripting object model, any features added by plug-ins that support In  Design scripting can be included in the IDML package.
+
+That said, IDML does not guarantee round-trip of data added to an In  Design document by third party plug-ins. If the third party plug-in does not implement scripting at all, or if the scripting support for the plug-in is not complete, the data will not be included when you export as IDML.
+
+If the IDML file calls for a plug-in that is not currently installed, In  Design will ignore the plugin data (i.e., omit it from the InDesign file created by opening the IDML document) and will not include it in a subsequent IDML export of the file. Note that this differs from InDesign's behavior when opening InDesign binary files, where third-party data is maintained when the plug-ins are missing (refer to the In  Design documentation for a more complete description of this behavior).
+
+Since IDML is an XML format, you can add your own XML elements the XML files in the IDML package. Note, however, that In  Design will ignore XML elements that do not exist in the IDML schema when opening the IDML file, and that the data will not be preserved in the converted InDesign binary document (and will therefore not be included in future IDML export from that document).

data/reference-docs/spec/05_uses_for_idml/00_index.md

@@ -0,0 +1,13 @@
+# 5 Uses for IDML
+
+IDML provides a way for InDesign layouts to interoperate with XML based formats and technologies. Documents can be created and manipulated in IDML format and can then be opened and interpreted using InDesign.
+
+We've designed IDML to make it a key part of automated workflows. Using IDML, you can:
+
+- Generate or modify IDML documents or document elements using data from databases or other data sources (programmatic assembly).
+- Reuse parts of IDML documents, or break a document into components that can be used in a development environment (programmatic disassembly).
+- Transform document elements using XSLT.
+- Find data in In  Design documents using XPath or XQuery.
+- Use source control to manage creative content, or to compare two versions of a design.
+
+IDML is intended for consumption by In  Design-family applications, including In  Design, In  Copy, and In  Design Server. IDML is not intended as an interchange format for use with applications outside the In  Design family of products, and does not attempt to write or structure In  Design content in a manner that is compatible with other XML layout formats (such as Mars, XSL-FO, or SVG). It is, however, possible to transform IDML content into these formats by applying XSLT transformations to the IDML structures. Writing such a transformation is a very large task, and is beyond the scope of this specification.

data/reference-docs/spec/06_idml_design_goals/00_index.md

@@ -0,0 +1,18 @@
+# 6 IDML Design Goals
+
+The primary design goals of IDML are as follows:
+
+- Completeness: Any object, property, or preference that can appear in an In  Design document can be represented in IDML. Complete 'round trip' compatibility is expected of IDML files.
+- Readability: The IDML format is human-readable, and should be easily understood by a user with basic knowledge of the page layout. Representations of In  Design elements-spreads, TextFrames, stories, and colors, for example-are found inside the XML structure in the same location as they appear in a document. A TextFrame inside a group, for example, appears inside the group element, which, in turn is inside a spread element.
+- For ease of programmatic assembly and disassembly, IDML is designed to be read and written by virtually any program or tool capable of reading and writing XML. Relative to INX, IDML files are easier to process using external tools, while maintaining the same full coverage of the In  Design object model.
+- Robustness: The In  Design mechanisms for reading and interpreting IDML will be robust in the face of mistakes and eliminate fatal consequences. A Relax NG schema definition for
+
+IDML will be provided for validation to help customers and workflow developers discover potential errors in their programmatically assembled or edited files. Since even validated files can contain unknown objects, errors will be reported during the interpretation process to assist in debugging.
+
+- Backward compatibility: A user will be able to take an IDML file generated for version X and open it in version X-1 (provided X-1 supports IDML). In  Design CS4 is the first version to provide IDML support. In  Design CS4 will support the INX format for compatibility with InDesign CS3.
+- Performance: IDML aims to maintain or exceed the performance of INX in In  Design CS4.
+- Improvements over INX: IDML offers the following advantages over INX (this is not an exhaustive list):
+- Provides a published format specification.
+- Avoids  obscure  element  and  attribute  ordering,  relationships,  and  processing  constraints contained in the In  Design export/import code.
+- Provides an XML schema (Relax NG) for validation.
+- Eliminates the use of processing instructions in text content for text object placement

data/reference-docs/spec/07_idml_design_approaches/00_index.md

@@ -0,0 +1,59 @@
+# 7 IDML Design Approaches
+
+To recognize our design goals for IDML, we have adopted a series of design philosophies, which we'll discuss in the following sections.
+
+## 7.1 Separate Content for Efficient Processing
+
+In  Design is often part of workflows where documents are broken into pieces so that they might be worked on in parallel. In a magazine production process, for example, sections, articles, or individual spreads might be given to different graphic artists or layout staff; stories can be given to different writers and editors. The same thing can be true for the process of assembling an IDML document. Stories might be populated with text from RSS feeds; informational graphics on a given spread might be generated from spreadsheet data.
+
+In addition, In  Design documents contain a large number of entities that might be standardized across an organization or publication. Document preferences, styles, fonts, and colors, for example, might be common to all production processes for a particular job. These preferences can be stored in separate XML files and added to an IDML package.
+
+All of the parts of an IDML file are put together in a Zip-compressed archive to represent one InDesign document. Inside this container, a specific 'master' file defines the relationships between the component files included in the container.
+
+## 7.2 Maximize Compatibility with In  Design
+
+IDML reflects the scripting DOM view of an In  Design document. It was designed to maximize compatibility and consistency with the In  Design binary file and represent In  Design document as accurately as possible.
+
+IDML files do not retain any view or history data of the document; the intent is to represent the appearance and content of the document in XML.
+
+Being able to convert back and forth between the In  Design binary file format and IDML is a requirement. In most cases, we must convert between IDML and In  Design binary representations, and each representation should be able to carry extensions added to the other.
+
+There are many workflows involving conversions between IDML format and In  Design binary format. We also want to encourage a variety of uses that we may not have envisioned. Some general classes of workflows include following:
+
+- IDML documents can be constructed from information in a database or from a wire feed using XML tools, and then opened in In  Design for further processing.
+- An In  Design document can be exported to IDML for use as a template outside of In  Design. The IDML template can be modified using XML tools, then converted back to In  Design.
+- An In  Design document can be exported to an IDML format file, which can be opened and saved in previous version of In  Design.
+
+When converting between formats, it is not necessary to maintain binary equivalence. We only need to guarantee a high percentage of visual fidelity.
+
+## 7.3 Maximize Independence of XML Elements
+
+In  Design objects represented as XML elements in IDML are intended to be independent whenever possible. For example, to add, change, or delete a rectangle, you should be able to manipulate the rectangle element in a specific spread file. Other object types are more complicated, however. A TextFrame element, for example, must include a reference to the story containing the text shown in the TextFrame. The story itself, including all text formatting attributes, is in a separate file inside the IDML package.
+
+## 7.4 Use Attributes Rather Than Elements
+
+Wherever possible, IDML uses XML attributes, rather than XML elements, for storing most object properties. XML attributes are more compact, and offer performance advantages over XML elements (XML attributes are parsed along with the opening of the element which contains them, rather than as child XML elements).
+
+## 7.5 Self-Documenting
+
+The structure of IDML should be as self-documenting as possible. While the parent-child relationships of the elements do not need to reflect the object relationship in the In  Design binary object model, they generally reflect the In  Design scripting model.
+
+Object and properties from the scripting model are represented in IDML as XML elements and attributes. The tag names of the elements and attributes are the 'long name' identifiers for the objects and properties defined in the scripting DOM.
+
+## 7.6 Not a Literal Representation of In  Design Data Structures
+
+IDML is not intended to represent the internal data structure of In  Design, nor is it intended as a replacement for the In  Design SDK. The In  Design API and binary file format will continue to evolve, and plug-in developers will continue to use the existing interfaces. By using the scripting DOM, IDML is insulated from changes to the In  Design API and low level changes to the file system.
+
+## 7.7 Performance
+
+IDML is designed with performance in mind. There are several design decisions that should result in performance improvement of IDML export and import:
+
+- Object information is organized to optimize for import/export.
+- At the C++ coding level, IDML core processing code and specific script providers have been tuned for better performance.
+- IDML documents have been split into functional components, which will give us the ability to take advantage of multi-tasking during export in a future version.
+
+## 7.8 Support for Previous Versions
+
+It must be possible to open an IDML in the previous version of In  Design (for example opening an IDML file from In  Design CS5 in In  Design CS4). Since IDML is being introduced in In  Design CS4, it is not possible for IDML files from In  Design CS4 to be opened in In  Design CS3 or earlier. Instead, In  Design CS4 will be able to export to INX, which will be able to be opened in earlier versions of In  Design.
+
+When a user opens an IDML file from an incompatible (due to plug-in configuration) version of In  Design/In  Copy, the application will display an error message. The user can choose to attempt to open the IDML file.