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
Allow multiple note types (footnotes, endnotes, etc.) #1425
Comments
|
A thought on |
The problem with Also how is That's why I think the best way to indicate endnotes and sidenotes is to I don't like Another matter is that automatic numbering of endnotes should probably use the a..z,aa,ab..zy,zz series. OTOH I think that the best change in the long run would be to store the |
Strawman idea: what if the location of the note body in the source affected its position in the output?
There are obviously holes in this proposal, and compatibility problems - until now all of these were footnotes of equal standing. But it's such a natural direction... |
Seems fragile -- I know I would always be getting it wrong. Plus it would break concatting docs, which is pretty useful for multi-file documents. My bigges interest is in having it in the AST -- I imagine you could filter to get there if you needed it, without disturbing most folks' use of just one note type. e.g.
It's a pain to write. But the point is, it can be in the AST and useful for the small percentage who need it without needing to decide on markdown syntax for it. This was what happened with the generic divs and spans. The above also has the advantage of degrading gracefully. That being said, if I had to vote for some sort of ascii markup, I would probably go for some replacement for the caret:
or the like. |
Or, yeah, the backwards-compatible version in @bpj 's version above. |
At least in the near term, at this point I'll agree the best is to get all of this info into the AST, so a filter can handle it. A fairly generic filter would then be a good thing for a 'pandoc extras' package. There is the possibility of leaving the options in the filters - not everything has to be built into pandoc, if there is a good set of readily-available filters for 'common uncommon' things. It would keep pandoc simpler (trying to avoid the 'kitchen sink effect'), while still allowing the more powerful uses. |
The only downside I'd see to leaving it in the filters is that you couldn't simulate the different-carets, since the AST doesn't keep the footnote marker. But other than that, I'd tend to agree. The only user-facing thing that would need to come with a change to the AST would be some sort of I also like the idea of a pandoc-extras/pandoc-contrib filters package. A place to set up niche features, or try out some features on their way to inclusion. This all makes me realize that I'd really like to see a filter option in the YAML block. In some docs I have a hefty amount of filters, but don't really want to set up a Makefile, for whatever reason. It would be nice to have the doc keep track of the filters it wants. |
You could place a marker character as the first char of the footnote text, optionally followed by an all-alphanumeric id and then a space. Perhaps you could put it in braces so you won't need to backslash escape the marker. Not as elegant but the filter could see it, inspect it, and remove it from the note's content list before it possibly munges the note element. I've been thinking all day about whipping up a proof of concept, but I'm going away on Saturday and won't likely have time before then. Of course the real solution would be for all elements to take attributes -- namely as braces as the very first thing in the element, at the top of block elements, as the first thing after the delimiter in inline elements. |
Interestingly, it turns out that someone has already made their own fork of Pandoc to accomplish this: https://github.com/susanemcg/pandoc-tufteLaTeX2GitBook. |
I've also written some filters for this, in dfaligertwood/utility-scripts. They're not particularly well described, however (e.g. pandoc-musicnotes is actually second level textual annotations using edNotes.sty in LaTeX..) I've used the first character of the footnote text to identify the type. This isn't really a brilliant method though, and my implementation is quite brittle. IMO the ideal method would be have either the footnote id or additional attributes available in the AST for filters. |
I think the best option would be to go ahead with the YAML method suggested by @jkr: #1425 (comment) If this is within the YAML metadata, then this would allow for docx/odt -> markdown -> docx/odt conversion to work, otherwise, it would only be a one-way process. |
FWIW, this would be a great feature, and this proposal seems quite attractive to me:
|
Wow @charlesangus comment jogged my memory! In the years since 2014 I have written two filters in Perl which addressed this issue. The first used the idea of having a character — actually a character in a code span — at the beginning of the note signal the note type: The other filter did part of the same thing but for HTML. It could theoretically place text in spans which could be turned into sidenotes or popups with CSS but my CSS skills weren't really good enough to make it work satisfactorily, at least not in all browsers. In this filter all types of notes had to have an id, which appeared as an actual part of the ids on the HTML elements which the filter created (and I changed the LaTeX filter so that it could either ignore those ids properly or use them properly): basically If there is interest I can clean up and document either or both of these filters (although not until after mid August). The LaTeX filter could be ported to Lua, but the HTML filter probably couldn't since it seems Lua filters don't traverse documents in linear order (@tarleb is this correct?), while the order in which Pandoc::Filter traverses the AST agrees with the order sections appear in the finished document. |
Unfortunately, yes.. One could write a linear order |
@tarleb I forget, do we have an existing issue about this (the order of traversal)? |
We have issue #4456 to track this. Edit: nope, bollocks: that's a completely different issue. I'll look again and create one if necessary. |
As of 2019-07-30 there is no such issue as far as I can see so I'll go ahead and create one. |
I'm not sure whether is this issue dead but I'll add my own suggestion nonetheless. I'd not complicate footnote/endnote syntax anymore and rather introduce something like footnote namespaces, which could be delimited from footnote identifier by semicolon or something, like My current use case for this is following: I'm translating book. In the translated document, there are two sets of footnotes: (1) endnotes from original author (2) notes from translator (me), which I'd like to distinguish in some way. I'd like to preserve numbering of original notes, but my insterted between them change their numbers. However, these notes aren't necessarily distinguished by their position (it does not matter whether they are footnotes or endnotes). |
@bpj -- did you ever rewrite your filters into Lua? Adding more than one note stream would of course still be a very welcome change to the AST, whatever format may be chosen... |
Oh I just saw this is at least on the Roadmap: https://github.com/jgm/pandoc/wiki/Roadmap 👍🏾 |
Just wanted to add my hope that endnotes can be supported. My rationale is here. Many thanks. |
As discussed on the mailing list, it is possible in Word, Open/LibreOffice, LaTeX, and elsewhere to have both footnotes and endnotes in a single document, and publishers (examples from Oxford, Peeters) request that texts be submitted this way for various purposes (e.g. citations plus a glossary; separate textual and source notes in a scholarly edition). The final version might be rendered as footnotes plus endnotes (e.g. a commentary at the end of a text); multiple sets of footnotes or endnotes (often using some sort of differentiated marker system, e.g. letters in addition to numbers or a key to line numbers); or footnotes plus sidenotes.
There have also been requests in the past for sidenotes/margin notes. The consensus on the list seems to be that this could be useful, but isn't as necessary as simply having some ability to have two separate series of notes, especially given that the creation of this in other formats is less clear-cut outside LaTeX (
marginpar
), DocBook (sidebar
; cf. the AsciiDoc implementation), and perhaps HTML (aside
). It can be done only awkwardly in LibreOffice and Word, though I have heard of publishers using Word comments as text to be put in the margin. As another approach, Classical Text Editor allows as many as fifty separate series of notes (plus text to be placed in the inner and outer margins), each of which has separately-controlled rendering. This is surely too extreme for Pandoc (cf. theeledmac
package in LaTeX), but it's an interesting approach.It was suggested by @jkr that it could be structured like this:
This is a summary of the list's proposals for the Markdown syntax, most of which centre around changing the character used for the footnote:
Written as footnotes
[^1]: footnote
and[#1]: endnote
and[>1]: sidenote
[^1]: footnote
and[^^1]: endnote
and[^^^1]: sidenote
[^1]: footnote
and[^a]: endnote
(i.e. if different identifiers are being consistently used)Written as inline notes
^[footnote]
and^^[endnote]
^[^ footnote]
(the extra caret being optional) and^[# endnote]
and^[> sidenote]
and^[| inline note]
The text was updated successfully, but these errors were encountered: