From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Thien-Thi Nguyen Newsgroups: gmane.emacs.devel Subject: Re: lispref/text.texi "Saving Properties" Date: 04 Aug 2006 14:09:51 -0400 Message-ID: References: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1154715055 27321 80.91.229.2 (4 Aug 2006 18:10:55 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Fri, 4 Aug 2006 18:10:55 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Aug 04 20:10:47 2006 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1G947y-0003fa-4Q for ged-emacs-devel@m.gmane.org; Fri, 04 Aug 2006 20:10:32 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1G947w-0006di-Ic for ged-emacs-devel@m.gmane.org; Fri, 04 Aug 2006 14:10:28 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1G947O-0006QY-D7 for emacs-devel@gnu.org; Fri, 04 Aug 2006 14:09:54 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1G947N-0006Q7-Fp for emacs-devel@gnu.org; Fri, 04 Aug 2006 14:09:54 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1G947N-0006Q1-B5 for emacs-devel@gnu.org; Fri, 04 Aug 2006 14:09:53 -0400 Original-Received: from [67.59.132.6] (helo=mail.agora-net.com) by monty-python.gnu.org with esmtps (TLS-1.0:RSA_AES_256_CBC_SHA:32) (Exim 4.52) id 1G94Az-0008Aj-5K for emacs-devel@gnu.org; Fri, 04 Aug 2006 14:13:37 -0400 Original-Received: from ttn by mail.agora-net.com with local (Exim 4.50) id 1G947L-0006t6-Ul for emacs-devel@gnu.org; Fri, 04 Aug 2006 14:09:51 -0400 Original-To: emacs-devel@gnu.org In-Reply-To: Original-Lines: 437 User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.4 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:58101 Archived-At: Richard Stallman 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 ----