Yes, that’s what I was thinking but it looks like Codeberg/ForgeJo formats them as literal footnotes instead of general interdocument links. That’s not really what I had in mind. My goal is that the reference “links” are actually links to the entry in the reference section.
However, I’ve learned that an interdocument link can be created with some MarkDown/Codeberg magic. The link is formatted as [MyRef](#myref) and the target in the references sections would need a <a name='user-content-myref'>[MyRef]</a>. I’ll submit an example.
heh, I’ve had a lot of trouble with divergent markdown link-styles at my dayjob running an Improvement Process as primary editor. adding markdown styleguide is in fact on my to-do list for today, ironically enough!
If you want markdown references to be clustered at the end of a doc as end-notes, which display well:
in codeberg,
rendered by a static-site-generator like jekyll or 11ty, AND
in VSC or vim when people view them as fixed-width text files,
my recommendation would be not to do too much html-specific #-linking (this only works in 1 and 2, and adds a lot of cruft to 3). instead, simply use the markdown pointer system, which can create spaghetti code unless you use it as follows:
example lorem ipsum text [with Complex Tag here][simple-tag] continues like this
...
## References
- [optional additional Complex Tag also pointing to][simple-tag]
[simple-tag]: https://example.com/stuff
EOF
hey thanks for letting me get one thing off my to-do list for today!
I’m realizing this might not cover the “textual endnote” case where you want to put a sentence at the bottom, but I can’t think of a way to do that in standard markdown that renders without gremlins in all three? Apologies if I missed the point talking about links when you actually wanted real endnotes like in a word document.
I like the distinction between opinion-venting and actual consensus-forming. The latter prefers single venues, I agree. Which begs the question of how to let people vent their opinions in many but designate one venue central to consensus at any given time. SH sounds like a good default to set for that, given it’s featureset and that it’s more welcoming to the non-developer stakeholders.
Maybe we simplify the question thusly:
Can discussionsTo be a YAML array, or only a single HTTPS URI? That’s how we do it at my dayjob, and I recommend it in case issues get forked by git management or forum management of the kind SH has.
Is discussionsTo where the FEP author(s) is encouraging discussion, or an array of all the places where significant discussion took place for future archival purposes?
If the latter, it’s a lot of work for the editors. If the former, we risk losing additional significant convos that happen in places the original author(s) didn’t intend, because a third party, say, opened a SH thread or a CG mailing list thread. Compromise solution: maybe third parties can PR additional links into that PR at the last minutes if that happens, at the discretion of (but not being the obligation of) editors and authors?
Ah, that’s interesting. I wasn’t aware of that technique. However, it doesn’t seem to create a link from the reference to the References list item, right? It just links directly to the external document (and uses a shared link for body text and reference section). That’s also a reasonable approach versus using internal links. My main issue was that when I see something like [SFRI] in the formatted text, I’d like to be able to click on it to view the referenced material (or take me to the References list, with the link and description). Currently, it’s just static text.
heh, i know what the meta FEP says now, my question is, does it ONLY point to a git issue, or could it point to an array of git issues, socialhub URLs, etc etc?
hmm I think they might be two separate question: how you format links (my example showed how two different links can share a common referent, and all links on a page can have their referents listed at the end for easy updating if one breaks) is different from internal nav. for internal nav, I’ve usually just done
But depending how the markdown gets rendered, it may not work in all HTML-ified browser contexts. At least it’s not too ugly/distracting/confusing for the vim audiences?
Yes, I think so. I was originally trying to link from a meta-reference ([SOME_REF]) to the associated list item in the References section. The approach you suggested is an alternative and I’d guess one would usually want to go to the external resource anyway. The alternative of linking to the References section heading would be better than no link at all. So, it seems there are currently four options:
No meta-reference link (status quo)
Link to reference list item
Link both meta-reference and References list item to external resource (common referent)
Link meta-reference to References section heading
I think option 2 captures the intent of the meta references (the reader should look them up in the References section, if interested), but any of the linked options are better than option 1 IMO.
I think the original idea was for the tracking issue to be the place where all kinds of links are (literally) tracked. So the FEP itself only needs one link to that issue.
For multiple link references in Markdown, you can also use the following syntax which is even simpler:
This refers to [RFC1234][] and this also refers to [RFC1234][]...
## References
**[[RFC1234]]**: Tunneling IPX Traffic through IP Networks (D. Provan, 1991)
[RFC1234]: https://www.rfc-editor.org/rfc/rfc1234
Note the empty line between the visible reference and the actual link definition.
It’s important to have a link to a tracking issue, because this is where links to discussions and PRs are collected, and status changes are recorded. I think we should rename the field.
Right-- [a][] and [a][a] are identical, but the annoying part of relying on empty []s is that…
...links to [a][] are case sensitive. [A][] points somewhere different. That is why using [a][a] and [A][a], though ugly and bad in a lot of ways, is safer, if the name of the link contains letters that might be cased differently in usage :D
Heh, thanks for making this more explicit, my head was swimming a bit. I agree that any of the three would be fine, if put into the styleguide and made the norm. stackranked by my personal and not-very-important preference, I’d say:
#3 has been the [underspecified, applied in editorial] styleguideat my dayjob, and I quite like it because if, SDO-style, you want every reference to XX externally-specified thing to be linked throughout the text, you can link it in one place and not have to be pasting long URLs in all over the place-- also, more intuitive readability when read as a bare text file in vsc/vim/etc.
#4 is more handy if you want each reference to take the reader first to a summary and/or commentary on said external referent, and only take the reader outside the doc if the reader clicks again. This can break down a bit in docs with tons of references, but that’s a corner case unlikely for FEPs.
#2 is more like the functionality of links in IETF RFCs and other SDOs, but more laborious/manual here and also kind of garbles the text file if read in vsc/vim/etc.
This tells how to calculate a slug from the initial title, but doesn’t discuss title changes. I can see arguments both ways. I’m guessing the reason for changing the slug is concern about the possibility of re-using changed titles in another FEP (?). However, there are also good reasons for FEP identifiers to be stable.
I’d expect a title change in a FINAL state to be unusual, but it doesn’t seem like it would typically lead to adjustments to implementations.
We got this chat discussion starting with the issue on categorization of FEP’s and then moving on to the ID’s. The mentioned reason to have them is to alleviate the editors of maintaining unique ID’s. But these generated ones are very unintuitive, not easily remembered, and causing rigidity to change title to something better isn’t good either.
I brought up the XMPP FEP as an example of a way more intuitve organization, with more metadata and formal procedures that are proven in practice.
We started the FEP as something lightweight without much expectations on what it would grow into. Right now we may be at an inflection point. The FEP is gaining authority and more people refer to it. Should the Fediverse go mainstream and things go fast, the FEP should be able to keep up. The FEP process isn’t ready for that rn.
The question is if we should keep on maturing our own version bit by bit, bug by bug. Or that we might rather take stock and consider if we shouldn’t take on the best-practices similar processes have learnt in one overhaul of the process. So that the FEP can scale and carry the weight.
