Link to anchors within pages

[pvb]

Feature request:

Option to link to places within the same page. This would be similar to the option to define bookmarks and link to them in some office packages.

It would require first an interface to mark the bookmark within the page. E.g., pushing a button after which a screen opens requesting the name of the bookmark. After filling in the name and pressing OK a bookmark will be placed (preferably invisible or with a small unique sign only) at the location of the cursor.

Second part is a button on the toolbar which when pushed opens a window with e.g., a pulldown list with all bookmarks on that page. Selecting a bookmark will enter a link to that bookmark at the location of the cursor. Alternatively, it could be a similar screen as the current 'insert link' screen with a auto-complete function in the 'links to' field. The problem with the auto-completion field is that one may not remember the names of the bookmarks

Additional functionality would be the option to link to bookmarks in other pages. Placing the bookmark would be the same, but creating a link to a bookmark would require a screen with two fields (three if you include a field to define a text for the link). One to select the page (should default to the current page) and a second with pulldown list or auto-completion field for the bookmarks in the selected page.

Hope this makes sense. I have no clue how difficult it is to implement, but it would mean a great enhancement of the already very useful software.

[Jaap Karssenberg (jaap.karssenberg)]

Yes, would really like a feature like this. From HTML-jargon this is called an anchor within the page.

Zim links could have a "#" separator, just like HTML links.

First step would not need the a "insert anchor" feature - just start with turning all headings into anchors.

[Jaap Karssenberg (jaap.karssenberg)]

Some discussion on implementation shows that we need the anchors coded in the wiki text as well. So you how this would work is you have a tag in the page like "#anchor1" and you can link to it like "pagename#anchor1". An alternative is to turn all headings into anchors (which I would favor) but the problem is how to deal with changes in the page titles.

A more general problem is how to deal with anchors when pieces of text move to a different page. An "update links" feature similar to the one when pages are moved becomes difficult to implement. One could deal with this by enforcing that anchor tags are unique throughout the notebook.

Although initial implementation could be simple, some further discussion is needed on how to make it full featured.

[Ian Starrie (xcausex)]

I really like this idea of adding anchors to links. I would get a ton of use out of it.

I also like the idea of headings being anchors as well. I don't think that they need to be unique to the notebook, as this would be detrimental if you use fairly standard templates for certain notebooks that use the same headers in multiple pages, though I can definately see a call for them being unique within a given page.

I say make it so if a link includes an anchor and that anchor is missing from the page it links to, it just drops the anchor portion of the link and defaults to the top of the page as if there wasn't an anchor included at all; perhaps have an option to have it do so silently or to give a warning that the anchor is missing.

As a side note, this feature can potential be used to enhance searches, being able to perhaps identify an anchor in the search window and have it look for that anchor in all pages of the notebook and from there, look within only the area following that anchor, but stopping where it encounters the next anchor or the end of page, for the given search query.

This would let you fairly easily organize collections, such as inventories, dictionaries, etc, where you have say a heading for a block of text including the title, another for text with similar items, another with known index values that someone may want to search for, etc. Then come back and more easily search for any one of a variety of specific parameters from specific ares of the text, to avoid a lot of false positives that can arise when you search the full text.

[Ian Starrie (xcausex)]

Another thought, it could be useful to allow the text portion of a link to be set as an anchor as well. This would allow for quick jumps from the main text to a note or reference and then back to the location of the link in the text. This would help avoid the need to have both a link and an anchor at the same spot every time this behaviour is desired.

[Jaap Karssenberg (jaap.karssenberg)]

On Wed, Sep 1, 2010 at 3:23 PM, Ian Starrie <email address hidden> wrote:
> Another thought, it could be useful to allow the text portion of a link
> to be set as an anchor as well. This would allow for quick jumps from
> the main text to a note or reference and then back to the location of
> the link in the text. This would help avoid the need to have both a link
> and an anchor at the same spot every time this behaviour is desired.

You can use the back button to jump back. Zim should remember the last
location in the page. Jumping back by a link is really inconvenient,
as you may have many pages refer to the same reference. Thus you would
need to select the right one from a set of backlinks.

-- Jaap

[Ian Starrie (xcausex)]

> You can use the back button to jump back.

This is true, and a very convienent method, but what happens when you need to go the other way around?

Say you start in your notes, rather than the text, and you want to jump to the point in the text that links to the note. You would be back in the situation of having to have a separate link and anchor in the text, as well in the notes, to allow this bi-directional movement when using the back botton isn't an option or when page back links are numerous and inconvienent.

Being able to add an anchor to the displayed text portion of a link would simplify this, from a work-flow and usability stand point.

[Jaap Karssenberg (jaap.karssenberg)]

On Wed, Sep 1, 2010 at 8:26 PM, Ian Starrie <email address hidden> wrote:
> Say you start in your notes, rather than the text, and you want to jump
> to the point in the text that links to the note. You would be back in
> the situation of having to have a separate link and anchor in the text,
> as well in the notes, to allow this bi-directional movement when using
> the back botton isn't an option or when page back links are numerous and
> inconvienent.

This would probably mean that you want to be able to open the
"backlinks" dialog and not only jump to a page linking here but also
to the link in that page. Very well possible but not directly related
to anchors. Please continue this discussion in a separate bug report
as it is a separate topic.

-- Jaap

[Ian Starrie (xcausex)]

On further consideration of this issue, with regards to how I see myself using it, I think most of my anchors would end up being headings, so the anchor within a link's display text would not be as useful as I was first speculating, and in fact could be detrimental if my earlier comment about offering an option to limit searches to areas following a specified anchor would be possible. I can just link to the associated heading anchor for the section in which the link appears instead.

I see anchors greatest strength in filling the same role they fill in html pages; which is to allow documents to be broken up into logical chunks or related text labeled with a header that can be easily moved to from a link. I would have no troubles with them being limited to headings if it could simplify matters, though at the same time I can see why they would be appealing to use more arbitrarily within the text. Though at that point they may be becoming confused with tags, as far as their purpose goes.

As far as the backlinks thing goes, I am not sure I should be the one making a bug report on that, as I really don't see myself using them much, it would make more sense if someone else with a more vested interest in them state a use case for enhancing that feature in a meaningful manner.

Would the suggested search addition be possible though? Should that be a seperate bug report? If so, would it be appropraite to make a feature request concerning a feature request at this time? I have to say that aside from anchors themselves, that ability to narrow a search down is my biggest concern at the moment, and this seems a perfect way to fullfill that need.

[Jaap Karssenberg (jaap.karssenberg)]

Please send an email to either me or the mailing list for discussions
- try to keep these comments focused on the exact feature / bug in the
description above. After discussion conclusions can land in separate
reports are can be added to this report.

Thanks,

Jaap

On Thu, Sep 2, 2010 at 3:05 PM, Ian Starrie <email address hidden> wrote:
> On further consideration of this issue, with regards to how I see myself
> using it, I think most of my anchors would end up being headings, so the
> anchor within a link's display text would not be as useful as I was
> first speculating, and in fact could be detrimental if my earlier
> comment about offering an option to limit searches to areas following a
> specified anchor would be possible. I can just link to the associated
> heading anchor for the section in which the link appears instead.
>
> I see anchors greatest strength in filling the same role they fill in
> html pages; which is to allow documents to be broken up into logical
> chunks or related text labeled with a header that can be easily moved to
> from a link. I would have no troubles with them being limited to
> headings if it could simplify matters, though at the same time I can see
> why they would be appealing to use more arbitrarily within the text.
> Though at that point they may be becoming confused with tags, as far as
> their purpose goes.
>
> As far as the backlinks thing goes, I am not sure I should be the one
> making a bug report on that, as I really don't see myself using them
> much, it would make more sense if someone else with a more vested
> interest in them state a use case for enhancing that feature in a
> meaningful manner.
>
> Would the suggested search addition be possible though? Should that be a
> seperate bug report? If so, would it be appropraite to make a feature
> request concerning a feature request at this time? I have to say that
> aside from anchors themselves, that ability to narrow a search down is
> my biggest concern at the moment, and this seems a perfect way to
> fullfill that need.
>
> --
> Link to anchors within pages
> https://bugs.launchpad.net/bugs/380844
> You received this bug notification because you are subscribed to Zim.
>

[nomnex (nomnex)]

Hi, I am looking for a simple way to create a link in the same page. I am not found of editing very long pages and I favor sub-level pages. However, linking in the same page comes in handy when, by example, a term in the top of one page refers to a chapter at the bottom.

I am not sure if I will ever need to see all my bookmarks in a bookmark windows; to have all my headers set as anchors; or to use a backlink feature with some bookmarks in a same page?

Having a TOC linking to the main document's headings makes sens in a word processor, but less in Zim. Zim pages structure (F9) is more visual than a traditional TOC. Sub pages--and the links that refer to--are also easier to manage than tenths of bookmarks in an unique page (in my opinion).

[Jiří Janoušek (fenryxo)]

I'm interested in this feature so I could try to implement it. I have summarized the current discussion and included my ideas. Let's create implementation draft.

* Anchors for headings only (may be extended in the future)
* Unique within page.

Syntax:
* Anchor definition: === Heading === #AnchorName
* Link to anchor: Foo:Bar#AnchorName
* Anchor name: same characters as page name (except :) or more strict?

Backend:
* All code operating with links has to be modified to support anchors.
* List of anchors for each page should be cached.

GUI:
* Insert/Edit link dialog should offer anchor names if link contains #
* Heading with anchor should be (optionally) marked. How? Small anchor image or a special character (★)?
* List of anchors of the current page. Located in status bar like back-links menu?

Export:
* HTML: Attribute "id" ("name" is deprecated), encode invalid characters.
* Latex: ?

Issues:
* How to deal with anchors when pieces of text move to a different page? I think this is not a blocker-issue for this feature, therefore initial implementation could just ignore missing anchor.

[Oliver Joos (oliver-joos)]

@Jiri: Great to hear that you will work on this!!

I fully agree with most points of the previous comment. I have an other idea to define anchors: so called "implicit anchors" could simply refer a slice of a heading. E.g. if there is a heading "1. My Nice Introductory Chapter" on MyPage, an valid anchor would be "MyPage#Intro". This works without a separate definition of the anchor, and would still be more robust than referring the full heading text. My idea is meant to supplement yours.

A heading with implicit anchor would not need to be marked somehow, nor should it appear in an anchor list button in the status bar (which is a nice idea for explicit anchors). Relating to your last point "Issues" I would change the foreground color of anchors to red if they are invalid or ambiguous (not unique). Invalid anchors would lead to the top of the page, ambiguous anchors to their first match.

Furthermore the command line interface could make use of anchors: zim <notebook> <page#anchor> would place the cursor to the target of the given anchor.

Open Issues:
* should an anchor match case-insensitive to make it even more robust? Case-sensitivity in titles may change, especially on English pages.

[Jiří Janoušek (fenryxo)]

On Sat, Jun 25, 2011 at 06:51, Oliver Joos <email address hidden> wrote:
> @Jiri: Great to hear that you will work on this!!
>
> I fully agree with most points of the previous comment. I have an other
> idea to define anchors: so called "implicit anchors" could simply refer
> a slice of a heading. E.g. if there is a heading "1. My Nice
> Introductory Chapter" on MyPage, an valid anchor would be
> "MyPage#Intro". This works without a separate definition of the anchor,
> and would still be more robust than referring the full heading text. My
> idea is meant to supplement yours.

Good idea. Let's compare pros and cons:

Explicit anchors:
+ Take precedence over implicit ones.
+ Independent on text of the heading (less likely to became invalid)
+ Can be easily implemented in HTML.
- Have to be defined before used

Implicit anchors
+ No need to define them, therefore quicker to use.
- Dependent on text of the heading (more likely to became invalid)
- Can't be easily implemented in HTML (JavaScript look-up function needed)

> A heading with implicit anchor would not need to be marked somehow, nor
> should it appear in an anchor list button in the status bar (which is a
> nice idea for explicit anchors). Relating to your last point "Issues" I
> would change the foreground color of anchors to red if they are invalid
> or ambiguous (not unique). Invalid anchors would lead to the top of the
> page, ambiguous anchors to their first match.

I agree invalid anchors (not unique) should be marked. But I'm not
sure about marking links to missing anchors, because Zim doesn't even
mark links to missing pages. It should be consistent.

> Furthermore the command line interface could make use of anchors: zim
> <notebook> <page#anchor> would place the cursor to the target of the
> given anchor.

I agree.

> Open Issues:
> * should an anchor match case-insensitive to make it even more robust? Case-sensitivity in titles may change, especially on English pages.

Anchors should be case-insensitive, multiple spaces replaced by one
space. Maybe not to distinguish space, underscore and dash?

[Jaap Karssenberg (jaap.karssenberg)]

2011/6/25 Jiří Janoušek <email address hidden>

> Implicit anchors
> + No need to define them, therefore quicker to use.
> - Dependent on text of the heading (more likely to became invalid)
> - Can't be easily implemented in HTML (JavaScript look-up function needed)
>

I favor implicit anchors over explicit ones - I even doubt if there should
be explicit anchors at all. My guess is that 99% of the time you want to
link to a section, which has an heading, or some other inline object like an
image / table / etc. I would add the pro "more natural to use".

Implementation in HTML is less difficult than it sounds - no javascript
needed I think. When exporting you can set an anchor tag on each heading.
For links you just need to replace the implicit anchor with the explicit
anchor for that heading.

This requires looking up e.g. the full text of that heading - so maybe we
should keep these in the index as well. But if we keep all explicit anchors
in an index table, why not implicit anchors as well ?

Similar it should be possible to update links when an heading changes text.
Another way to deal with this is to assign each heading an unique ID
(preferable unique throughout the notebook) and deal with this as a kind of
hidden explicit anchor. So make it look like the user that you link the
heading directly, but keep the unique ID in the index for this link, so it
keeps the reference even when the text changes. But maybe I'm now making it
more complex than it needs be....

> I agree invalid anchors (not unique) should be marked. But I'm not
> sure about marking links to missing anchors, because Zim doesn't even
> mark links to missing pages. It should be consistent.

Well I would welcome a patch that does similar marking for links to
non-existing pages etc.

-- Jaap

[Oliver Joos (oliver-joos)]

Jiří Janoušek wrote:
> Anchors should be case-insensitive, multiple spaces replaced by
> one space. Maybe not to distinguish space, underscore and dash?

Nice! This is even more robust. And if it goes too far, we could add a checkbox for "Fuzzy anchor matching" in the prefs.

Jaap Karssenberg wrote:
> But if we keep all explicit anchors in an index table, why not implicit anchors as well ?

Do you mean an internal index table of anchor targets? Keeping this always consistent sounds difficult and would not help to find matching headings much faster for average page sizes, does it?

Your hidden IDs nicely solve the problem of implicit anchors getting invalid! But I would prefer Jiřís explicit anchors for that. Then we offer the best of both, and nothing must be hidden (which generally is not good IMHO).

Yes, although html rendering might be different, the rendered html itself should be the same for implicit and explicit anchors. The dynamic searching for headings is not necessary in html once it is rendered (=> no javascript needed).

About marking invalid links (and then anchors): I can search or open a bug report on that (tomorrow...)

[Jaap Karssenberg (jaap.karssenberg)]

On Sun, Jun 26, 2011 at 11:39 PM, Oliver Joos <email address hidden>wrote:

> Jaap Karssenberg wrote:
> > But if we keep all explicit anchors in an index table, why not implicit
> anchors as well ?
>
> Do you mean an internal index table of anchor targets? Keeping this
> always consistent sounds difficult and would not help to find matching
> headings much faster for average page sizes, does it?
>

I mean a table in the sqlite database we use to keep the index. It will
definitely improve lookup time as you don't have to read and parse wiki text
every time you want to know the headings in another page. Maintaining it is
not more difficult than maintaining the tables with links and tags, what we
already do.

Especially when you want to highlight links to non-existing anchors it
becomes important to have such an index table. For example you load a page
that has links to 5 other pages, without the table you now have to read and
parse 5 more pages, in contrast to doing 5 sql queries on a medium size
database, file access is usually slow.

But I leave it to the implementer to determine the performance and check for
bottlenecks. Just trying to think ahead what may become limiting.

-- Jaap

[Oliver Joos (oliver-joos)]

Good point! I only thought of find-in-page being fast even on big pages. But highlighting links to non-existing anchors really could profit much, especially with remote notebook on smb, sftp, davs. I opened a new bug about marking invalid links: bug 802439.

To summarize my view of implicit and explicit anchors:
Like Jiří writes there could be anchor symbols insertable after a heading or anywhere on a page, represented as '#AnchorName' in wiki-syntax. They would be inserted by a menu "Insert anchor" and edited by a context menu "Edit anchor name". Links then may have a postfix '#AnchorName' to lead directly to the named anchor *or* (if non-existing) to the first heading that contains the anchors name. Exporting a html would generate html-anchors, for both cases.

[Jiří Janoušek (fenryxo)]

> Similar it should be possible to update links when an heading changes text.
> Another way to deal with this is to assign each heading an unique ID
> (preferable unique throughout the notebook) and deal with this as a kind of
> hidden explicit anchor. So make it look like the user that you link the
> heading directly, but keep the unique ID in the index for this link, so it
> keeps the reference even when the text changes. But maybe I'm now making it
> more complex than it needs be....

Unique id is a nice solution for implicit anchors. I should be generated from the text of the heading, e.g. "Chapter One: To be or not to be? → #chapter-one-to-be-or-not-to-be-3
1) replace non-word characters with dash
2) strip multiple dashes and trailing/leading dashes
3) lowercase
4) append number to resolve conflicts (if there is any)

The full id will be prefixed by page path to be unique throughout the notebook, therefore we don't get large conflict number for common headings (#introduction-378). The source code will contain page-unique id. However, these identifiers will be used internally, users will get a list of original headings after pressing # in the insert link dialog.

> But I leave it to the implementer to determine the performance and check for
> bottlenecks. Just trying to think ahead what may become limiting.

Anchors and original text of headings definitely have to be indexed to provide good performance. Also backlinks with anchor have to be indexed to be updated when heading changes.

> To summarize my view of implicit and explicit anchors:
> Like Jiří writes there could be anchor symbols insertable after a heading or anywhere on a page, represented as '#AnchorName' in wiki-syntax. They would be inserted by a menu "Insert anchor" and edited by a context menu "Edit anchor name". Links then may have a postfix '#AnchorName' to lead directly to the named anchor *or* (if non-existing) to the first heading that contains the anchors name. Exporting a html would generate html-anchors, for both cases.

The first implementation will allow anchors only for headings, maybe implicit anchors only.

[Oliver Joos (oliver-joos)]

> Unique id is a nice solution for implicit anchors. I should be generated
> from the text of the heading, e.g. "Chapter One: To be or not to be?
> → #chapter-one-to-be-or-not-to-be-3

Nice! Am I right, that your mappings 1...4) will be applied to links too?
So valid links are "Page#Chapter One" or Page#--To__bE--oR__nOt--

I talked with a zim-using friend about anchors. Using # to separate link and anchor is intuitive. But #AnchorName to define an explicit anchor could interfere with sourcecode comments. It might lead to unwanted anchors like #!/bin/bash (at least in non-verbatim text blocks) . Near solutions could be #AnchorName# or [#Anchorname] which would also allow Spaces within anchor names.

Another question (perhaps there is already a solution that I don't know): how do we refer the current page? With anchors it could be worth to have a syntax that does not include the pagename, like "+#chapter-one" or ".#chapter-one" to refer "chapter one" on the same page (ATM my favorite is the +#first).

[Jiří Janoušek (fenryxo)]

>> Unique id is a nice solution for implicit anchors. I should be generated
>> from the text of the heading, e.g. "Chapter One: To be or not to be?
>> → #chapter-one-to-be-or-not-to-be-3
>
> Nice! Am I right, that your mappings 1...4) will be applied to links too?
> So valid links are "Page#Chapter One" or Page#--To__bE--oR__nOt--

Valid link is "Page#chapter-one-to-be-or-not-to-be-3". However, the
Insert link dialog will provide list of headings and create the proper
id automatically when user hits OK.

When user types "Page#" the list of headings "Introduction, Chapter
One, ..." appears. The user selects "Chapter One" and hits OK button.
The source code contains "[[Page#chapter-one|mylink]]" not
"[[Page#Chapter One|mylink]]".

> I talked with a zim-using friend about anchors. Using # to separate link
> and anchor is intuitive. But #AnchorName to define an explicit anchor
> could interfere with sourcecode comments. It might lead to unwanted
> anchors like #!/bin/bash (at least in non-verbatim text blocks) . Near
> solutions could be #AnchorName# or [#Anchorname] which would also allow
> Spaces within anchor names.

Verbatim paragraph should be used for code blocks. Generally, it's the
only way how to avoid interferences.

> Another question (perhaps there is already a solution that I don't
> know): how do we refer the current page? With anchors it could be worth
> to have a syntax that does not include the pagename, like "+#chapter-
> one" or ".#chapter-one" to refer "chapter one" on the same page (ATM my
> favorite is the +#first).

Simply "#chapter-one".

[Oliver Joos (oliver-joos)]

> When user types "Page#" the list of headings appears

Sounds cool. Will it still be possible to write "Page#one" as valid link to heading "Chapter One: To be or not to be" ?

> Simply "#chapter-one"

Nice and short, but confusing. Is it an anchor target or a link within the current page (or a source code comment)?

My view so far:
Links to explicit anchors or headings could look like "Page#chapter-one" or "#chapter-one" both in Zims window and in its txt-files. In the txt-files they can change to [[Page#chapter-one|mylink]]. Explicit anchor definitions are icons in Zims window, and written as "#[AnchorName]" to its txt-files.

Why "#[AnchorName]" to define explicit anchors?
The 3 chars # [ ] are already associated with links and anchors. Marking also the end of an anchor name allows all characters but "]" in a name. And I would prefer a markup that does not depend on multi-line context like verbatim blocks, to be able to use line-based tools like grep or diff.
Variants like [#AnchorName] or #[[AnchorName]] are too similar to a link. And please forget my idea of #AnchorName#, I found plenty of lines with two or more "#" in my Zim.

[Jaap Karssenberg (jaap.karssenberg)]

On Sat, Jul 2, 2011 at 3:01 AM, Oliver Joos <email address hidden>wrote:

> > Simply "#chapter-one"
>
> Nice and short, but confusing. Is it an anchor target or a link within
> the current page (or a source code comment)?
>

My expectation would be that "#name" results in an anchor (similar to
"@name" resulting in a tag) and "[[#name]]" resulting in a link to a anchor
in the current page.

An the other hand you might consider that users probably type links to
anchors more often than the anchors themselves. In that case you might
consider using "{{#name}}" for the anchor itself (syntax more like an
object) and than reserve "#name" for linking to it.

@jiri: you may also want to think about anchors for images and objects -
either implicit or explicit defined in the image/object syntax. My
experience is that internal references to internal objects like images,
tables, formulas etc. will be the most common in technical writing. But this
can wait till I come around to merge your object branch..

[Jiří Janoušek (fenryxo)]

> Sounds cool. Will it still be possible to write "Page#one" as valid link
> to heading "Chapter One: To be or not to be" ?

I afraid it won't be possible.

> Why "#[AnchorName]" to define explicit anchors?
> The 3 chars # [ ] are already associated with links and anchors. Marking also the end of an anchor name allows all characters but "]" in a name. And I would prefer a markup that does not depend on multi-line context like verbatim blocks, to be able to use line-based tools like grep or diff.

Zim syntax is context-sensitive, therefore it's pretty expected that context-insensitive tools (grep) may produce wrong results. The syntax "#anchor_name" should be preferred, because it is more close to syntax of tag definition ("@tag_name" ).

> My expectation would be that "#name" results in an anchor (similar to
> "@name" resulting in a tag) and "[[#name]]" resulting in a link to a anchor
> in the current page.

Exactly.

> An the other hand you might consider that users probably type links to
> anchors more often than the anchors themselves. In that case you might
> consider using "{{#name}}" for the anchor itself (syntax more like an
> object) and than reserve "#name" for linking to it.

I think more common usage will be a link with custom text (e.g The mechanism is described in section [[#under-the-hood|Under the hood]].) than raw link (The mechanism is described in section [[#under-the-hood]]).

> @jiri: you may also want to think about anchors for images and objects -
> either implicit or explicit defined in the image/object syntax. My
> experience is that internal references to internal objects like images,
> tables, formulas etc. will be the most common in technical writing. But this
> can wait till I come around to merge your object branch..

Object will be able to use common backend for anchor management and can store anchor id in the param "anchor".
{{{myobject anchor="anchor-name" foo="bar" ...
data
}}}

[Jaap Karssenberg (jaap.karssenberg)]

2011/7/2 Jiří Janoušek <email address hidden>

> I think more common usage will be a link with custom text (e.g The
> mechanism is described in section [[#under-the-hood|Under the hood]].)
> than raw link (The mechanism is described in section [[#under-the-
> hood]]).
>

Agreed. So it is "[[#name|text]]" or "[[#name]]" for the link and "#name"
for the anchor itself.

-- Jaap

[Oliver Joos (oliver-joos)]

>> Will it still be possible to write "Page#one" as valid link
>> to heading "Chapter One: To be or not to be" ?
> I afraid it won't be possible.

That would be a major drawback, because this is what makes implicit anchors robust and handy!

> I think more common usage will be a link with custom text

I try to omit custom texts for links, because searching for "pad" skips links like [[http://launchpad.net/zim|Zim]]. Perhaps this is a bug of the Search feature?

> Zim syntax is context-sensitive, therefore it's pretty
> expected that context-insensitive tools (grep) may
> produce wrong results.

8-) grep is not "case-insensitive", "grep -i" is.
My point here is that a syntax is clever if it does not force to look back and forth several lines to know if "#chapter" is an anchor or a sourcecode comment (if it's outside or inside a verbatim block). @Jaap: Zims syntax for tags can also be a bit simplistic: @Jaap is not a tag here and @1MHz (common on hardware pages) is not either. Ok, "<SPACE>@" is seldom enough, but "<SPACE>#" is used for various purposes: source comments, colorcodes #F1E2D3, error messages like "inodes count wrong for group #3261", phone service codes #21*, ...

Anyway, I look forward to your anchor feature!

[Jiří Janoušek (fenryxo)]

>> I think more common usage will be a link with custom text
>
> I try to omit custom texts for links, because searching for " pad" skips
> links like [[http://launchpad.net/zim|Zim]]. Perhaps this is a bug of
> the Search feature?

I think it's an usual behavior. Or do you know any application that
seeks through the target addresses of the links?

>> Zim syntax is context-sensitive, therefore it's pretty
>> expected that context-insensitive tools (grep) may
>> produce wrong results.
>
> 8-)  grep is not "case-insensitive", "grep -i" is.

I wrote context-insensitive, not case-insensitive.

> My point here is that a syntax is clever if it does not force to look back and forth several lines to know if "#chapter" is an anchor or a sourcecode comment (if it's outside or inside a verbatim block).

I don't agree. When syntax is context sensitive it doesn't mean it is
stupid or bad designed.

> @Jaap: Zims syntax for tags can also be a bit simplistic: @Jaap is not a tag here and @1MHz (common on hardware pages) is not either. Ok, "<SPACE>@" is seldom enough, but "<SPACE>#" is used for various purposes: source comments, colorcodes #F1E2D3, error messages like "inodes count wrong for group #3261", phone service codes #21*, ...

You're right. We should use different syntax for inline anchors if we
decide to implement them.

[Oliver Joos (oliver-joos)]

> I wrote context-insensitive, not case-insensitive.

Sorry, my fault! You're completely right.

> Or do you know any application that seeks through the target
> addresses of the links?

I just checked Moin (my previous wiki), and it does exactly that. When I have an idea how Zim could do that, I'll open a feature request.

> When syntax is context sensitive it doesn't mean it is stupid or
> bad designed.

No! Just more complex to parse. Wiki syntax is always a compromise between easy to write/read and non-ambiguous.

> You're right. We should use different syntax for inline anchors if
> we decide to implement them.

I re-checked all my texts in Zim and Moin (with grep ;-). Perhaps #anchor# would still be a nice variant, but without white-space or newlines between. This would be easy to write/read, and seems very uncommon in normal texts or even source code. An inline anchor definition would then be:
  [asciichar<=32] '#' [asciichars>32] '#' [asciichar<=32]
(I know, Zim is utf8 - with ascii it's just simpler here)

[Jaap Karssenberg (jaap.karssenberg)]

On Sat, Jul 2, 2011 at 4:24 PM, Oliver Joos <email address hidden>wrote:

> I re-checked all my texts in Zim and Moin (with grep ;-). Perhaps #anchor#
> would still be a nice variant, but without white-space or newlines between.
> This would be easy to write/read, and seems very uncommon in normal texts or
> even source code. An inline anchor definition would then be:
> [asciichar<=32] '#' [asciichars>32] '#' [asciichar<=32]
> (I know, Zim is utf8 - with ascii it's just simpler here)
>

I would prefer something along the lines of "{{#name}}" if you feel "#name"
gives to much conflicts. Think of anchors as a kind of empty object. (Plus
we may need "##" markup for other features later on.)

Btw. even if wiki text is "{{#name}}" we could still make the pageview
automatically turn "#name" into an anchor when typed (user can hit ^Z if
they intended something else).

-- Jaap

[Jiří Janoušek (fenryxo)]

A few notes about current progress:

Source file
 * Implicit anchors are not saved in the source file, they are generated from their labels when page is parsed.

Indexing
 * Anchor id and label are indexed to provide autocompletion in Insert Link dialog.

Parsetree
 * Elements with anchors (only headings for now) have "anchor" attribute.

TextBuffer
 * Tags with anchors (only headings for now) have "anchor" attribute.
 * Editing of page can cause inconsistencies in anchors, anchors become dirty (TextBuffer.anchors_dirty = True).
 * TextBuffer.cleanup_anchors() finds and repairs dirty anchors.
 * Dirty anchors don't affect editing except autocompletion of local anchors ("#anchor"), therefore anchors have to be cleaned up when Insert Link dialog is opened.
 * Dirty anchors have to be cleaned up before page is saved and reindexed.

Modified anchors
 * Links to local anchors (within the current page) are repaired in TextBuffer.cleanup_anchors()
 * TextBuffer.cleanup_anchors() emits "anchors-modified" signal and stores changes in a dict self.modified_anchors (old_id => new_id)

TODO:
 * Support for image links to anchors
 * Index links to anchors
 * Repair links to anchors outside the current page
 * Detect anchor moved to another page
 * Show anchor type (heading, object, ...) in anchor selector

[Jaap Karssenberg (jaap.karssenberg)]

Nice work!

Two quick note:
1/ I'm refactoring the parser (see the "next" branch on launchpad) - I'll
take care of supporting anchors there when merging these branches
2/ I see you put notes in HACKING/Ideas -- I killed that parts of the notes
as most of it was quite stale - can you move it to HACKING/Anchors
directly (this is something I will forget about when merging I'm afraid)

-- Jaap

[Matthew Hoener (ionsquare)]

Has there been any movement on this in the past year?

[Jiří Janoušek (fenryxo)]

No and I'm afraid I won't finish my work on this feature in the near future.

[Hector Z (m8r-15x1tp)]

I've been using zim for many years and love that it is simple and doesn't have excessive features, so I don't waste time with endless tweaking. That said, there are a few features that I started feeling would be very desirable to have.

Anchors in the page, as html has with "#", is one of them.

[hvf (hvonfintel)]

Any progress on this? Or has it died?

I would love to have anchors/links in same page. (html "#")

[[e-mail] (neozvuck)]

No progress, it was finished about a year ago and then new zim came with
different parsers. Since than I haven't touch it.

On Thu, Apr 2, 2015, 16:01 hvf <email address hidden> wrote:

> Any progress on this? Or has it died?
>
> I would love to have anchors/links in same page. (html "#")
>
> --
> You received this bug notification because you are subscribed to the bug
> report.
> https://bugs.launchpad.net/bugs/380844
>
> Title:
> Link to anchors within pages
>
> Status in Zim desktop wiki:
> Confirmed
>
> Bug description:
> Feature request:
>
> Option to link to places within the same page. This would be similar
> to the option to define bookmarks and link to them in some office
> packages.
>
> It would require first an interface to mark the bookmark within the
> page. E.g., pushing a button after which a screen opens requesting the
> name of the bookmark. After filling in the name and pressing OK a
> bookmark will be placed (preferably invisible or with a small unique
> sign only) at the location of the cursor.
>
> Second part is a button on the toolbar which when pushed opens a
> window with e.g., a pulldown list with all bookmarks on that page.
> Selecting a bookmark will enter a link to that bookmark at the
> location of the cursor. Alternatively, it could be a similar screen as
> the current 'insert link' screen with a auto-complete function in the
> 'links to' field. The problem with the auto-completion field is that
> one may not remember the names of the bookmarks
>
> Additional functionality would be the option to link to bookmarks in
> other pages. Placing the bookmark would be the same, but creating a
> link to a bookmark would require a screen with two fields (three if
> you include a field to define a text for the link). One to select the
> page (should default to the current page) and a second with pulldown
> list or auto-completion field for the bookmarks in the selected page.
>
> Hope this makes sense. I have no clue how difficult it is to
> implement, but it would mean a great enhancement of the already very
> useful software.
>
> To manage notifications about this bug go to:
> https://bugs.launchpad.net/zim/+bug/380844/+subscriptions
>

[sojusnik (sojusnik)]

That's a pity, since anchoring is a must-have for a wiki.

[Ari (ari-reads)]

I concur. Using zim daily now with big pages and in-page linking is sorely needed

[Jaap Karssenberg (jaap.karssenberg)]

Sorry for the slow progress. All I can say is that it is still on my list
and I will not make zim "1.0" without anchors.

-- Jaap

On Fri, Apr 10, 2015 at 11:53 PM, Ari <email address hidden> wrote:

> I concur. Using zim daily now with big pages and in-page linking is
> sorely needed
>
> --
> You received this bug notification because you are subscribed to Zim.
> https://bugs.launchpad.net/bugs/380844
>
> Title:
> Link to anchors within pages
>
> To manage notifications about this bug go to:
> https://bugs.launchpad.net/zim/+bug/380844/+subscriptions
>

[Jaap Karssenberg (jaap.karssenberg)]

See https://github.com/jaap-karssenberg/zim-wiki/wiki/Blueprint-anchors

[Ben Dobson (billben74)]

I concur with the above sentiments. This has stopped my brief show with what seems like a great idea and easy to use and install software.
Without internal links I think I'm abandoning ship....

[kklepper (gmcgmx)]

Sorry to see this. I program all day and if I need a feature like this I just do it. That said, I'm sorry to not having time and energy to jump onto this bandwagon.

I'd like to see automatic anchor creation for headings like in Wikipedia. That would suffice.

It is not vital for me, I just thought it should be taken for granted to have such a feature. Linking between pages without it just doesn't make that much sense.

[Jaap Karssenberg (jaap.karssenberg)]

Nothing is to be taken for granted until someone puts in the effort to
create it - I myself never really missed the feature - else it would be in
already.

On Tue, Jul 7, 2020 at 7:15 PM kklepper <email address hidden> wrote:

> Sorry to see this. I program all day and if I need a feature like this I
> just do it. That said, I'm sorry to not having time and energy to jump
> onto this bandwagon.
>
> I'd like to see automatic anchor creation for headings like in
> Wikipedia. That would suffice.
>
> It is not vital for me, I just thought it should be taken for granted to
> have such a feature. Linking between pages without it just doesn't make
> that much sense.
>
> --
> You received this bug notification because you are subscribed to Zim.
> https://bugs.launchpad.net/bugs/380844
>
> Title:
> Link to anchors within pages
>
> To manage notifications about this bug go to:
> https://bugs.launchpad.net/zim/+bug/380844/+subscriptions
>