doc patch: "Saving Properties" merge into "Format Conversion"

doc patch: "Saving Properties" merge into "Format Conversion"

[Thien-Thi Nguyen]

[-- Attachment #1: Type: text/plain, Size: 580 bytes --]

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



[-- Attachment #2: \"Saving Properties\" merge into \"Format Conversion\" --]
[-- Type: text/plain, Size: 18403 bytes --]

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

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Richard Stallman]

Your change is a good start, but the combined node needs subnodes and a menu,
not just subheadings.  Could you try doing that?

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Thien-Thi Nguyen]

[-- Attachment #1: Type: text/plain, Size: 746 bytes --]

() Richard Stallman <rms@gnu.org>
() Tue, 01 May 2007 13:25:08 -0400

   Your change is a good start, but the combined node needs subnodes and a
   menu, not just subheadings.  Could you try doing that?

certainly.  please find attached latest revision w/ subnodes and menu.
here is the updated ChangeLog entry:

 * elisp.texi (Top): Remove "Saving Properties" from detailed menu.
 * files.texi (Format Conversion): Expand intro; add menu.
 (Format Conversion Overview, Format Conversion Round-Trip)
 (Format Conversion Piecemeal): New nodes/subsections.
 * hooks.texi: Xref "Format Conversion" , not "Saving Properties".
 * text.texi (Text Properties): Remove "Saving Properties" from menu.
 (Saving Properties): Delete node/subsection.
	
thi



[-- Attachment #2: doc patch: \"Saving Properties\" merge into \"Format Conversion\" --]
[-- Type: text/plain, Size: 18852 bytes --]

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	2 May 2007 09:25:44 -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	2 May 2007 09:25:44 -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,2871 ----
  @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.
! 
! @menu
! * Overview: Format Conversion Overview.     @code{insert-file-contents} and @code{write-region}
! * Round-Trip: Format Conversion Round-Trip. Using @code{format-alist}.
! * Piecemeal: Format Conversion Piecemeal.   Specifying non-paired conversion.
! @end menu
! 
! @node Format Conversion Overview
! @subsection Overview
! @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.
! 
! @node Format Conversion Round-Trip
! @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
! (@pxref{Format Conversion Piecemeal}, for non-paired 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
--- 2886,2893 ----
  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
--- 2910,2917 ----
  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 ****
--- 2993,3077 ----
  in all buffers.
  @end defvar
  
+ @node Format Conversion Piecemeal
+ @subsection Piecemeal Specification
+ 
+   In contrast to the round-trip specification described in the previous
+ subsection (@pxref{Format Conversion Round-Trip}), 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	2 May 2007 09:25:44 -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	2 May 2007 09:25:45 -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 ----

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Richard Stallman]

It needs some polishing, but it would be good to install for Emacs 23.
Would you like to install it in the unicode-2 branch?

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Stefan Monnier]

> It needs some polishing, but it would be good to install for Emacs 23.
> Would you like to install it in the unicode-2 branch?

Why not simply install it on the trunk?


        Stefan

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Thien-Thi Nguyen]

() Stefan Monnier <monnier@iro.umontreal.ca>
() Wed, 02 May 2007 15:34:22 -0400

   > It needs some polishing, but it would be good to install for Emacs
   > 23.  Would you like to install it in the unicode-2 branch?

   Why not simply install it on the trunk?

do format conversion mechanisms on the unicode-2 branch differ from that
of the trunk?  if not, i concur that installing on the trunk is better.

thi

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Richard Stallman]

We might use the trunk to make Emacs 22.2.  But these changes I'd
rather not put into 22.2.

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Nick Roberts]

 > We might use the trunk to make Emacs 22.2. ...

Will this be before or after Unicode/multi-tty is merged in?  What timescale
are you thinking of? 3 months? 5 years?  Or will you just decide when we get
there?

It's very hard to make any plans if we have no idea when the next release
(after 22.1) is coming, or whether it will be from the trunk or the branch.

-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Juanma Barranquero]

On 5/3/07, Richard Stallman <rms@gnu.org> wrote:

> We might use the trunk to make Emacs 22.2.

Why? What would be the advantage of using the trunk for 22.2 instead
of the EMACS_22_BASE branch?

There is at least one specific disadvantage, i.e., it would delay
merging the unicode and multi-tty branches onto the trunk.

             Juanma

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Kim F. Storm]

"Juanma Barranquero" <lekktu@gmail.com> writes:
"Juanma Barranquero" <lekktu@gmail.com> writes:

> On 5/3/07, Richard Stallman <rms@gnu.org> wrote:
>
>> We might use the trunk to make Emacs 22.2.

What a wonderful idea!  Soooo completely illogical and out of sync
with any release procedure (that actually aims are making progress
towards a release).

>
> Why? What would be the advantage of using the trunk for 22.2 instead
> of the EMACS_22_BASE branch?

His statement above and the current talks about merging the RMAIL mbox
branch (which IIUC don't really have a current maintainer) could
indicate that RMS wants to make a 22.2 release which includes just the
Rmail branch...

>
> There is at least one specific disadvantage, i.e., it would delay
> merging the unicode and multi-tty branches onto the trunk.

Indeed!

I'm not usually paranoid, but isn't this just another strong
indication of the secret(?) plan to delay -- as much as possible --
not just 22.1, but also every possible future release.


-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Thien-Thi Nguyen]

() Richard Stallman <rms@gnu.org>
() Wed, 02 May 2007 22:02:16 -0400

   We might use the trunk to make Emacs 22.2.  But these changes I'd
   rather not put into 22.2.

i would rather not check it into any particular branch.  doing so makes
it easy to forget about.  instead, i'll keep polishing the changes until
the time when they will be acceptable fir installation on the trunk.

could you tell me what you had in mind wrt further polishing?

thi

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Stefan Monnier]

> We might use the trunk to make Emacs 22.2.  But these changes I'd
> rather not put into 22.2.

Sorry, Richard, but that makes no sense.


        Stefan

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Richard Stallman]

    > We might use the trunk to make Emacs 22.2.

    Why? What would be the advantage of using the trunk for 22.2 instead
    of the EMACS_22_BASE branch?

It enables me to install changes now for 22.2 without putting them
into 22.1.

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Richard Stallman]

    could you tell me what you had in mind wrt further polishing?

Just details of the wording.  I figured on doing that myself
after installation.

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Nick Roberts]

 >     Why? What would be the advantage of using the trunk for 22.2 instead
 >     of the EMACS_22_BASE branch?
 > 
 > It enables me to install changes now for 22.2 without putting them
 > into 22.1.

Or, alternatively, you could make a release from EMACS_22_BASE and then
install your changes there.  Just an idea.

-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Juanma Barranquero]

On 5/4/07, Nick Roberts <nickrob@snap.net.nz> wrote:

> Or, alternatively, you could make a release from EMACS_22_BASE and then
> install your changes there.  Just an idea.

Naaa. Way too radical.

             Juanma

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Thien-Thi Nguyen]

() Richard Stallman <rms@gnu.org>
() Thu, 03 May 2007 19:55:48 -0400

       could you tell me what you had in mind wrt further polishing?

   Just details of the wording.  I figured on doing that myself
   after installation.

in that case, there is nothing for me to do except wait (and possibly futz
further).  i will ping periodically (every 2-3 months) to find out when it
will be acceptable to install in the trunk.

thi

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

>     > We might use the trunk to make Emacs 22.2.
>
>     Why? What would be the advantage of using the trunk for 22.2 instead
>     of the EMACS_22_BASE branch?
>
> It enables me to install changes now for 22.2 without putting them
> into 22.1.

And further delay anything else for everybody else.

Typical, just typical.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Richard Stallman]

     > It enables me to install changes now for 22.2 without putting them
     > into 22.1.

    Or, alternatively, you could make a release from EMACS_22_BASE and then
    install your changes there.  Just an idea.

You mean, not install those changes at all until after the release?
That would work, but I want to get them off my plate now.

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

>      > It enables me to install changes now for 22.2 without putting them
>      > into 22.1.
>
>     Or, alternatively, you could make a release from EMACS_22_BASE and then
>     install your changes there.  Just an idea.
>
> You mean, not install those changes at all until after the release?
> That would work, but I want to get them off my plate now.

So make the release _today_, and install your changes _tomorrow_.


We all have a huge pile of changes that we would like to get off our
plates (where they have been boiling for years already).

Why should there be special rules for your changes?

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Nick Roberts]

 >     Or, alternatively, you could make a release from EMACS_22_BASE and then
 >     install your changes there.  Just an idea.
 > 
 > You mean, not install those changes at all until after the release?
 > That would work, but I want to get them off my plate now.

When I started contributing, emacs-devel was a vibrant mailing list, but it
no longer feels like one, and statistics seem to confirm this (*).

You don't say what changes you intend to install, but I can see no logic in
putting them there.  I can only guess that the purpose is to stall development
on the trunk.  Whatever your goals, I think some of us feel that we are just
being used to serve them.  You talk of community, but it's not the kind
with which I'm familiar.

-- 
Nick                                           http://www.inet.net.nz/~nickrob


(*) http://www.ohloh.net/projects/3547/factoids/121960

Factoid: "Decreasing year-over-year development activity"

Over the last twelve months, GNU Emacs has seen a substantial decline in
development activity. This could mean many things. This may be a warning sign
that interest in this project is waning, or it may indicate a maturing software
base that requires fewer fixes.

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Richard Stallman]

    We all have a huge pile of changes that we would like to get off our
    plates (where they have been boiling for years already).

    Why should there be special rules for your changes?

They aren't special rules.  I think your anger is running away with
you.

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Richard Stallman]

    When I started contributing, emacs-devel was a vibrant mailing list, but it
    no longer feels like one, and statistics seem to confirm this (*).

What that proves that a number of people don't like my decisions
and are saying negative things.  I know what they think.  That doesn't
mean they are right.

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

>     When I started contributing, emacs-devel was a vibrant mailing
>     list, but it no longer feels like one, and statistics seem to
>     confirm this (*).
>
> What that proves that a number of people don't like my decisions

The word "decision" only makes sense in connection with actually going
through with something.

> and are saying negative things.  I know what they think.  That
> doesn't mean they are right.

But it means they are stopping to contribute, and that does not
particularly help Emacs.  Being "right" does nothing to help your
cause.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Nick Roberts]

 >     When I started contributing, emacs-devel was a vibrant mailing list, but
 >     it no longer feels like one, and statistics seem to confirm this (*).
 > 
 > What that proves that a number of people don't like my decisions
 > and are saying negative things.  I know what they think.  That doesn't
 > mean they are right.

It's not so much about what is right, but what is reasonable.  With social
issues, that's normally decided collectively, as with a jury in a court of
law.

-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Miles Bader]

Nick Roberts <nickrob@snap.net.nz> writes:
> It's not so much about what is right, but what is reasonable.  With social
> issues, that's normally decided collectively, as with a jury in a court of
> law.

Richard's actions towards the release aren't perfect, but in general
things seem like they're getting there.

There are some people who apparently think hysterics, apocalyptic
predictions, and sheer volume are the key to promoting their point of
view.

I also disagree with some of Richard's ideas (e.g. releasing 22.2 from
the trunk, the microseconds/milliseconds/whatever patch), but I don't
think screaming and moaning is going to solve a damn thing, particularly
at a time when the right thing to do is move carefully and deliberately.

Grow up people.  You can disagree without acting like a spoiled 2 year old.

-miles
-- 
[|nurgle|]  ddt- demonic? so quake will have an evil kinda setting? one that
            will  make every christian in the world foamm at the mouth?
[iddt]      nurg, that's the goal

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[David Kastrup]

Miles Bader <miles@gnu.org> writes:

> I also disagree with some of Richard's ideas (e.g. releasing 22.2
> from the trunk, the microseconds/milliseconds/whatever patch), but I
> don't think screaming and moaning is going to solve a damn thing,
> particularly at a time when the right thing to do is move carefully
> and deliberately.

The "screaming and moaning" happens exactly because the right thing to
do would be to move carefully and deliberately, and this simply does
not happen.  Since there is pretty much nothing left for people on the
trunk/base to facilitate a release, I don't consider it out of the
place to discuss how and where people can actually still accomplish
work without being at fault for delaying the release.

> Grow up people.  You can disagree without acting like a spoiled 2
> year old.

A 2 year old would not remember what an Emacs release was like...

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Juanma Barranquero]

On 5/6/07, Miles Bader <miles@gnu.org> wrote:

> Richard's actions towards the release aren't perfect, but in general
> things seem like they're getting there.

Do you want the same (non-documented, AFAIK) release procedures being
used for future releases? Would you consider acceptable to delay 23.1
if not for five years like 22.1, for two or three?

People who volunteer their time and energy to this project, and just
want a more productive development/release model, do not deserve being
called "negative" or compared to spoiled brats, IMO.

             Juanma

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Jan Djärv]

David Kastrup skrev:
> Miles Bader <miles@gnu.org> writes:
> 
> 
>> Grow up people.  You can disagree without acting like a spoiled 2
>> year old.
> 
> A 2 year old would not remember what an Emacs release was like...

That should go into etc/DEVEL.HUMOR.

	Jan D.

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Miles Bader]

"Juanma Barranquero" <lekktu@gmail.com> writes:
>> Richard's actions towards the release aren't perfect, but in general
>> things seem like they're getting there.
>
> Do you want the same (non-documented, AFAIK) release procedures being
> used for future releases? Would you consider acceptable to delay 23.1
> if not for five years like 22.1, for two or three?

No.  But these stupid antics are _not_ helping.

-miles

-- 
Everywhere is walking distance if you have the time.  -- Steven Wright

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[David Kastrup]

Jan Djärv <jan.h.d@swipnet.se> writes:

> David Kastrup skrev:
>> Miles Bader <miles@gnu.org> writes:
>>
>>
>>> Grow up people.  You can disagree without acting like a spoiled 2
>>> year old.
>>
>> A 2 year old would not remember what an Emacs release was like...
>
> That should go into etc/DEVEL.HUMOR.

Not before the release.  We don't have the time to design and run
regression tests for all possibly affected humor evaluating entities.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Juanma Barranquero]

On 5/6/07, Miles Bader <miles@gnu.org> wrote:

> No.  But these stupid antics are _not_ helping.

I wouldn't call questioning the procedures and the wisdom of freezing
the trunk "stupid antics".

             Juanma

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[David Kastrup]

"Juanma Barranquero" <lekktu@gmail.com> writes:

> On 5/6/07, Miles Bader <miles@gnu.org> wrote:
>
>> No.  But these stupid antics are _not_ helping.
>
> I wouldn't call questioning the procedures and the wisdom of
> freezing the trunk "stupid antics".

To "question procedures", there must be procedures in place.  I don't
think we have any, and certainly not any that everybody would adhere
to.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Miles Bader]

"Juanma Barranquero" <lekktu@gmail.com> writes:
>> No.  But these stupid antics are _not_ helping.
>
> I wouldn't call questioning the procedures and the wisdom of freezing
> the trunk "stupid antics".

I'm not objecting to "questioning", I'm objecting to over the top
flaming.  Tone counts.

-miles
-- 
Come now, if we were really planning to harm you, would we be waiting here,
 beside the path, in the very darkest part of the forest?

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Juanma Barranquero]

On 5/6/07, Miles Bader <miles@gnu.org> wrote:

> I'm objecting to over the top flaming.

Well, I'd say that calling "over the top flaming" to messages of
people in this list venting a little frustration is over the top
flaming itself.

> Tone counts.

Agreed.

             Juanma

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Eli Zaretskii]

> From: Miles Bader <miles@gnu.org>
> Date: Sun, 06 May 2007 13:51:52 +0900
> Cc: lekktu@gmail.com, rms@gnu.org, emacs-devel@gnu.org
> 
> There are some people who apparently think hysterics, apocalyptic
> predictions, and sheer volume are the key to promoting their point of
> view.
> 
> I also disagree with some of Richard's ideas (e.g. releasing 22.2 from
> the trunk, the microseconds/milliseconds/whatever patch), but I don't
> think screaming and moaning is going to solve a damn thing, particularly
> at a time when the right thing to do is move carefully and deliberately.
> 
> Grow up people.  You can disagree without acting like a spoiled 2 year old.

I don't necessarily subscribe to every heated word that's been uttered
here lately, but I think your interpretation is mistaken.  People are
not hysterical nor spoiled-2-year-olds, they are desperate.  Desperate
people can act like this, I'm sure you will agree.

The way to avoid this is not to cause despair in the first place.

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Richard Stallman]

    It's not so much about what is right, but what is reasonable.  With social
    issues, that's normally decided collectively, as with a jury in a court of
    law.

When and how to make a release is a question for the maintainer
to decide, and I'm the maintainer.

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Richard Stallman]

I try to read as little as possible of the messages that vent
frustration at me.  Even so, they make me angry at the people who sent
them.  If I focused on them more, I might start to develop a permanent
bitterness towards the senders.

I appreciate the help that many of you have given to the development
of Emacs, but badgering and bullying is not help.

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Stefan Monnier]

> I appreciate the help that many of you have given to the development
> of Emacs, but badgering and bullying is not help.

I think we all understand that.  But you are extremely hard headed, which is
a great quality in many cases, but also risks alienating people.
People don't vent their frustration just for the fun of it.  I believe they
merit more respect than to just ignore their frustration.


        Stefan "who wishes you could use your hard headedness when deciding
                and imposing a feature freeze"

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Thien-Thi Nguyen]

() Richard Stallman <rms@gnu.org>
() Sun, 06 May 2007 18:25:40 -0400

   When and how to make a release is a question for the maintainer
   to decide, and I'm the maintainer.

maintaining the source code requires transparency of source code
manipulation; maintaining the peace requires transparency of intent.

what frustrates people is insufficiency in the latter, not because they
wish to take away the decision from the maintainer, but because they
wish to organize their (parallel, unrelated to the release) efforts
best.

not taking the seething into account is the difference between hardware
and software engineers: in hardware, one-armed-if is a latent bug; even
when you don't care, it's better to explicitly don't care.

practically speaking, i think you would be wise as the maintainer to
declare the trunk open to full-fledged non-release-related hacking, and
confine edits slated only for the release to a branch.  (if that branch
is not yet in place, make it immediately, then declare the trunk open.)

that's all i have to say on the matter.

thi

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Kevin Ryde]

At the risk of posting in this thread on its original subject ...

Thien-Thi Nguyen <ttn@gnuvola.org> writes:
>
> ! 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.
>   
> --- 2886,2893 ----
>   
> ! If @var{from-fn} is a function, it is treated like those listed
> ! in @code{after-insert-file-functions}.

That's not losing how the decode func is called is it?  The calls are
not the same as after-insert-file-functions are they?

> + @defvar after-insert-file-functions
> + A list of functions for @code{insert-file-contents} to call.
> + @end defvar

Is that also losing the description of the args to those funcs?

Re: doc patch: "Saving Properties" merge into "Format Conversion"

[Thien-Thi Nguyen]

[-- Attachment #1: Type: text/plain, Size: 358 bytes --]

() Kevin Ryde <user42@zip.com.au>
() Tue, 08 May 2007 01:59:19 +1000

   [...] That's not losing how the decode func is called is it?  The
   calls are not the same as after-insert-file-functions are they?

   [...] Is that also losing the description of the args to those funcs?

good catch.  i've reverted the lossage (locally).  latest diff below.

thi



[-- Attachment #2: \"Saving Properties\" merge into \"Format Conversion\" --]
[-- Type: text/plain, Size: 17193 bytes --]

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	8 May 2007 20:16:38 -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	8 May 2007 20:16:39 -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,2871 ----
  @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.
! 
! @menu
! * Overview: Format Conversion Overview.     @code{insert-file-contents} and @code{write-region}
! * Round-Trip: Format Conversion Round-Trip. Using @code{format-alist}.
! * Piecemeal: Format Conversion Piecemeal.   Specifying non-paired conversion.
! @end menu
! 
! @node Format Conversion Overview
! @subsection Overview
! @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.
! 
! @node Format Conversion Round-Trip
! @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
! (@pxref{Format Conversion Piecemeal}, for non-paired 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
***************
*** 2956,2961 ****
--- 3003,3091 ----
  in all buffers.
  @end defvar
  
+ @node Format Conversion Piecemeal
+ @subsection Piecemeal Specification
+ 
+   In contrast to the round-trip specification described in the previous
+ subsection (@pxref{Format Conversion Round-Trip}), 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
+ Each function in this list is called by @code{insert-file-contents}
+ with one argument, the number of characters inserted, and should
+ return the new character count, leaving point the same.
+ @c ??? The docstring mentions a handler from `file-name-handler-alist'
+ @c     "intercepting" `insert-file-contents'.  Hmmm.  --ttn
+ @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	8 May 2007 20:16:39 -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	8 May 2007 20:16:39 -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 ----

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel