[Doc-SIG] Scoping for implicit link targets? (was Re: Query)

[David Goodger]

I repeat the original message in its entirety for the benefit of the Doc-SI=
G
members. How about joining us, R=E9mi?

Bertholet R=E9mi wrote:
> Hello,
>=20
> I have a question.
>=20
> If I write the follow text :
>=20
>    Title 1
>    =3D=3D=3D=3D=3D=3D=3D
>=20
>    Introduction
>    ------------
>=20
>    Title 2
>    =3D=3D=3D=3D=3D=3D=3D
>=20
>    Introduction
>    ------------
>=20
> In this case I have an error "Duplicate implicit link name: "introduction=
" "

Actually, it's just a level-0 ("Information") system warning, which is not
intended to be reported, except under some kind of "strict" mode. Level-0
warnings are intended to be removed from the final output. Unless you
explicitly ask to see them, they won't bother you.

> The title "introduction" appear twice but under title. Why the link name =
is
> not composed with all level of sections names. Example "title1_introducti=
on"
> and "title2_introduction", in this case the name will not be duplicated ?=
.
>=20
> Small proposal:
> By default, the links names definitions are only composed by the title na=
me
> (or under title name) (compatibility with existing text), in this case yo=
ur
> tools search the right link name. If the tools detect an ambiguity for a
> link, only in this case, the user must add the root title in his link.

When the idea of "implicit link targets" came up, I considered some kind of
scoping scheme like this, but decided it was too complex and error-prone.
Most of the time, a title's implicit link will not be referenced, especiall=
y
not for repeating titles like this. When an implicit link name duplicates
another link name (implicit or explicit), all duplicate implicit link names
are disabled. If you *do* reference a disabled link name (example: ``See th=
e
Introduction_``), there will be no target, and this will generate a stronge=
r
(probably level-2 or "error") warning, which *will* show up in the output o=
r
in the processing. The level-2 warning will be generated by a later stage o=
f
the DPS processing, after the parser is finished its work.

If you need a hyperlink reference in such a case, you must declare the link
target explicitly, with something like ``.. Title 2 Introduction:`` before
the title you want to reference, and ``See the `Title 2 Introduction`_`` fo=
r
the reference.

I think requiring explicit targets is a small price to pay, compared to the
complexity of the alternative.

> Best regard
>=20
> R=E9mi BERTHOLET ;-)

Je vous remercie encore pour votre contribution.
(Although I am a native of Montreal, my French is very rusty so that's all
I'm going to attempt! ;-)

--=20
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net