Switch to using reference-style links

[flexibeast]

@jeffayle suggested here that we use reference-style links in the Handbook when linking to man pages. i like this idea, particularly as we factor out common information and increasingly link to page fragments: if all man page links can simply have the format [ls(1)], we won't have to worry about users being directed to a fragment which contains a non-linked man page reference.

[ericonr]

I love this idea! Some refactoring would be needed, of course :p

[jeffayle]

My recommendation:

• man pages should always use reference style links
• other links should use a reference if the url is too long to be reflowed in a nice way (eg https://github.com/void-linux/void-docs/blame/master/src/config/graphical-session/xorg.md#L40 ) or if the same url is linked in more than one place.
• man pages should use the form [linkref] whereas other links should use the form [link text][linkref]
• ~it might be worth pointing to the spec which has a lot of examples~ (cf https://github.com/void-linux/void-docs/issues/286#issuecomment-631236269 )

vmdfmt rewrites reference style links as inline links, so that's going to be an issue.

edit: adding this to vmdfmt looks like it could be pretty involved. rather than converting markdown text to markdown text, it looks like vmdfmt converts the input to an abstract data structure, and then converts that back to markdown text. I haven't looked through the code, but that internal format probably doesn't distinguish between inline and reference style links and probably throws out the reference name (because it's based on a markdown parser that was designed to generate html).

[hippi777]

maybe that "spec" link could be included in the docs somewhere around contributing

[flexibeast]

@hippi777: Yeah, it would probably be good to reference it from the style guide.

[flexibeast]

@jeffayle: Oh, so we can't just start using reference links without having to modify vmdfmt first? i'd been assuming vmdfmt could already handle this.

[flexibeast]

Upon further thought, even though i can understand why it might be useful to point to the CommonMark spec as a general guide to Markdown, i'm not sure we should actually do so, since we use Versioned Markdown, not CommonMark - i wouldn't want people to assume that they can use anything described by the latter spec. That said, it could certainly be used as a basis for adding reference-style links to Versioned Markdown.

[jeffayle]

@flexibeast yeah, I assumed vmdfmt would just leave them alone if it hadn't been written to handle it. I might take a look at vmdfmt, but I've never programmed in go before, and don't have a whole lot of experience with parsers

edit: I've looked over the code a bit more. The blackfriday AST produces a link object that doesn't differentiate between inline and reference links (which is why vmdfmt converts reference links to inline), however it looks like we could use the reference object to reconstruct the reference links.

My idea: modify vmd/internal/renderer/renderer.go: func link() to do a reverse reference lookup. If the url has a reference name attached, write the link in reference format (either [x] or [link text][x]. At the end of the document, output the reference table (if it's not empty) in a particular order (if we sort by url then all the man pages will get grouped together). (i guess it should also remove all references that don't have a link pointing to them)

This would have the following effects on the vmd spec:

• links may be written either inline or reference style
• reference table must appear in one piece at the end of the document sorted in a particular order
• if a url appears in a reference table then all links to that url must be in reference style
• no url can be listed in the reference table under more than one name
• every url listed in the reference table must be linked to somewhere in the document

But I guess this issue is blocked for now. I'll file an issue at the vmd repository since this is a pretty major diversion from that spec.