search

lervag / wiki.vim

A wiki plugin for Vim
MIT License
628 stars 66 forks source link

Feature request asciidoc links #122

Closed boydkelly closed 3 years ago

boydkelly commented 3 years ago

Hi, Thanks very much for a great vim plugin. I noticed with great interest the support for asciidoc cross reference links in this format: <<test.adoc#,testlink:>> Those are probably super useful. But I have dozens of exisiting adoc files and course material with external file links like: link:new.adoc[New] Are you able to add this link type? I think it would be a nice + for wiki.vim.

Cheers!

lervag commented 3 years ago

Hi, Thanks very much for a great vim plugin.

Thanks, I'm glad you find it useful!

I noticed with great interest the support for asciidoc cross reference links in this format: <<test.adoc#,testlink:>> Those are probably super useful. But I have dozens of exisiting adoc files and course material with external file links like: link:new.adoc[New] Are you able to add this link type? I think it would be a nice + for wiki.vim.

Perhaps, but it would be useful/necessary with a more clear description. Some examples can be useful as well. Is this link type described somewhere, is it an official syntax?

boydkelly commented 3 years ago

Yes the official docs supply the syntax for linking to a relative document. link:thisotherfile.adoc[This Other File]

(That could also be an .md or .txt etc) https://docs.asciidoctor.org/asciidoc/latest/macros/link-macro/#link-to-a-relative-file

The link syntax you are currently using resembles more the cross reference for asciidocs. (Im not saying to replace that... It seems to work, but Im wondering if it is an older syntax)

https://docs.asciidoctor.org/asciidoc/latest/macros/inter-document-xref/

This could perhaps even be build upon to make some kind of backlink (ie roam) feature.

On Mon, 28 Dec 2020 at 10:25, Karl Yngve Lervåg notifications@github.com wrote:

Hi, Thanks very much for a great vim plugin.

Thanks, I'm glad you find it useful!

I noticed with great interest the support for asciidoc cross reference links in this format: <<test.adoc#,testlink:>> Those are probably super useful. But I have dozens of exisiting adoc files and course material with external file links like: link:new.adoc[New] Are you able to add this link type? I think it would be a nice + for wiki.vim.

Perhaps, but it would be useful/necessary with a more clear description. Some examples can be useful as well. Is this link type described somewhere, is it an official syntax?

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/lervag/wiki.vim/issues/122#issuecomment-751664491, or unsubscribe https://github.com/notifications/unsubscribe-auth/AA2BH3BRXSURE2LTGD7TXOLSXBMKFANCNFSM4VHIMLFA .

-- Boyd Kelly bkelly@coastsystems.net www: http://www.coastsystems.net Tel: +1 604 837-0765

lervag commented 3 years ago

Ah, thanks. The initial support was added as a result of #109. The reference I was pointed to was this:

https://asciidoctor.org/docs/user-manual/#inter-document-cross-references

Your links seem to be to a different version? Or a different documentation?

boydkelly commented 3 years ago

Its actually brand new documentation. It went live last week. So lets assume its current!!

Please note don't remove that cross reference functionality. It could prove to be useful. But please include the standard "link:" syntax to open/create a document on the file system.

Thanks!!!

On Mon, 28 Dec 2020 at 11:09, Karl Yngve Lervåg notifications@github.com wrote:

Ah, thanks. The initial support was added as a result of #109 https://github.com/lervag/wiki.vim/issues/109. The reference I was pointed to was this:

https://asciidoctor.org/docs/user-manual/#inter-document-cross-references

Your links seem to be to a different version? Or a different documentation?

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/lervag/wiki.vim/issues/122#issuecomment-751676491, or unsubscribe https://github.com/notifications/unsubscribe-auth/AA2BH3AVTHYNL3NVQKYSWY3SXBRPNANCNFSM4VHIMLFA .

-- Boyd Kelly bkelly@coastsystems.net www: http://www.coastsystems.net Tel: +1 604 837-0765

lervag commented 3 years ago

Thanks for the info. Before I implement anything I want to understand things more completely.

First, I'm curious: do I understand correctly that the link macro is meant for any type of links, whereas the cross references (xrefs) <<...>> are specifically meant for linking within a document or between asciidoc documents?

It seems it is also possible to use the xref:URL[text] as an alternative to the brackets. Should this be supported as well?

Finally, for xrefs, it seems that for links within the current document, one should not use the # prefix. E.g. xref:link[text] would be a link to the link section in the current document. wiki.vim will currently identify this as a link to the file link.adoc. Do I understand correctly that this is wrong and should be fixed?

If I understand correctly, the required updates are then the following:

I'm pinging @mgoral as they might also have an opinion/thoughts on the matter.

mgoral commented 3 years ago

I think that link:URL[Text] syntax is mostly for linking non-asciidoc documents and xref macro is the correct syntax for inter-linking documents with Asciidoc/Asciidoctor. The linked documentation states:

If you want to link to a non-AsciiDoc file that is relative to the current document, use the link macro in front of the file name.

TIP: To link to a relative AsciiDoc file, use the xref macro instead.

The problem with link macro shows when we try to compile our documents to any other format (HTML, PDF, ...). If we choose to generate, say, HTML from our adoc files, links will still target the original adoc source:

link:foo.adoc[Foo] -> <a href="foo.adoc">Foo</a>
xref:foo.adoc[Foo] -> <a href="foo.html">Foo</a>
<<foo.adoc#,Foo>> -> <a href="foo.html">Foo</a>

Frankly, I don't remember what problems I had with xref: macros. Maybe my old Asciidoctor version didn't support it when I was testing it? :) It seems however more appropriate and easier on eyes than the current syntax. It also resembles the way in which Asciidoc links to other files (e.g. file:foo.pdf[Foo], image:bar.jpg[Bar,width=300px]). Additionally, the "old" syntax (<<..>>) has been replaced in newer docs (new vs old), so maybe this is the way indeed.

However, I'm not sure though if it isn't Asciidoctor's extension to Asciidoc. (See e.g. https://github.com/asciidoctor/asciidoctor/issues/3876#issuecomment-739093620: the tone of that reply suggests that using xref macros is better for inter-linking, but also suggests that it is Asciidoctor-specific extension).

mgoral commented 3 years ago

https://asciidoc.org/chunked/ch21.html has similar tone about <<..>>, xref: and link: macros. Both have their place, but links are for creating hypertext links to arbitrary files on the file system, while xref is for creating internal cross references. I think that the latter is better equivalent for cross linking between wiki pages from markdown and wiki syntax.

So, in my opinion, if we intend to cross-link wiki pages, we should stick to xref syntax (<<..>> and xref:) and if we intend to link to any arbitrary file, link: is the way to go.

lervag commented 3 years ago

Thanks, @mgoral. I think your comments are correct and they align with my proposed actions. I'll add support for the xref: style as an alternative to the <<...>> style, and I'll add support for the link: macro as well. It may be useful to comment in the docs that the link: macro should preferably not be used for inter-linking documents, but instead for "external" links, with a reference to the asciidoc documentation.

Note: The main priority of wiki.vim is of course support for inter-linking documents, but there is also support for external links (e.g. the markdown image link ![]() is supported). A user can specify handlers for various schemes and file types. This explains why I think it makes sense to also include support for link:.

boydkelly commented 3 years ago

@mgoral @lervag Conclusion seems right to me. Just to supplement, if wiki.vim 'creates' a link it should probably be in the simple format. But if there are existing docs incorporated to a wiki, any local links should open if possible. Just wanted to add here too that asciidoc now is on its way to becoming a standard. The specification is now maintained by the Eclipse foundation. Asciidoctor is simply the ruby processor. There is an updated asciidoc.py although I believe it doesnt support newer features. Go is also working on their own processor. Also: Another go. The good news here is there is or will be no 'Git hub flavored asciidoc' or 'Asciidoctor flavored asciidoc'. Ie those links should be ok for everyone.

lervag commented 3 years ago

I've opened a related issue #129 to make it easier for myself, I therefore close this one now.