Completion: display of candidates

[Tassilo Horn <tsdh@gnu.org>]

Hi all,

I have a function of one argument which computes a list of completions
matching the given argument.  I can then use

  (completing-read "Prompt: " (completion-table-dynamic #'my-function))

in order to read with completion from the minibuffer.

So far, so good, but I have two questions:

1. The docs for completion-table-dynamic say that the given function
   should return an alist (not just a list) but doesn't describe the
   structure of the entries.  Neither do I find a description in the
   info docs.  So what should it be?

2. Is there a way to display and complete on a different representation
   than the actual completion candidates?  In my case, my-func returns
   absolute file names but I'd like to complete on just the basename,
   and display the entries in the form of "basename (directory)".

Bye,
Tassilo