* Re: lispref/text.texi "Saving Properties"
2006-07-25 22:14 ` Richard Stallman
@ 2006-08-04 18:09 ` Thien-Thi Nguyen
2006-08-04 20:59 ` Richard Stallman
0 siblings, 1 reply; 4+ messages in thread
From: Thien-Thi Nguyen @ 2006-08-04 18:09 UTC (permalink / raw)
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 ----
^ permalink raw reply [flat|nested] 4+ messages in thread