-
-
Notifications
You must be signed in to change notification settings - Fork 1.5k
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
Footnotes in documentation generation seem to be broken by default #21080
Comments
It went like this: "Nim's docgen uses RST, deal with it." People: "No, omg! We can only understand and use markdown" Me: "There are thousands of lines already written that successfully use RST and markdown and RST are so similar we can easily support both and make everybody happy" My analysis might have been off but Markdown also keeps changing and nobody knows what Markdown is, are tables now part of the markdown spec? Who knows, I cannot keep up with this nonsense. |
Hmm, might I offer the following hypothetical as a diplomatic plan of attack:
|
I don't like What's wrong with "we support our own hybrid format which we claim to be markdown compatible". It's not my fault that markdown is not particularly well thought-out. RST also has plenty of flaws though. What we have works reasonably well. We should just give it a name like "Nim structured text" so that people don't draw the wrong conclusions. |
Fair enough, & the IDE integration point is indeed a good one! Tho then the concrete problem I originally had remains, as there is no way to access the footnote code path / functionality without it? (That I can figure out.) So then Nim Structured Text does not support footnotes and the dead code can be eliminated?
I strongly sympathize with the distaste of implementing a spec you think is badly designed or flawed. Tho I also feel using a custom/homemade/hybrid format will paradoxically lead to a lot more work in the end, as in such cases there's a lot of extra documentation, guides, answers, etc. that need to be written to demarcate the differences and ease users into this new dialect. Following a spec is potentially more work in actual code, but in that case there's an already extant cornucopia of documentation, tutorials, & examples which can be referred to, offloading a lot (if not all) of documentation work. (And I find writing full & complete documentation is just as arduous as coding, if not more-so.) |
But that's what we already have and in practice "in the end" people need a preview of how it's rendered regardless if we follow spec X closely as most people cannot keep X in their heads reliably. |
This implements Pandoc Markdown-style footnotes, that are compatible with Pandoc referencing syntax: Ref. [^ftn]. [^ftn]: Block. See https://pandoc.org/MANUAL.html#footnotes for more examples.
Description
Running
nim doc
to produce HTML documentation on something likeerrors out with
Similarly,
gives a "broken link" warning, footnote is a regular link pointing to nothing; it was (likely) incorrectly interpreted as a Markdown link? Same goes for
[1]_
etc.I didn't analyze deeply but the problem seems to be caused by
roSupportMarkdown
(default) getting priority and interpreting either case as a pandoc implicit header ref Markdown link.Here:
Nim/lib/packages/docutils/rst.nim
Line 1714 in 6505bd3
Nim/lib/packages/docutils/rst.nim
Line 1590 in 6505bd3
WORKAROUND: there's a
doctype
pragma to turn off theroSupportMarkdown
default, but it seems rather obscure as I had to look at the compiler code to even know about it; it should probably be mentioned on https://nim-lang.org/docs/docgen.html ? I'm not sure what the purpose is of making this weird rST+Markdown amalgam the default.However, I still contend something is wrong as currently there seems to be no way to actually use the footnote functionality by default (or I am dumb), nor does the
markdown
doctype seem to support pandoc style footnotes.Nim Version
Nim Compiler Version 1.7.3 [Linux: amd64]
Compiled at 2022-10-27
Copyright (c) 2006-2022 by Andreas Rumpf
git hash: 3469f37
active boot switches: -d:release
Current Output
No response
Expected Output
No response
Possible Solution
No response
Additional Information
No response
The text was updated successfully, but these errors were encountered: