-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA512 Hi folks, This wraps up an examplenimplementation of `Ix' for mdoc(7) by extending `Xr' to handle indices made with `Ix'. In other words, linking to sections in other manpages. Enclosed is the patch. * BACKGROUND `Ix' is a macro proposal that inserts an anchor at an arbitrary location in an mdoc(7) document. There are already two implicit anchors generated with `Sh' and `Ss'; `Ix' allows for the same. As with `Sh' and `Ss', `Ix' anchors can be linked with the `Sx' macro. In effect, this allows doing things like: .Bl -tag -width Ds .It Fl b Ar moo .Ix -b flag This is a flag... ... .El Then later: The .Sx -b flag allows us to... For completeness, I also add an `Lkx' macro that serves to link to sections in the same document by a different name. Thus, The .Lkx "-b flag" "bee flag" allows us to... I actually don't like the `Lkx' and would prefer `Sxx' or something, but bikeshed bikeshed bikeshed. `Ix' is nice because it fits with the existing `Sx' model and can simply be ignored in non-conformant tools like groff(1). Output modes /not/ allowing for linkage, such as -Tascii, can simply discard `Ix' and render the contents of `Sx' as-is. This is the existing behaviour when using `Sx' to link to `Sh' and so on. * INTER-PAGE LINKING The remaining problem is inter-document linkage. This can be easily accomodated by extending `Xr' to accept 1, 2, 3, or 4 arguments: .Xr NAME [SECTION [LINK [LINKNAME]]] So we can have .Xr foo .Xr foo 1 .Xr foo 1 NAME .Xr foo 1 NAME "name section" By default, links to other sections can be formatted as "foo(1) section NAME", but this needs some more consideration because it might not be a section that's linked. * PROBLEMS All of this works beautifully in -Thtml (and can be extended to -Tpdf and friends). The problem is in -Tascii, which as it stands can't support links. (That's beyond the scope of these patches.) While we can get away with `Sx' doing nothing for sections, using `Sx' in console mode to refer to `Ix' tags is confusing because, well, they don't exist. There is, however, a solution. I don't have a patch for this (yet), but am working on it. Essentially, -Tascii knows the exact line and column of its output. When we invoke an `Ix', we remember the output line and column. Then when we use `Sx', we can refer to the line and column of the origin. For example, Hello .Ix world world. ... ... Link to .Sx world . Right now, this produces "Link to world". Why not make it do "Link to world [line 23, column 45]"? This way, we can have arbitrary links in - -Tascii and quickly jump to the locations in the manpager. This doesn't do much for `Xr', unfortunately. Best, Kristaps -----BEGIN PGP SIGNATURE----- Comment: GPGTools - https://gpgtools.org iQIcBAEBCgAGBQJVAP8VAAoJEMT2SUY9XBES7A8QAIbH4nUAzZwf05As7tKiOW+u YV9kHedKZjgYWPX6MgUwGyl+MRwqdVcT+Xx/LPhJtXsnzBGwd+1CsKsAZFTfi7rr dyB3ZupSf3ZF89X+aRn3MpY8A+7XiKUm/seXZFLtB/u7rMRnEP0TVJF1oWF6V5oW fLAQvuq7Aw5HkPj1nscUSQO6pQx/xpYozgZ5R8E3aBSN7DRFj/6U6784C7AlIia8 IKrnvp4WJVYulDgwADxQE0SgxOfeIT+aDDIqGCy3gqfIeH1xsgiXHsB+IJQkgsLT lxnw3blrPnDoEcYaUu0/u+i57z+Q+REbPYgkNENp7lZaHqopovY/lX2nZCmacyOE yMONC9E7vLvnPVikyNfz2V6FXG3hb76m1HBxtPCcTZnn25uzbUI3Ha+N8pyMEL77 6tV+H7G8/ffkoS9UBXODyXETGqjCLG09L24k+iiIKuamEfaQcyHY46p8Nyo+TpH9 LES3RsquRUIdz96yK4kbLH964x8juU6fdCkZ8cR5iPYb+SdUz6RkmBAChlFHYPjB 3W/sEr+aw3AOsghaNwUznSCeNx9Ag492U0nIwPOeeUaWG9k68/Jd7mbcuy8avPLP 7F1O9j+g7mugmhHCcaIkPlsfbgwhtWmbmbPVGAqDgalzccxPA/0UyOsZ3/lGRy/t hgOknxeuWPvk7B4vlC14 =cGAE -----END PGP SIGNATURE-----