[TxMt] Regarding the LaTeX bundle

[Charilaos Skiadas]

(Forwarded to the list after Max's permission. I've commented inline,  
also added Allan's comments)

Hi Max,
On Sep 9, 2006, at 6:40 PM, Max Lein wrote:

> Dear Haris:
>
> You've asked for user feedback on the LaTeX bundle (I'm Max Lein  
> who posted on the textmate mailing list).
> To be honest, I didn't know about many features until I've seen  
> your webcast … :-) You're doing great work, I use your bundle  
> pretty much on a daily basis (I'm a mathematical physicist). I'll  
> be overly critical here to help you make your bundle even better.

Thanks for the feedback!

> I would think (i) is my most important suggestion. There are some  
> commands I have a tendency to misspell -- \smallksip, I mean  
> \smallskip is one of them.
>
> (i) No known command list: suggestion: type command: text stays  
> grayish-blue until a command is recognized. Then the text turns  
> dark blue. Basically there should be user feedback whenever a  
> command is recognized.
>
> I can provide you with a list of `official' LaTeX commands if needed.
>
> Obviously, something similar should be implemented in math mode as  
> well (start with dark red which changes to red once a command is  
> recognized).

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.


>
> (ii) Sometimes when beginning inline formulae, the whole screen  
> blinks as if there is a syntax error.

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)

me: I would say that's a good enough reason to use \( \) instead of $ $

> (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.

Update: marginpars are now matched with scope  
meta.paragraph.marginpar.latex, so you can color them as you like.

> (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.

Of course, you can easily change this in your own copy, by opening  
the bundle editor and finding the appropriate drag command. All you  
have to do is change the \\\\include that appears there to \\\\input.

> (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.)

Do you have references to these guidelines of these journals  
(including non-math/physics journals)?

> (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.

> (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.

>
> (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.

> (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}).

> 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.

There used to be a section containing all the variables, back when  
there were 10 of them, but we thought that since there are not that  
many of them, we'd just mention them in the corresponding section of  
the help file.

Basically we are trying to keep the help at ar reasonable size, while  
still making sure it maintains all the important information.

> (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?
>
> If you wish to post this on a mailing list, feel free to do so. As  
> an avid user, I would like to participate in the discussion,  
> though :-)
>
> Greetings from Germany
>
> Max

Thanks again for your feedback (and let me thank in advance everyone  
else participating in this discussion). There's a lot of areas in  
which the LaTeX bundle could be improved, and because of the very  
diverse group of people using it it's hard to know what would help  
every individual user. So your feedback is instrumental in seeing the  
needs of the users of the bundle.

Haris