lispref/text.texi "Saving Properties"

lispref/text.texi "Saving Properties"

[Thien-Thi Nguyen]

the node "Saving Properties" finishes with this comment:

@c ??? In next edition, merge this info Format Conversion.

appended is a patch that does the merge.
here is a suitable ChangeLog entry:

	* text.texi (Saving Properties): Delete.
	(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.

is it ok to do this change?

thi

___________________________________________________
Index: text.texi
===================================================================
RCS file: /sources/emacs/emacs/lispref/text.texi,v
retrieving revision 1.125
diff -c -r1.125 text.texi
*** text.texi	23 Jul 2006 21:20:50 -0000	1.125
--- text.texi	24 Jul 2006 11:20:17 -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	24 Jul 2006 11:20:21 -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}
***************
*** 2924,2929 ****
--- 2924,2992 ----
  in all buffers.
  @end defvar
  
+ @cindex text properties in files
+ @cindex saving text properties
+   You can save text properties (@pxref{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.
+ 
  @ignore
     arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c
  @end ignore
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	24 Jul 2006 11:20:21 -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.79
diff -c -r1.79 elisp.texi
*** elisp.texi	17 Jul 2006 23:58:49 -0000	1.79
--- elisp.texi	24 Jul 2006 11:20:23 -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 ----

Re: lispref/text.texi "Saving Properties"

[Richard Stallman]

It is good, for the part of the job it does; but the text needs
more change in order to read as a unit.

For instance, the Format Conversion feature uses annotations just like
write-region-annotate-functions.  So the text of the two parts of the
node needs some additional reworking to operate as a whole.  This text

    @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.

becomes redundant with part of the new text which also defines
annotations; there should be just one definition.

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

Re: lispref/text.texi "Saving Properties"

[Thien-Thi Nguyen]

Richard Stallman <rms@gnu.org> 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 ----

Re: lispref/text.texi "Saving Properties"

[Richard Stallman]

      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:
    ! 

That order is counterintuitive, since it is the reverse of the order in which
things are really normally done.  I suggest you describe reading first,
and then describe writing.

I think there is no need for the outer @itemize level.

    !   Generally, conversion starts with one thing and ends with something
    ! else.

Conversion starts with one representation and produces another
representation.

    !   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.

This approach makes sense for reading because annotations removed by
the first converter can't be mistakenly processed by a later converter.

I think it would be better to discuss format-alist first, because it is
a more general feature.