string handling

[matlab2tikz]

string handling

[burkart]

Hi Katherine!

I'm the one who's responsible for the rewriting of how strings are processed. The goal was to have the matlab2tikz output resemble--as closely as possible--that which you see directly in MATLAB/Octave. If you used the strings you mentioned, they'd look not at all the way you'd want them to in MATLAB, as does the output of m2t. So in order to get the strings parsed correctly, what you have to do is make them look right in MATLAB first. Please don't try to work around m2t internals to achieve your goal. Once the output looks good in MATLAB, it should be converted correctly by m2t -- otherwise please file a bug.

In your case, if you use the commands cited above, MATLAB would give you a warning that it's unable to interpret the TeX strings. What does work is

xlabel('time [s]')
ylabel('\omega_{\iteq} [p.u.]')

The output generated by matlab2tikz('filename.tikz', 'mathmode', true) is

xlabel={time [s]},
ylabel={$\omega{}_{\it\text{eq}}\text{ [p}.u.\text{]}$},

and the output of matlab2tikz('filename.tikz', 'mathmode', false) is

xlabel={time [s]},
ylabel={$\omega{}_{\it\text{eq}}\text{ [p.u.]}$},

As you can see the m2t parameter "mathmode" has an influence on how the output strings are formatted. Generally speaking it tends to think of strings as holding mathematical expressions which should not be wrapped in a \text command. This is true for e.g. plus and minus signs as well as numbers including periods / decimal points and single letters (supposedly variable names). This is why in your case the ".u." is excluded from the \text command. So you either manually set "mathmode" to true or you didn't set it at all and the default value (true) came into play. As to whether this parameter should be false by default, I'm very open for comments. However, generally speaking you should get the output to work by making it work in MATLAB, thus changing your labels to the ones I suggested plus setting "mathmode" to false, should solve your problem. You'd also have the added benefit of your strings looking good in MATLAB itself and any generated output other than m2t (e.g. PNG or PDF).

While I think this bug should be closed, I do like the idea of a new m2t parameter that would disable any string processing whatsoever inside m2t. It would be easy to implement and allowed people to sacrifice proper string display in MATLAB for ultimate flexibility in the m2t LaTeX output. Nico, any comments?

[burkart]

Hi Nico!

In commit bb7cec9 to my branch "nostringparsing" I implemented a new matlab2tikz parameter which enables users to pass strings to the LaTeX output unmodified. Let me know if you need me to send a formal pull request.

As far as Katherine's problem is concerned, this isn't exactly a revert to the "good old times". In particular the new code does not use TeX's math mode by putting dollar signs around the strings. However, I do think that this should not simply be a compatibility mode but rather offer full flexibility for whoever may need it. See also the commit message.

[nschloe]

I think the problem is real and I like the idea of that parameter. We might even forget about 'mathmode' then altogether. Do you see a use case for it if we introduce the new parameter?
For simplicity's sake, I'd suggest to name it 'parseStrings' (or similar) and have it default to 'true'.

[burkart]

Historically speaking, "mathmode" took the unmodified strings and encapsulated them in $...$, i.e. made them use TeX's math mode. This was useful as a lot of the TeX commands MATLAB knows are valid in math mode but not in text mode. An example for this would be \alpha with the one counter-example I know of being \0 which is text mode and thus transformed to \emptyset by recent matlab2tikz versions.

The re-written string processing always encloses the strings in $...$ and only removes this if the entire string contains plain text. Thus "mathmode" could have been dropped at that point, but I decided to use it for a different purpose, namely a heuristic to use TeX math mode for as much of the strings as possible. Enabling "mathmode", title('sin(2\pit)') produces title={$\text{sin}(2\pi{}t)$} whereas with "mathmode" set to false it produces title={$\text{sin(2}\pi\text{t)}$}. In cases like this one you probably want the output you get with mathmode=true.

The problem is that with mathmode=true, m2t essentially guesses what the user wants and that is bound to fail in some cases. Nevertheless the benefit of having "mathmode" is that it produces valid LaTeX output for valid MATLAB input. The difference to mathmode=false is that the output is more WYMIWYG (what you mean is what you get) instead of WYSIWYG (what you see is what you get).

The downside to "nostringparsing" (or parseStrings=false) is that you will most likely end up with (La)TeX code that MATLAB doesn't recognize and thus will warn you about. In addition to that you will get a weird result if you save the same figure as e.g. PNG. Therefore I would recommend to use "nostringparsing" only if you really need a specific m2t output that can't be achieved by MATLAB. Everything that MATLAB displays should be convertible by m2t or else it's a bug.

In conclusion I'd say it's probably best to have "mathmode" default to false. Personally I would not scrap its new functionality altogether as it can be useful in cases like the "sin(2 pi t)" example. However, maybe it would avoid confusion if this behavior was sensitive to a new parameter (say, "mathHeuristic") that defaults to false while the legacy "mathmode" parameter is removed.

If you're okay with it, Nico, I'd make a commit and send you a pull request with the following changes:

• remove the parameter "mathmode" and give a deprecation warning if people use it,
• make the math mode heuristic in prettyPrint sensitive to a new parameter "mathHeuristic" that is false by default, and
• introduce a new parameter "parseStrings" that is true by default.

[nschloe]

title('sin(2\pit)')
In cases like this one you probably want the output you get with mathmode=true.

I think in cases like this, if the user isn't happy with the crooked wysiwyg output, he or she should use title('$\sin(2\pi t)$','Interpreter','none') and have it piped literally to the LaTeX output. Indeed, if one would like to generate a PNG and a TikZ out of this, you can't use the same code. I don't think this ever happens though.

I'd suggest the following:

• introduce a new parameter 'parseStrings' that is true by default.
• Rename 'mathmode' to 'parseStringsAsMath', set to false by default, and warn if someone uses it. Something like "If you would like to have more control over the strings, what you want is setting 'parseStrings' to false."

After all, as you say, we could but tons of brains into parsing methods that guess what people want, but those will never be good enough to cover all cases (see this issue).

[burkart]

title('$\sin(2\pi t)$','Interpreter','none') wouldn't work as with interpreter set to "none", the backslashes and dollar signs would be escaped. What is gonna work, though, is the planned parameter "parseStrings" and

title('$\sin(2\pi t)$') % interpreter doesn't matter
matlab2tikz('filename.tikz', 'parseStrings', false)

The downside is that it looks awful in MATLAB itself. And that's really the point: if at all possible I wouldn't want users to adapt their code--which works perfectly in vanilla MATLAB--to suit m2t's behavior. Instead, any disparities should be ironed out in m2t. I'm nevertheless for an optional parseStrings=false, but that one should be a last resort. The use case where both m2t and e.g. PNG output is generated is obviously not too common(*), but the one where you have a figure look a certain way in MATLAB itself and then in the m2t output certainly is. The same code should work for both.

I'm not convinced why m2t should give a warning if a user manually and thus consciously set parseStringsAsMath=true. Otherwise I think we've come to a good solution and I'll work on a patch.

(*) Personally, I have used PNG and m2t output at the same time, though mostly during development. The other occurrence that comes to mind is the test suite.

[nschloe]

Okay, we're talking the same language here.

I mentioned the 'Interpreter','none' setting because it'd be useful for anyone who doesn't like MATLAB(R) warnings and still wants to use parseStrings==false.

I'm not convinced why m2t should give a warning if a user manually and thus consciously set parseStringsAsMath=true.

Good point. I was thinking of users such as Katherine and don't want anyone to get distracted by parseStringsAsMath while they'd actually be better off with parseStrings=false. This is more or a documentation thing though indeed, so I'm find with no warning there.

I'd love to have the ability to do -h or --help in MATLAB(R) in some way. Are you aware of anything? Otherwise I guess I should sit down and extend the README.

[burkart]

How about the changes in my commit a732a60? As far as I can see this implements the established consensus.

As for help messages in MATLAB, maybe it's possible to hook into doc matlab2tikz or at least help matlab2tikz.

[nschloe]

Feel free to reopen.

[burkart]

Regarding the on-line help, if you type help matlab2tikz on the command prompt it displays the first block of comments in matlab2tikz.m.