Re: Linking in mdoc(7)

[Kristaps Dzonsons <kristaps@bsd.lv>]

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

Replying to myself with an example...

Here's an example of `Ix' and `Lkx' at work:

http://kristaps.bsd.lv/gsl-test.7.html

It's a rendering of the following:

% texi2mdoc ~/src/gsl-1.16/doc/gsl-ref.texi | \
  mandoc -Thtml >gsl-test.7.html

In this you can see the menu items (`Lkx') pointing to arbitrary nodes
(`Ix': chapters, sections, subsections, etc.).  I use `Lkx' instead of
`Sx' because I give the nodes a unique namespace to separate them from
the `Sh' heading, which may share the same name.

For example, the (x)_n symbol is as follows:

http://kristaps.bsd.lv/gsl-test.7.html#index-NodePochhammer_Symbol

This is a sub-sub-sub-section.  Earlier, I was trying to do this with
`Sx', but it would only nest to `Ss' while texinfo goes much deeper.
Moreover, the menu item name is sometimes different from the node
identifier, which wouldn't work with `Sx'.

Something that you don't see in this manual which would be (and now
is) possible is topical indexing.  I would basically build up a set of
`Ix' entries for each index entry (e.g., @cindex), with a unique
namespace prefix, e.g., the concept index for "foo bar" would be
"CPIndexfoo bar" or something.  When Texinfo asks that I print the
concept index list, I simply sort the entries and output a list of
`Lkx' entries to the respective locations in the page, e.g., `Lkx
"CPIndexfoobar" "foo bar"'.  These will jump back smartly to the indices.

P.S., be gentle on the GSL page.  It's one of the heavier users of
texinfo semantics, so there are still glitches, e.g., the function
declarations are un-pretty.
-----BEGIN PGP SIGNATURE-----
Comment: GPGTools - https://gpgtools.org

iQIcBAEBCgAGBQJU/b4EAAoJEMT2SUY9XBESeOEP/0BTo/De+p13B4kpjGLI4PG+
n8ulB0qlvAvbdFDKUFcPEt1yKU8jCLorKS7R9X0rTHlBfdEDMZ+P+Krp15SHea0n
NgbI+nvje4x6r0RRmswwM3pqajiPsNWSMTOQ24TNVMwmNHgIqtuYkSZWIfleGnws
bmeN/32qlM22YjTld7qO2B893gPd/rXv9LrGlqFezJ14co6nmeVRJxsV0dtP5pBY
xPC8PKw6E+LZhYpykhMN7fPoSDbjA+OPj0mrUugUZVDzPJYNG0s1GEFqQniATqRU
Dtnw7MSoz4gqi5LvJNe5I3JNskKCKMm8FOwHySRV+CYLQ+WjfytTptF0w5DnRKSw
d5JKhxM4+eCxAOKKxrFQcXNdkHLBrMg+ZMdlSTbzqAPzmqh+bnt1DYqhjNezAqva
ne1PqdlV70I4E8kScX/EG3otbaKFZH4fxjkyoi3l6GdxnX+0CN2rk0FBlJT4Hxzz
wHery7gqsPY6yww/X1E0ba8hEfcUVQA/1YW2VzwNeG1EyTLmwJi6j0GIPjsO1NTl
1UzviYALFCmndhoQcJWLqDsFz5hBbCSgm7slyVRLAMUZIpYboZMqXXpt8H9d+qLc
TTtv2kJCCrqgXNt3gh6xJuo5yo/0Gbsapkg41/O5ZOPa+PnrL7dm+g+gMTqjduOR
iQIeqzolgQOjXtGoDoiX
=NAB2
-----END PGP SIGNATURE-----
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv