Re: Linking in mdoc(7)

[Kristaps Dzonsons <kristaps@bsd.lv>]

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

>>> 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.
> 
> My initial reaction is:  It is about time to do something like
> that. However, introducing new macros is not be taken lightly, and
> the design must not be rushed.  Before committing to something
> specific, we should make sure that it is as powerful as possible,
> as extensible as possible, and as simple as possible.  I'm not yet
> convinced the proposed design is the most general and simple one.
> In particular, it isn't obvious to me yet how implicit linking -
> i.e. internal linking that doesn't require any new markup -
> integrates into Kristaps concept, and lack of an idea how terminal
> output can profit is a very serious downside too, give that
> terminal output is by far the most important output mode.
> 
> Then again, we have a tradition of having good designs override bad
> ones soon afterwards (no insult intended :).
> 
>> I have proposed something similar back in September 2014 on
>> groff@
> 
> Exactly what i wanted to say.  :-)
> 
> The thread is here:
> 
> http://lists.gnu.org/archive/html/groff/2014-09/msg00145.html

Ingo, Steffen,

Yes, I'd read through this and subsequent messages, including the
mdocmx(7) package linked here:

https://lists.gnu.org/archive/html/groff/2014-11/msg00281.html

`Ix' is very very very simple: it's just an arbitrary place for `Sx'
to jump to.  The motivation is that we already have the ability to
jump *to* locations, but to date we're restricted to `Ss' and `Sh'.

My implementation of `Ix' simply adds a <a id=""></a> in -Thtml and
does nothing in -Tascii and friends since `Sx' can't "jump" in text
mode.  Steffen had patched less(1) with magic to recognise anchors,
which seems pretty useful.  If this becomes a standard idiom, we'd
need to patch -Tascii to emit the proper magic for `Sh', `Ss', and
`Sx' anyway--adding the `Ix' would be as trivial as it was for -Thtml.

Groff can just ignore the `Ix', as it doesn't do anything with `Sx'
anyway.

The general field of topical indexing, including the mdocmx(7)
concept, is much broader.  `Ix' doesn't try to solve that at all.
`Ix' is just a place for `Sx' to jump to--no more.  However, whether
it's topical indexing or sub-sub-section linkage, an `Ix' macro will
be necessary to define that link destination.  That's all it does.

Best,

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

iQIcBAEBCgAGBQJU/ZFWAAoJEMT2SUY9XBESxdIP/10XNqkAe7oLghOTe9B9HUPU
vmytGhsp7LCtuv7FjAQmIfj4UrrCGex1T9HQWxiEkRL2FZERZ799msJng02JJ7hM
6X/ACYuYbTA+NUb3C04Pcer+XxnLJK63cjxc8Koppw7UmWVPjEmAMA2biQHEnnjm
6RzI8mLlD4rwL5Of4eX2DD814MHaADYykvAqJFRwgJRiTLyWbhUPu/c55Is1dJhu
bXAvCxfEMnvNgKpiB2d0xLJwZ2hwxVcl8Prq+h3oXsgBdoj6Q9/SiXS6nWCYGNs1
i59Ws/fEyjR13HFFq+dZ41xOYr3whiv3FnjTFnCznF+2WXzTqdI10IGTWbVNM0ok
1X+2LbWROiljbaGd30AHfJRDRLtpfBsLkj0ZfH/VchVedXnxzfZz6zvJ5Jpqo5/p
GlM0Ph6/wIWoGEsI8YwtZkfG2hq8rc6B9Zk9L9XACaD+5W0I/NxPCb6rJf11FsGx
eGvS1m6DkZA6ahYdSjn77wazmQddbH0Zr81BzP6g/tsO1FaathZvWFaYjcgJ4JJb
Cwh13VK1qe2lRv3X6o2amcb6Wn69uFJDDycyRqIGzwMk/5i16nIprD7vU2jPf+8y
u35yXa6RzAZwff9iiO4T2zUcGV50wICKyaJJ6zWB33c8f9T413/+mpZx96pCdHjv
DT92GdEafvY8yEjaCq/W
=ZgWU
-----END PGP SIGNATURE-----
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv