Re: 5x5 documentation

Re: 5x5 documentation

[Stefan Monnier]

> Somebody from this forum asked for documentation of the algorithm which
> I used.  So I wrote a comprehensive documentation of 5x5.  Actually the
> primary objective was just to describe the algorithm, but it ended in
> describing the whole thing.

Thanks.  I don't think we'll want to include a separate Texinfo manual
for that with Emacs, tho.  We could include a version of that doc as
a comment in 5x5.el (could be marked up (maybe even with Texinfo markup)
and come with a command that would extract the text from the comment and
pass it to some tool for rendering, if you want to get fancy).


        Stefan

RE: 5x5 documentation

[Vincent Belaïche]

[-- Attachment #1: Type: text/plain, Size: 2452 bytes --]


Hello,


I removed Manuel from the recipient because I had put them in the loop only for the math aspects...


Concerning your suggestion, this is something that I had often thought about that it would be good if docstrings would allow better interaction with manuals, like be written with some markup to allow other format (like some Org mode like, or some simplified texinfo). 


It would be good if a docstring could point at some anchor in a manual. I had started to think about that because in Calc there is no docstrings at all, but rather some function that scans the manual for the function description. Unfortunately this function first uses the language in which the manual is written, which is not good programming practice to make any algorithm locale-dependent, and second this function had a number of bugs which were corrected over time, which shows that this method is hard to tune. 


It would be better to have some markup to say "hey !  go the the point that correspond to index entry XXX where you find that index in this index info node", and XXX is the function/variable/etc... to document and that has some index entry.


That would also allow to make function/variable documentation internationalized.


Anyhow, a simple-to-do thing would be to place this manual in some place, like similar to that of sed:


http://gnu.april.org/software/sed/manual/


And then put an url to this page in some docstring or in the emacs manual info node about games.


   Vincent.





> From: monnier@iro.umontreal.ca
> To: vincent.b.1@hotmail.fr
> Subject: Re: 5x5 documentation
> Date: Mon, 20 Jun 2011 23:19:09 -0400
> CC: pertusus@free.fr; jay.p.belanger@gmail.com; karl@freefriends.org; mpg@elzevir.fr; emacs-devel@gnu.org
> 
> > Somebody from this forum asked for documentation of the algorithm which
> > I used.  So I wrote a comprehensive documentation of 5x5.  Actually the
> > primary objective was just to describe the algorithm, but it ended in
> > describing the whole thing.
> 
> Thanks.  I don't think we'll want to include a separate Texinfo manual
> for that with Emacs, tho.  We could include a version of that doc as
> a comment in 5x5.el (could be marked up (maybe even with Texinfo markup)
> and come with a command that would extract the text from the comment and
> pass it to some tool for rendering, if you want to get fancy).
> 
> 
>         Stefan
> 
 		 	   		  

[-- Attachment #2: Type: text/html, Size: 2884 bytes --]

RE: 5x5 documentation

[Drew Adams]

> It would be good if a docstring could point at some anchor
> in a manual...
>	 
> It would be better to have some markup to say "hey !  go
> the point that correspond to index entry XXX where you find
> that index in this index info node", and XXX is the
> function/variable/etc... to document and that has some index
> entry.

I provided a patch to do this recently - see thread "adding manual cross-ref
links to *Help*".

However, I cannot give you a URL to that thread, because for some reason it is
not recorded in the archive!  What's up with that?

Anyway, I have since improved the code slightly.  To give it a try, or to
examine the code:
http://www.emacswiki.org/emacs/download/help-fns%2b.el

Just load the file and try `C-h v', `C-h f', etc.
See also user option `help-cross-reference-manuals'. 

(Juri will soon apply the code or otherwise provide similar behavior to Emacs.)

I made `describe-*' commands offer links to the manuals:

* `describe-mode' (each mode doc'd gets a link to manuals)
* `describe-function' and derivatives, e.g. `describe-key'
* `describe-variable'
* `describe-face'
* `describe-package'

I did this for each standard `describe-*' command that I felt could reasonably
link to manuals.  Others could also be done, in some cases linking to specific
manuals - e.g., `describe-character-set', `describe-class' (EIEIO),
`describe-generic' (EIEIO).  Some `describe-*' commands of course produce output
that has nothing that could be linked to a manual - e.g. `describe-bindings'.

Obviously anyone can use the code to add manual links for their own describe
commands.  You just need to add this sexp to the command's code, where THING is
the thing to look up (e.g. function, var, face whatever):

(Info-make-manuals-xref THING)

THING needs to match an index entry exactly (we don't want apropos matching
here).  So if the index entry has extra stuff then that needs to be taken into
account.

For example, package names are indexed with " package" after the name (e.g.
"Semantic package"), so I use this in `describe-package':

(Info-make-manuals-xref
 (concat (symbol-name package) " package"))
	
> That would also allow to make function/variable documentation
> internationalized.

RE: 5x5 documentation

[Drew Adams]

> However, I cannot give you a URL to that thread, because for 
> some reason it is not recorded in the archive!

Oops, dunno why I didn't see it - 
http://lists.gnu.org/archive/html/emacs-devel/2011-06/msg00368.html

RE: 5x5 documentation

[Vincent Belaïche]

[-- Attachment #1: Type: text/plain, Size: 1295 bytes --]




> From: drew.adams@oracle.com
> To: vincent.b.1@hotmail.fr; monnier@iro.umontreal.ca; jay.p.belanger@gmail.com
> Subject: RE: 5x5 documentation
> Date: Tue, 21 Jun 2011 14:07:18 -0700
> CC: pertusus@free.fr; emacs-devel@gnu.org; karl@freefriends.org
> 
> > However, I cannot give you a URL to that thread, because for 
> > some reason it is not recorded in the archive!
> 
> Oops, dunno why I didn't see it - 
> http://lists.gnu.org/archive/html/emacs-devel/2011-06/msg00368.html
> 
> 

Hello Drew,
Just a few question on this new feature: 
1) can you use it if you do not link directly to some 
manual 
anchor point, but you make some indirection like "go to the point defined in index entry XXX of info node NNN" ? This is what is really needed for Calc ...
2) would it be easy just based on the function name, and assuming that you can find it in some info node index to compute the link --- I am thinking  that all math function could be added this link by one simple macro modification
3) is the method to introduce that new markup futureproof and easily extensible to other kind of markup (like to define other format for docstring, typically some simplified texinfo would be a good choice, so that you can cut and paste with manuals).
  Vincent.

 		 	   		  

[-- Attachment #2: Type: text/html, Size: 1784 bytes --]

RE: 5x5 documentation

[Drew Adams]

>> http://lists.gnu.org/archive/html/emacs-devel/2011-06/msg00368.html

First, let me say again that Juri will be adding this to Emacs soon, and he may
choose to implement it differently.  So you might want to wait.  The rest of my
reply assumes you want to use the implementation I provided.

> 1) can you use it if you do not link directly to some
>    manual anchor point, but you make some indirection
>    like "go to the point defined in index entry XXX of
>    info node NNN" ? This is what is really needed for Calc ...

Not sure what you mean by "point defined...".  This feature works with existing
manual indexes.  It creates an Info virtual index that is an Info "menu" of
links to manual sections, those links being, in effect, grabbed from the indexes
of the searched manuals.

So the index entries must already be in the manual indexes.  This just collects
them into an Info page: a virtual index.

This is similar to what commands `Info-apropos-matches' and `Info-virtual-index'
do, with these differences:

a. Unlike `Info-apropos-matches', this does not do apropos matching.  It looks
up a given term in the indexes of the target manuals.  It looks for an exact
match (ignoring case).

b. Unlike `Info-virtual-index', this works across multiple manuals; it does not
look only in the index of the current manual.

c. Unlike `Info-virtual-index', you do not have to be inside Info to use this.

You can specify the manuals to be searched.  The user has control over this with
user option `help-cross-reference-manuals'.  But code can control this as well,
of course.

By default, a link to the manuals is added to the *Help* buffer for a
`describe-*' command, without first checking whether there are in fact any index
entries for the target term (e.g. function, var).  This is to save time, since
the index searching can take time, especially if many manual indexes are
searched.  (Index searching is cached, so it takes longer the first time.)

But you can optionally have the link be added to *Help* only if an index search
is successful.  This too is controlled by option `help-cross-reference-manuals'.

> 2) would it be easy just based on the function name, and
>    assuming that you can find it in some info node index
>    to compute the link --- I am thinking  that all math
>    function could be added this link by one simple macro
>    modification

I don't follow you.  The virtual Info index (aka "menu") is created when the
user clicks the link in *Help*.  Each entry in that virtual index is a direct
link to a manual section describing the target term (e.g. function).

Perhaps describe the use case you are thinking of - give a scenario, so I can
understand better.

> 3) is the method to introduce that new markup futureproof
>    and easily extensible to other kind of markup (like to
>    define other format for docstring, typically some
>    simplified texinfo would be a good choice, so that you
>    can cut and paste with manuals).

Again, I don't follow you; sorry.  

There is no markup.  There is no change to the doc strings - this is not like
using \\[...], for instance.

This represents a change not to the doc strings themselves but to the
`describe-*' commands that print out the doc in *Help*.  It just adds this line
to the printed text, with a link to the manuals:
"For more information check the manuals", with `manuals' being the link.

What happens is that when the link is clicked the indexes of the appropriate
manuals (as determined by `help-cross-reference-manuals') are searched for the
given term (the term that is passed to `Info-make-manuals-xref' in the code for
the `describe-*' command).

For instance, for `describe-variable', the variable is passed:
(Info-make-manuals-xref VARIABLE).  That call in the `describe-variable' code
just adds the "For more information..." text and link to *Help*.  When that link
is clicked, the actual Info lookup takes place: the indexes of the given manuals
are searched for the given VARIABLE.

Give it a try and you will quickly understand.  Then try again to describe your
scenario, what you're looking for.

RE: 5x5 documentation

[Vincent Belaïche]

[-- Attachment #1: Type: text/plain, Size: 5874 bytes --]



Hello,


It seems that there was a mistunderstanding, I thought that your module allows to add some addtional markup into the doctstring itself (similar to \\[...]) to display some part of some manual instead of the docstring content.



Here is the use case I was thinking of.


Type `C-x  * *' to enter the calculator. Then type `h f cos <ret>' that will direct you to line 45 of info node`(Calc) Trigonometric and Hyperbolic Functions'. What I am wondering is that it be possible to have such kind of a mechanism generalized, so that when I type `C-h C-f calc-cos' I would reach the same place of the same manual. And this would just be achieved, by just adding some docstring to function calc-cos which would contain a special markup telling "search info about `calc-cos' in manual `calc'".


Note that calc-cos, as well as all the other Calc function are not documented, and that the `h' (calling calc-help-prefix function) make some custom search in the Calc manual that could be generalized --- the current implementation does not use that index field also contains  some line number, instead is looks for some string in the corresponding node, which makes it local dependent.


   Vincent.


> From: drew.adams@oracle.com
> To: vincent.b.1@hotmail.fr; monnier@iro.umontreal.ca; jay.p.belanger@gmail.com
> Subject: RE: 5x5 documentation
> Date: Wed, 22 Jun 2011 06:35:33 -0700
> CC: karl@freefriends.org; pertusus@free.fr; emacs-devel@gnu.org
> 
> >> http://lists.gnu.org/archive/html/emacs-devel/2011-06/msg00368.html
> 
> First, let me say again that Juri will be adding this to Emacs soon, and he may
> choose to implement it differently.  So you might want to wait.  The rest of my
> reply assumes you want to use the implementation I provided.
> 
> > 1) can you use it if you do not link directly to some
> >    manual anchor point, but you make some indirection
> >    like "go to the point defined in index entry XXX of
> >    info node NNN" ? This is what is really needed for Calc ...
> 
> Not sure what you mean by "point defined...".  This feature works with existing
> manual indexes.  It creates an Info virtual index that is an Info "menu" of
> links to manual sections, those links being, in effect, grabbed from the indexes
> of the searched manuals.
> 
> So the index entries must already be in the manual indexes.  This just collects
> them into an Info page: a virtual index.
> 
> This is similar to what commands `Info-apropos-matches' and `Info-virtual-index'
> do, with these differences:
> 
> a. Unlike `Info-apropos-matches', this does not do apropos matching.  It looks
> up a given term in the indexes of the target manuals.  It looks for an exact
> match (ignoring case).
> 
> b. Unlike `Info-virtual-index', this works across multiple manuals; it does not
> look only in the index of the current manual.
> 
> c. Unlike `Info-virtual-index', you do not have to be inside Info to use this.
> 
> You can specify the manuals to be searched.  The user has control over this with
> user option `help-cross-reference-manuals'.  But code can control this as well,
> of course.
> 
> By default, a link to the manuals is added to the *Help* buffer for a
> `describe-*' command, without first checking whether there are in fact any index
> entries for the target term (e.g. function, var).  This is to save time, since
> the index searching can take time, especially if many manual indexes are
> searched.  (Index searching is cached, so it takes longer the first time.)
> 
> But you can optionally have the link be added to *Help* only if an index search
> is successful.  This too is controlled by option `help-cross-reference-manuals'.
> 
> > 2) would it be easy just based on the function name, and
> >    assuming that you can find it in some info node index
> >    to compute the link --- I am thinking  that all math
> >    function could be added this link by one simple macro
> >    modification
> 
> I don't follow you.  The virtual Info index (aka "menu") is created when the
> user clicks the link in *Help*.  Each entry in that virtual index is a direct
> link to a manual section describing the target term (e.g. function).
> 
> Perhaps describe the use case you are thinking of - give a scenario, so I can
> understand better.
> 
> > 3) is the method to introduce that new markup futureproof
> >    and easily extensible to other kind of markup (like to
> >    define other format for docstring, typically some
> >    simplified texinfo would be a good choice, so that you
> >    can cut and paste with manuals).
> 
> Again, I don't follow you; sorry.  
> 
> There is no markup.  There is no change to the doc strings - this is not like
> using \\[...], for instance.
> 
> This represents a change not to the doc strings themselves but to the
> `describe-*' commands that print out the doc in *Help*.  It just adds this line
> to the printed text, with a link to the manuals:
> "For more information check the manuals", with `manuals' being the link.
> 
> What happens is that when the link is clicked the indexes of the appropriate
> manuals (as determined by `help-cross-reference-manuals') are searched for the
> given term (the term that is passed to `Info-make-manuals-xref' in the code for
> the `describe-*' command).
> 
> For instance, for `describe-variable', the variable is passed:
> (Info-make-manuals-xref VARIABLE).  That call in the `describe-variable' code
> just adds the "For more information..." text and link to *Help*.  When that link
> is clicked, the actual Info lookup takes place: the indexes of the given manuals
> are searched for the given VARIABLE.
> 
> Give it a try and you will quickly understand.  Then try again to describe your
> scenario, what you're looking for.
> 
> 
 		 	   		  

[-- Attachment #2: Type: text/html, Size: 6685 bytes --]

RE: 5x5 documentation

[Drew Adams]

> It seems that there was a mistunderstanding, I thought
> that your module allows to add some addtional markup
> into the doctstring itself (similar to \\[...]) to
> display some part of some manual instead of the docstring
> content.
	
Nope.
	
> Here is the use case I was thinking of...

Yes, what I did probably won't help you with that, at least not directly.
AFAICT, the Calc stuff is pretty much a special case.

If, on the other hand, the Calc function `cos' had a doc string, then the `C-h f
cos' output would, with my code, include a link to its doc in the Calc manual.

In fact, because there is also an Emacs-Lisp function named `cos', `C-h f cos'
does show *Help*, and it does therefore show a link to the manuals.

When you then click that manuals link, and assuming option
`help-cross-reference-manuals' says to check the Calc manual (i.e., if it has
value `all' or a list containing "calc"), you'll get an Info virtual index with
a link to the location in the Calc manual.

For example, with value `all', so that all manuals are searched, I get this
virtual index when I click `manuals':

* cos [elisp]: (elisp)Math Functions
* cos [calc]:  (calc)Trigonometric and Hyperbolic Functions

That won't work for something like `sinh', however, because `C-h f' does not
recognize `sinh' (no match) - there is no doc for that function.

If calc-math.el has been loaded, then `C-h f calc-sinh' does show *Help* (with
just "Not documented").  But because the Calc manual index entry for this is
`sinh', not `calc-sinh', no `manuals' link is added to *Help* for this:
`calc-sinh' is indexed.

See my comment about `describe-package' - this is similar.  In the case of
package names, the index entries have " package" appended to the names, so in
`describe-package' I set up the manuals link to look for the package name with
that text appended.

Something similar could be done for Calc perhaps (remove the `calc-' to get the
proper index entry), but we probably would not want to do that at the level of
the general command `describe-function' (`C-h f').  It might be appropriate to
do it for a Calc-specific help command, but it seems that Calc already gives you
everything you could want in this regard.

In sum, what I've done probably won't help you directly, and it won't do what
you describe as the special, built-in behavior for looking up stuff in the Calc
manual.  But it could perhaps be leveraged, the same as is done for other
`describe-*' functions.

RE: 5x5 documentation

[Vincent Belaïche]

[-- Attachment #1: Type: text/plain, Size: 4751 bytes --]






Hello,


Actually, if your describe-* function would take some optional argument that in the case of Calc would be some function calc-strip-leading-calc  that 
stripes the leading `calc-' then the `h f' in calc could be simplified by calling your describe-* function with that  
calc-strip-leading-calc argument. 


That would commonalize some code. 


 
Something that I did not understand: it seems that you look at all manuals in some variable rather than some manual pointed at by some markup in the docstring --- which was my original idea --- that seems rather inefficient to look at many manuals, and also as you make some cache it takes memory.
 


I had rather that a markup would explicitely indicate which manuals to inspect for the describe-* by using some markup in the docstring, or alternatively, that for each lisp file loaded to memory you can associate one or several manuals, and use the lisp file as a pointer to those manuals. 


BTW, even with knowing the manual to look at, how do you know which node contains the appropriate index ? 


The cost for the docstring markup method would to add a docstring to all the calc-... functions, that could be made systematic by defining those function by a specfic macro rather than by defun. Given that docstrings are not, AFAIK, loaded to memory, that may make emacs more compact.


Also, as I mentioned previously, the Calc implementation is in my view a bit outdated, as it reads from the index only the node name, and not the line number. This is compensated by searching some language dependent regexp, which would be bad practice, even if the manual was written in French :-P. Besides this way of doing has already proved prone to bugs in the past. This is mainly the reason why I got interested in your package.


   Vincent.



> From: drew.adams@oracle.com
> To: vincent.b.1@hotmail.fr; monnier@iro.umontreal.ca; jay.p.belanger@gmail.com
> Subject: RE: 5x5 documentation
> Date: Wed, 22 Jun 2011 10:55:20 -0700
> CC: pertusus@free.fr; emacs-devel@gnu.org; karl@freefriends.org
> 
> > It seems that there was a mistunderstanding, I thought
> > that your module allows to add some addtional markup
> > into the doctstring itself (similar to \\[...]) to
> > display some part of some manual instead of the docstring
> > content.
> 	
> Nope.
> 	
> > Here is the use case I was thinking of...
> 
> Yes, what I did probably won't help you with that, at least not directly.
> AFAICT, the Calc stuff is pretty much a special case.
> 
> If, on the other hand, the Calc function `cos' had a doc string, then the `C-h f
> cos' output would, with my code, include a link to its doc in the Calc manual.
> 
> In fact, because there is also an Emacs-Lisp function named `cos', `C-h f cos'
> does show *Help*, and it does therefore show a link to the manuals.
> 
> When you then click that manuals link, and assuming option
> `help-cross-reference-manuals' says to check the Calc manual (i.e., if it has
> value `all' or a list containing "calc"), you'll get an Info virtual index with
> a link to the location in the Calc manual.
> 
> For example, with value `all', so that all manuals are searched, I get this
> virtual index when I click `manuals':
> 
> * cos [elisp]: (elisp)Math Functions
> * cos [calc]:  (calc)Trigonometric and Hyperbolic Functions
> 
> That won't work for something like `sinh', however, because `C-h f' does not
> recognize `sinh' (no match) - there is no doc for that function.
> 
> If calc-math.el has been loaded, then `C-h f calc-sinh' does show *Help* (with
> just "Not documented").  But because the Calc manual index entry for this is
> `sinh', not `calc-sinh', no `manuals' link is added to *Help* for this:
> `calc-sinh' is indexed.
> 
> See my comment about `describe-package' - this is similar.  In the case of
> package names, the index entries have " package" appended to the names, so in
> `describe-package' I set up the manuals link to look for the package name with
> that text appended.
> 
> Something similar could be done for Calc perhaps (remove the `calc-' to get the
> proper index entry), but we probably would not want to do that at the level of
> the general command `describe-function' (`C-h f').  It might be appropriate to
> do it for a Calc-specific help command, but it seems that Calc already gives you
> everything you could want in this regard.
> 
> In sum, what I've done probably won't help you directly, and it won't do what
> you describe as the special, built-in behavior for looking up stuff in the Calc
> manual.  But it could perhaps be leveraged, the same as is done for other
> `describe-*' functions.
> 
> 

 		 	   		  

[-- Attachment #2: Type: text/html, Size: 5557 bytes --]

Theme submission: adwaita

[William Stevenson]

[-- Attachment #1: Type: text/plain, Size: 306 bytes --]

Hi,
I made a color theme to fit in with the default gnome 3 theme adwaita
and was asked by Carsten Mattner to make a emacs 24 version and submit
it here. 

Comments welcome, hopefully it is good enough for inclusion in 24.
Github link (has screenshot):
https://github.com/yhvh/color-theme-gnome-3-adwaita


[-- Attachment #2: emacs 24 theme to match gnome 3 default adwaita --]
[-- Type: text/plain, Size: 3648 bytes --]

(deftheme adwaita
  "Created 2011-06-22.")

(let ((class '((class color) (min-colors 89))))
  (custom-theme-set-faces
   'adwaita
   `(cursor ((,class (:background "#00BBFF"))))
   `(border-color ((,class (:background "#EDEDED"))))
   `(foreground-color ((,class (:background "black"))))
   `(backgound-color ((,class (:background "#EDEDED"))))

   '(default ((t (:background "#EDEDED" :foreground "#000000"))))
   `(fringe ((t (:background "#EDEDED"))))
   `(mode-line ((t (:foreground "black" :background "white"))))
   `(mode-line-inactive ((t (:foreground "#C6C6C6" :background ,"white"))))
   (set-face-attribute 'mode-line nil :box nil)
   (set-face-attribute 'mode-line-inactive nil :box nil)
   `(minibuffer-prompt ((t (:foreground "#0084C8" :bold t))))
   `(region ((t (:foreground "black" :background "#FEFFBF"))))
   `(dired-header ((t (:bold t :foreground "#0084C8"))))
   `(widget-button ((t (:bold t :foreground "#0084C8"))))

   `(font-lock-builtin-face ((t (:bold t :foreground "#F5666D"))))
   `(font-lock-comment-face ((t (:foreground ,"#4CB64A"))))
   `(font-lock-constant-face ((t (:foreground "#F5666D"))))
   `(font-lock-doc-face ((t (:foreground ,"#4CB64A" :bold t))))
   `(font-lock-function-name-face ((t (:foreground "#00578E" :bold t))))
   `(font-lock-keyword-face ((t (:bold t :foreground "#5179B5"))))
   `(font-lock-preprocessor-face ((t (:foreground "black"))))
   `(font-lock-string-face ((t (:foreground "#FF7092"))))
   `(font-lock-type-face ((t (:foreground "#F74D97" :bold t))))
   `(font-lock-variable-name-face ((t (:foreground "#0084C8" :bold t))))
   `(font-lock-warning-face ((t (:foreground "#F5666D" :bold t))))

   `(erc-action-face ((t (:foreground "#F5666D"))))
   `(erc-button ((t (:foreground "#A8799C"))))
   `(erc-current-nick-face ((t (:bold t :foreground "#FF7092"))))
   `(erc-error-face ((t (:foreground "#F5666D" :bold t))))
   `(erc-input-face ((t (:foreground "black"))))
   `(erc-keyword-face ((t (:foreground "#F5666D"))))
   `(erc-my-nick-face ((t (:bold t :foreground "#FF8CA7"))))
   `(erc-nick-default-face ((t (:bold t :foreground "#0084C8"))))
   `(erc-notice-face ((t (:foreground "#0084C8"))))
   `(erc-prompt-face ((t (:foreground "black"))))
   `(erc-timestamp-face ((t (:foreground ,"#4CB64A"))))

   `(magit-log-sha1 ((t (:foreground "#FF7092"))))
   `(magit-log-head-label-local ((t (:foreground "#4F78B5"))))
   `(magit-log-head-label-remote ((t (:foreground ,"#4CB64A"))))
   `(magit-branch ((t (:bold t :foreground "#0084C8"))))
   `(magit-section-title ((t (:bold t :foreground "#00578E"))))
   `(magit-item-highlight ((t (:background "#FEFFBF"))))
   `(magit-diff-add ((t (:bold t :foreground ,"#4CB64A"))))
   `(magit-diff-del ((t (:bold nil :foreground "#F5666D"))))

   `(gnus-group-mail-1-empty ((t (:foreground "#00578E"))))
   `(gnus-group-mail-1 ((t (:bold t :foreground "#4F78B5"))))
   `(gnus-group-mail-3-empty ((t (:foreground "#00578E"))))
   `(gnus-group-mail-3 ((t (:bold t :foreground "#00BBFF"))))
   `(gnus-group-news-3-empty ((t (:foreground "#00578E"))))
   `(gnus-group-news-3 ((t (:bold t :foreground "#9CBB43"))))
   `(gnus-header-name ((t (:bold t :foreground "#0084C8"))))
   `(gnus-header-subject ((t (:bold t :foreground "#FF7092"))))
   `(gnus-header-content ((t (:foreground "#FF7092"))))
   `(gnus-button ((t (:bold t :foreground "#00578E"))))
   `(gnus-cite-1 ((t (:foreground "#00578E"))))
   `(gnus-cite-2 ((t (:foreground "#0084C8"))))

   `(diff-added ((t (:bold t :foreground ,"#4CB64A"))))
   `(diff-removed ((t (:bold t :foreground "#F5666D"))))
))

;; Local Variables:
;; no-byte-compile: t
;; End:

;;; adwaita-theme.el  ends here

RE: 5x5 documentation

[Drew Adams]

> Actually, if your describe-* function

To be clear, I don't have a `describe-*' function.  I was using that name as an
abbreviation for all of the various `describe-<SOMETHING>' commands that are in
Emacs.

To use the feature that I added, you just need to add a sexp,
(Info-make-manuals-xref...), to the code for such a command.

That needs to be done for each such command that you want to take advantage of
the feature (or to a command that gets called by that command - e.g. doing it to
`describe-function' took care of `describe-key' too, since the latter calls the
former).

> would take some optional argument that in the case of
> Calc would be some function calc-strip-leading-calc  that 
> stripes the leading `calc-' then the `h f' in calc could be
> simplified by calling your describe-* function with that
> calc-strip-leading-calc argument.

Again, there is no `describe-*' function.  In this case, the relevant describe
command (if there is one) would probably be `describe-function' (bound to `C-h
f').

If Calc made use of `describe-function', perhaps by stripping `calc-' from
function names first, then yes, perhaps the feature could be leveraged without
explicitly modifying Calc to use `Info-make-manuals-xref'.

But it's perhaps as bothersome to make Calc use `describe-function' as it would
be to make it use (Info-make-manuals-xref...).  Dunno.
	
> That would commonalize some code. 
>	
> Something that I did not understand: it seems that you
> look at all manuals in some variable rather than some
> manual pointed at by some markup in the docstring

`Info-make-manuals-xref', which you call to create the link to manuals, takes
these arguments:

a. the thing (index entry) to be looked up (e.g. `forward-char')

b. optionally, a flag about extra newlines after the link

c. optionally, the manuals to search and whether to also look search them before
creating the link

If (c) is nil then a user option is used for deciding which manuals to use.
That is, if a describing command doesn't specify which manuals to search then
the user decides.

In this approach, nothing is keyed off of the doc string for the thing being
described.  It is instead the help command that creates the link to the manuals.
That describing command can link to whatever manuals it likes.  It could even
accept an argument (e.g. interactively a prefix arg) to determine which manuals
to search.

> --- which was my original idea --- that seems rather
> inefficient to look at many manuals, and also as you
> make some cache it takes memory.

You can search any number of manuals you want to.

If you know that for your particular term to look up you want to look in only
one manual, then you invoke `Info-make-manuals-xref' passing it only that one
manual along with the term.  When the user clicks the resulting link, only that
one manual is searched for the term.

Searching multiple manuals is optional.  It has a cost, but it can be useful if
that's really what you want/need.

In the case of the very general, standard `describe-*' commands (e.g.
`describe-variable'), which manuals should be searched by default?  

Dunno.  I chose the Emacs and Elisp manuals as the default value for the user
option, and I chose the user option's value as the default value for these
commands.

But any set of manuals can be used for any command.  It is the describing
command that specifies the manuals to use.

In this approach it is not up to the individual doc string to choose the manual
- that would be a different approach, with certain advantages and disadvantages,
no doubt.
	
> I had rather that a markup would explicitely indicate
> which manuals to inspect for the describe-* by using
> some markup in the docstring,

Feel free to implement it.

> or alternatively, that for each lisp file loaded to
> memory you can associate one or several manuals, and
> use the lisp file as a pointer to those manuals.
>	
> BTW, even with knowing the manual to look at, how do
> you know which node contains the appropriate index?

Not sure I understand the question.  Example:

The Elisp manual has one index, which has many index entries (for functions,
variables, keymaps, etc.).  When you click a *Help* link that searches the Elisp
manual, the search looks up the term you're looking for in the index.

In effect, it just grabs that index entry, with its link to a node, and pastes
it onto a virtual index page.  When you click the *Help* link you are put into
Info looking at that virual index page.  It will have one or more links to the
nodes that discuss the thing you're looking up.  Click one of those links et
voila.

This is no different from clicking the links in the manual's index itself.  All
that has happened is that you've been presented with a subset of that index,
which covers only the one term you're looking for.  But if more than one manual
is searched then you get the matching entries from each of those manuals, all on
the same virtual-index page.
	
> The cost for the docstring markup method would to add a
> docstring to all the calc-... functions,

If you do that then you can already take advantage of what I've done, I think,
as I said earlier.

Consider the example of `cos': that one works, because there is a doc string for
function `cos' - in the _Elisp_ manual (a different `cos' function from Calc's).

If you do not load Calc, then when you click the `manuals' link for `cos' in
*Help* you see only one index entry: for the Elisp manual.  If you do load Calc
(e.g. do `C-x * *') then when you click the link you see two index entries: one
for the Elisp manual, one for the Calc manual.

This is in spite of the fact that the Calc function `cos' has no doc string.
But it works because there is _some_ function `cos' that does have a doc string.
Give a doc string to each of the Calc commands and this should work for them all
(once Calc is loaded).

> that could be made systematic by defining those function
> by a specfic macro rather than by defun. Given that
> docstrings are not, AFAIK, loaded to memory, that may make
> emacs more compact.
>
> Also, as I mentioned previously, the Calc implementation
> is in my view a bit outdated, as it reads from the index
> only the node name, and not the line number. This is
> compensated by searching some language dependent regexp,
> which would be bad practice, even if the manual was
> written in French :-P. Besides this way of doing has
> already proved prone to bugs in the past. This is mainly
> the reason why I got interested in your package.

To be clear - I am not trying to propose this manual-links feature for use by
Calc or as a solution to anything beyond what it does already.  If someone wants
to try to use it for something like Calc it might - or it might not - be
appropriate.  I don't know.

And as I mentioned a couple of times, Juri Linkov will soon be doing something
like this for Emacs itself.  It's not clear that what he will do will be similar
to what I did - he spoke of using "Help templates" instead etc.  I know nothing
about that.  I'm sure he'll take a look at what I did before deciding what to
do, but that's all I know.

I'm just saying that if you wait a bit you might have something in Emacs that
you could use to do what you want, and it might fit what you need better than
what I've done.  If not then you can always try using what I've done or roll
your own.  HTH.