-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Hi folks,

Summary: mdoc(7) has linking, but it's very restrictive.  You can link
to `Sh' and `Ss' macros by using the `Sx' macro.  I propose adding
another macro, `Ix', that creates an invisible anchor that `Sx' can
jump to.  Thus, `Sh' and `Ss' work as they always did and `Sx' works
as it always did, but we can also jump to arbitrary locations from
`Sx' as defined with `Ix', which is otherwise silent.  Obviously, this
is only useful in -Thtml.  On the console, nothing happens at all.  I
also propose an `Lkx', which is like `Lk' but for inter-page links.
This is when the argument to `Sx' should be different from the index name.

I've put together a patch that does this.  Enclosed.  Obviously, this
only works in -Thtml mode; otherwise, it's ignored.

The story is that  texi2mdoc(1) is coming along nicely but I hate hate
hate throwing away all the linkage.  docbook2mdoc(1) has the same
issue.  Both of these formats encourage lots of linking.  Texinfo, for
example, allows you to create index entries along the way, then
generate indices later that jump back to these areas.  It's handy if
you've ever used larger manuals.  Moreover, there's also lots of menu
generation that jumps forward to chapters (sections), sections
(subsections), and so forth.  I can do the first two, but I lose
anything under a section.  Sad face.

I started implementing indices in mdoc(7) by remembering the section
in which the index was invoked and jumping to it, but most larger
manuals have not just sections and subsections, but subsubsections,
etc.  Moreover, the menus are all but useless, as they all point to
the same thing.  By having just one extra macro, `Ix', we can get all
of that indexing goodness.  By having `Lkx' as well, we can fully
generalise jumping to those indices.

While here, I also updated the ID-generation function to be clearer.
Now instead of linking to "foo.htm#x1234124312341" or whatever, it's a
much clearer "foo.html#index-NAME" or whatnot.  Basically, "index-"
followed by the link identifier, with spaces made to underscores and
otherwise non-alnums replaced by a two-digit hex code.

Thoughts?

Best,

Kristaps
-----BEGIN PGP SIGNATURE-----
Comment: GPGTools - https://gpgtools.org

iQIcBAEBCgAGBQJU/HT0AAoJEMT2SUY9XBESgU4QAL038BszrWMlN1HWTi4DX3gC
IdxXWCLZUR9LZfcCsFC6er3xzJojB3nJhaZydPjdTlX8QZLzlbdG3Xx2B8fgklwl
1Yw0zGef+a2GQ46oZm3+Sva7ZYIOIiBYhQBjcLlhp5leokCQKRIXCGqnoFgq6Agf
Q0o8qMEL7R6YF/ACytQP9XNVlxfd5XighbMfjs4BbbEKtJY8Hos192i7mojCtDXT
6r0BhigARbfgktHiVfSfjLlMHsAjmc6Vf0LIk55pk1zRHKeXUzunRSoAuwKUxLnl
b6QMDMpb67VsKCCUhXahBWeHrZuRUfNSkXGo020fKVnzIKCaRzZkONUdjAIP5iDj
ImISWoLjX9EqCj2UOOEaO51iRIhP7fqWwEM7yBK9KHb0LhOGly3WdLBQjSN9l8ia
8bW5jr7MvFp5gryx2NV/QOajDXKB9I0G/vHwyZdZkaJEagB8yc9Z8JxbOFxo8LVP
FYiSmb2krVok4106QXhQZT0rCOM9a99OyNc2w7lNo5gzzIk0J+3li314pCtboe+M
znpWM8TX560yqc5rBr8dyfLfzVJKbDlFCAI1ICGCC2T3tGIzE/02S8qYpQyofdOx
HrcxTDD05cMK3zlnWjjyyOPl/aYk6kdOmgDwvHwL99e6OGssWdPwOHTgeMS5XKFN
P5swW6zPpVinfRYOj71c
=VCLw
-----END PGP SIGNATURE-----