From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from forward5j.cmail.yandex.net (forward5j.cmail.yandex.net [5.255.227.23]); by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 0cfdd610; for ; Tue, 10 Mar 2015 11:31:11 -0500 (EST) Received: from smtp13.mail.yandex.net (smtp13.mail.yandex.net [95.108.130.68]) by forward5j.cmail.yandex.net (Yandex) with ESMTP id 51A3B1875 for ; Tue, 10 Mar 2015 19:31:04 +0300 (MSK) Received: from smtp13.mail.yandex.net (localhost [127.0.0.1]) by smtp13.mail.yandex.net (Yandex) with ESMTP id 1445DE40308 for ; Tue, 10 Mar 2015 19:31:03 +0300 (MSK) Received: from unknown (unknown [89.204.138.126]) by smtp13.mail.yandex.net (nwsmtp/Yandex) with ESMTPSA id XLq58QPI8e-V2V0K6mX; Tue, 10 Mar 2015 19:31:02 +0300 (using TLSv1.2 with cipher AES256-GCM-SHA384 (256/256 bits)) (Client certificate not present) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yandex.com; s=mail; t=1426005063; bh=YPrI6eZuwvf8kYfOxRBGBPLfM96bArkTYOIcaC7kKaY=; h=Date:From:To:Subject:Message-ID:References:In-Reply-To: Mail-Followup-To:User-Agent:MIME-Version:Content-Type: Content-Transfer-Encoding; b=aVwQUg+9QmDrLTJfJX6/kI45SoMPHfo+Cny0RgJ2OzVtEm5Ui0JchkB4/aXhHC4Cr +91fpt+yLvIl50LoH21y1dzoeV49pMHY2HB7oRX5ycimGLEZqibmUb3ddtioHLtMDA 19E8wniOfhGXvRrN0KfHGzb3AZbBQvuIVnQ79kf8= Authentication-Results: smtp13.mail.yandex.net; dkim=pass header.i=@yandex.com Date: Tue, 10 Mar 2015 17:30:53 +0100 From: Steffen Nurpmeso To: discuss@mdocml.bsd.lv Subject: Re: Linking in mdoc(7) Message-ID: <20150310163053.I3TjLbTZ%sdaoden@yandex.com> References: <54FC74F4.9090200@bsd.lv> <20150309110908.gN5E-QPE%sdaoden@yandex.com> <20150309114648.GA18431@athene.usta.de> <54FD9156.2010201@bsd.lv> <54FDBE04.9030108@bsd.lv> In-Reply-To: <54FDBE04.9030108@bsd.lv> Mail-Followup-To: discuss@mdocml.bsd.lv User-Agent: s-nail v14.7.11-238-ge39f9bb-dirty X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit To the initial message and from the troff(1) / mdoc(7) on tty output side, to the best of my understanding, Kristaps Dzonsons wrote: |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 unfortunately this is not possible, which caused me a lot of pain when coding mdocmx(7) -- you cannot create an anchor "from nothing". I mean surely you can easily do so for mdocml, but for troff(1) tty output through mdoc(7) you must be aware of the recursive and indirect (via "pointer-to-function" calls) approach that mdoc(7) has taken. For example in (and if i recall this correctly) .Bl -tag -width ".It Fn _atexit" .Mx .It Va bla the evaluation order won't work if the .Mx would generate the invisible anchor, because the "Fn _atexit" is lazily evaluated; the only possibility was -- and is. -- a stack that was popped during actual evaluation of .Va. Things are actually worse because you currently can perform the injection only once the macro to be anchored/linked is left, a problem with e.g. long function prototypes that wrap around lines, in which case scrolling back will in the worst case leave you with only the closing semicolon... There is no hope to improve this except by completely rewriting mdoc(7) macros the very same way i have posted to groff@ (instead of dumping data on the fly during recursion implement a new ".doc-output-node TYPE [DATA]" so that a complete, flat structure is available that can be iterated upon and be modified on-the-fly before that structure is dumped. Shall i made it that far anchors/links can be generated at the front for TTY output / anchors/links can be enclosed in device-dependend output (Y, PDF..). | Kristaps Dzonsons wrote: |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'. The .Mx (or call it .Ix if you want to) can surely be extended by more modes, e.g., .Mx -anchor whatever .Mx -link whatever Or there could be a second new command so that mdoc(7) would gain a .Ix / .Lx pair. And even though i think that mdocml will become increasingly popular i want to speak for troff(1) and remain compatibility, and then i mean that on the functional level. Realistically a texi2mdoc(1) subsubsection would become .Pp .Mx -anchor-start whatever .Em subsubsection with nothing that creates anchors or links .Mx -anchor-end .Pp blabla .Mx -link-start whatever more blabla that doesn't create anchors or links .Mx -link-end The problem surely being that something like .Mx -anchor whatever TEXT .Mx -link whatever TEXT will produce no output unless there is compatibility available. Well if it is then having .S[34567] would most likely be the better option. Freely definable anchors and the possibility to link them i would really like to see myself, but to make that possible in troff(1) / mdoc(7) *today* both must enwrap something. I.e., Mr. Bob Beck would say "where is the meat?". We cannot simply attach to some C structure tree node and enwrap it. Maybe (maybe!) .Pp .Mx -anchor Em .Em subsubsection with nothing that creates anchors or links Whereas mdocmx(1) (mdocmx(7) not yet) takes care for duplicates regarding .Ar,.Cm etc. it doesn't yet for .Sh and .Ss. Effectively i think the first one defined will always be matched when creating links via .Sx. They do share a namespace in the end. So all i'm saying is that i'm willing to spend time on mdocmx(7) (or mdocix(7); i didn't use .Ix because someone already uses it; ditto .Lx...). I'd like to see that improved and be in sync across projects. My S-roff(1) will include the pimped mdoc(7), whatever its name will be. I plan to release S-nail v14.8 at the end of March or somewhen after Easter, and work on S-roff for several months rather exclusively. Ciao, --steffen -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv