Square Brackets in Definition Lists

[mrkwnzl]

Hello! I think this is related to #128, but I thought it might be best to open a new ticket.

Regarding LaTeX export: When creating a Definition List, the definiendum cannot be in square brackets, because then the closing square bracket ] is interpreted by LaTeX as the first line of the definiens, while the actual definiens becomes the second line. Example:

MMD:

[Definiendum]
: Definiens

LaTeX:

\begin{description}
\item[[Definiendum]]

 Definiens
\end{description}

This is the result:

[fletcher]

This may be a case of "be careful what you wish for"....

My first reaction was that this was more of a LaTeX problem than a MMD problem per se, but then it occurred to me that you are right. This is a bug in MMD.

MMD is not properly escaping square brackets in LaTeX. So in that sense it is somewhat related to what you describe in #128.

But what it actually does is shed additional light on the proper fix (that you alluded to previously).

Which is to wrap all instances of [foo] as {[foo]} when [foo] does not perform any MMD-related purpose and is going to end up unchanged in the final text. Which properly fixes this instance involving definition lists. (Remember that [foo] has a certain possible meaning in MMD, but if it doesn't match an existing MMD reference link/etc., then the brackets go from having meaning to being literal square brackets that should appear in the final text unchanged.)

However, it also "properly" fixes your list example:

- [A.] Item 1
- [B.] Item 2

becomes:

\begin{itemize}
\item{} {[A.]} Item 1

\item{} {[B.]} Item 2

\end{itemize}

In this case, the fix was not absolutely necessary, since the square brackets were already protected by the {} preceding them.

Good news: this means that MMD can again use \item instead of \item{}, since the square brackets will be escaped on their own. (Aside related to a comment I made in #128 -- in this particular instance, it is possible to provide "string-level escaping", since [foo bar] is actually a single entity in the parse tree and is handled by a single function call when it fails to match something "meaningful" in terms of MMD syntax, such as a reference link. So that single function can be wrapped by braces easily to provide the escaping.).

Good news part 2: This means that HTML and LaTeX output of your list constructs now match.

Bad news (for you): This means that the loophole you used in MMD-5 for custom latex list numbering is still closed, and will require a slightly more advanced regexp to change, should you choose to do so.

Bad news (for you) part 2: This means that HTML and LaTeX output of your list constructs now match.

[mrkwnzl]

While I’d like to have a way for me to handle my LaTeX list labels in MMD, I also value consistency. So even with the bad news for me, it’s still good news, in a way.

I have still two good news, then, I believe:

1. The metadata configuration might even be easier to implement, I imagine (remember, I’m not a programmer). Checking whether [foo] needs to be {[foo]} could simply be deactivated if latex-itemize: labeled is configured in the metadata.

2. Not as pretty, but as a workaround I now could use the following for my labeled lists:

- `{=latex}[A.]` Item

Which with your new fix should result in the desired LaTeX-code, right?

EDIT: I think it’s better to also provide the desired LaTeX-code:

\begin{itemize}
\item [A.] Item
\end{itemize}

[fletcher]

1. The proper syntax would be `[A.]`{=latex}.

2. But yes, that is a functional approach. You could also use {=html} to define alternatives.

3. This would not work for [w~1 =], however, since w~1 is a MMD construct, not a LaTeX construct. You would have to manually use the LaTeX subscript code here.

4. BTW -- is there a reason you use a bulleted list construct for an enumerated list? Would it not be more accurate (and more "cross-format tolerant") to use:

    1. [A.] Item 1
    2. [B.] Item 2
   

5. I'll do you one better. Since \[ escapes a square bracket resulting in a literal character, \[foo\] does not result in a paired construct. So it is not subsequently escaped into {[foo]}. Since the literal character for \[ in LaTeX is [, the result of \[A.\] is [A.]. So you can now use:

    1. \[A.\] Item 1
    2. \[B.\] Item 2
   

The `[A.]`{=latex} construct is the most "correct" one. It clearly states, "I am doing something specific to LaTeX here. All other formats can move along. Nothing to see." It is the most unlikely to change behavior in the future, assuming that no other problems arise from replacing \item{} with \item.

The \[A.\] construct is basically a new loophole that replaces the one you previously used. That said, it's a loophole that I don't see a compelling argument to close. You're making a choice to escape the square brackets, explicitly stating that you do not intend this to be a MultiMarkdown construct. By "unnecessarily" escaping the bracket and effectively bypassing MMD, I consider myself absolved from any side effects this behavior may create in the output format. And since, in this case, the side effect is desired, everybody is happy.

Note, however, that this would not work (as it puts us right back where we were at the top of this issue):

\[Definiendum\]
: Definiens

But if you write me to say that is broken and needs fixing, then screw you.... ;)

[fletcher]

PS> I'm still not enamored with the idea of a special metadata option for the lists. And in light of the alternative syntax I suggested, I don't think it's necessary.

[mrkwnzl]

The proper syntax would be [A.]{=latex}.

I got it confused with the code block that has the {=latex} argument before the code.

This would not work for [w~1 =], however, since w~1 is a MMD construct, not a LaTeX construct. You would have to manually use the LaTeX subscript code here.

This is not a problem because of the \[A.\] loophole. I don’t really care that syntax I use or if I need a little LaTeX, I just want the label argument in LaTeX to show up and the MMD to stay more or less readable. Worst case, I use [$w_{1}$ =]. Still pretty readable.

So, to be honest, this would make me happy. For the LaTeX export, I mainly use Scrivener. Those inconveniences I can easily avoid with their new Styles. What I cannot avoid are curly brackets MMD puts after \item. So, yeah, no metadata configuration needed.

But if you write me to say that is broken and needs fixing, then screw you.... ;)

Fair point. I could still use this, though:

`{[Definiendum]}`{=latex}
: Definiens

Thank you so much!

[fletcher]

You can just use the original:

[Definiendum]
: Definiens

It's only if you try to get clever and escape the brackets inside the definition that there are problems.

(FYI -- these changes are pushed into the development branch already, so are available there now, or will be in the next release version as well.)

[mrkwnzl]

BTW -- is there a reason you use a bulleted list construct for an enumerated list?

Yes. there is. I use labels to number my examples, in best academic fashion. Those numbers need to be consistent throughout the text. So if I have some examples in list A and use the same examples in a list B, the numbers need to be the same in lists A and B. Even if this means that list B looks more like this:

(3) Example 3
(1) Example 1
(4) Example 4

Using labels is an easy and convenient way to do that. In Scrivener even more so, since I can use variables that number those examples automatically.