Re: [R21.4] [COMMIT] Update glyph documentation

Moving to xemacs-design.

>>>>> "Ben" == Ben Wing <[email protected]> writes:

    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.