Line Number Link feature should be depreciated

[boltlessengineer]

I feel Line Number Link feature in Norg is bit nonsense considering Norg is a free-form-markup.

• If I link to norg document, it can be easily break because Norg is free-form markup
• If I link to a general code file, the only usecase I can think about linking to specific line of code is in GFM, and GFM supports it with quite intuitive way using tags
• When converted to HTML, it would be basically URL fragment which Norg already supports by other feature (forgot the name of it)

In these reasons, I think line number link feature should be depreciated, or replaced to another feature (maybe link to n^th footnote .)

Line Number Link is easy to parse, but It would be really hard to implement it's feature.

[SevorisDoe]

I disagree.

• links can break, but that goes for any link in the absense of dynamic link maintenance - heading and document links are also brittle under file re-names or edits of the title
• while other plugins are nice, if you can't plug it into the neog syntax, it is a higher-friction extension

For me the ability to link into another file by line number is a neat fallback from more advanced semantically anchord links and actually lets the link system extend beyond just other norg files or generic file-level links. It is not a perfect tool, but it is a tool that exists at all for those cases where i.e. you link from a note to a part within the source code. This was always IMO one of the weaknesses of markdown-based notes: they capsule links away too much between each other and don't allow you to reach into the wider file system. Neorg does, and the capability to specify a line number to open on is a simple extension of that, that has some use.

[boltlessengineer]

I agree that it is useful when linking to source code file.

Maybe we can change the behavior of line number linking to only support source code files.

Norg is a free-form markup language, which means the line number can be easily change when formatting or converting to other formats. Linking to line number would not work well when it is linking to Norg files.

How about following GFM style (path/to/file#L123) and only support line number links for non-norg files? In this way, it is easy to understand that it is only supported for source code files.

Line Number feature itself can exists, but I think we need to remove linking to line number of current(or other) Norg file feature. It will make implementing parser or formatters way harder.

[SevorisDoe]

Could we alias "linking to line number" as „link to paragraph block“ to alleviate some of the issues? With line numbers that target into white spaces between paragraphs snapping to the nearest block, biased downwards?

[boltlessengineer]

That still leaves the main problem: line number can be changed in same Norg document.

i.e.

some
paragraph
with multiple lines

target paragraph

see line {7}

This Norg file should be equal to:

some paragraph

target paragraph

see line {7} %now this should be updated%

To solve this issue without removing the feature itself, all kinds of Norg formatter/converter should re-calculate the line number.

linking to Block should be implemented with something like carryover tags, not via line numbers.

[SevorisDoe]

In that case I might agree with supporting the notion of doing line number-based links only to non-norg files.

[vhyrro]

Norg is a free-form markup language, which means the line number can be easily change when formatting or converting to other formats.

This is the biggest blow to the existing line number implementation. I agree that deprecating such a link might be a good idea. The {/ path:123} syntax is already a thing, so all it takes is eliminating the {123} syntax.

Although I have a counterargument which I just realized now. The existing syntax actually allows for a very useful generalization of line number links. I really dislike the {/ path:123} syntax, mainly because no other link allows for a :123 suffix after itself. There is no syntactical indication that this link type should allow such a suffix. In theory if the {123} syntax were still a thing, we could convert the {/ path:123} syntax into {/ path : 123}. How is it any different? Well:

• The : delimiter is actually norg's scoping delimiter, allowing for things like {* Heading : ** Heading 2}.
• Given that {* Heading : ** Heading 2} can be broken down into two searches, {* Heading}+{** Heading 2}, the {/ path : 123} syntax could be broken down into {/ path} and {123}, searching for line number 123 within {/ path}.

If we really want to deprecate the {123} syntax then we should really find a better alternative to the {/ path:123} syntax too in order to stop random inconsistencies.

[SevorisDoe]

One good option I think that was already outlined is that the first place where the syntax breaks is when line number targets go from a Neorg file to another neorg file. So if we disallow targeting line number links into other norg files, we could solve most to all of the problems that cause this?

That said, this could break again if something like a link target to another file in say ASCIdoc exists and that file gets converted too.

[SevorisDoe]

On second thought what I like about the idea of generalizing the scoping delimiter is that it could also allow things like injecting custom link handlers into tired scope searches? If true, that would make the syntax more general and more powerful extendable.

[vhyrro]

@SevorisDoe this would actually make the syntax very satisfyingly consistent. Currently URIs cannot have an attached path (obviously): {:this:https://is-invalid}. Similarly the {:path:123} syntax could be disallowed, but line links to the current file ({123}) could still be supported. Then a parser that converts these line numbers could create a hidden anchor to that line since it's in the same file.

[vhyrro]

@boltlessengineer what are your thoughts on these compromises?

Summary:

• {:path:123} is disallowed
• Line numbers within the same file are allowed: {123}
• The path + line number syntax is generalized from {/ path:123} to {/ path : 123}. In cases like {* Heading : 10} this means "10 lines from the start of the heading". In the case of the path it's "10 lines from the start of this path (from the start of the file at this path)".

[SevorisDoe]

@SevorisDoe this would actually make the syntax very satisfyingly consistent. Currently URIs cannot have an attached path (obviously): {:this:https://is-invalid}. Similarly the {:path:123} syntax could be disallowed, but line links to the current file ({123}) could still be supported. Then a parser that converts these line numbers could create a hidden anchor to that line since it's in the same file.

Yeah, we can then define tired parsing to either supply a "pasable within scope" by returning some limited-scope object, or it returns an "end of parse" capper that terminates the pipeline and returns the resolution of the link?

The path + line number syntax is generalized from {/ path:123} to {/ path : 123}. In cases like {* Heading : 10} this means "10 lines from the start of the heading". In the case of the path it's "10 lines from the start of this path (from the start of the file at this path)".

we could model this, for the purpose of link resolution, in that searches using headings return virtual file objects of increasingly smaller sizes? THat may break the interpretation of some objects that require scope beyond the virtual view, IDK.

---

exciting thought - if you can do tired searches, doing something like "call the URL, get a document return, then scope within the document" actually becomes possible?

[boltlessengineer]

I agree what you said @vhyrro . Consistency is definitely one of most important parts in Norg syntax.

But still, line number would only works well for / modifier. {* Heading : 10} won't work with same reason why {:path:123} breaks easily.

I'm thinking new # fragment identifier syntax only for / modifier and completely remove the previous line number link syntax. This would work same as URL fragment identifier syntax that github uses (i.e. path/to/file.txt#L10-L12)

So if user wants to link to specific line of file, they can use

{/ path/to/file.txt#L10-L12}

[SevorisDoe]

How does that avoid breaking? The cause of breaking line number links, to my understanding, is that the target can‘t be garuanteed to be stable in that line number under conversion.

[boltlessengineer]

Sorry for the lack of explanation. I meant to add syntax to the / modifier itself to make the line number only work on external files. This is more concise than adding extra exceptions to the existing line number link syntax.

• We can remove existing line number link syntax totally. Both {:file:123}, {123} can easily break.
• But as we still want it explicitly for file locations (the / modifier), we can modify the / modifier syntax itself to have optional line number inside.

[SevorisDoe]

This is an auxillery idea to what started this issue, but what I like about the scope syntax in a larger view is it could be extended with custom target scope parsers such as say, Markdown element targeting commands or other such things. (Maybe external file links could point to function artefacts for a given language?)

I like the idea of a separate syntax to keep users from messing things up, but I would like to synergize it with the above idea to have that extension possibility in the spec.

[boltlessengineer]

Ok, then how about allow existing line number links only at the end of scoping? Because line number between scopes is nonsense. We usually need line number only at the end (e.g. n lines below the preceding scope)

Invalid:

{123}
{:file:123}
{/ path/to/file : 123 : function-artefact-modifier}
{:file:* heading : 123 : ** sub heading}

Valid:

{/ path/to/file : 123}
{/ path/to/file : function-artefact-modifier : 123}
{:file:* heading : ** sub heading : 123}

Now user can have line number inside Norg file... We should at least note that this may break on Norg files. (another LSP feature idea here)

Edit: typo

[SevorisDoe]

The thing is, we cannot garuantee that there isn't a custom scoper function below that that may still resolve a valid target. If we have LSP feedback, we can actually just throw "link spec failed to bind" and print the error report.

Thinking about this bit that @vhyrro said:

Then a parser that converts these line numbers could create a hidden anchor to that line since it's in the same file.