emacs documentation for (La)TeX

emacs documentation for (La)TeX

[Joe Corneli]

I am thinking about trying to use Emacs' self-documenting features to
create some "native" documentation for LaTeX.  I'm thinking
about building this based on the TeX documentation being
made available at www.miwie.org

What I'm talking about is having something like this for each TeX
function:

(defun alph ()
"`\\alph{counter}' 

This command causes the value of the `counter' to
be printed in alphabetic characters.  The `\\alph' command uses lower
case alphabetic alphabetic characters, i.e., `a, b, c...' while the
`\\Alph' command uses upper case alphabetic characters, i.e., `A, B,
C...'.")


There are certainly some problems here!  

Upon defining the above "function" and hitting C-f h alph RET,
I see this:


alph is a Lisp function in `/Users/joe/site-lisp/JOESMACROS.elc'.
(alph)

`\alph{counter}' 

This command causes the value of the `counter' to
be printed in alphabetic characters.  The `\alph' command uses lower
case alphabetic alphabetic characters, i.e., `a, b, c...' while the
`\Alph' command uses upper case alphabetic characters, i.e., `A, B,
C...'.


whereas, I 'd like to see something more like this:


alph is a TeX function in `<link to wherever alph is actually defined>'.
`\alph{counter}' 

This command causes the value of the `counter' to
be printed in alphabetic characters.  The `\alph' command uses lower
case alphabetic alphabetic characters, i.e., `a, b, c...' while the
`\Alph' command uses upper case alphabetic characters, i.e., `A, B,
C...'.


Has ever tried to use Emacs' self-documenting features to document
another computer language?

Re: emacs documentation for (La)TeX

[Kai Grossjohann]

Joe Corneli <jcorneli@math.utexas.edu> writes:

> Has ever tried to use Emacs' self-documenting features to document
> another computer language?

The sawfish mode does it by defining commands
sawfish-describe-function, sawfish-describe-variable and so on.

I guess you might also try to leverage info-look.el (or infolook.el?)
to your purposes.  It can already give you the documentation for libc
functions, I think, so it would be natural to extend it to LaTeX.

What do people think?

Kai

Re: emacs documentation for (La)TeX

[Jesper Harder]

Joe Corneli <jcorneli@math.utexas.edu> writes:

> I am thinking about trying to use Emacs' self-documenting features
> to create some "native" documentation for LaTeX.  I'm thinking about
> building this based on the TeX documentation being made available at
> www.miwie.org

Just install 'latex2e.texi' from the tarball.  Then you can look up
LaTeX commands with `C-h C-i' [1] -- no extra work required :-)

> Has ever tried to use Emacs' self-documenting features to document
> another computer language?

I think the best approach is to write Texinfo documentation like
latex2e.texi.

[1] Unfortunately changed to `C-h S' in CVS.

Re: emacs documentation for (La)TeX

[Joe Corneli]

> I think the best approach is to write Texinfo documentation like
> latex2e.texi.

Indeed Michael Wiedmann is currently looking into exporting his
DocBook XML documentation of LaTeX to texinfo format.  But there is
something very nice in my opinion about being able to get the
documentation for Lisp functions with C-h f RET when you are writing
code. Between info-look.el and a more robust latex texinfo manual, it
looks like most of my questions about latex could be answered just as
easily as my ELisp questions[0].  Except perhaps for links to the
source, which may be the most useful feature of describe-function.
Perhaps this feature could be added directly to the texinfo package
(?), but that seems a bit non-standard.

[0] In general I tend to prefer looking at the documentation of
functions whose names I know -- for complicated questions (E.g. "how
do I get the diary to work properly?") that have relatively simple
answers, this often isn't as effective as looking in the manual.  But
it is a habit, and for simple questions it seems to be a very
effective strategy.  It might be that Emacs could do a better job of
providing in-line documentation for high-level questions in the
source files -- or maybe I just need to train myself to reflexively
look in the manual instead of the code for these kinds of
questions. At any rate, the reason I'm so keen on in-line help for
latex functions is mostly my interest in better understanding
low-level questions, where a link to the source together with a terse
doc string is typically the most useful thing one can look at.

Re: emacs documentation for (La)TeX

[Jesper Harder]

Joe Corneli <jcorneli@math.utexas.edu> writes:

> Except perhaps for links to the source, which may be the most useful
> feature of describe-function. 

Yes, that is incredible useful.  BTW, if you don't already know it
take a look at `find-function-setup-keys'.  It defines more handy key
bindings in the same vein.

But I don't think it generalizes easily to non-Emacs native language.
The standard way to handle it for other languages is /tags tables/,
see <info://emacs/Tags>.

And LaTeX is already supported by that ... though probably not exactly
the way you want if you're mostly interested in low-level
functionality.  But it is possible to define your own regexps -- it
might work well enough for your purpose.

Re: emacs documentation for (La)TeX

[Joe Corneli]

Just one more word on this right now; I'll be following up on your
recommendations shortly.

> But I don't think [find-function-setup-keys] generalizes easily to
> non-Emacs native language.

I'll give the tags apparatus a serious scrutiny.  But my thought here
is that it would be nice indeed to make TeX an "emacs native"
language, on par, in some sense, with Elisp.  I am solicitous of any
feedback on this idea.

Re: emacs documentation for (La)TeX

[Kevin Rodgers]

Joe Corneli wrote:

> I'll give the tags apparatus a serious scrutiny.  But my thought here
> is that it would be nice indeed to make TeX an "emacs native"
> language, on par, in some sense, with Elisp.  I am solicitous of any
> feedback on this idea.

I don't see why a markup language, or any programming language, ought

to "be on a par" with Emacs Lisp within Emacs itself.  But if you pursue
this idea, you might want to consider interning all the TeX symbols in
their own obarray.

-- 
Kevin Rodgers

Re: emacs documentation for (La)TeX

[Joe Corneli]

> I don't see why a markup language, or any programming language, ought
> to "be on a par" with Emacs Lisp within Emacs itself.

OK, maybe not quite on a par -- how about the level of Jack (assuming
that ELisp and Emacs C collectively make up QKA)?  After all, TeX is
is the GNU text formatter (this is according to the Manifesto, though
the prase "the GNU text formatter" is not perhaps 100% kosher) and
Emacs is the GNU text editor (again, I'm not necessarily being
perfectly precise). 

Seems like they should go together hand in hand... or more like, hand
in glove -- since they already do go together hand in hand. Maybe I'm
thinking about how to acheive my goals here in the wrong way -- it
wouldn't be the first time. Nevertheless, I am finding in my work
that the boundaries between TeX and Lisp have blurred -- and I'm
liking it, I would like it if they blurred more.

Re: emacs documentation for (La)TeX

[Kai Grossjohann]

Joe Corneli <jcorneli@math.utexas.edu> writes:

> But there is something very nice in my opinion about being able to
> get the documentation for Lisp functions with C-h f RET when you are
> writing code. Between info-look.el and a more robust latex texinfo
> manual, it looks like most of my questions about latex could be
> answered just as easily as my ELisp questions[0].

What's the difference between typing C-h f and C-h C-i, except for the
keybinding?

Hm.  I just tried C-h C-i and the message buffer tells me:

    Loading info-look...done
    Processing Info node `(emacs)Command Index'...
    Cannot access Info node `(emacs)Command Index'
    Processing Info node `(emacs)Command Index'...done
    Processing Info node `(emacs)Variable Index'...
    Cannot access Info node `(emacs)Variable Index'
    Processing Info node `(emacs)Variable Index'...done
    Processing Info node `(elisp)Index'...
    Cannot access Info node `(elisp)Index'
    Processing Info node `(elisp)Index'...done

"Cannot access Info node" -- bad.  I guess it's just a
misconfiguration on my part, though.

Kai

Re: emacs documentation for (La)TeX

[Joe Corneli]

> Hm.  I just tried C-h C-i and the message buffer tells me:
> 
>     Loading info-look...done
>     Processing Info node `(emacs)Command Index'...
>     Cannot access Info node `(emacs)Command Index'
>     Processing Info node `(emacs)Command Index'...done
>     Processing Info node `(emacs)Variable Index'...
>     Cannot access Info node `(emacs)Variable Index'
>     Processing Info node `(emacs)Variable Index'...done
>     Processing Info node `(elisp)Index'...
>     Cannot access Info node `(elisp)Index'
>     Processing Info node `(elisp)Index'...done
> 
> "Cannot access Info node" -- bad.  I guess it's just a
> misconfiguration on my part, though.

I had the same problem.  However, info-lookup-symbol worked fine in
latex mode.  I haven't looked further into the problem with emacs
info lookup.

The main difference between info lookup and describe-function is that
the latter (typically) has links to the source, whereas the former
doesn't.

Re: emacs documentation for (La)TeX

[Kai Grossjohann]

Joe Corneli <jcorneli@math.utexas.edu> writes:

> The main difference between info lookup and describe-function is that
> the latter (typically) has links to the source, whereas the former
> doesn't.

Ah, links to the source.  That is useful indeed.

Kai

Re: emacs documentation for (La)TeX

[Brad Collins]

Kai Grossjohann <kai@emptydomain.de> writes:

> Joe Corneli <jcorneli@math.utexas.edu> writes:
>
>> The main difference between info lookup and describe-function is that
>> the latter (typically) has links to the source, whereas the former
>> doesn't.
>
> Ah, links to the source.  That is useful indeed.

Well it links to the *documentation* in the source, not the whole source
itself.

The wonderful thing is that C-h f/m/c are internal documentation--it's
in context with what you are doing or looking at in a way that an
external manual--even the very good info manuals, can not do.

This is why Emacs is called a self-documenting editor--because it not
not only lets you peek under the hood to see what's going on, it tells
you exactly what's going on why you do it.

Try 'C-h k h" 

,----[ C-h k h ]
| h runs the command self-insert-command
| (self-insert-command N)
|    which is an interactive built-in function.
| 
| Insert the character you type.
| Whichever character you type to run this command is inserted.
`----

This really blew me away when I first saw it.  Typing the 'h' key runs
the command self-insert-character which inserts the character into the
buffer. 

The question that I think many people would ask is, why would
I need or even want to know this?

This is what sets Emacs apart from everything else in the world of
software--it changes the relationship that the user has with the
software and encourages you to understand and tinker with everything.

Emacs forces you to drop your illusions about text and to understand
that practically everything in computing is just plain text when you
boil away the fat and fur.

This explains the obsession that people who have drunk the Emacs
Cool-Aid have with trying to do everything in Emacs.  After you
understand that, say email, is just plain text, you want to start
using the power of Emacs to edit and work with. 

So if Emacs is an editor, for editing text, you can also think of
Emacs itself as a collection of text files (written in elisp) which
can in turn be edited by Emacs.  The purpose of Emacs then, (at least
one reason) is to edit Emacs....

b/

--
Brad Collins
Chenla Labs
Bangkok, Thailand