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: lispref/text.texi "Saving Properties" Date: 24 Jul 2006 07:43:31 -0400 Message-ID: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1153741425 25447 80.91.229.2 (24 Jul 2006 11:43:45 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Mon, 24 Jul 2006 11:43:45 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Jul 24 13:43:44 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 1G4yqb-0006fu-8o for ged-emacs-devel@m.gmane.org; Mon, 24 Jul 2006 13:43:42 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1G4yqa-0007g1-JO for ged-emacs-devel@m.gmane.org; Mon, 24 Jul 2006 07:43:40 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1G4yqN-0007dd-49 for emacs-devel@gnu.org; Mon, 24 Jul 2006 07:43:27 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1G4yqK-0007av-3B for emacs-devel@gnu.org; Mon, 24 Jul 2006 07:43:26 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1G4yqJ-0007ap-Ux for emacs-devel@gnu.org; Mon, 24 Jul 2006 07:43:23 -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 1G4yrO-0007Tz-JP for emacs-devel@gnu.org; Mon, 24 Jul 2006 07:44:30 -0400 Original-Received: from ttn by mail.agora-net.com with local (Exim 4.50) id 1G4yqR-000645-KS for emacs-devel@gnu.org; Mon, 24 Jul 2006 07:43:31 -0400 Original-To: emacs-devel@gnu.org Original-Lines: 319 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:57530 Archived-At: 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 ----