Closed mattpalermo closed 7 years ago
can you add a screenshot ?
I figured out that if I leave spaces where it is allowed, this can be avoided.
The problem here is that [env.equation]
above an open block is not recognized universally as a passthrough block. This is something specific to Asciidoctor LaTeX. I think this raises the question about whether an open block should be used for this purpose. As a structural container, it doesn't communicate the semantics of "passthrough". I realize the ++++
is longer to type, but semantically it is more correct.
(What I'm talking about here is that the block delimiters are supposed to communicate how the content should be treated...it's content type. While extensions are free to break this assumption, we can't assume that tools will know about it).
Using the passthrough block would seem fix the problem since it clearly communicates that absolutely no substitutions are to be made on the content of the block (source). Additionally, this seems to be the method taken by the built in stem block (source).
I thought using the passthrough would be poor semantics because the passthrough is a type of hack to get behaviour into the output which cannot be produced by the processor. I say this because of the following statement in the documentation (source).
Using passthroughs to pass content without processing can couple your document to a specific output format, such as HTML. In these cases, you can use conditional preprocessor directives to declare passthrough markup for each backend you need to support.
I did some experimentation with the open block to see how the content would be displayed in atom when it was used to masquerade various different built-in block types. It seems to be flexible and displays the content correctly for each different type of block.
I did some experimentation with the open block to see how the content would be displayed in atom when it was used to masquerade various different built-in block types. It seems to be flexible and displays the content correctly for each different type of block.
That's because it's open block + block style. The problem with "env" is that it itself is generic, so then we'd have to start looking at roles.
I thought using the passthrough would be poor semantics because the passthrough is a type of hack to get behaviour into the output which cannot be produced by the processor.
A passthrough all by itself isn't recommended, but a passthrough that is processed by an extension is an appropriate use of a "raw" block.
The problem with "env" is that it itself is generic, so then we'd have to start looking at roles.
Hmm. So if the open block was to be used as the only block type for extensions then figuring out how the content should be treated by tools could be complicated and perhaps introduce restricting rules the inhibit creativity. By simply extending the description of the pass-through block type to be the "verbatim" block type for extensions then it is very simple. Users would then just have to remember when to use -- and when to use ++++. This does introduce the oddity that sometimes env must use -- and sometimes ++++. Would it be going to far to use a different style for the special env roles? So instead of using env.equation, it would just be eqn?
The final piece to the puzzle is the $ ... $ and [ ... ] syntax that asciidoctor-latex introduces. Clearly this would require the atom language plugin to be extension aware since substitution will happen inside these tags without the extension. I think I remember seeing an objection to the $ ... $ and [ ... ] syntax for this very reason, in favour for the proper syntax e.g. stem:[sqrt(4) = 2].
So if the open block was to be used as the only block type for extensions then figuring out how the content should be treated by tools could be complicated and perhaps introduce restricting rules the inhibit creativity.
Exactly. That's why we have different delimiters. They are hints.
By simply extending the description of the pass-through block type to be the "verbatim" block type for extensions then it is very simple.
"verbatim" and "raw" are different. Verbatim means to present the source as is appears (so some transformation must be done). Raw means to pass through the content as written, presumably to be interpreted in some unknown way (no attempt to alter).
The final piece to the puzzle is the $ ... $ and [ ... ] syntax that asciidoctor-latex introduces.
I'm still considering whether these delimiters should be recognized natively or whether it introduces too much risk of false positives. I'm not ruling it out, but I'm not ready to go there yet. That's why we have stem:[...]
.
I don't really know enough yet above the "env" block to understand how a writer will perceive it. However, it seems to me like the intent to make an equation should be understood that it's a passthrough (unaltered). It's so close to a stem block that this should be instinctual. I don't know about the other env blocks.
That's why we have stem:[...].
If this mark up works for inline equations I will consider using this. It is longer to type but if it will have improved tooling support then that will save me more time than a few keystrokes. I will have to see how it goes with Latex output.
However, it seems to me like the intent to make an equation should be understood that it's a passthrough (unaltered).
It seems clear to me as well after this discussion that the pass-through should be used for env.equation and env.code. However env.* (e.g. env.theorem, env.joke) should all be open block since the contents of those are expected to be normal content. Sometimes it is useful to include inline math and sometimes even block/display math, but that is only a component of the normal content. Example (taken from asciidoctor-latex readme):
[env.theorem]
--
The Diophantine equation
\[
x^n + y^n = z^n
\]
for \$n > 2\$ has only trivial solutions
--
It's so close to a stem block that this should be instinctual.
So far, the only difference to me is that a stem block does not give me numbered equations. And less importantly, a border is placed around the equation.
It seems clear to me as well after this discussion that the pass-through should be used for env.equation
yes
and env.code
no, in that case, it should be a listing block (four hyphens). I think it's important that env work on each of the structure containers (what I call delimited blocks) that support the nature of the content.
So far, the only difference to me is that a stem block does not give me numbered equations. And less importantly, a border is placed around the equation.
It's seems better to me to enhance the stem block rather than introduce a totally separate block. Something like:
[stem.equation]
++++
++++
That gives equation semantics to a stem block.
However env.* (e.g. env.theorem, env.joke) should all be open block since the contents of those are expected to be normal content.
The correct way to phrase it is that an open block contains compound content (content which is composed of other types of blocks).
It's seems better to me to enhance the stem block rather than introduce a totally separate block.
Can this be done with an extension?
Absolutely. It can probably be done in the converter. If not there, the Treeprocessor can also visit and make any enhancements.
Description
Normal text highlighting is applied to text inside equations. Please see syntax example. In the example the superscript formatting is applied to the text between the two carat symbols for both equations. This makes it difficult to read.
Syntax example