Heading References: Looking for the best possible approach

Heading References: Looking for the best possible approach

[name name]

[-- Attachment #1.1: Type: text/plain, Size: 1490 bytes --]

I'm new to Pandoc.

From what I see in the manual, it seems there are only two ways to create 
heading references:

~~~
# Heading {#identifier .class .class key=value key=value}
~~~

~~~
For more information about <...>, see [the previous section](#identifier).

or
For more information about <...>, see [Heading][].
~~~

The drawback of using the 2nd approach is that if you change the heading 
itself, the link will be broken.

And the drawback of using the 1st approach is that you need to write (and 
update, if necessary) the link text manually.

Is it possible to have the best from both approaches without their 
drawbacks? Here is what I search for:

~~~
For more information about <...>, see [][#identifier].

or maybe
For more information about <...>, see [](#identifier).
~~~

These variations don't work, but the idea is that because the link uses 
#identifier and not the heading text itself, it is not "fragile", and at 
the same time, the displayed text is updated automatically, so if you 
change the heading "Heading" to "My Heading", this won't break the link.

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/8b08b876-118d-41cb-9475-e097d069fc1cn%40googlegroups.com.

[-- Attachment #1.2: Type: text/html, Size: 2103 bytes --]

Re: Heading References: Looking for the best possible approach

[BPJ]

[-- Attachment #1: Type: text/plain, Size: 2785 bytes --]

In either case you have to either rely on the heading text remaining
constant or on explicitly providing and referencing an identifier which
remains constant. Regardless of notation there is no other approach
possible. You could use a filter to replace identifiers/fragments you want
to change, but in already published documents that would be a bad idea
since old links would not work anymore.  I've sometimes done this to keep
old links from breaking:

``````markdown
# Heading []{#old-identifier} {#new-identifier}
``````

Not ideal, but it works.

Den tis 16 aug. 2022 14:13name name <ivan20151013-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> skrev:

> I'm new to Pandoc.
>
> From what I see in the manual, it seems there are only two ways to create
> heading references:
>
> ~~~
> # Heading {#identifier .class .class key=value key=value}
> ~~~
>
> ~~~
> For more information about <...>, see [the previous section](#identifier).
>
> or
> For more information about <...>, see [Heading][].
> ~~~
>
> The drawback of using the 2nd approach is that if you change the heading
> itself, the link will be broken.
>
> And the drawback of using the 1st approach is that you need to write (and
> update, if necessary) the link text manually.
>
> Is it possible to have the best from both approaches without their
> drawbacks? Here is what I search for:
>
> ~~~
> For more information about <...>, see [][#identifier].
>
> or maybe
> For more information about <...>, see [](#identifier).
> ~~~
>
> These variations don't work, but the idea is that because the link uses
> #identifier and not the heading text itself, it is not "fragile", and at
> the same time, the displayed text is updated automatically, so if you
> change the heading "Heading" to "My Heading", this won't break the link.
>
> --
> You received this message because you are subscribed to the Google Groups
> "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/pandoc-discuss/8b08b876-118d-41cb-9475-e097d069fc1cn%40googlegroups.com
> <https://groups.google.com/d/msgid/pandoc-discuss/8b08b876-118d-41cb-9475-e097d069fc1cn%40googlegroups.com?utm_medium=email&utm_source=footer>
> .
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CADAJKhB_qHiZEVBVT-s9fA0MniVCzOnqgu%3D5sQkDRvedC23hmw%40mail.gmail.com.

[-- Attachment #2: Type: text/html, Size: 3985 bytes --]

Re: Heading References: Looking for the best possible approach

[Bastien DUMONT]

You can do that using a filter that first collects the information you need about the headers, and then update the link text. Here is such a filter:

``` automatic-link-text.lua
local header_id_to_content = {}

local function get_header_infos(header)
  local id = header.identifier
  if id then
    header_id_to_content[id] = header.content
  end
end

local function update_internal_link_content(link)
  if string.sub(link.target, 1, 1) == '#'
    and #link.content == 0
    and header_id_to_content[string.sub(link.target, 2)]
  then
    link.content = header_id_to_content[string.sub(link.target, 2)]
  end
  return link
end

return {
  { Header = get_header_infos },
  { Link = update_internal_link_content }
}
```

The following command:

```
pandoc -L automatic-link-text.lua <<< '
# My header {#headerid}

See [](#headerid).
'
```

outputs:

```
<h1 id="headerid">My header</h1>
<p>See <a href="#headerid">My header</a>.</p>
```


Le Tuesday 16 August 2022 à 05:12:15AM, name name a écrit :
> I'm new to Pandoc.
> 
> From what I see in the manual, it seems there are only two ways to create
> heading references:
> 
> ~~~
> # Heading {#identifier .class .class key=value key=value}
> ~~~
> 
> ~~~
> For more information about <...>, see [the previous section](#identifier).
> 
> or
> For more information about <...>, see [Heading][].
> ~~~
> 
> The drawback of using the 2nd approach is that if you change the heading
> itself, the link will be broken.
> 
> And the drawback of using the 1st approach is that you need to write (and
> update, if necessary) the link text manually.
> 
> Is it possible to have the best from both approaches without their drawbacks?
> Here is what I search for:
> 
> ~~~
> For more information about <...>, see [][#identifier].
> 
> or maybe
> For more information about <...>, see [](#identifier).
> ~~~
> 
> These variations don't work, but the idea is that because the link uses #
> identifier and not the heading text itself, it is not "fragile", and at the
> same time, the displayed text is updated automatically, so if you change the
> heading "Heading" to "My Heading", this won't break the link.
> 
> --
> You received this message because you are subscribed to the Google Groups
> "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an email
> to [1]pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit [2]https://groups.google.com/d/msgid/
> pandoc-discuss/8b08b876-118d-41cb-9475-e097d069fc1cn%40googlegroups.com.
> 
> References:
> 
> [1] mailto:pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
> [2] https://groups.google.com/d/msgid/pandoc-discuss/8b08b876-118d-41cb-9475-e097d069fc1cn%40googlegroups.com?utm_medium=email&utm_source=footer

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/Yvueqq6Qo2xt3BCG%40localhost.

Re: Heading References: Looking for the best possible approach

[name name]

[-- Attachment #1.1: Type: text/plain, Size: 3988 bytes --]

Thanks BPJ, and thanks  Bastien Dumont, for a working workaround.

What I don't understand, though, is that why such an essential thing 
doesn't work out of the box. The similar syntax (I mean the *idea*, not the 
syntax itself) works, for example, for hyperlinks; and so why it doesn't 
work for headings?

~~~
[hyperlink text][hyperlink label]

[hyperlink label]: http://site.web/page.html
~~~

On Tuesday, August 16, 2022 at 4:42:08 PM UTC+3 Bastien Dumont wrote:

> You can do that using a filter that first collects the information you 
> need about the headers, and then update the link text. Here is such a 
> filter:
>
> ``` automatic-link-text.lua
> local header_id_to_content = {}
>
> local function get_header_infos(header)
> local id = header.identifier
> if id then
> header_id_to_content[id] = header.content
> end
> end
>
> local function update_internal_link_content(link)
> if string.sub(link.target, 1, 1) == '#'
> and #link.content == 0
> and header_id_to_content[string.sub(link.target, 2)]
> then
> link.content = header_id_to_content[string.sub(link.target, 2)]
> end
> return link
> end
>
> return {
> { Header = get_header_infos },
> { Link = update_internal_link_content }
> }
> ```
>
> The following command:
>
> ```
> pandoc -L automatic-link-text.lua <<< '
> # My header {#headerid}
>
> See [](#headerid).
> '
> ```
>
> outputs:
>
> ```
> <h1 id="headerid">My header</h1>
> <p>See <a href="#headerid">My header</a>.</p>
> ```
>
>
> Le Tuesday 16 August 2022 à 05:12:15AM, name name a écrit :
> > I'm new to Pandoc.
> > 
> > From what I see in the manual, it seems there are only two ways to create
> > heading references:
> > 
> > ~~~
> > # Heading {#identifier .class .class key=value key=value}
> > ~~~
> > 
> > ~~~
> > For more information about <...>, see [the previous 
> section](#identifier).
> > 
> > or
> > For more information about <...>, see [Heading][].
> > ~~~
> > 
> > The drawback of using the 2nd approach is that if you change the heading
> > itself, the link will be broken.
> > 
> > And the drawback of using the 1st approach is that you need to write (and
> > update, if necessary) the link text manually.
> > 
> > Is it possible to have the best from both approaches without their 
> drawbacks?
> > Here is what I search for:
> > 
> > ~~~
> > For more information about <...>, see [][#identifier].
> > 
> > or maybe
> > For more information about <...>, see [](#identifier).
> > ~~~
> > 
> > These variations don't work, but the idea is that because the link uses #
> > identifier and not the heading text itself, it is not "fragile", and at 
> the
> > same time, the displayed text is updated automatically, so if you change 
> the
> > heading "Heading" to "My Heading", this won't break the link.
> > 
> > --
> > You received this message because you are subscribed to the Google Groups
> > "pandoc-discuss" group.
> > To unsubscribe from this group and stop receiving emails from it, send 
> an email
> > to [1]pandoc-discus...-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> > To view this discussion on the web visit [2]
> https://groups.google.com/d/msgid/
> > pandoc-discuss/8b08b876-118d-41cb-9475-e097d069fc1cn%40googlegroups.com.
> > 
> > References:
> > 
> > [1] mailto:pandoc-discus...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
> > [2] 
> https://groups.google.com/d/msgid/pandoc-discuss/8b08b876-118d-41cb-9475-e097d069fc1cn%40googlegroups.com?utm_medium=email&utm_source=footer
>
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/9dfb80b3-422c-4e95-9b22-ad5ab378f990n%40googlegroups.com.

[-- Attachment #1.2: Type: text/html, Size: 6077 bytes --]