Re: [Q] Re: [PATCH] all my package fixes, mostly build-related

ok. i find packages extremely confusing. almost all documentation i've seen has been a total mess. i've spent some time trying to clean the docs up to be clear. this discussion seems to be typical of it. michael, i don't want to be overcritical of you but you need to spend more time thinking of how to make clear, concise, introductory documentation. this may be why so many people seem confused about how packages work -- much of your docs goes into lots of detail very quickly, but the overviews presenting what you really need to know are not there or very confusing. [btw many many apologies in advance if you didn't write the docs i'm complaining about!!!] currently some of the intro files [e.g. README.packages] are clear, but only because i rewrote them! Beforehand the files were just dismal. The documentation in the .el files is unfortunately even worse, e.g.: (defun paths-construct-info-path (roots early-packages late-packages last-packages) "Construct the info path." ...) (defun paths-find-doc-directory (roots) "Find the documentation directory." ...) (defun paths-find-exec-directory (roots) "Find the binary directory." ...) (defun paths-construct-exec-path (roots exec-directory early-packages late-packages last-packages) "Find the binary path." ...) some examples of problems in the docs: [1] introductory docs need to have clear cross-references to where to find more info. in this case, this might mean a pointer from README.packages to the node in xemacs/startup.texi; but no such pointers exist. [2] startup.texi talks generically about "roots" but its definition of "root" is over-general and very confusing. You need to put in examples -- for example, the fact that <root> = /usr/local [typically] appears nowhere in the document. in fact, there's almost no mention of /usr/local. in general, examples are sorely lacking. [3] it says: By default, XEmacs expects an early package hierarchy in the subdirectory ＠file{.xemacs/xemacs-packages} of the user's home directory. but what goes there? do i put subdirectories xemacs-packages, mule-packages, and site-packages? why do we look only for xemacs-packages here, but elsewhere also mule-packages? what's the purpose of mule-packages? what should the layout under xemacs-packages look like, if i'm new to packages and confused about the whole thing? does xemacs require a specific layout or is it fairly flexible? [i know the answer here [i think!] but i'm indicating areas of problem] in general the docs suffer from a serious case of assumptionitis -- assuming the reader already knows various basic facts, and thereby not specifying them, when in fact these are exactly what is most important to specify. Now: In my case, i have xemacs in-place in /src/xemacs/someworkspace/src/xemacs.exe, and my packages typically get installed into /src/xemacs/xemacs-packages, /src/xemacs/mule-packages, etc. i have to manually set a package-path like PACKAGE_PREFIX=\src\xemacs PACKAGE_PATH=~\.xemacs;;$(PACKAGE_PREFIX)\site-packages;$(PACKAGE_PREFIX)\mule-p ackages;$(PACKAGE_PREFIX)\xemacs-packages for native Windows, or configure ... --package-path=~/.xemacs::/src/xemacs/site-packages:/src/xemacs/xemacs-packa ges:/src/xemacs/mule-packages for Cygwin. Note that symlinks DO NOT work under native Windows. Having to set package-path like this is way bogus. i should just be able to say something like --package-prefix=/src/xemacs and have it construct everything else automatically. can i? i don't know, and the documentation doesn't say. since you think setting package-patch is bad, what should i be doing instead? ben ----- Original Message ----- From: "Michael Sperber [Mr. Preprocessor]" <sperber(a)informatik.uni-tuebingen.de&gt; To: "Stephen J. Turnbull" <stephen(a)xemacs.org&gt; Cc: "Ville Skytt" <scop(a)xemacs.org>; "Ben Wing" <ben(a)xemacs.org>; <xemacs-beta(a)xemacs.org>; <mike(a)xemacs.org>; "Peter Brown" <rendhalver(a)xemacs.org&gt; Sent: Friday, December 06, 2002 5:15 AM Subject: Re: [Q] Re: [PATCH] all my package fixes, mostly build-related packages)