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: doc patch: "Saving Properties" merge into "Format Conversion" Date: Mon, 30 Apr 2007 10:15:28 +0200 Message-ID: <87ps5m2s7z.fsf@ambire.localdomain> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: sea.gmane.org 1177920964 18358 80.91.229.12 (30 Apr 2007 08:16:04 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Mon, 30 Apr 2007 08:16:04 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Apr 30 10:16:03 2007 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1HiR3B-0005s8-Bl for ged-emacs-devel@m.gmane.org; Mon, 30 Apr 2007 10:16:01 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1HiR9K-0002WN-Ub for ged-emacs-devel@m.gmane.org; Mon, 30 Apr 2007 04:22:22 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1HiR9F-0002St-4e for emacs-devel@gnu.org; Mon, 30 Apr 2007 04:22:17 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1HiR9D-0002RQ-TW for emacs-devel@gnu.org; Mon, 30 Apr 2007 04:22:16 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1HiR9D-0002R4-Or for emacs-devel@gnu.org; Mon, 30 Apr 2007 04:22:15 -0400 Original-Received: from smtp-out3.libero.it ([212.52.84.43]) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1HiR32-0003nD-JZ for emacs-devel@gnu.org; Mon, 30 Apr 2007 04:15:53 -0400 Original-Received: from localhost (172.31.0.49) by smtp-out3.libero.it (7.3.120) id 4611FE5E019BAA5A for emacs-devel@gnu.org; Mon, 30 Apr 2007 10:15:20 +0200 X-Scanned: with antispam and antivirus automated system at libero.it Original-Received: from smtp-out4.libero.it ([172.31.0.40]) by localhost (asav-out8.libero.it [192.168.32.36]) (amavisd-new, port 10024) with ESMTP id 4fh8-t7017BZ for ; Mon, 30 Apr 2007 10:15:19 +0200 (CEST) Original-Received: from ambire.localdomain (151.21.37.221) by smtp-out4.libero.it (7.3.120) id 4611FEBC0266E411 for emacs-devel@gnu.org; Mon, 30 Apr 2007 10:15:19 +0200 Original-Received: from ttn by ambire.localdomain with local (Exim 4.50) id 1HiR2e-0000ob-Gd for emacs-devel@gnu.org; Mon, 30 Apr 2007 10:15:28 +0200 User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.1.50 (gnu/linux) X-detected-kernel: Linux 2.4-2.6 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:70395 Archived-At: --=-=-= a month or two back i posted a patch for comment but recevied no replies. i've twiddled it further and post again, including a suitable ChangeLog entry this time: * elisp.texi (Top): Remove "Saving Properties" from detailed menu. * files.texi (Format Conversion): Expand intro. Add documentation for annotations handling, and subsection "Piecemeal Specification". * hooks.texi: Xref "Format Conversion" , not "Saving Properties". * text.texi (Text Properties): Remove "Saving Properties" from menu. (Saving Properties): Delete node/subsection. what do you think? thi --=-=-= Content-Disposition: attachment; filename=.ttn.diff Content-Description: \"Saving Properties\" merge into \"Format Conversion\" Index: elisp.texi =================================================================== RCS file: /sources/emacs/emacs/lispref/elisp.texi,v retrieving revision 1.100 diff -c -r1.100 elisp.texi *** elisp.texi 26 Apr 2007 03:28:30 -0000 1.100 --- elisp.texi 30 Apr 2007 07:41:03 -0000 *************** *** 1062,1069 **** * 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 --- 1062,1067 ---- Index: files.texi =================================================================== RCS file: /sources/emacs/emacs/lispref/files.texi,v retrieving revision 1.106 diff -c -r1.106 files.texi *** files.texi 21 Apr 2007 08:58:15 -0000 1.106 --- files.texi 30 Apr 2007 07:41:03 -0000 *************** *** 374,381 **** @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 --- 374,380 ---- @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 *************** *** 496,504 **** 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. --- 495,503 ---- 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. *************** *** 620,628 **** @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} --- 619,628 ---- @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} *************** *** 2802,2824 **** @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. - @end defvar - - @cindex format definition Each format definition is a list of this form: @example (@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn}) @end example Here is what the elements in a format definition mean: @table @var --- 2802,2862 ---- @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. This section describes ! the fundamental functions that perform this @dfn{format conversion}, ! namely @code{insert-file-contents} for reading a file into a buffer, ! and @code{write-region} for writing a buffer into a file. ! ! @noindent ! 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}; and ! @item calls functions in @code{after-insert-file-functions}. ! @end itemize ! ! @noindent ! The function @code{write-region}: ! ! @itemize ! @item initially, 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 modifies the file with the bytes. ! @end itemize ! ! This shows the symmetry of the lowest-level operations; reading and ! writing handle things in opposite order. The rest of this section ! describes the two facilities surrounding the three variables named ! above, as well as some related functions. @ref{Coding Systems}, for ! details on character encoding and decoding. ! ! @subsection Round-Trip Specification ! ! The most general of the two facilities is controlled by the variable ! @code{format-alist}, a list of @dfn{file format} specifications, which ! describe textual representations used in files for the data in an Emacs ! buffer. The descriptions for reading and writing are paired, which is ! why we call this ``round-trip'' specification (see the following ! subsection for piecemeal specification). @defvar format-alist This list contains one format definition for each defined file format. Each format definition is a list of this form: @example (@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn}) @end example + @end defvar + @cindex format definition + @noindent Here is what the elements in a format definition mean: @table @var *************** *** 2839,2849 **** 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 --- 2877,2884 ---- 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 *************** *** 2866,2880 **** 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 --- 2901,2908 ---- 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 *************** *** 2956,2961 **** --- 2984,3067 ---- in all buffers. @end defvar + @subsection Piecemeal Specification + + In contrast to the round-trip specification described in the previous + subsection, you can use the variables @code{after-insert-file-functions} + and @code{write-region-annotate-functions} to separately control the + respective reading and writing conversions. + + Conversion starts with one representation and produces another + representation. When there is only one conversion to do, there is no + conflict about what to start with. However, when there are multiple + conversions involved, conflict may arise 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. This approach + makes sense for reading because annotations removed by the first + converter can't be mistakenly processed by a later converter. + + 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. + @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.31 diff -c -r1.31 hooks.texi *** hooks.texi 16 Jan 2007 03:28:53 -0000 1.31 --- hooks.texi 30 Apr 2007 07:41:03 -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: text.texi =================================================================== RCS file: /sources/emacs/emacs/lispref/text.texi,v retrieving revision 1.140 diff -c -r1.140 text.texi *** text.texi 28 Apr 2007 03:46:59 -0000 1.140 --- text.texi 30 Apr 2007 07:41:04 -0000 *************** *** 2577,2584 **** * 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 --- 2577,2582 ---- *************** *** 3399,3473 **** @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 --- 3397,3402 ---- --=-=-= Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ Emacs-devel mailing list Emacs-devel@gnu.org http://lists.gnu.org/mailman/listinfo/emacs-devel --=-=-=--