-
Notifications
You must be signed in to change notification settings - Fork 196
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
Add footnote syntax? #98
Comments
On the question "should we have a syntax for footnotes?" I think the answer is "yes", since it's a common-enough syntax in writing documents. To the question "which syntax should we use?" I think it should Pandoc syntax:
This use-case is worth supporting since it is already quite similar to the rST footnote syntax. The second question is whether to support inline footnotes, like this:
My intuition is that we should hold off on this one for now and revisit later on if it makes sense to accept this use-case (ie, if lots of people ask for it). What do folks think? |
Yep I’m for it. Just wanted to make clear the potential cons of its implementation. |
What are your thoughts on inline footnotes? On the one hand, RMarkdown already supports this, but on the other hand, this would be breaking out of the strict "we don't do things that rST doesn't do" rules |
I'd say no because its pretty non-standard and could just as easily be handled in a simple extension: {foot}`this is a footnote to be auto-numbered` rather than introducing more complexity into the parser, leading to a slower parse and more potential bugs. |
I like the idea of using roles for in-line footnotes, that's a clever idea. Gee who would have thought that extension points in a markup language would be useful 😅 |
I prefer Pandoc syntax - which is straightforward and simple - and I like @chrisjsewell's idea for in-line footnotes. |
Would |
@akhmerov I think it would be possible but that this role doesn't yet exist, so somebody would need to write a little sphinx extension for it (similar to what Pandoc does...I believe that syntax is only enabled w/ an extension) |
I meant to ask whether role names may contain special characters like ^ in myst. That would provide a compact syntax for inline references. |
ohhh interesting - I'm not sure...maybe that's a question of whether rST allows for roles names with those characters? |
But MyST's goal is not syntax compatibility, rather than AST compatibility, isn't it? That seems to be more within the responsibility of a parser. |
yes-and-no, we want to be thoughtful and probably slow in deciding to branch off in new directions. One of the goals of MyST is "be as close to CommonMark as possible, but extend the syntax so we can use Sphinx". Adding in-line footnotes with special syntax would be another departure from CommonMark and in a direction that doesn't map on to a pre-existing Sphinx behavior. That's why I agree w/ @chrisjsewell 's intuition to use roles for this, and why I think the question is "would Sphinx allow for a role called |
Seemingly the answer is "no"—the role names seemingly need to be alphanumeric. |
Bummer - well, perhaps it could be |
MyST's goal is to be spec compliant; this means parsing the tests outlined in: https://spec.commonmark.org/0.28/spec.json As you can see here: https://github.com/ExecutableBookProject/MyST-Parser/blob/fb83d74243a6e8bf00e872ef4707c223d9fe56dd/tests/test_commonmark/test_commonmark.py#L17 All these tests currently pass, except a few minor non-compliances (reasons documented), |
This is the docutils regex for allowed role names: # Alphanumerics with isolated internal [-._+:] chars (i.e. not 2 together):
simplename = r'(?:(?!_)\w)+(?:[-._+:](?:(?!_)\w)+)*' So a no on |
I think either way, we should table the "shorthand for inline footnotes" conversation to a different issue, and in the meantime can we agree that this style syntax:
should be included in MyST? |
@choldgraf certainly need it supported and a short hand would be nice. We use it in I like the proposed syntax but I think @chrisjsewell is saying the regex excludes being able to use |
Correct me if I'm wrong, but I think he meant we can't use a directive or role with a special character in it, but we can still use it as part of the regex we search for w/ the myst parser. |
oh I see. So for myst parser this is just a special syntax that would resolve |
yeah, well it would probably just directly go from |
closed in #119 |
As discussed in #31 it appears that people are for a footnote syntax, as implemented in some flavours of Markdown (see Extended Syntax):
Can we come to a decision on this, bearing in mind
Note these footnotes would be inherently auto-numbered, as can be tried in the VS Code standard preview (GitHub markdown does not support footnotes)
paging @choldgraf @mmcky @jstac @akhmerov @najuzilu
The text was updated successfully, but these errors were encountered: