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