docs for ewoc.el

docs for ewoc.el

[Thien-Thi Nguyen]

below is a texinfo @node for ewoc.el, written w/ the operating
assumption that it should go into lispref/display.texi right before
@node Fringes.  is there is a better place for it?  what do you think?

thi


_________________________________________
@node Abstract Display
@section Abstract Display

  Generally, to display an object in a buffer, you must decide on its
representation, as either text or image, and insert that representation in
the buffer.  When the object changes, you must update its representation
appropriately.  The common infrastructure of these tasks is the focus of the
@code{ewoc-} set of functions, which altogether form a utility to maintain a
view of a list of objects in a buffer.

  These functions define and pass around an @dfn{ewoc}, which is a data
structure encapsulating @dfn{header} and @dfn{footer} (strings); a
@dfn{pretty-printer} function that is responsible for inserting object
representations in the buffer; and an ordered set of @dfn{nodes}, with one
node per object in your list.

  To define an ewoc, use @code{ewoc-create}.  To get an ewoc's buffer, header
and footer, use @code{ewoc-buffer} and @code{ewoc-get-hf}, respectively.  To
change the header and/or footer, use @code{ewoc-set-hf}.

@defun ewoc-create pretty-printer &optional header footer
This constructs and returns a new ewoc, with no data elements.
@var{pretty-printer} should be a function that tkaes one argument,
a data element, and inserts at point a string representation of it,
using @code{insert} (and not @code{insert-before-markers}).
@end defun

@defun ewoc-buffer ewoc
@defunx ewoc-get-hf ewoc
These return, respectively, the buffer where @var{ewoc} was created,
and its header and footer as a cons cell @code{(header . footer)}.
@end defun

@defun ewoc-set-hf ewoc header footer
This sets the header and footer of @var{ewoc} to @var{header} and @var{footer}
(both strings).
@end defun

  To add nodes, use the @code{ewoc-enter-FOO} functions.  To refer to a node's
neighbor, use @code{ewoc-prev} and @code{ewoc-next}.  To refer to a node by a
modulo index into the ewoc, use @code{ewoc-nth}.  To access a node's data, use
@code{ewoc-data}.

@defun ewoc-enter-first ewoc data
@defunx ewoc-enter-last ewoc data
These construct a new node encapsulating @var{data}, adding it to @var{ewoc}
at the beginning or end, respectively, of the set of ordered nodes.
@end defun

@defun ewoc-enter-before ewoc node data
@defunx ewoc-enter-after ewoc node data
These construct a new node encapsulating @var{data}, adding it to @var{ewoc}
before or after @var{node}, respectively.
@end defun

@defun ewoc-prev ewoc node
@defunx ewoc-next ewoc node
These return the previous and next node, respectively, of @var{node}
in @var{ewoc}.
@end defun

@defun ewoc-nth ewoc n
This returns the node in @var{ewoc} found at zero-based index @var{n}.
A negative @var{n} means count from the end.  @code{ewoc-nth} returns
@code{nil} if there are less than @var{n} elements.
@end defun

@defun ewoc-data node
This extracts the data encapsulated by @var{node} and returns it.
@end defun

  To find out which node (if any) point is at in an ewoc, use
@code{ewoc-locate}.  If you already have a node, to find its start position,
use @code{ewoc-location}.  To move point from the start of one representation
to another, use the @code{ewoc-goto-FOO} functions.

@defun ewoc-locate ewoc &optional pos guess
This determines which node in @var{ewoc} point (or @var{pos} if specified) is
within and returns that node.  If @var{ewoc} is empty, it returns @code{nil}.
If @var{pos} is before the first node or after the last node, it returns that
node.  Optional third arg @var{guess} should be a node that is likely to be
near @var{pos}.
@end defun

@defun ewoc-location node
This returns the start position of @var{node}.
@end defun

@defun ewoc-goto-prev ewoc arg
@defunx ewoc-goto-next ewoc arg
These move point to the previous or next, respectively, @var{arg}th node
in @var{ewoc}.  @code{ewoc-goto-prev} does not move if it is already at the
first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next} moves past
the last node, returning @code{nil}.  Excepting this special case, these
functions return the node moved to.
@end defun

@defun ewoc-goto-node ewoc node
This moves point to the start of @var{node} in @var{ewoc}.
@end defun

  To completely recompute and redisplay the representations of all nodes in an
ewoc, use @code{ewoc-refresh}.  For only a few, use @code{ewoc-invalidate}.
To delete nodes, use @code{ewoc-filter}.  To form a list of data elements
satisfying a certain predicate, use @code{ewoc-collect}.  To map a function
over all nodes, use @code{ewoc-map}.

@defun ewoc-refresh ewoc
This deletes the region bounded by the header end and the footer beginning in
@var{ewoc}, i.e., all the data elements' representations, and then calls the
pretty-printer function for each node, in order.
@end defun

@defun ewoc-invalidate ewoc &rest nodes
This is similar to @code{ewoc-refresh}, except that only @var{nodes} in
@var{ewoc} are updated instead of the entire set.
@end defun

@defun ewoc-filter ewoc predicate &rest args
This calls @var{predicate} for each data element in @var{ewoc} and
removes those nodes for which @var{predicate} returns @code{nil}.
If any @var{args} are given they will be passed to @var{predicate}.
@end defun

@defun ewoc-collect ewoc predicate &rest args
This calls @var{predicate} for each data element in @var{ewoc}
and returns a list of those elements for which @var{predicate}
returns non-@code{nil}.  The elements in the list are ordered
as in the buffer.  If more than two arguments are
given the remaining arguments will be passed to @var{predicate}.
@end defun

@defun ewoc-map map-function ewoc &rest args
This calls @var{map-function} for each data element in @var{ewoc} and
updates those nodes for which @var{map-function} returns non-@code{nil}.
If more than two arguments are given, the remaining
arguments will be passed to @var{map-function}.
@end defun

Re: docs for ewoc.el

[Eli Zaretskii]

> From: Thien-Thi Nguyen <ttn@gnu.org>
> Date: Wed, 17 May 2006 13:06:36 +0200
> 
> below is a texinfo @node for ewoc.el, written w/ the operating
> assumption that it should go into lispref/display.texi right before
> @node Fringes.  is there is a better place for it?  what do you think?

Thanks.

Please wait for Richard to give the definitive answers.  What's below
is some comments on the markup and the text you wrote.

> @node Abstract Display
> @section Abstract Display

One or more @cindex entries here, please.  Imagine someone who is in
search of this stuff, and add index entries for words or phrases she
will think of when looking for this information.

>   These functions define and pass around an @dfn{ewoc}, which is a data
> structure encapsulating @dfn{header} and @dfn{footer} (strings); a

I suggest ``encapsulating two strings, @dfn{header} and @dfn{footer}''.

> a data element, and inserts at point a string representation of it,
                                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
I think it's better to say ``its string representation''.

> appropriately.  The common infrastructure of these tasks is the focus of the
> @code{ewoc-} set of functions, which altogether form a utility to maintain a
> view of a list of objects in a buffer.

Wouldn't it be better to say ``together'' instead of ``altogether''?

> @var{pretty-printer} should be a function that tkaes one argument,
                                                 ^^^^^
A typo.

> @defun ewoc-buffer ewoc
> @defunx ewoc-get-hf ewoc
> These return, respectively, the buffer where @var{ewoc} was created,
> and its header and footer as a cons cell @code{(header . footer)}.
                                                  ^^^^^^^^^^^^^^^
This should use @var{header} and @var{footer}, since those are
placebos, not actual symbols.

>   To add nodes, use the @code{ewoc-enter-FOO} functions.  To refer to a node's
                          ^^^^^^^^^^^^^^^^^^^^^
This should be @code{ewoc-enter-@var{node-spec}} or some such, and
there should be text that shows the full repertoire of the node-spec
part.  I understand that @var{node-spec} can be first, last, before,
and after, is that right?

> to another, use the @code{ewoc-goto-FOO} functions.
                      ^^^^^^^^^^^^^^^^^^^^
Same here.

> This determines which node in @var{ewoc} point (or @var{pos} if specified) is
> within and returns that node.

This style looks awkwardly non-English.  I'd rearrange like this:

  This determines the node in @var{ewoc} which contains point (or
  @var{pos} if specified), and returns that node.

> If any @var{args} are given they will be passed to @var{predicate}.

I think this needs a comma after ``given''.

> as in the buffer.  If more than two arguments are
> given the remaining arguments will be passed to @var{predicate}.

Same here.

> @defun ewoc-map map-function ewoc &rest args
> This calls @var{map-function} for each data element in @var{ewoc} and
> updates those nodes for which @var{map-function} returns non-@code{nil}.

I couldn't understand from this description how are the nodes
updated.  Elaborate, please.

TIA

Re: docs for ewoc.el

[Thien-Thi Nguyen]

Eli Zaretskii <eliz@gnu.org> writes:

> comments

thanks for the comments.
following is a revision taking them into account.

thi


___________________________________
@node Abstract Display
@section Abstract Display
@cindex display, abstract
@cindex display, arbitrary objects
@cindex model/view/controller
@cindex view part, model/view/controller

  Generally, to display an object in a buffer, you must decide on its
representation, as either text or image, and insert that representation in
the buffer.  When the object changes, you must update its representation
appropriately.  The common infrastructure of these tasks is the focus of the
@code{ewoc-} set of functions, which together form a utility to maintain a
view of a list of objects in a buffer.

  These functions define and pass around an @dfn{ewoc}, which is a data
structure encapsulating two strings, @dfn{header} and @dfn{footer}; a
@dfn{pretty-printer} function that is responsible for inserting object
representations in the buffer; and an ordered set of @dfn{nodes}, with one
node per object in your list.

  To define an ewoc, use @code{ewoc-create}.  To get an ewoc's buffer, header
and footer, use @code{ewoc-buffer} and @code{ewoc-get-hf}, respectively.  To
change the header and/or footer, use @code{ewoc-set-hf}.

@defun ewoc-create pretty-printer &optional header footer
This constructs and returns a new ewoc, with no data elements.
@var{pretty-printer} should be a function that takes one argument,
a data element, and inserts at point its string representation,
using @code{insert} (and not @code{insert-before-markers}).
@end defun

@defun ewoc-buffer ewoc
@defunx ewoc-get-hf ewoc
These return, respectively, the buffer where @var{ewoc} was created, and
its header and footer as a cons cell @code{(@var{header} . @var{footer})}.
@end defun

@defun ewoc-set-hf ewoc header footer
This sets the header and footer of @var{ewoc} to the strings @var{header}
and @var{footer}, respectively.
@end defun

  To add nodes, use the @code{ewoc-enter-@var{where}} functions.  To refer to
a node's neighbor, use @code{ewoc-prev} and @code{ewoc-next}.  To refer to a
node by a modulo index into the ewoc, use @code{ewoc-nth}.  To access a node's
data, use @code{ewoc-data}.

@defun ewoc-enter-first ewoc data
@defunx ewoc-enter-last ewoc data
These construct a new node encapsulating @var{data}, adding it to @var{ewoc}
at the beginning or end, respectively, of the set of ordered nodes.
@end defun

@defun ewoc-enter-before ewoc node data
@defunx ewoc-enter-after ewoc node data
These construct a new node encapsulating @var{data}, adding it to @var{ewoc}
before or after @var{node}, respectively.
@end defun

@defun ewoc-prev ewoc node
@defunx ewoc-next ewoc node
These return the previous and next node, respectively, of @var{node}
in @var{ewoc}.
@end defun

@defun ewoc-nth ewoc n
This returns the node in @var{ewoc} found at zero-based index @var{n}.
A negative @var{n} means count from the end.  @code{ewoc-nth} returns
@code{nil} if there are less than @var{n} elements.
@end defun

@defun ewoc-data node
This extracts the data encapsulated by @var{node} and returns it.
@end defun

  To find out which node (if any) point is at in an ewoc, use
@code{ewoc-locate}.  If you already have a node, to find its start position,
use @code{ewoc-location}.  To move point from the start of one representation
to another, use the @code{ewoc-goto-@var{where}} functions.

@defun ewoc-locate ewoc &optional pos guess
This determines the node in @var{ewoc} which contains point (or @var{pos} if
specified), and returns that node.  If @var{ewoc} is empty, it returns
@code{nil}.  If @var{pos} is before the first node or after the last node, it
returns that node.  Optional third arg @var{guess} should be a node that is
likely to be near @var{pos}.
@end defun

@defun ewoc-location node
This returns the start position of @var{node}.
@end defun

@defun ewoc-goto-prev ewoc arg
@defunx ewoc-goto-next ewoc arg
These move point to the previous or next, respectively, @var{arg}th node
in @var{ewoc}.  @code{ewoc-goto-prev} does not move if it is already at the
first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next} moves past
the last node, returning @code{nil}.  Excepting this special case, these
functions return the node moved to.
@end defun

@defun ewoc-goto-node ewoc node
This moves point to the start of @var{node} in @var{ewoc}.
@end defun

  To completely recompute and redisplay the representations of all nodes in an
ewoc, use @code{ewoc-refresh}.  For only a few, use @code{ewoc-invalidate}.
To delete nodes, use @code{ewoc-filter}.  To form a list of data elements
satisfying a certain predicate, use @code{ewoc-collect}.  To map a function
over all nodes, use @code{ewoc-map}.

@defun ewoc-refresh ewoc
This deletes the region bounded by the header end and the footer beginning in
@var{ewoc}, i.e., all the data elements' representations, and then calls the
pretty-printer function for each node, in order.
@end defun

@defun ewoc-invalidate ewoc &rest nodes
This is similar to @code{ewoc-refresh}, except that only @var{nodes} in
@var{ewoc} are updated instead of the entire set.
@end defun

@defun ewoc-filter ewoc predicate &rest args
This calls @var{predicate} for each data element in @var{ewoc} and
removes those nodes for which @var{predicate} returns @code{nil}.
Any @var{args} are passed to @var{predicate}.
@end defun

@defun ewoc-collect ewoc predicate &rest args
This calls @var{predicate} for each data element in @var{ewoc}
and returns a list of those elements for which @var{predicate}
returns non-@code{nil}.  The elements in the list are ordered
as in the buffer.  Any @var{args} are passed to @var{predicate}.
@end defun

@defun ewoc-map map-function ewoc &rest args
This calls @var{map-function} for each data element in @var{ewoc} and
updates those nodes for which @var{map-function} returns non-@code{nil}.
Any @var{args} are passed to @var{map-function}.
@end defun