Re: autoload and auto-compression-mode

[Eli Zaretskii]

> Date: Mon, 20 Feb 2006 23:28:22 -0600 (CST)
> From: Luc Teirlinck <address@hidden>
> CC: address@hidden, address@hidden,
>         address@hidden
> 
> I substantialy shortened the docstrings of `load-suffixes' and the
> still to be renamed `load-file-rep-suffixes'

Too much, I think.  See below.

> *** 669,674 ****
> --- 691,708 ----
>   If optional fifth arg MUST-SUFFIX is non-nil, insist on
>    the suffix `.elc' or `.el'; don't accept just FILE unless
>    it ends in one of those suffixes or includes a directory name.
> + If this function fails to find a file, it may look for different
> +  representations of that file before trying another file.
> +  It does so by adding the non-empty suffixes in `load-file-rep-suffixes'
> +  to the file name.  Emacs uses this feature mainly to find compressed
> +  versions of files when Auto Compression mode is enabled.
> + 
> + The exact suffixes that this function tries out, in the exact order,
> + are given by the value of the variable `load-file-rep-suffixes' if
> + NOSUFFIX is non-nil and by the return value of the function
> + `get-load-suffixes' if MUST-SUFFIX is non-nil.  If both NOSUFFIX and
> + MUST-SUFFIX are nil, this function first tries out the latter suffixes
> + and then the former..

First, what happened to indentation here?  The extra spaces are funny.

Second, there's a spurious period at the end of the last sentence.

And finally, I'm sorry to say that this description still leaves me
confused.  Why do we need 2 lists, and why one of them is a literal
list, while the other is returned by a function?

>     DEFVAR_LISP ("load-suffixes", &Vload_suffixes,
> !            doc: /* List of suffixes for (compiled or source) Emacs Lisp 
> files.
> ! This should not include the empty string.
> ! `load' and related functions use this.  */);
>     Vload_suffixes = Fcons (build_string (".elc"),
>                         Fcons (build_string (".el"), Qnil));
> +   DEFVAR_LISP ("load-file-rep-suffixes", &Vload_file_rep_suffixes,
> +            doc: /* List of suffixes that indicate representations of \
> + the same file.
> + This list should normally start with the empty string.
> + `load' and related functions use this.  */);

These two doc strings should at least tell that the details of how
these lists are used are described in the doc string of `load' (if
that's the intent).  Just saying that `load' and the unnamed ``related
functions'' use does not immediately invites me to look there for a
detailed description.  Perhaps even duplicate the necessary parts of
the description, the xref feature shouldn't be abused too much, I
think.  I never liked the approach that forces me to read half-dozen
other doc strings to figure out all the details of some variable.