(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
Dear Haris, Allan, Max and all the LaTeX-ed Maters out there…
now that I have finished almost my whole thesis (I am a chemist) with TextMate and the LaTeX bundle, as well as having another larger LaTeX project ahead of me, I would like to offer some feedback as well. I am not sure I would have enjoyed writing thousand of lines of text in LaTeX without the usefulness of TM or the bundle… so first of all many thanks to Allan and everyone involved!
Am 10. Sep 2006 um 05:12 schrieb Charilaos Skiadas:
On Sep 9, 2006, at 6:40 PM, Max Lein wrote:
(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.
a very good idea, but I would like to have two such lists. One for the official commands, and another one for bundle commands (possibly including the most used ones) that is also user configurable, maybe via a TM_LATEX_BLABLA variable? As an example: I have used glosstex and there are quite a bit of possibly commands coming with it (as mentioned previously on the list where I posted a snippet of my personal flavor of the latex.grammar). Also I would love to have my custom commands as defined in my preamble color-coded, but thos would either have to be parsed by a script or added manually to the "second" list.
(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.
Folding: I have toyed with changing my snippets for the headings to include a commented line corresponding to the heading and then have TM fold over the two, such as:
\section{section name}\label{sec:sectionname}
%endsection
This works when the grammar contains the correct folding start- and stop- markers.
Footnote coloring was one of the first things I added to my tmTheme ;) If we added a snippet "fn" that created a footnote beginning on a new line and provided some help for folding I believe this would do as well, not?
(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.
(…)
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.
Or set a TM_VARIABLE? I am always a bit careful about changing the predefined bundles - you do lose any upcoming updates, although one could expect no major changes at a certain level of maturity of the bundle. But debugging things will become quite difficult… or have I missed an important change in the way things are handled?
(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.
If you add a transparent background you can also markup lists and have nested lists shown in distinct colors!
(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)
is it missing? I have one sitting here in my "sec" snippet, but then I do have many changes in the bundle itself and not all of the migrated out to my personal flavor… ;)
(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.
Is it normal that latexmk.pl does 6 runs of pdflatex? I have found this to be too slow for most things and added my own "render"- commands; but I also had to include glosstex in the mix… Is there some easy way to configure this? But maybe one can expect that most latex-users would be able to hack their own changes into the bundle, but a certain level of comfortable configuration might be useful as well - best achieved by setting TM_VARIABLE, not?
So much for now… there are some more things that I cannot get my head straight at yet, but I will post updates in the future -- better observed while actually working on it.
Have a nice sunday, Dan
Dear Harris, Allan, Max, Dan, ...
This weekend's thread is very helpful. Clearly, a lot of thought has gone into it. I wanted to thank Haris for introducing me to the Latex Bundle with his excellent screencasts, and, of course, Allan for making it all possible.
I have an idea of a fix for folding of sections. Whenever I talk a Latex user into trying out TextMate the first response is invariably, "Folding on its own is worth its weight in gold." Yet folding of sections does not work well and I have quit trying to do it. The problem is this: if I create a custom fold for a selection, the fold marks usually vanish when I return to it and edit. I then have to reselect the material which is counter to the TextMate philosophy.
Not many people know this, but Latex permits \begin{section} and \end{section}, instead of \section. If we could type sec, followed by tab, with the following outcome:
\begin{section}{section name}\label{sec:section_name} \end{section}
instead of the current
\section{section name}\label{sec:section_name}
then all would be well. The tabs would be correctly placed and folding would work as it should for sections. I realize this is nonstandard and journals might not like it, but a quick search and replace could restore this to the standard. Of course, the same goes for chapter, paragraph, subsection, subsubsection, all of which I use.
Jenny
On Sep 10, 2006, at 5:26 PM, Jenny Harrison wrote:
Dear Harris, Allan, Max, Dan, ...
I have an idea of a fix for folding of sections. Whenever I talk a Latex user into trying out TextMate the first response is invariably, "Folding on its own is worth its weight in gold." Yet folding of sections does not work well and I have quit trying to do it. The problem is this: if I create a custom fold for a selection, the fold marks usually vanish when I return to it and edit. I then have to reselect the material which is counter to the TextMate philosophy.
Actually, I think there might be a simple fix, without having to stop using the more standard \section commands. A new folding option has been added, so that lines of the form:
% stuff here (fold) ..... % other stuff here (end)
will fold, the key here being the words (fold) and (end) in parentheses and at the end of a comment line. So we could have the sectioning commands create:
\section{section name}\label{sec:section_name} % begin section section name (fold) % end section section name (end)
Then you could fold all but the \section line.
And there is also what Dan suggested, i.e. to just have the (end) line, and to add the \section... lines to the list of acceptable folding markers.
On Sep 10, 2006, at 6:41 AM, Daniel Käsmayr wrote:
Dear Haris, Allan, Max and all the LaTeX-ed Maters out there…
Am 10. Sep 2006 um 05:12 schrieb Charilaos Skiadas:
On Sep 9, 2006, at 6:40 PM, Max Lein wrote:
(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.
a very good idea, but I would like to have two such lists. One for the official commands, and another one for bundle commands (possibly including the most used ones) that is also user configurable, maybe via a TM_LATEX_BLABLA variable? As an example: I have used glosstex and there are quite a bit of possibly commands coming with it (as mentioned previously on the list where I posted a snippet of my personal flavor of the latex.grammar). Also I would love to have my custom commands as defined in my preamble color- coded, but thos would either have to be parsed by a script or added manually to the "second" list.
The problem with this is that the grammar has a kind of static form.
Folding: I have toyed with changing my snippets for the headings to include a commented line corresponding to the heading and then have TM fold over the two, such as:
\section{section name}\label{sec:sectionname}
%endsection
This works when the grammar contains the correct folding start- and stop- markers.
Footnote coloring was one of the first things I added to my tmTheme ;) If we added a snippet "fn" that created a footnote beginning on a new line and provided some help for folding I believe this would do as well, not?
Currently, pressing fn and then cmd-} results in "\footnote{}". You can change that by editing the latex_config file via the command in the bundle, and changing the line:
fn = '\footnote{$1} ';
to:
fn = '\n\footnote{$1} ';
or perhaps even better:
fn = '%\n\footnote{$1} ';
Not really sure how to achieve the folding.
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.
Or set a TM_VARIABLE? I am always a bit careful about changing the predefined bundles - you do lose any upcoming updates, although one could expect no major changes at a certain level of maturity of the bundle. But debugging things will become quite difficult… or have I missed an important change in the way things are handled?
We are trying to keep the number of TM_VARIABLE's to a bare minimum, in favor of using the LaTeX configuration file for customization. As far as changes go,TextMate uses a "deltas" system now. What this means is that if you change any aspect of a bundle command, then this change is kept in a "delta file" and is merged with whatever the current command is, so you can stay updated on other aspects. In this particular case, the only thing you would miss is if we changed the actual text of the drag command.
Btw, this delta idea applies equally well to shortcuts. You can now safely change the shortcut for a command, and rest assured that the actual text of the command will remain up-to-date if we change it at a later date. The only thing not up to date would be the shortcut.
(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)
is it missing? I have one sitting here in my "sec" snippet, but then I do have many changes in the bundle itself and not all of the migrated out to my personal flavor… ;)
A snippet for "chapter" is missing. There are snippets for sections.
(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.
Is it normal that latexmk.pl does 6 runs of pdflatex? I have found this to be too slow for most things and added my own "render"- commands; but I also had to include glosstex in the mix… Is there some easy way to configure this? But maybe one can expect that most latex-users would be able to hack their own changes into the bundle, but a certain level of comfortable configuration might be useful as well - best achieved by setting TM_VARIABLE, not?
The help does briefly mention that you can use your own script for the compiling. It doesn't provide many details since that would be a bit too technical.
Haris
Haris,
Actually, I think there might be a simple fix, without having to stop using the more standard \section commands. (...) \section{section name}\label{sec:section_name} % begin section section name (fold) % end section section name (end)
Then you could fold all but the \section line.
And there is also what Dan suggested, i.e. to just have the (end) line, and to add the \section... lines to the list of acceptable folding markers.
Would anyone mind if one of these became part of the snippet? Both work well, but I like the visual symmetry of (fold)/(end).
Jenny