Previous chapter

Appendix A

Appendix A

The multipart/digiment and application/digiment MIME Types

The multipart/digiment and application/digiment MIME Types

A.1 The Multipart/digiment Type

The multipart/digiment is the base MIME type for a digiment. When transferring a digiment, the type used should be multipart/digiment. The multipart digiment is syntactically equivalent to the multipart/mixed type, but with different semantics. The only type allowed within a multipart/digiment is application/digiment. The use of multipart/digiment instead of multipart/mixed is to differentiate a digiment from a random multipart message. This allows MIME agents to detect a multipart/digiment and invoke the proper action to process it. When referring to a "digiment", we are actually referring to the multipart/digiment object which contains all the other data objects; the whole is known as the digiment.

A multipart/digiment consists of a number of application/digiment objects, which are defined in the following section. A minimal multipart/digiment consists of a application/digiment of type page-list, followed by one or more application/digiment parts of varying types. Any object which is not of application/digiment MIME type may be ignored.

A.2 The application/digiment type

The application/digiment type is the meat of the digiment. A digiment is made up of a collection of application/digiments which describe the available data formats for the digiment and the relationships between them. Each application/digiment consists of two MIME headers; a Content-Type: of application/digiment, and a Content-ID with a globally unique ID. These headers must always be present. Following these headers is a blank line and the body of the application/digiment. Thus, the beginning of an application/digiment would look like this:

Content-Type:      application/digiment
Content-ID:      MIT-LCS//MIT/LCS/TR-341.map
start of application/digiment body
There a multiple types of application/digiments. Each application/digiment describes some data of the digiment, or a relationship between different data types. The type of application/digiment is specified in the application/digiment headers.

A.2.1 Application/digiment headers
Each digiment-type has the same first two lines as a header. The first line must contain the tag Version:, followed by the version number. This document describes version 1.0 of each digiment-type. The only current legal version number is 1.0. Any future version may describe a different format and must be described in a separate document. The second line must contain the tag Digiment-type: followed by a legal digiment-type. The currently defined types are described below, as well as being listed in Table A.1 on page 91. Thus, a correct part-list application/digiment would start like this (including the MIME headers):

Content-Type:      application/digiment
Content-ID:      MIT-LCS//MIT/LCS/TR-341.parts
Version:      1.0
Digiment-type:      part-list
The rest of the application/digiment body follows immediately afterwards, without any blank lines.

A.2.2 The part-list type
The part-list type is the only required type of application/digiment in a digiment, and must be the first part in a digiment. This type contains a listing of each of the other application/digiments in the digiment, with their Digiment-type and Content-ID. In addition, types which contain data, such as a page-list or body-list, may also have the MIME type of the data included as a hint.

The part-list type consists of the application/digiment headers followed by a line for each of the other application/digiments. Each line starts with the tag Part:, followed by the digiment-type of the part, followed by the Content-ID of the part. For parts that contain references to data, such as page-list or body-list, the format of the data can also be included. Each of these values is separated by a tab, and the line is terminated by a newline. Each application/digiment object contained within the digiment must have its own Part: line within the part-list. A part-list for a digiment with a bibliography, a single page-list and a page-map would look like this:

Version:        1.0
Digiment-content:        part-list
Part:  bibliography          MIT-AILab//AIM-1066.bib
Part:  page-map          AIM-1066.100x5cLZW.map
Part:  page-list          AIM-1066.100x5cLZW.list                image/gif;dpi=100;bits=5
A.2.3 The bibliography type
The bibliography type is meant to contain bibliographic and other meta-data about the document which is not otherwise found in the body of the document. It consists of the standard application/digiment headers followed by bibliographic information about the document in RFC1357 format. This format generally consists of a tag, followed by two colons (::), followed by the data for that tag. The data continues until the start of the next tag. A sample bibliography type might consist of the following:

Version:        1.0
Digiment-content:        bibliography
 BIB-VERSION:: v2.0
          ID:: MIT-AILab//AIM-1050a
       ENTRY:: February 27, 1995
ORGANIZATION:: Massachusetts Institute of Technology, Artificial
     Intelligence Laboratory
       TITLE:: What Are Plans For?
      AUTHOR:: Agre, Philip E.
      AUTHOR:: Chapman, David
        TYPE:: Technical Memo
        DATE:: September 1988
       PAGES:: 18
       GRANT:: N00014-85-K-0124
    ABSTRACT:: What plans are like depends on how they're used. We
  contrast two views of plan use. On the plan-as-program-view, plan use
  is the execution of an effective procedure. On the plan-as-
  communication view, plan use is like following natural language
  instructions. We have begun work on computational models of plans-as-
  communication, building on our previous work on improvised activity
  and on ideas from sociology.
         END:: MIT-AILab//AIM-1050a
A.2.4 The page-list type
The page-list type is the main digiment-type used for specifying page-based data. Page-based data refers to any data which is accessible a single page at a time. This type may be used for any data type which is available a page at a time. For example, a document may be available in Postscript form, which would be specified in a body-list. Normally, a client would have to download the entire Postscript file to view a single page. However, a server may be able to serve a single page of a Postscript version of a document at a time. The entire Postscript version could then be listed as a page-list and accessed a page at a time, permitting additional information to be assigned to each page and allowing finer control of the relationships between different versions. This also has the advantage of not requiring an entire body-list part to be transferred to view a single page, making for more effective use of bandwidth.

Each distinct data format should have its own page-list, even if it does not contain an entry for each page. For example, if a digiment contained pages 1-15 of a document in greyscale GIF, but also included a separate copy of page 12 in color GIF, the digiment would have two separate page-lists. One would contain a listing for each of the pages 1-15 available in greyscale, while the other would only have an entry for page 12, which is a color GIF. The relationship between pages which contain alternate forms of the same data is maintained in a separate part called a page-map.

The page-list type starts with the standard application/digiment headers. These are followed by three more headers and a list of pages available in the specified data type. The first header is URL-stem:, followed by the stem of a URL that can be used to access a page. By placing the first part of a URL in this header, it is not necessary to repeat a part of a URL that is common to all the pages of a given type. This stem is prepended to the URL given for a specific page to form a complete URL. If this header is empty or missing, the URL used to access a given page is simply that URL which is given for that page.

The next header is Content-Type:, followed by a MIME content type/subtype that describes the format of the pages. Each page in the page-list must be in the format described by the Content-Type header. This header is required.

The final header is Page-map:, followed by the Content-ID of a application/digiment of type page-map which this page-list uses. If this header is missing, the digiment browser should assume an implied page-map with all entries as "unknown". The page-map type, described in section A.2.5, contains various meta-data about an individual page, as well as preserves relationships between pages which contain the same data, but in different formats.

Following the headers is a list of pages. Each page has a single entry in the page-list. An entry begins with the tag Page:. This is followed by a Virtual Sequence Number, or VSN. The VSN uniquely identifies a page within a given page-list, and is assumed to have some in-order. That is, a page with a VSN less than a second page should be displayed before the page with the higher VSN and vice-versa. VSNs do not have to be sequential, but must be have some absolute relative ordering. Following the VSN is a URL which can be used to access the page data. If the URL-stem: header is present and non-empty, the contents of that header will be prepended to the URL, so the URL field does not need to be a valid URL by itself; however, the combination of the URL-stem: field and the URL field must create a valid URL which can be resolved to access the page data. The URL field is followed by a Page Description field. This field is free text and may contain any of the characters [a-zA-Z_- ] and punctuation characters. The page description field is displayed by the browser to indicate which version of a page a user is looking at, and which others are available. For example, page 12 which is in greyscale format might have a page description field of "Standard image", while a color version of page 12 might have a field of "Color image", while an extremely low resolution version might have a field of "Quick preview". Each of these fields is separated by a tab and the line is terminated by a newline.

The following sample shows a page-list which specifies 5 pages in GIF format. The URL field of each page is appended to the URL-stem: header to form a valid URL to access the specified page. This page-list points to a page-map which is also contained within the digiment; this page map contains additional information about each page. Finally, each page is labeled with a page description of "Viewable image". This text will be shown by the browser in a button which can be used to select among different versions of the same page.

Version:        1.0
Digiment-content:        page-list
URL-stem:   http://cstr-http.lcs.mit.edu/Server/TR/MIT-AILab:AIM-1066/Page/
Content-type:        image/gif;dpi=100;bits=5
Page-map:        AIM-1066.100x5cLZW.map
Page:  1      1?type=image/gif;dpi=100;bits=5                        Viewable image
Page:  2      2?type=image/gif;dpi=100;bits=5                        Viewable image
Page:  3      3?type=image/gif;dpi=100;bits=5                        Viewable image
Page:  4      4?type=image/gif;dpi=100;bits=5                        Viewable image
Page:  5      5?type=image/gif;dpi=100;bits=5                        Viewable image
A.2.5 The page-map type
The page-map type includes extra data about a specific page, and is used to relate different versions of the same page together. Multiple page-lists can share a single page-map; this is how multiple pages can indicate that they refer to the same virtual page. Page-maps are also used to describe the type of page, as well as provide the page number.

A page-map consists of the standard application/digiment headers followed by a mapping for each page in the page-map. Each page has a single entry in the page-map. The entry begins with the tag Map:, which is followed by a VSN. This VSN corresponds to the VSN for a specific page in every page-list which points to this page-map. For example, if page-list A pointed to page-map A', the page with VSN 12 in A would correspond to the map with VSN 12 in A'. In addition, if page-list B also pointed to page-map A', the page with VSN 12 in A would be considered an alternate version of the page with VSN 12 in B. It is permissible for multiple page-lists which all point to a single page-map to have VSN series that do not completely overlap, as long as those VSNs that do overlap refer to the same page in alternate formats and the VSNs that do not overlap refer to pages which are only available in certain formats. This allows flexibility in specifying relationships between pages in various formats, where all the pages may not be available in each format.

The next field after the VSN is the Page Type field. This field can hold one of five values; supporting, title page, unnumbered, an integer number, or unknown. This field can be used by the browser to determine what type of logical page this is. A value of supporting means that the page is not really part of the document, but is used in processing or contains calibration or miscellaneous information. These pages are not normally displayed or printed. A value of title page indicates that the given page is the first or title page for the given digiment. A value of unnumbered means that the page has no page number, while an integer number refers to the actual page number in the document. Finally, unknown indicates that there is no logical information about this page.

The last field is the Page Name field. This is simply displayed by the browser to indicate which page is currently being viewed. Normally this field will contain the page number, but it may contain "Title page", or a description of a processing control or calibration page.

The following example is part of a page-map. Notice that the first page, with VSN 1, is a supporting page of type "doccontrol", while the second page, with VSN 2, is a IEEE-167A-1987 calibration target. The actual digiment does not start until VSN 3, which is the title page.

Version:        1.0
Digiment-content:        page-map
Map:  1      supporting          doccontrol
Map:  2      supporting          calibration IEEE-167A-1987
Map:  3      title page          Title page
Map:  4      1          1
Map:  5      2          2
Map:  6      3          3
A.2.6 The body-list type
The body-list type is the main digiment-type used for specifying data segments that contain multiple pages, or are not page based. For example, a Postscript version of a document would be placed in a body-list. However, sometimes a segment may contain only part of a document, such as a Postscript file for each chapter in a document. In this case, a body-list will contain an entry for each file which makes up the document.

The body-list type starts with the standard application/digiment headers. These are followed by two more headers and a list of segments that are available in the specified data type. The first header is URL-stem:, followed by the stem of a URL which can be used to access a segment. By placing the first part of a URL in this header, it is not necessary to repeat a part of a URL which is common to all the segments of a given type. This stem is prepended to the URL given for a specific segment to form a complete URL. If this header is empty or missing, the URL used to access a given segment is simply that URL which is given for that segment.

The second header is Content-Type:, followed by a MIME content type/subtype which describes the format of the segments. Each segment in the body-list must be in the format described by the Content-Type header. This header is required.

Following the headers is a list of segments. Each segment has a single entry in the body-list. An entry begins with the tag Body:. This is followed by a Virtual Sequence Number, or VSN. The VSN uniquely identifies a segment within a given body-list, and is assumed to have some absolute ordering. That is, a segment with a VSN less than a second segment should be displayed before the segment with the higher VSN and vice-versa. VSNs do not have to be sequential, but must have some absolute relative ordering. Following the VSN is a URL which can be used to access the page data. If the URL-stem: header is present and non-empty, the contents of that header will be prepended to the URL, so the URL field does not need to be a valid URL by itself; however, the combination of the URL-stem: field and the URL field must create a valid URL which can be resolved to access the segment data. The URL field is followed by a Segment Description field. This field is free text and may contain any of the characters [a-zA-Z_- ] and punctuation characters. The segment description field is displayed by the browser to label a button, indicate which version of a page a user is looking at. For example, a segment may be named "Chapter 1" or "Chapters 4-7". Each of these fields is separated by a tab and the line is terminated by a newline.

The following sample shows a body-list which specifies a segment in Postscript format. The URL field of each segment is appended to the URL-stem: header to form a valid URL to access the specified segment. Finally, each segment is labeled with a segment description. This text will be shown by the browser in a button.

Version:        1.0
Digiment-content:        body-list
URL-stem:   http://cstr-http.lcs.mit.edu/Server/TR/MIT-AILab:AIM-1066/Body
Content-type:        application/postscript
Body:  1      ?type=application/postscript                        Pages 1-115
A.2.7 The preferred-order type
The preferred-order type is used to specify a preferred sequence of data objects for the browser to display. Although page-lists and body-lists can do this, they are limited to only specifying pages or segments which are in a specific format. By using a preferred-order type, a digiment can specify a sequence of objects which are listed in any page-list or body-list in the digiment. For example, a digiment can specify that a preferred viewing order is pages 1 through 5 from page-list A, pages 6 and 7 from page-list B, segment 3 from body-list C, and pages 8 through 45 from page-list A. Digiments may contain multiple preferred-order parts. Thus, another preferred-order may be identical to the previous one described, but use page-list C instead of page-list A.

The preferred-order type starts with the standard application/digiment headers. These are followed by another header and a list of data objects. The header is Preference Description:, followed by a short description of the preferred-order. This text may contain any of the characters [a-zA-Z_- ] and punctuation characters, and is displayed by the browser to let the user choose which version of the digiment he wishes to view.

Following the headers is a list of data objects. Each object has a single entry in the preferred-order list. An entry begins with the tag Object:. This is followed by a Preferred Sequence Number, or PSN. The PSN specifies the order in which the objects are to be displayed. The first object displayed is the object which corresponds to the lowest PSN, and objects are displayed in order of increasing PSNs. PSNs do not have to be sequential, but must have some absolute relative ordering. Following the VSN is a Content-ID, which is the content-ID of either a part-list or body-list digiment part within the digiment. The Content-ID field is followed by a VSN field. The VSN specifies a specific page or segment from the part-list or body-list part. By using a VSN and Content-ID pair, it is possible to specify any object which is contained in a digiment. Each of these fields is separated by a tab and the line is terminated by a newline.

The following sample shows a preferred-order part with 5 objects; 3 pages and 2 body segments. The first two objects are the cover and abstract pages. The next two objects are the two Postscript files which make up the body of the document. The final object is the bibliography page. This order is preferred for using color output devices.

Version:        1.0
Digiment-content:        preferred-order
Preference-Description:            Color for high resolution devices
Object:  AIM-1066.600x5cLZW.list                  1
Object:  AIM-1066.600x5cLZW.list                  2
Object:  AIM-1066.postcolor.body                  1
Object:  AIM-1066.postcolor.body                  2
Object:  AIM-1066.600x5cLZW.list                  115
These types are designed to cover the common cases for digiment delivery. However, they are certainly not a complete set of all possibilities for capturing all the various types of data and relationships between types which may be delivered. Therefore, it is expected that this set will be expanded by future types to enhance the flexibility of delivery options and capture more data. A complete listing of the types defined in this document is in Table A.1 on page 91

Table A.1:  Application/digiment Digiment-types
-----------------------------------------------------
Digiment-type:   Description                           
-----------------------------------------------------
part-list        Listing of all the application/digi   
                 ments in this digiment                
bibliography     Bibliographic material in             
                 RFC1357 format                        
page-map         A mapping from VSN to page #          
page-list        A list of pages available in a cer    
                 tain format                           
preferred-order  A listing of pages or body-list       
                 parts in a particular order from      
                 various page-list or body-list parts  
body-list        A file which contains multiple        
                 pages                                 
                                                       
-----------------------------------------------------

Next chapter