lispref structure really confused (was Re: [Bug: xemacs-beta tip] tables of contents at wrong end manual)
5:27 p.m.
On Mon, Oct 4, 2010 at 7:37 PM, Samuel Bronson <naesten(a)gmail.com> wrote:
Hmm, I've noticed that the print-formatted manuals I'm
building have
their tables of contents at the end instead of the beginning.
Hmm, it looks like there are worse problems, at least in lispref: the
sectioning hierarchy doesn't match the node next/previous/up links
doesn't match the node menu structure. I realize there's no reason
that all three trees need to be identical, but this seems ridiculous:
some nodes are even given in a *different order* in the menu structure
and in the next/previous/up links!
I'd like to straighten this out a bit; any hints as to how to tell
which order/structure(s) to keep?
One other thing I've noticed: usually, when I try "C-h C-f", it says
that whatever I was looking for is missing from the index, but when
the .texi file has a perfectly-good looking ＠defun (or similar) in it.
Am I wrong in thinking that ＠defun is supposed to put the function
described into the function index, or is something just mysteriously
broken?
_______________________________________________
XEmacs-Beta mailing list
XEmacs-Beta(a)xemacs.org
http://lists.xemacs.org/mailman/listinfo/xemacs-beta
6:55 a.m.
Thanks for looking at this!
Samuel Bronson writes:
Hmm, it looks like there are worse problems, at least in lispref:
the
sectioning hierarchy doesn't match the node next/previous/up links
doesn't match the node menu structure.
There is Lisp code in a comment in either the XEmacs User Guide or the
Lispref (or maybe both) that is useful for maintaining both menus and
links.
I'd like to straighten this out a bit; any hints as to how to
tell
which order/structure(s) to keep?
Use your good taste as far as order goes. If as far as you can tell
it doesn't matter, see if the helper code will decide for you (IIRC it
either constructs menu from the node graph or vice versa) and if not,
flip a coin.
One other thing I've noticed: usually, when I try "C-h
C-f", it says
that whatever I was looking for is missing from the index, but when
the .texi file has a perfectly-good looking ＠defun (or similar) in it.
Am I wrong in thinking that ＠defun is supposed to put the function
described into the function index, or is something just mysteriously
broken?
AFAIK the primitive ＠def* directives handle this, so, yes, it should
update the index automatically.
Sounds like possibly Makefile breakage to me. I don't use C-h C-f
except by accident (I generally work with the manual source 'cause
there's always something I want to change ;-), so I haven't paid much
attention to that.
_______________________________________________
XEmacs-Beta mailing list
XEmacs-Beta(a)xemacs.org
http://lists.xemacs.org/mailman/listinfo/xemacs-beta
4:58 p.m.
On Fri, Oct 8, 2010 at 1:55 AM, Stephen J. Turnbull <stephen(a)xemacs.org> wrote:
Thanks for looking at this!
Samuel Bronson writes:
> Hmm, it looks like there are worse problems, at least in lispref: the
> sectioning hierarchy doesn't match the node next/previous/up links
> doesn't match the node menu structure.
I'm having trouble finding this code. Perhaps there should be
directions for finding it in man/README?
There is Lisp code in a comment in either the XEmacs User Guide or
the
Lispref (or maybe both) that is useful for maintaining both menus and
links.
> I'd like to straighten this out a bit; any hints as to how to tell
> which order/structure(s) to keep?
Use your good taste as far as order goes. If as far as you can tell
it doesn't matter, see if the helper code will decide for you (IIRC it
either constructs menu from the node graph or vice versa) and if not,
flip a coin.
Gotcha.
> One other thing I've noticed: usually, when I try "C-h
C-f", it says
> that whatever I was looking for is missing from the index, but when
> the .texi file has a perfectly-good looking ＠defun (or similar) in it.
> Am I wrong in thinking that ＠defun is supposed to put the function
> described into the function index, or is something just mysteriously
> broken?
AFAIK the primitive ＠def* directives handle this, so, yes, it should
update the index automatically.
Sounds like possibly Makefile breakage to me. I don't use C-h C-f
except by accident (I generally work with the manual source 'cause
there's always something I want to change ;-), so I haven't paid much
attention to that.
Too bad there's no way for the Info mode to take you to the source for
the text near point.
Hmm. Looking closer, I see that lispref has one index for everything.
Is it possible that this somehow confuses the `Info-index' code?
_______________________________________________
XEmacs-Beta mailing list
XEmacs-Beta(a)xemacs.org
http://lists.xemacs.org/mailman/listinfo/xemacs-beta
6:38 p.m.
Samuel Bronson writes:
On Fri, Oct 8, 2010 at 1:55 AM, Stephen J. Turnbull
<stephen(a)xemacs.org> wrote:
> There is Lisp code in a comment in either the XEmacs User Guide
or the
> Lispref (or maybe both) that is useful for maintaining both menus and
> links.
>
I'm having trouble finding this code. Perhaps there should be
directions for finding it in man/README?
Sorry, early onset senility. It was the Internals manual (reproduced
below) and the FAQ (seems very FAQ-specific, so omitted). Most of it
is actually part of Texinfo mode.
Hmm. Looking closer, I see that lispref has one index for
everything.
Is it possible that this somehow confuses the `Info-index' code?
Well, according to C-h f for that command, it shouldn't.
**** Tips for maintaining the Internals manual: ****
1. Updating the forward, back and up pointers in a ＠＠node line:
---------------------------------------------------------------
Don't do it by hand!
Use C-c C-u C-e (aka M-x texinfo-every-node-update).
2. Updating the menus:
----------------------
This section describes how to update the menus at the end of chapters,
sections with subsections, etc., and the master menu near the top of
the file:
Don't do it by hand!
Use C-u C-c C-u m (aka C-u M-x texinfo-master-menu).
N
OTE: This command does not include the Index:: menu entry.
You must add it by hand.
3. Converting plain text into Texinfo:
--------------------------------------
3a. Here are some useful Lisp routines for quickly Texinfo-izing text
that has been formatted into ASCII lists and tables.
Note: to define these routines, put point after the end of the definition
and type C-x C-e.
(defun convert-list-to-texinfo (b e)
"Convert the selected region from an ASCII list to a Texinfo list."
(interactive "r")
(save-restriction
(narrow-to-region b e)
(goto-char (point-min))
(let ((dash-type "^ *\\(-+\\|o\\) +")
;; allow single-letter numbering or roman numerals
(letter-type "^ *[[(]?\\([a-zA-Z]\\|[IVXivx]+\\)[]).] +")
(num-type "^ *[[(]?[0-9]+[]).] +")
dash regexp)
(save-excursion
(re-search-forward "\\s-*")
(cond ((looking-at dash-type) (setq regexp dash-type dash t))
((looking-at letter-type) (setq regexp letter-type))
((looking-at num-type) (setq regexp num-type))
((re-search-forward num-type nil t) (setq regexp num-type))
((re-search-forward letter-type nil t) (setq regexp letter-type))
((re-search-forward dash-type nil t)
(setq regexp dash-type dash t))
(t (error "No table entries?"))))
(if dash (insert "＠itemize ＠bullet\n")
(insert "＠enumerate\n"))
(re-search-forward regexp nil 'limit)
(while (not (eobp))
(delete-region (point-at-bol) (point))
(insert "＠item\n")
;; move forward over any text following the dash to not screw
;; up remove-spacing.
(forward-line 1)
(let ((p (point)))
(or (re-search-forward regexp nil t)
(goto-char (point-max)))
;; trick to avoid using a marker
(save-excursion
;; back up so as not to affect the line we're on (beginning of
;; next entry)
(forward-line -1)
(remove-spacing p (point)))))
(beginning-of-line)
(if dash (insert "＠end itemize\n")
(insert "＠end enumerate\n")))))
(defun remove-spacing (b e)
"Remove leading space from the selected region.
This finds the maximum leading blank area common to all lines in the region.
This includes all lines any part of which are in the region."
(interactive "r")
(save-excursion
(let ((min 999999)
seen)
(goto-char e)
(end-of-line)
(setq e (point))
(goto-char b)
(beginning-of-line)
(setq b (point))
(while (< (point) e)
(cond ((looking-at "^\\s-+")
(goto-char (match-end 0))
(setq min (min min (current-column))
seen t))
((looking-at "^\\s-*$"))
(t (setq min 0)))
(forward-line 1))
(when (and seen (> min 0))
(goto-char e)
(untabify b e)
;; we are at end of line already.
(if (not (= (point) (point-at-eol)))
(error "Logic error"))
;; Pad line with spaces if necessary (it may be just a blank line)
(if (< (current-column) min)
(insert-char ?\ (- min (current-column)))
(beginning-of-line)
(forward-char min))
(kill-rectangle b (point))))))
(defun convert-table-to-texinfo (b e)
"Convert the selected region from an ASCII table to a Texinfo table.
Assumes entries are separated by a blank line, and the first sexp in
each entry is the table heading."
(interactive "r")
(save-restriction
(narrow-to-region b e)
(goto-char (point-min))
(insert "＠table ＠code\n")
(while (not (eobp))
;; remember where we want to insert the ＠item.
;; delete the spacing first since inserting the ＠item may create
;; a line with no spacing, if there is text following the heading on
;; the same line.
(let ((beg (point)))
;; removing the space and inserting the ＠item will change the
;; position of the end of the region, so to make it easy on us
;; leave point at end so it will be adjusted.
(forward-line 1)
(let ((beg2 (point)))
(or (re-search-forward "^$" nil t)
(goto-char (point-max)))
(backward-char 1)
(remove-spacing beg2 (point)))
(ignore-errors (forward-char 2))
(save-excursion
(goto-char beg)
(insert "＠item ")
(forward-sexp)
(delete-char)
(insert "\n"))))
(beginning-of-line)
(insert "＠end table\n")))
3b. A useful Lisp routine for adding markup based on conventions used
in plain text files; see doc string below.
(defun convert-text-to-texinfo (&optional no-narrow)
"Convert text to Texinfo.
If the region is active, do the region; otherwise, go from point to the end
of the buffer. This query-replaces for various kinds of conventions used
in text: ＠code{} surrounded by ` and ' or followed by a (); ＠strong{}
surrounded by *'s; ＠file{} something that looks like a file name."
(interactive)
(save-excursion
(if (and (not no-narrow) (region-active-p))
(save-restriction
(narrow-to-region (region-beginning) (region-end))
(goto-char (region-beginning))
(zmacs-deactivate-region)
(convert-text-to-texinfo t))
(let ((p (point))
(case-replace nil))
(message "Point is %d" (point))
(query-replace-regexp "`\\([^']+\\)'\\([^']\\)"
"＠code{\\1}\\2" nil)
(goto-char p)
(query-replace-regexp
"\\(\\Sw\\)\\*\\(\\(?:\\s_\\|\\sw\\)+\\)\\*\\([^A-Za-z.}]\\)"
"\\1＠strong{\\2}\\3" nil)
(goto-char p)
(query-replace-regexp "\\(\\(\\s_\\|\\sw\\)+()\\)\\([^}]\\)"
"＠code{\\1}\\3" nil)
(goto-char p)
(query-replace-regexp "\\(\\(\\s_\\|\\sw\\)+\\.[A-Za-z]+\\)\\([^A-Za-z.}]\\)"
"＠file{\\1}\\3" nil)
))))
4. Adding new sections:
-----------------------
NOTE: These are in the form of macros. #### FIXME Convert them to
proper functions. To edit these macros, define them and then use
M-x edit-kbd-macro.
Macro to generate the "Future Work" section from a title; put
point at the beginning of the title.
(defalias 'make-future (read-kbd-macro
"<S-end> M-w <home> ＠node SPC <end> RET ＠section SPC C-y
<home> <up> <C-right> <right> Future SPC Work SPC - - SPC
<home> <down> <C-right> <right> Future SPC Work SPC - - SPC
<end> RET ＠cindex SPC future SPC work, SPC C-y C-r , RET C-x C-x M-l RET ＠cindex SPC
C-y <home> <C-right> <S-end> M-l , SPC future SPC work RET"))
Similar but generates a "Discussion" section.
(defalias 'make-discussion (read-kbd-macro
"<S-end> M-w <home> ＠node SPC <end> RET ＠section SPC C-y
<home> <up> <C-right> <right> Discussion SPC - - SPC <home>
<down> <C-right> <right> Discussion SPC - - SPC <end> RET ＠cindex
SPC discussion, SPC C-y C-r , RET C-x C-x M-l RET ＠cindex SPC C-y <home>
<C-right> <S-end> M-l , SPC discussion RET"))
Similar but generates an "Old Future Work" section.
(defalias 'make-old-future (read-kbd-macro
"<S-end> M-w <home> ＠node SPC <end> RET ＠section SPC C-y
<home> <up> <C-right> <right> Old SPC Future SPC Work SPC - - SPC
<home> <down> <C-right> <right> Old SPC Future SPC Work SPC - -
SPC <end> RET ＠cindex SPC old SPC future SPC work, SPC C-y C-r , RET C-x C-x M-l RET
＠cindex SPC C-y <home> <C-right> <S-end> M-l , SPC old SPC future SPC
work RET"))
Similar but generates a general section.
(defalias 'make-section (read-kbd-macro
"<S-end> M-w <home> ＠node SPC <end> RET ＠section SPC C-y RET
＠cindex SPC C-SPC C-g C-y C-x C-x M-l <home> <down>"))
Similar but generates a general subsection.
(defalias 'make-subsection (read-kbd-macro
"<S-end> M-w <home> ＠node SPC <end> RET ＠subsection SPC C-y RET
＠cindex SPC C-SPC C-g C-y C-x C-x M-l <home> <down>"))
_______________________________________________
XEmacs-Beta mailing list
XEmacs-Beta(a)xemacs.org
http://lists.xemacs.org/mailman/listinfo/xemacs-beta
5270
days inactive
5271
days old
3 comments
2 participants
participants (2)
-
Samuel Bronson -
Stephen J. Turnbull