Moving to xemacs-design. Ben> Either we generate sections of the Lisp manual directly from Ben> the doc strings or we incorporate the doc strings into the Ben> Lisp manual and fix C-h f to automatically go to the right Ben> place. Ben> The latter solution is what Microsoft uses. Well, so do we, really. That's what etc/DOC is, as you point out. Ben> What think you, stephen? Any time? The biggest technical problem I see is how to handle user-defined and packaged docstrings seamlessly. Simply generalizing the current scheme (if it's a string, it's a conventional docstring, if it's a cons the car is an info reference, the cdr is a list of additional indexing information---eg, if we decide not to do a node-per-defun strategy, maybe a line number) should work. But it's not "seamless," they wouldn't have access to the info-docstring features. The big problem in doing a quality job on a real manual is the God- Forsaken-Documentation-License. We can't put docstrings under the doc license, and we can't mix GPLed docstrings or postprocessed versions of them with our Texinfo docs. For unifying help into Info, I'd suggest a transition strategy of creating a DOC.info based on picking up _all_ docstrings, creating a nodename from the symbol name (which has to be unique since Emacs Lisp doesn't have namespaces), and have the master menu simply be an alphabetical list of .el and .c names, which also have to be unique because of our rather flat directory structure. This would also have the advantage that you could use Info's strategy for finding nodes rather than the brain-dead straight indexing that C-h f uses. Slow? Dunno, let's try it and see. Give me a week and ping me. I probably won't get done by then, not even started, but I should have some free time after next Tuesday. This looks actually doable, and we can add bells and whistles for creating real manuals later. The real manual might even just refer to DOC.info for function and variable defs. Finally, we could think about doing more sensible things with Info, like hiding the stupid *note: markers and things like that. I think GNU is already doing some of that in their info.el. ======================================================================== The following is a possibly dumb idea that I wrote first and now don't know if it make sense in context. May as well document it here. I think we should generate everything except the toplevel menu from the source files. As an interim step, we could have something like this (borrowing the pragma notation from autoloads): ;;;###info:lispref ;;; ;;; the Lisp-to-texi code that processes lispref-declaration ;;; 0. ignores a header comment (like this) and blank lines up to an ;;; ＠node line (alternatively, we could just require ＠c) ;;; 1. strips off the leading and trailing (in C) comment syntax ;;; 2. copies it to man/lispref/thisfile-basename.texi ;;; ＠node Glyphs ;;; ＠chapter Glyphs ;;; ＠cindex glyphs ;;; ＠cindex images ;;; ;;; Glyphs are the Lisp-level API used by XEmacs to display anything ;;; other than buffer text. A glyph contains a generalized image ;;; specifier. "Generalized" means that things not usually considered ;;; to be images such as formatted text and GUI widgets are handled ;;; with a uniform API. A "specifier" is used so that the "image" may ;;; vary according to display context (TTY vs. graphical console, ;;; color vs. monochrome visual). The glyph also contains other ;;; information such as the baseline so that alignment of the image ;;; can be controlled via the glyph API. ;;; ;;; ＠menu ;;; make-glyph:: ;;; set-glyph-image:: ;;; ＠end menu ;;;###endinfo ;;;###info:lispref-declaration ;;; ;;; the Lisp-to-texi code that processes lispref-declaration ;;; 0. ignores a header comment (like this) and blank lines ;;; 1. parses out the kind of declaration (function, macro, variable, ;;; custom, behavior, ...) ;;; 2. in this case creates ;;; ＠node make-glyph ;;; ＠section make-glyph ;;; ＠defun make-glyph &optional spec-list type ;;; then inserts the docstring as the body ;;; 3. filters out literate programming codes like ＠ifmanual below ;;; ;;; the help code needs to deal with a limited number of ＠ codes ;;; appropriate to docstrings. I hope, anyway. (defun make-glyph (&optional spec-list type) "Return a new glyph. Optional argument ＠var{spec-list}, if non-nil, should be an image specification. Optional argument ＠var{type}, if non-nil, should be one of the symbols ＠samp{buffer}, ＠samp{pointer}, or ＠samp{icon}. ＠ifmanual ＠c not really Texinfo; replaced by a hyperlink "for more ＠c info" in help User code should never use types ＠samp{pointer} or ＠samp{icon}, since only one global glyph for each of those types is needed, and those are created at initialization. ＠end ifmanual " ;; Lisp definition here ) We could obviously do without the lispref-declaration marker, but I don't think that internal, implementation code should get into the lispref. If we really want it documented, it could get an internals-declaration marker. Note that this comment pragma would allow us to put XEmacs User Guide documentation close to the code it documents, too. -- Institute of Policy and Planning Sciences http://turnbull.sk.tsukuba.ac.jp University of Tsukuba Tennodai 1-1-1 Tsukuba 305-8573 JAPAN Ask not how you can "do" free software business; ask what your business can "do for" free software.