Re: docs for ewoc.el

[Eli Zaretskii]

> From: Thien-Thi Nguyen <address@hidden>
> 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 @address@hidden 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 address@hidden

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

TIA