[Search] [txt|pdf|bibtex] [Tracker] [WG] [Email] [Nits]

Versions: 00 01 02 03 04 05 06 07 08 09 rfc5147                         
Network Working Group                                           E. Wilde
Internet-Draft                                Swiss Federal Institute of
Expires: January 9, 2003                                      Technology
                                                           July 11, 2002


         URI Fragment Identifiers for the text/plain Media Type
                      draft-wilde-text-fragment-00

Status of this Memo

   This document is an Internet-Draft and is in full conformance with
   all provisions of Section 10 of RFC2026.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as Internet-
   Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at http://
   www.ietf.org/ietf/1id-abstracts.txt.

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

   This Internet-Draft will expire on January 9, 2003.

Copyright Notice

   Copyright (C) The Internet Society (2002).  All Rights Reserved.

Abstract

   This memo defines URI fragment identifiers for text/plain resources.
   These fragment identifiers make it possible to refer to parts of a
   text resource, identified by character count or range, line count or
   range, or a regular expression.  These identification methods can be
   combined to identify more than one sub-resource of a text/plain
   resource.








Wilde                   Expires January 9, 2003                 [Page 1]


Internet-Draft      text/plain Fragment Identifiers            July 2002


Table of Contents

   1.    Introduction . . . . . . . . . . . . . . . . . . . . . . . .  3
   1.1   What is text/plain?  . . . . . . . . . . . . . . . . . . . .  3
   1.2   What is a URI Fragment Identifier? . . . . . . . . . . . . .  3
   1.3   Why text/plain Fragment Identifiers? . . . . . . . . . . . .  4
   2.    Fragment Identification Methods  . . . . . . . . . . . . . .  4
   2.1   Fragment Identification Schemes  . . . . . . . . . . . . . .  5
   2.1.1 Character Count  . . . . . . . . . . . . . . . . . . . . . .  5
   2.1.2 Character Range  . . . . . . . . . . . . . . . . . . . . . .  5
   2.1.3 Line Count . . . . . . . . . . . . . . . . . . . . . . . . .  5
   2.1.4 Line Range . . . . . . . . . . . . . . . . . . . . . . . . .  5
   2.1.5 Regular Expressions  . . . . . . . . . . . . . . . . . . . .  5
   2.1.6 Combining Fragment Identification Schemes  . . . . . . . . .  6
   3.    Fragment Identification Syntax . . . . . . . . . . . . . . .  6
   4.    Examples . . . . . . . . . . . . . . . . . . . . . . . . . .  7
   5.    Security Considerations  . . . . . . . . . . . . . . . . . .  8
         Normative References . . . . . . . . . . . . . . . . . . . .  8
         Non-Normative References . . . . . . . . . . . . . . . . . .  8
         Author's Address . . . . . . . . . . . . . . . . . . . . . .  9
   A.    POSIX BRE Syntax . . . . . . . . . . . . . . . . . . . . . .  9
   B.    Where to send Comments . . . . . . . . . . . . . . . . . . .  9
   C.    Acknowledgements . . . . . . . . . . . . . . . . . . . . . .  9
         Full Copyright Statement . . . . . . . . . . . . . . . . . . 10



























Wilde                   Expires January 9, 2003                 [Page 2]


Internet-Draft      text/plain Fragment Identifiers            July 2002


1. Introduction

   Compliant software MUST follow this specification.  The capitalized
   key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in RFC 2119 [RFC2119].

1.1 What is text/plain?

   Internet Media Types as defined in RFC 2045 [RFC2045] and RFC 2046
   [RFC2046] are used to identify different types and sub-types of
   media.  RFC 2046 [RFC2046] and RFC 2646 [RFC2646] specify the text/
   plain media type, which is used for simple, unformatted text.
   Quoting from RFC 2046 [RFC2046]: "Plain text does not provide for or
   allow  formatting commands, font attribute specifications, processing
   instructions, interpretation directives, or content markup.  Plain
   text is seen simply as a linear sequence of characters, possibly
   interrupted by line breaks or page breaks."

   The text/plain media type does not restrict the character encoding,
   any character encoding may be used.  In the absence of an explicit
   character encoding declaration, US-ASCII is assumed as the default
   character encoding.  This variability of the character encoding makes
   it impossible to count characters in a text/plain resource without
   taking the character encoding into account, because there are many
   character encodings using more than one octet per character.

   The biggest advantage of text/plain resources is their portability
   among different platforms.  As long as they use popular character
   encodings (such as US-ASCII), they can be displayed and processed on
   virtually every computer system.

1.2 What is a URI Fragment Identifier?

   URIs are the identification mechanism for resources on the Web.  The
   URI syntax specified in RFC 2396 [RFC2396] includes as part of a URI
   reference a fragment identifier, which (quoting from RFC 2396
   [RFC2396]) "consists of additional reference information to be
   interpreted by the user agent after the retrieval action has been
   successfully completed.  As such, it is not part of a URI, but is
   often used in conjunction with a URI".

   The most popular fragment identifier is defined for text/html
   (defined in RFC 2854 [RFC2854]), and makes it possible to refer to a
   specific element of an HTML document.






Wilde                   Expires January 9, 2003                 [Page 3]


Internet-Draft      text/plain Fragment Identifiers            July 2002


1.3 Why text/plain Fragment Identifiers?

   Referring to specific parts of a resource can be very useful, because
   it enables users to create more specific references.  Rather than
   pointing to a whole resource, users can create references to the part
   they really are interested in or want to talk about.  Even though it
   is suggested that fragment identification methods are specified in a
   media type's MIME registration, many media types do not have fragment
   identification methods associated with them.

   Fragment identifiers are only useful if supported by the client,
   because they are only interpreted by the client.  Therefore, a new
   fragment identification method will require some time to be adopted
   by clients, and older clients will not support it.  However, because
   the URI reference still works even if the fragment identifier is not
   supported (the resource is retrieved, but the fragment identifier is
   not interpreted), rapid adoption is not highly critical to ensure the
   success of a new fragment identification method.

   Fragment identifiers for text/plain make it possible to refer to
   specific parts of a text resource, either by line count, by character
   count, or by using a regular expression for searching for a specific
   character sequence.  Thus, text/plain fragment identifiers enable
   users to exchange information more specifically, thereby reducing
   time and effort that is necessary to manually search for the relevant
   part of a text/plain resource.

2. Fragment Identification Methods

   The identification of resource fragments of text/plain resources can
   be based on different foundations.  Since it is not necessary to
   insert explicit identifiers into a text/plain resource (as is
   possible with HTML documents by using special attributes), fragment
   identification has to rely on certain inherent criteria of the
   resource.  This memo specifies fragment identification using five
   different methods, character counts and ranges, line counts and
   ranges, and regular expression matching.

   When interpreting character or line numbers, implementations MUST
   take the character encoding of the resource into account, because
   character count and octet count may differ for the character encoding
   being used.  For example, a resource using UTF-16 encoding uses two
   octets per character, and it may have a leading BOM (Byte-Order Mark)
   which does not count as a character and thus also affects the mapping
   from a simple octet count to a character count.






Wilde                   Expires January 9, 2003                 [Page 4]


Internet-Draft      text/plain Fragment Identifiers            July 2002


2.1 Fragment Identification Schemes

2.1.1 Character Count

   The simplest way to identify a fragment is to point to a certain
   character of the resource.  Rather than identifying a fragment
   consisting of a number of characters, this method only identifies a
   single character, but this often is sufficient by referring to the
   start of a region of interest.  Character counting starts with 1, so
   the first character of a text/plain resource has the count 1.

2.1.2 Character Range

   If it is necessary to identify a fragment of multiple characters
   using character counting, this can be done by using a character
   range.  A character range is a consecutive region of the resource
   that extends from the starting character of the range to the ending
   character of the range.  The ending character of the range must have
   a greater number than the starting character.

2.1.3 Line Count

   Lines in text/plain resources are separated by CRLF sequences, and
   consequently it is easy to identify lines.  Because lines are the
   only structural property of text/plain resources, it is possible to
   identify a fragment of a resource by referring to a particular line.
   Line counting starts with 1, so the first line of a text/plain
   resource has the count 1.  If a resource does not contain any CRLF
   sequences, then it consists of a single (the first) line.

2.1.4 Line Range

   If it is necessary to identify a fragment of multiple lines using
   line counting, this can be done by using a line range.  A line range
   is a consecutive region of the resource that extends from the
   starting line of the range to the ending line of the range.  The
   ending line of the range must have a greater number than the starting
   line.

2.1.5 Regular Expressions

   A common problem with fragment identifiers is their robustness (to
   changes in the resource), and character and line counts can be broken
   very easily.  A more robust way of identifying a fragment is by
   searching for a specific pattern.  Thus, it is possible to use a
   Basic Regular Expression (BRE) as defined by ISO 9945-2 [ISO9945-2]
   (the POSIX standard) as a fragment identifier (Appendix A contains a
   short summary of the POSIX BRE syntax).



Wilde                   Expires January 9, 2003                 [Page 5]


Internet-Draft      text/plain Fragment Identifiers            July 2002


2.1.6 Combining Fragment Identification Schemes

   While in most cases only one fragment identification scheme will be
   used, it is possible to combine them.  By simply concatenating
   different fragment identification schemes, the whole fragment
   identifier refers to the union of all parts of the text resource
   identified by the individual fragment identification schemes.  This
   way, it is possible to identify disjoint ranges, such as multiple
   line ranges.

   It should be noticed that regular expressions by themselves may
   identify disjoint fragments, which is true in any case where the
   regular expression matches more than one occurrence in the resource.

   Since disjoint fragments can be identified, implementations SHOULD
   make sure that these fragments are appropriately marked, for example
   by highlighting the fragment (rather than only scrolling to some
   line, which only identifies a single location in the resource).
   However, the exact method of how implementations deal with disjoint
   fragments depends on the application and interface, and is beyond the
   scope of this memo.

3. Fragment Identification Syntax

   The syntax for the fragment identifiers is very straightforward.  The
   syntax defines three schemes, 'char', 'line', and 'match'.  The
   'char' and 'line' can be used in two different variants, either the
   count variant (with a single number), or the range variant (with two
   comma-separated numbers).  The 'match' scheme has a regular
   expression as parameter, which must be specified as a string with
   balanced parentheses.

   The following syntax definition uses ABNF as defined in RFC 2234
   [RFC2234].


   text-fragment =  1*text-scheme
   text-scheme   =  ( char-scheme / line-scheme / regex-scheme )
   char-scheme   =  "char(" ( count / range ) ")"
   line-scheme   =  "line(" ( count / range ) ")"
   match-scheme  =  "match(" regex ")"
   count         =  1*DIGIT
   range         =  count "," count
   regex         =  StringWithBalancedParens

   The StringWithBalancedParens may only contain balanced parentheses,
   if unbalanced parentheses need to be used, they must be escaped with
   a '^' character.  A literal '^' must be escaped as '^^'.  Thus,



Wilde                   Expires January 9, 2003                 [Page 6]


Internet-Draft      text/plain Fragment Identifiers            July 2002


   before interpreting the StringWithBalancedParens as a BRE, it must be
   searched for '^(', '^)', and '^^', and these strings must be
   substituted with their unescaped variants.

   If any count value is greater than the value for the actual resource,
   then it identifies the last character or line of the resource.  If a
   range scheme's counts are not properly ordered (ie, the first number
   is less than the second), then this scheme part has to be ignored.

4. Examples

   The following examples show some usages for the fragment identifiers
   defined in this memo.


   http://example.com/text.txt#char(100)

   This URI reference identifies the 100th character of the text.txt
   resource.  It should be noted that it is not clear which octet(s) of
   the resource this will be without retrieving the resource and thus
   knowing which character encoding is used for it (in case of HTTP,
   this information will be given in the response's Content-type
   header).


   http://example.com/text.txt#line(10,20)

   This URI reference identifies lines 10 to 20 of the text.txt
   resource.  If the resource has fewer than 10 lines, it identifies the
   last line.  If the resource has less than 20 but at least 10 lines,
   it identifies the lines 10 to the last line of the resource.


   http://example.com/text.txt#match(searchterm)

   This URI reference identifies all occurrences of the regular
   expression 'searchterm' in the resource, ie all occurrences of the
   string 'searchterm'.  If there is more than one occurrence, then this
   URI references a disjoint fragment, consisting of all of these
   occurrences.


   http://example.com/text.txt#line(1)match(searchterm)

   This URI reference identifies the first line and all occurrences of
   the regular expression 'searchterm' in the resource.  If there is an
   occurrence of 'searchterm' outside of the first line, then this URI
   references a disjoint fragment.



Wilde                   Expires January 9, 2003                 [Page 7]


Internet-Draft      text/plain Fragment Identifiers            July 2002


   http://example.com/text.txt#match(hello%5E()

   This URI reference identifies all occurrences of the regular
   expression 'hello(' in the resource.  It must first be URL decoded,
   which leads to the scheme part 'hello^('.  This is then interpreted
   according to the definition of a string with balanced parentheses,
   treating the '^(' as an escaped '(', so that the actual regular
   expression is 'hello('.  If there is more than one occurrence of this
   regular expression, then this URI references a disjoint fragment,
   consisting of all of these occurrences.

5. Security Considerations

   There are no relevant security considerations for this memo.

Normative References

   [ISO9945-2]  International Organization for Standardization,
                "Information technology - Portable Operating System
                Interface (POSIX) - Part 2: Shell and Utilities", ISO
                9945-2, xxxxx 1993.

   [RFC2045]    Freed, N. and N. Borenstein, "Multipurpose Internet Mail
                Extensions (MIME) Part One: Format of Internet Message
                Bodies", RFC 2045, November 1996.

   [RFC2046]    Freed, N. and N. Borenstein, "Multipurpose Internet Mail
                Extensions (MIME) Part Two: Media Types", RFC 2046,
                November 1996.

   [RFC2119]    Bradner, S., "Key words for use in RFCs to Indicate
                Requirement Levels", RFC 2119, March 1997.

   [RFC2234]    Crocker, D. and P. Overell, "Augmented BNF for Syntax
                Specifications: ABNF", RFC 2234, November 1997.

   [RFC2396]    Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
                Resource Identifiers (URI): Generic Syntax", RFC 2396,
                August 1998.

   [RFC2646]    Gellens, R., "The Text/Plain Format Parameter", RFC
                2646, August 1999.

Non-Normative References

   [RFC2629]  Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629,
              June 1999.




Wilde                   Expires January 9, 2003                 [Page 8]


Internet-Draft      text/plain Fragment Identifiers            July 2002


   [RFC2854]  Connolly, D. and L. Masinter, "The 'text/html' Media
              Type", RFC 2854, June 2000.


Author's Address

   Erik Wilde
   Swiss Federal Institute of Technology
   ETH-Zentrum
   8092 Zurich
   Switzerland

   Phone: +41-1-6325132
   EMail: ietf@dret.net
   URI:   http://dret.net/netdret/

Appendix A. POSIX BRE Syntax

   This section contains a short (and non-normative) summary of the
   POSIX BRE synatx defined in ISO 9945-2 [ISO9945-2].

   (tbd - is there some rfc that could be referenced instead?)

Appendix B. Where to send Comments

   Please send all comments about this document to Erik Wilde.

Appendix C. Acknowledgements

   This document has been written using the IETF document DTD described
   in RFC 2629 [RFC2629].




















Wilde                   Expires January 9, 2003                 [Page 9]


Internet-Draft      text/plain Fragment Identifiers            July 2002


Full Copyright Statement

   Copyright (C) The Internet Society (2002).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.



















Wilde                   Expires January 9, 2003                [Page 10]