-
-
Notifications
You must be signed in to change notification settings - Fork 19
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Re-consider the use of square brackets to signify keyrefs #225
Comments
Another person experiencing a similar problem here: dita-ot/dita-ot#4304 (comment)
|
How about if the content inside [...] is not a valid key name or cannot be mapped to an existing key name, the brackets and their content could be preserved exactly as they are instead of being converted to:
? |
Keyrefs use shortcut reference link and it's part of Commonmark. The only reason why |
Valid key check is something that could be done, but checking for existing key name is not possible because these key references are in topics and the parser doesn't have access to all key definitions at parsing time. |
I understand, maybe we could pass some kind of interface to the parser through which it could ask some basic key-related questions? Also if the value inside the "[]" brackets is not a valid key name, we could just keep that value as it is? |
The problem I see is that if the user has e.g. * a = [m, n]
* b = [m] In this case the first case is not a valid key name, so it would come out as Having different fallback in Markdown and Markdown DITA would make it even more confusing. The best option would probably be to add a feature the disable shortcut reference links as key references. You can either have
The question is, are these users willing and/or able to configure the parser so that they can disable this feature? |
Probably most users will not be able to configure the parser unless this setting becomes some sort of DITA OT parameter. I would see the most correct Markdown-aligned approach as trying to see if that referenced key name actually exists. |
For DITA-OT, verifying whether the key exists will work only for preprocess2 for topics, but for maps even that will not work without resolving the shortcut reference after keys spaces are collected. The other problem is that if the user explicitly wants to have a key without definition, something that's a valid use case in DITA content. |
Is this the kind of situation where at the end of the build you might notify the user with a "NOTICE: You seem to be using feature-xxx. Because this works both in Markdown and DITA-OT different, if you get un-preferred results then..." That could point to details of "Here is how to format it to work as you expect." The reason I ask is that another way to look at the build, which I feel like you are alluding to, is that the user is either doing a "MARKDOWN ONLY BASED BUILD" or "DITA-OT BUILD THAT HAPPENS TO USE MARKDOWN-DITA." In the former, a notice would be pleasant-enough. In the latter, the user would have a good chance at fixing it. Disclaimer: FWIW I only study DITA and am not using it so this is all theory. |
Unescaped square brackets in Markdown indicate a reference link, regardless if DITA-OT is involved. https://www.markdownguide.org/basic-syntax/#reference-style-links
Output: Click here for more info. Therefore, the correct Markdown format requires the user to escape the square brackets as such:
Output:
|
One of our clients used in their Markdown files square brackets just as text content like:
The problem is that the when the Markdown file gets interpreted as DITA XML, there is an attempt to convert the content in the square brackets to key refs, which the person writing the Markdown content did not intend to do. So the Markdown no longer can be used as it was written, someone needs to \ escape the square brackets manually when used with a DITA Map.
The text was updated successfully, but these errors were encountered: