Missing dired documentation

rrt> I just noticed that the dired documentation appears to be way rrt> out of date [...]. Dired is externally maintained, and there should be a separate dired topic under packages. I'm cc'ing dired-bugs(a)xemacs.org, which redirects reports to the Dired maintainer. I suspect Michael would be very happy to receive a contribution of a split-out and up-to-date Info manual for Dired. [Mike: the rest is not directly relevant to Dired, except that it looks like you may have a volunteer to do exactly that. :) ] rrt> This is a problem I've noticed more than once in XEmacs: that rrt> the main info files appear to be horribly out of date in rrt> several cases. Would it not be possible to sync them with FSF rrt> Emacs's latest versions? Yes, it's possible. We do our best, but documentation is relatively low priority to most of our volunteers. I'd like to change that, but volunteers are volunteers. We don't have _any_ paid staff (AFAIK), unlike the FSF. You are very welcome to do the synchs and submit patches. rrt> I can't imagine that the changes would be very great rrt> (although I'm sure that it's a bit more than rrt> s/Emacs/XEmacs/!). Try it. It's harder than you think to do it well. It's not clear to me that doing it halfway, and then fixing what's broke, is a good strategy, either. There's likely to be a fair amount of breakage. The FSF regularly makes API and semantic changes. We don't find out about them until after release because it is apparently FSF policy to deny XEmacs developers access to the FSF developer lists for the purpose of synchronization. rms considers it "industrial espionage." Nor does the FSF make any visible attempt to avoid collision with XEmacs extensions to the API. Finally, due to the package system, it is extremely common that our package is newer than that of the FSF (eg, Gnus---a very special case---was 2.5 years older in FSF 20.x than in our package system the last time I checked). Not to mention that the FSF assumes a free hand to modify the packages to fit in better with FSF UIs and APIs. This means that although there may be few changes from FSF reality to XEmacs reality, _every single proposed doc synch_ must be vetted to ensure that it doesn't introduce an error. I wish we had volunteers to do this, too, but I can't quite bring myself to berate the volunteers we do have for not doing more of it. It's painstaking, not very exciting work. Our best developers do it for their own changes, and some even go the extra mile and work on other developers' docs. But we're spread too thin to do it very quickly. Even the documentation I'm working on personally is _new_ documentation. Arguably we should get what we have up-to-date first, but I happen to disagree. I'm working on "process" documents in the hope that explaining how we do things will encourage people to submit more fixes and enhancements, including to docs rrt> I'm very keen to have this fixed, so I'd be happy to do it rrt> myself with a bit of guidance. 1. Read the info files on Texinfo: C-h i m info RET m creating RET. 2. Skim the standards documents, C-h i m standards RET. Note that our coding practices differ from the GNU standard in a few ways, but the standards are mostly accurate. Coding standards are generally not applicable to user documentation, but some code does leak through into the user documentation and it should be done correctly. If you decide to work on the Lispref or Internals documents, you should also read the first 9 chapters of the Internals manual. 3. I don't know what our policy on texinfo mode is (ie, there isn't one), but I know that many of our texi files do not comply with its conventions. You're welcome to improve conformance. 4. Compare changes against docstrings, which are typically more up-to-date than the Info documentation. Eg, C-h m in Dired mode presumably _does_ document the "m" command. 5. Test all changes to make sure that XEmacs actually behaves as documented. 6. The style (ie, usage of face-changing directives, etc) in the XEmacs Texinfo sources is as unreliable as the content. I don't have good examples to point to offhand, so you might want to follow the FSF docs you're synching to. However, at this point we are trying to support both texinfo.el and makeinfo 1.68 (IIRC), so some of the more modern "logical" directives (eg, the ＠env{} form) should be avoided. (This policy is due to the fact that native Windows builds do not have an easy source of up-to-date GNU utilities; we are considering changing it, but for the moment that is the policy.) 7. Submit patches to xemacs-patches(a)xemacs.org, or in the case of packaged Lisp libraries like Dired, to the maintainer. We have convenience aliases ＠xemacs.org for each package. The preferred format for patches is unified CVS diff against the trunk (cvs diff -u), but any form of context diff is acceptable. Diffs without context will probably be returned for revision to unified format. Please include a ChangeLog entry (the ChangeLog for the texi sources is in the ./man subdirectory). Use the format Use the format of M-x add-change-log-entry. The ChangeLog entry can be submitted as plain text or as a zero-context unified diff (diff -U 0). You may wish to browse http://list-archive.xemacs.org/xemacs-patches/ for samples. Ben Wing, Martin Buchholz, Didier Verna, and Adrian Aichner are known for producing excellent patches. Also, in the xemacs-devel Lisp package there is a library patcher.el which is useful for generating patches from CVS diffs, and will even set up the ChangeLog entries for you. -- University of Tsukuba Tennodai 1-1-1 Tsukuba 305-8573 JAPAN Institute of Policy and Planning Sciences Tel/fax: +81 (298) 53-5091 _________________ _________________ _________________ _________________ What are those straight lines for? "XEmacs rules."