Re: Info enhancements

[Luc Teirlinck <teirllm@dms.auburn.edu>]

It might be useful to split up some nodes and, as I already said, I am
willing to help do so.  However, I believe that we might also have to
increase the number of @anchor's in the elisp manual from the current
four.  The two efforts could complement each other.

I believe that, for instance, a node like `(elisp)Documentation Tips'
(216 lines) is best kept together and, at the same time, large enough
to be a nuisance to wade through to find the correct item.

I CC the following proposed change to Emacs devel because I believe
that it is relevant to the discussion we are having.  The somewhat
strange name of the anchor is deliberate, to avoid interfering with
present or, especially, future, anchor or node names, and to avoid
problems with `g' completion.  It is overridden by the third argument
to @xref anyway.  It could, of course be changed.  (The [Tips] refers
to tips.texi.)

I propose to systematically rely on @anchor rather than on Juri's
feature, because it is more reliable, more flexible and because it is
an existing Texinfo feature, that does not require a departure from
current Texinfo style and conventions.

I believe that the @anchor in the diffs below could save the user
quite a bit of searching and confusion.  To me, it seems very helpful
to the user in both Info and the printed manual.  

If desired, I could commit when Savannah starts working again.  We
could start making more of these @anchor's, in similar situations.

===File ~/tips-diff=========================================
*** tips.texi.~1.53.~	Mon Oct 20 14:37:21 2003
--- tips.texi	Sun Dec  7 19:28:58 2003
***************
*** 647,652 ****
--- 647,653 ----
  This prevents the open-parenthesis from being treated as the start of a
  defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
  
+ @anchor{doc-hyperlinks [Tips]}
  @item
  @iftex
  When a documentation string refers to a Lisp symbol, write it as it
============================================================


===File ~/displaydiff=======================================
*** display.texi.~1.106.~	Sun Nov  2 12:23:12 2003
--- display.texi	Sun Dec  7 20:03:32 2003
***************
*** 805,812 ****
  so that it is still Help mode at the end of their execution, then
  @code{with-output-to-temp-buffer} makes this buffer read-only at the
  end, and also scans it for function and variable names to make them
! into clickable cross-references.  @xref{Documentation Tips, , Tips for
! Documentation Strings}.
  
  The string @var{buffer-name} specifies the temporary buffer, which
  need not already exist.  The argument must be a string, not a buffer.
--- 805,813 ----
  so that it is still Help mode at the end of their execution, then
  @code{with-output-to-temp-buffer} makes this buffer read-only at the
  end, and also scans it for function and variable names to make them
! into clickable cross-references.  @xref{doc-hyperlinks [Tips], , Tips
! for Documentation Strings}, more particularly the item on hyperlinks
! in documentation strings, for more details.
  
  The string @var{buffer-name} specifies the temporary buffer, which
  need not already exist.  The argument must be a string, not a buffer.
============================================================

Appendix: Exhaustive list (grep) of all current @anchor's in the Elisp
manual (four total):

@anchor{modifier bits} in (elisp)Character Type, 165 lines.

@anchor{Display Face Attribute Testing} in (elisp)Display Feature
Testing, 133 lines.

@anchor{Text help-echo} and @anchor{Help display}, both in
(elisp)Special Properties, 224 lines.