[TxMt] Regarding the LaTeX bundle

[Charilaos Skiadas]

On Sep 11, 2006, at 8:31 AM, Max Lein wrote:
>>
>> allan: (i) I prefer that as well — if we can get a list, that’d  
>> be
>> great!
>>
>> me: I agree too. Max (and anyone else as well), if you provide us
>> with the commands, for within math and out of math, then we'll add
>> them in.
> Ok, I will compile a list over the course of the week. Basically, I  
> will start by copying the standard commands from the various  
> handbooks.

Just send them to me (or the list) when you are done. These can  
easily be included. The custom one are a bit more difficult:

> Please document how to add your own commands to that list! (E. g. I  
> have created commands like \norm, \scpro (scalar product), \ket,  
> \bra, \C, \R, etc.)

This won't be very easy to do, we'll have to figure out the best way  
to do it in terms of making sure the user stays up to date with newer  
versions of the bundle. We could tell you how to edit the language  
grammar to add these things, but that's not very easy to do and  
results in the user having local modifications to the bundle which  
might result in them not seeing any official changes that happen to  
the grammar.

One thing that can be done now, is that you can create a new language  
that basically has the extra commands, and then includes the latex  
language, and you would be using that new language instead. I could  
offer a template language and tell you what you need to edit where.  
However, I would consider that only a temporary fix, because my  
understanding is that the next major version of TextMate will have  
tools that will make this customization process a lot easier/powerful.

>> allan: (ii) this is because $ is a smart-typing pair, and it finds
>> that there is a “starting” $ outside the screen — not sure how
>> to best address that (probably we want to keep it a smart typing  
>> pair)
> Definitely, definitely, definitely keep smart-pairing $s, it was my  
> #1 syntax error with TeXShop and very tedious sometimes to find the  
> erroneous line of code.

That's exactly why I advocate the use of \( \).

(we could actually make it so that pressing the dollar sign produces  
the \( \) pair instead ;). )

>>> (iii) Footnotes and marginpars should be marked within the text;
>>> perhaps the footnote's/marginpar's text could even be folded (not
>>> sure if automatic foldmark recognition works on a bundle level).
>>
>> allan: (iii) marking: yes, folding: we can’t do w/o having the
>> braces align
>>
>> me: The text in the footnote gets a scope of meta.footnote.latex
>> So if you add that scope to your coloring theme and add some color to
>> it, you'll get highlighted footnotes. Not immediately possible for
>> marginpars, but we are thinking of matching those as well and giving
>> them some scope extending both footnotes and marginpars, so that you
>> could color both of them at the same time.
>
> Yes, it is immediately possible. I've just added marginpar to the  
> footnote environment (so its scope is now both footnotes and  
> marginpars alike), took about 10 seconds :-)

I meant it was not possible without editing the language grammar.  
However I did add yesterday marginpar as a separate scope. It is  
meta.paragraph.margin.latex (not meta.paragraph.marginpar.latex as I  
mentioned in my last email).
>>
>>> (iv) Use input instead of include when dragging a .tex document
>>> into another: afaik include is deprecated and input is preferred
>>> instead. You cannot `include' some bundles for instance (diagxy
>>> comes to mind), you have to use input instead.
>>
>> allan: (iv) probably then we should even markup include as
>> invalid.deprecated
>>
>> me: I don't think \include is deprecated. I use \include for
>> different chapter of a book etc, and it does a number of special
>> things like clear all the floats, start on a new page, generate
>> separate aux files etc.
>
> input also creates separate aux files. I just ran into some  
> problems with include and have used input ever since. Page breaks  
> are not a concern since I usually have separate files for each  
> chapter -- the chapter command takes care of the page break.

Can input do selective includes, like via \includeonly? [http:// 
www.eng.cam.ac.uk/help/tpl/textprocessing/teTeX/latex/latex2e-html/ 
ltx-245.html]

I was actually thinking, that one could simply duplicate the include  
drag command, and have a new one with input. Now, when you drag a  
file, you would be getting a menu with two options, and selecting one  
of them (with arrows or 1/2 numbers) would do the corresponding  
thing. We could do the same thing for graphics,

>>> (v) Forget about the deprecated math environments `\[ … \]' and `\
>>> ( … \)', just remove them from your bundle. Guidelines by relevant
>>> journals suggest to use specific environments anyway (align for
>>> instance).
>>
>> allan: (v) I’m all for removing stuff, especially when  
>> deprecated ;)
>>
>> me: I would need some stronger evidence that it is deprecated. As far
>> as I understand, the alternative to \( \) would be $ $, and I don't
>> see what advantages that has except that it is much harder to parse
>> the file looking for math in it, and if you miss one of the $ you
>> might not find out until much much later.
>>
>> As for \[, \], I again don't think they are deprecated, but I would
>> love to be proven wrong. The only alternative I see is \begin
>> {equation*}, which requires the amsmath package. I might possibly
>> agree with you that in the context of writing math papers for
>> submission to journals, one might want to avoid \[, \], (though still
>> I would need to see some strong evidence for that), but I don't see
>> why I shouldn't be using it in the notes for my students for
>> instance. Replacing them all by \begin{equation*} is a single search
>> and replace anyway. (Note to self: Actually, having a command that
>> toggles the various math environments might not be a bad idea at  
>> all.)
> I usually use align and align*. I have never personally used \[ …  
> \] and I have seen only one person use it, and that person still  
> writes his (brilliant) papers in plain TeX.
>
> It doesn't really bother me if you keep it, but I just thought that  
> we could very well eliminate everything which is superfluous in a way.
>
>> Do you have references to these guidelines of these journals
>> (including non-math/physics journals)?
> One of the guidelines I use is the revtex guidelines which is used  
> for a wide number of journals, including Phys. Rev. A-E and Phys.  
> Rev. Lett.

I was just looking at: http://authors.aps.org/revtex4/auguide.ps
Section 6.4 explicitly mentions using \[, \] for unnumbered  
equations. And nowhere is it mentioned that \(, \) should not be used  
(though it does mention $).

The AMS-LaTeX guidelines do make it clear that both options are fine:
[ftp://ftp.ams.org/pub/tex/doc/amsmath/short-math-guide.pdf]

The only thing they discurage is the use of the eqnarray environment.  
They also recommend not using $$..$$

>>> (vi) Inline formulas should have a grayish background so it's
>>> easier to see where formulas begin and where they end. (This one is
>>> also important to me.)
>>
>> allan: (vi) that’d be a theme-thing, as long as the grammar marks
>> them up
>>
>> me: Do you want the background for inline formulas to be different
>> than the one for multiline formulas? Because as things are already,
>> you can target the scope math.tex in your theme, and that would color
>> all math however you tell it to.
> Yes, I want it to be different. I add a commented line above and  
> below the align environment, i. e.
> %
> \begin{align}
> formulas
> \end{align}
> %
> So I don't need any background. In either case, it is desirable to  
> have different settings for inline formulas and displayed equations.

Working on it. Actually the grammar will undergo a series of changes  
in the next couple of weeks probably.

>>> (vii) You already have tab triggers for section, subsection and
>>> subsubsection, so how come chapter is missing?
>>
>> allan: (vii) oversight (and we rarely need it)
>>
>> me: Basically, initially we were trying to keep the number of
>> snippets at a bare minimum because of the way they were showing up in
>> the menu, as a flat list. On top of that, most of those can instead
>> be accomplished via the “Insert Command…” command, along with
>> customizing it through the LaTeX Configuration file, so the other
>> maintainers had a hard time even convincing me to keep the section
>> ones in. Now that we can create submenus, we've toyed with the idea
>> of adding more snippets, so any ideas on what other snippets to
>> include are welcome.
> I know I can add it. However that is something I definitely think  
> is missing. \chapter is one of the most basic commands in TeX and I  
> would strongly suggest to add it.

I've just added command for part, chapter, paragraph, subparagraph.  
The triggers now are:

part -> part
cha  -> chapter
sec  -> section
sub  -> subsection
subs -> subsubsection
par  -> paragraph
subp -> subparagraph

Also, all these commands now create the (fold) (end) comments  
described earlier, so they would fold and that should keep Jenny happy.

Further, they have been designed so that you could execute them with  
a selection, and then they would wrap around that selection.

>>> (viii) A way to execute bibtex (and pdflatex twice to see whether
>>> all additional citations have been included).
>>
>> allan: (viii) latexmk.pl should do that — maybe we should make this
>> the default, not sure if that would bother anyone (maybe some
>> workflows would mean much more time typesetting)
>>
>> me: latexmk.pl will actually do a lot more for you. The Help file
>> should describe how to set it up. I'd personally prefer not to have
>> it as the default. It is however easy to set it in your system.
> I think I wasn't expressing myself clearly here: when you run  
> bibtex via the LaTeX bundle, it does just that. However, I think it  
> is a lot more useful if you actually pdflatex the document twice  
> and display the document so you can check whether or not it worked.

This sounds more like what latexmk.pl was made for. Running bibtex is  
exactly that.

>>> (ix) Closing environments: when I manually type \begin{environment}
>>> and then close the environment, the `\end{environment}' which is
>>> added is indented like the text within the environment. Hence,
>>> TextMate's code folding does not recognize the block.
>>
>> allan: (ix) http://macromates.com/ticket/show?ticket_id=B34CCC0C --
>> the request might be granted, but use begin⇥ or ⌘{ until then
>>
>> me: just follow the workaround suggested in that ticket (and most
>> importantly, don't manually type \begin{environment}).
> No, I usually don't. But sometimes I need to break a displayed  
> formula into two, I use that command.

I would do: select the second part of the formula: press cmd-x, move  
down until out of the environment, type eq (or the right shortcut)  
followed by cmd-{ to generate a new equation environment, and then  
press cmd-v.

Alternatively, you can again select the second part of the formula,  
use ctrl-cmd-down arrow to move it out, and then use shift-ctrl-cmd-W  
to wrap it in a new environment.

The advantage of the second method is that it does not affect what is  
in the pasteboard.

>>> Now concerning the Help. The help is nicely structured, although I
>>> miss a nice webpage with the key features of your bundle. That
>>> would have helped me to use more of the functions included in your
>>> bundle.
>>
>> Hm, that was actually partly our intent with rewriting the help file
>> this way. To make it easy to find out how to do stuff. Looking at the
>> bundle is of course the best way to find out what commands are
>> available. How is the help lacking in showing you what the bundle can
>> do?
>>>
>>> (i) A glossary of TM_LATEX_BLABLA variables. That would be really
>>> helpful, especially for people who just want to check out what you
>>> can do with the LaTeX bundle.
>>
>> There are basically only five such variables, most of them having to
>> do with more particular workflow setups:
>>
>> TM_LATEX_VIEWER       if you don't want to use the built in previewer
>> TM_LATEX_ERRLVL       if you want some finer control on what errors
>> show up
>> TM_LATEX_COMPILER     if you want to use latexmk.pl
>> TM_LATEX_OPTIONS      for any options you might want to add to the
>> command line call to the compiler.
>>
>> and finally, TM_LATEX_MASTER, the only one of more frequent use, when
>> setting that a master document should be used for the compiling.
>
> That needs to be documented in the form of a howto. ( I am seeing  
> now you've mentioned some further down.)

That is a good idea. Please suggest a list of specific howto topics.
I'll see if I can also do a screencast demonstrating a typical  
complete workflow.

>>> (ii) Overview over key functions (auto completion of citations,  
>>> etc.).
>>
>> Isn't the explanation in section 5.2 of the manual adequate for that?
>> In general that's the purpose of the entire section 5. In what ways
>> is that failing?
> In the way that people like me don't read the help until section  
> 5.2 to discover new features. I know I sometimes should, but it's  
> just the way it is. In this way, I would suggest to add one section  
> in the very beginning (section 1.2 or so) about basic features. If  
> they are hidden in section 5.2, fewer people will actually use them  
> -- which is a pity.

I guess that's why we have the outline at the very beginning, which  
links to the subsequent sections. In the first draft of the help  
there was such a thing, but then it was removed. We were trying to  
keep the size of the LaTeX file a small as possible, so that users  
could actually read the entire thing.

How about a cheatsheet instead? A single page containing all the  
necessary information, in the form of a pdf?

> I have given the help some more thought and I think that also one  
> chapter about customizing the LaTeX bundle is missing. Somehow I  
> haven't come across a good documentation on how to edit bundles,  
> something like a HowTo is definitely missing.

Allan and I both agree with that. This is something that's missing.  
However, a lot of the customization of the LaTeX bundle should be  
done via the LaTeX Configuration file instead. What kinds of  
customizations did you have in mind? Things like creating a new  
snippet or a new command, or changing a current command? Or more deep  
things related to the syntax?

> For me, the most helpful kind of documentation is one that explains  
> by example (e. g. Samba by Example). So I would suggest to write  
> HowTo sections on `Getting Started', `Big LaTeX Projects',  
> `Customizing The LaTeX Bundle'. I would be willing to make  
> additions of my own.

I take it you have seen the posts here: http://skiadas.dcostanet.net/ 
afterthought/list-of-my-textmate-pages/
They are a bit outdated I must say, need some new ones. Not sure if  
they count as HowTo's.

>
> Ok, that's all for now.
>
> Max

Haris