Re: lispref/text.texi "Saving Properties"

[Thien-Thi Nguyen]

Richard Stallman <address@hidden> writes:

> Please read thru the whole text of that node again, looking for
> other ways to make it read more naturally as a unified whole.

below is a revised patch that better integrates the text.  i hope
these changes are not too drastic, now.  (ChangeLog entry the same.)

if there are no objections i will install this and move on
(that is, onwards backwards) w/ lispref/text.texi proofreading.

thi

_____________________________________________________________________
        * text.texi (Saving Properties): Delete node.
        (Text Properties): Remove "Saving Properties" from menu.
        * files.texi (Saving Buffers, Reading from Files, Writing to Files):
        Remove xref to "Saving Properties".
        (Format Conversion): Merge in text from "Saving Properties".
        Also, add xref to "Text Properties".
        * hooks.texi (Standard Hooks): Convert all "Saving Properties"
        xrefs to xref "Format Conversion" instead.
        * elisp.texi (Top): Remove "Saving Properties" from menu.

Index: text.texi
===================================================================
RCS file: /sources/emacs/emacs/lispref/text.texi,v
retrieving revision 1.128
diff -c -r1.128 text.texi
*** text.texi   31 Jul 2006 20:32:10 -0000      1.128
--- text.texi   4 Aug 2006 17:59:02 -0000
***************
*** 2566,2573 ****
  * Format Properties::      Properties for representing formatting of text.
  * Sticky Properties::      How inserted text gets properties from
                               neighboring text.
- * Saving Properties::      Saving text properties in files, and reading
-                              them back.
  * Lazy Properties::        Computing text properties in a lazy fashion
                               only when text is examined.
  * Clickable Text::         Using text properties to make regions of text
--- 2566,2571 ----
***************
*** 3361,3435 ****
    @xref{Insertion}, for the ordinary insertion functions which do not
  inherit.
  
- @node Saving Properties
- @subsection Saving Text Properties in Files
- @cindex text properties in files
- @cindex saving text properties
- 
-   You can save text properties in files (along with the text itself),
- and restore the same text properties when visiting or inserting the
- files, using these two hooks:
- 
- @defvar write-region-annotate-functions
- This variable's value is a list of functions for @code{write-region} to
- run to encode text properties in some fashion as annotations to the text
- being written in the file.  @xref{Writing to Files}.
- 
- Each function in the list is called with two arguments: the start and
- end of the region to be written.  These functions should not alter the
- contents of the buffer.  Instead, they should return lists indicating
- annotations to write in the file in addition to the text in the
- buffer.
- 
- Each function should return a list of elements of the form
- @code{(@var{position} . @var{string})}, where @var{position} is an
- integer specifying the relative position within the text to be written,
- and @var{string} is the annotation to add there.
- 
- Each list returned by one of these functions must be already sorted in
- increasing order by @var{position}.  If there is more than one function,
- @code{write-region} merges the lists destructively into one sorted list.
- 
- When @code{write-region} actually writes the text from the buffer to the
- file, it intermixes the specified annotations at the corresponding
- positions.  All this takes place without modifying the buffer.
- @end defvar
- 
- @defvar after-insert-file-functions
- This variable holds a list of functions for @code{insert-file-contents}
- to call after inserting a file's contents.  These functions should scan
- the inserted text for annotations, and convert them to the text
- properties they stand for.
- 
- Each function receives one argument, the length of the inserted text;
- point indicates the start of that text.  The function should scan that
- text for annotations, delete them, and create the text properties that
- the annotations specify.  The function should return the updated length
- of the inserted text, as it stands after those changes.  The value
- returned by one function becomes the argument to the next function.
- 
- These functions should always return with point at the beginning of
- the inserted text.
- 
- The intended use of @code{after-insert-file-functions} is for converting
- some sort of textual annotations into actual text properties.  But other
- uses may be possible.
- @end defvar
- 
- We invite users to write Lisp programs to store and retrieve text
- properties in files, using these hooks, and thus to experiment with
- various data formats and find good ones.  Eventually we hope users
- will produce good, general extensions we can install in Emacs.
- 
- We suggest not trying to handle arbitrary Lisp objects as text property
- names or values---because a program that general is probably difficult
- to write, and slow.  Instead, choose a set of possible data types that
- are reasonably flexible, and not too hard to encode.
- 
- @xref{Format Conversion}, for a related feature.
- 
- @c ??? In next edition, merge this info Format Conversion.
- 
  @node Lazy Properties
  @subsection Lazy Computation of Text Properties
  
--- 3359,3364 ----
Index: files.texi
===================================================================
RCS file: /sources/emacs/emacs/lispref/files.texi,v
retrieving revision 1.99
diff -c -r1.99 files.texi
*** files.texi  17 Jul 2006 23:59:35 -0000      1.99
--- files.texi  4 Aug 2006 17:59:05 -0000
***************
*** 373,380 ****
  @end deffn
  
    Saving a buffer runs several hooks.  It also performs format
! conversion (@pxref{Format Conversion}), and may save text properties in
! ``annotations'' (@pxref{Saving Properties}).
  
  @defvar write-file-functions
  The value of this variable is a list of functions to be called before
--- 373,379 ----
  @end deffn
  
    Saving a buffer runs several hooks.  It also performs format
! conversion (@pxref{Format Conversion}).
  
  @defvar write-file-functions
  The value of this variable is a list of functions to be called before
***************
*** 494,502 ****
  
  The function @code{insert-file-contents} checks the file contents
  against the defined file formats, and converts the file contents if
! appropriate.  @xref{Format Conversion}.  It also calls the functions in
! the list @code{after-insert-file-functions}; see @ref{Saving
! Properties}.  Normally, one of the functions in the
  @code{after-insert-file-functions} list determines the coding system
  (@pxref{Coding Systems}) used for decoding the file's contents,
  including end-of-line conversion.
--- 493,501 ----
  
  The function @code{insert-file-contents} checks the file contents
  against the defined file formats, and converts the file contents if
! appropriate and also calls the functions in
! the list @code{after-insert-file-functions}.  @xref{Format Conversion}.
! Normally, one of the functions in the
  @code{after-insert-file-functions} list determines the coding system
  (@pxref{Coding Systems}) used for decoding the file's contents,
  including end-of-line conversion.
***************
*** 617,625 ****
  @var{filename} and @var{visit} for that purpose.
  
  The function @code{write-region} converts the data which it writes to
! the appropriate file formats specified by @code{buffer-file-format}.
! @xref{Format Conversion}.  It also calls the functions in the list
! @code{write-region-annotate-functions}; see @ref{Saving Properties}.
  
  Normally, @code{write-region} displays the message @samp{Wrote
  @var{filename}} in the echo area.  If @var{visit} is neither @code{t}
--- 616,625 ----
  @var{filename} and @var{visit} for that purpose.
  
  The function @code{write-region} converts the data which it writes to
! the appropriate file formats specified by @code{buffer-file-format}
! and also calls the functions in the list
! @code{write-region-annotate-functions}.
! @xref{Format Conversion}.
  
  Normally, @code{write-region} displays the message @samp{Wrote
  @var{filename}} in the echo area.  If @var{visit} is neither @code{t}
***************
*** 2770,2780 ****
  @cindex file format conversion
  @cindex encoding file formats
  @cindex decoding file formats
!   The variable @code{format-alist} defines a list of @dfn{file formats},
! which describe textual representations used in files for the data (text,
! text-properties, and possibly other information) in an Emacs buffer.
! Emacs performs format conversion if appropriate when reading and writing
! files.
  
  @defvar format-alist
  This list contains one format definition for each defined file format.
--- 2770,2896 ----
  @cindex file format conversion
  @cindex encoding file formats
  @cindex decoding file formats
! @cindex text properties in files
! @cindex saving text properties
!   Emacs performs several steps to convert the data in a buffer (text,
! text properties, and possibly other information) to and from a
! representation suitable for storing into a file.  For example, when you
! write a buffer to a file, delete the buffer, and read that file back
! into a new buffer, here is what happens at the lowest levels:
! 
! @itemize
! @item The function @code{write-region}:
! 
! @itemize
! @item
! calls functions in @code{write-region-annotate-functions};
! 
! @item
! processes formats as defined by entries in @code{format-alist};
! 
! @item
! encodes characters to bytes as appropriate; and,
! 
! @item
! finally, modifies the file with the bytes.
! @end itemize
! 
! @item Emacs creates a new buffer and makes it the current buffer.
! 
! @item The function @code{insert-file-contents}:
! 
! @itemize
! @item
! initially, inserts bytes from the file into the buffer;
! 
! @item
! decodes bytes to characters as appropriate;
! 
! @item
! processes formats as defined by entries in @code{format-alist};
! 
! @item
! calls functions in @code{after-insert-file-functions}.
! @end itemize
! @end itemize
! 
!   This example shows the symmetry of the low-level operations; the order
! for writing and reading is opposite.  The rest of this section describes
! the three variables named above, as well as some related functions.
! For details on character encoding and decoding, @ref{Coding Systems}.
! 
!   Generally, conversion starts with one thing and ends with something
! else.  When there is only one conversion to do, there is no conflict
! about what to start with.  From the example above, however, we see that
! there can be multiple conversions involved, which might result in
! conflict when two conversions need to start with the same data.
! 
!   This situation is best understood in the context of converting text
! properties during @code{write-region}.  For example, the character at
! position 42 in a buffer is @samp{X} with a text property @code{foo}.  If
! the conversion for @code{foo} is done by inserting into the buffer, say,
! @samp{FOO:}, then that changes the character at position 42 from
! @samp{X} to @samp{F}.  The next conversion will start with the wrong
! data straight away.
! 
!   To avoid conflict, cooperative conversions do not modify the buffer,
! but instead specify @dfn{annotations}, a list of elements of the form
! @code{(@var{position} . @var{string})}, sorted in order of increasing
! @var{position}.
! 
!   If there is more than one conversion, @code{write-region} merges their
! annotations destructively into one sorted list.  Later, when the text
! from the buffer is actually written to the file, it intermixes the
! specified annotations at the corresponding positions.  All this takes
! place without modifying the buffer.
! 
! @c ??? What about ``overriding'' conversions like those allowed
! @c ??? for `write-region-annotate-functions', below?  --ttn
! 
!   In contrast, when reading, the annotations intermixed with the text
! are handled immediately.  @code{insert-file-contents} sets point to the
! beginning of some text to be converted, then calls the conversion
! functions with the length of that text.  These functions should always
! return with point at the beginning of the inserted text.
! 
!   Each conversion function should scan for the annotations it
! recognizes, remove the annotation, modify the buffer text (to set a text
! property, for example), and return the updated length of the text, as it
! stands after those changes.  The value returned by one function becomes
! the argument to the next function.
! 
! @defvar write-region-annotate-functions
! A list of functions for @code{write-region} to call.  Each function in
! the list is called with two arguments: the start and end of the region
! to be written.  These functions should not alter the contents of the
! buffer.  Instead, they should return annotations.
! 
! @c ??? Following adapted from comment in `build_annotations' (fileio.c).
! @c ??? Perhaps this is intended for internal use only?
! @c ??? Someone who understands this, please reword it. --ttn
! As a special case, if a function returns with a different buffer
! current, Emacs takes it to mean the current buffer contains altered text
! to be output, and discards all previous annotations because they should
! have been dealt with by this function.
! @end defvar
! 
! @defvar after-insert-file-functions
! A list of functions for @code{insert-file-contents} to call.
! @end defvar
! 
!   We invite users to write Lisp programs to store and retrieve text
! properties in files, using these hooks, and thus to experiment with
! various data formats and find good ones.  Eventually we hope users
! will produce good, general extensions we can install in Emacs.
! 
!   We suggest not trying to handle arbitrary Lisp objects as text property
! names or values---because a program that general is probably difficult
! to write, and slow.  Instead, choose a set of possible data types that
! are reasonably flexible, and not too hard to encode.
! 
!   Another way to specify conversion functions is to use the variable
! @code{format-alist}, whose value lists @dfn{file format}, which describe
! textual representations used in files for the data in an Emacs buffer.
  
  @defvar format-alist
  This list contains one format definition for each defined file format.
***************
*** 2807,2817 ****
  A shell command is represented as a string; Emacs runs the command as a
  filter to perform the conversion.
  
! If @var{from-fn} is a function, it is called with two arguments, @var{begin}
! and @var{end}, which specify the part of the buffer it should convert.
! It should convert the text by editing it in place.  Since this can
! change the length of the text, @var{from-fn} should return the modified
! end position.
  
  One responsibility of @var{from-fn} is to make sure that the beginning
  of the file no longer matches @var{regexp}.  Otherwise it is likely to
--- 2923,2930 ----
  A shell command is represented as a string; Emacs runs the command as a
  filter to perform the conversion.
  
! If @var{from-fn} is a function, it is treated like those listed
! in @code{after-insert-file-functions}.
  
  One responsibility of @var{from-fn} is to make sure that the beginning
  of the file no longer matches @var{regexp}.  Otherwise it is likely to
***************
*** 2834,2848 ****
  return the end-position of the range of text, as modified.
  
  @item
! By returning a list of annotations.  This is a list of elements of the
! form @code{(@var{position} . @var{string})}, where @var{position} is an
! integer specifying the relative position in the text to be written, and
! @var{string} is the annotation to add there.  The list must be sorted in
! order of position when @var{to-fn} returns it.
! 
! When @code{write-region} actually writes the text from the buffer to the
! file, it intermixes the specified annotations at the corresponding
! positions.  All this takes place without modifying the buffer.
  @end itemize
  
  @item modify
--- 2947,2954 ----
  return the end-position of the range of text, as modified.
  
  @item
! By returning a list of annotations, as would functions listed
! in @code{write-region-annotate-functions}.
  @end itemize
  
  @item modify
Index: hooks.texi
===================================================================
RCS file: /sources/emacs/emacs/lispref/hooks.texi,v
retrieving revision 1.30
diff -c -r1.30 hooks.texi
*** hooks.texi  20 May 2006 02:28:50 -0000      1.30
--- hooks.texi  4 Aug 2006 17:59:06 -0000
***************
*** 48,54 ****
  @xref{Init File}.
  
  @item after-insert-file-functions
! @xref{Saving Properties}.
  
  @item after-make-frame-functions
  @xref{Creating Frames}.
--- 48,54 ----
  @xref{Init File}.
  
  @item after-insert-file-functions
! @xref{Format Conversion}.
  
  @item after-make-frame-functions
  @xref{Creating Frames}.
***************
*** 330,336 ****
  @xref{Saving Buffers}.
  
  @item write-region-annotate-functions
! @xref{Saving Properties}.
  @end table
  
  @ignore
--- 330,336 ----
  @xref{Saving Buffers}.
  
  @item write-region-annotate-functions
! @xref{Format Conversion}.
  @end table
  
  @ignore
Index: elisp.texi
===================================================================
RCS file: /sources/emacs/emacs/lispref/elisp.texi,v
retrieving revision 1.80
diff -c -r1.80 elisp.texi
*** elisp.texi  31 Jul 2006 18:34:36 -0000      1.80
--- elisp.texi  4 Aug 2006 17:59:07 -0000
***************
*** 893,900 ****
  * Format Properties::       Properties for representing formatting of text.
  * Sticky Properties::       How inserted text gets properties from
                                neighboring text.
- * Saving Properties::       Saving text properties in files, and reading
-                               them back.
  * Lazy Properties::         Computing text properties in a lazy fashion
                                only when text is examined.
  * Clickable Text::          Using text properties to make regions of text
--- 893,898 ----