From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from forward1h.cmail.yandex.net (forward1h.cmail.yandex.net [87.250.230.16]); by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id a4189904; for ; Thu, 30 Apr 2015 12:32:02 -0500 (EST) Received: from smtp3h.mail.yandex.net (smtp3h.mail.yandex.net [84.201.186.20]) by forward1h.cmail.yandex.net (Yandex) with ESMTP id 114DB1307 for ; Thu, 30 Apr 2015 20:32:00 +0300 (MSK) Received: from smtp3h.mail.yandex.net (localhost [127.0.0.1]) by smtp3h.mail.yandex.net (Yandex) with ESMTP id D72A01B4909E for ; Thu, 30 Apr 2015 20:32:00 +0300 (MSK) Received: from unknown (unknown [89.204.153.85]) by smtp3h.mail.yandex.net (nwsmtp/Yandex) with ESMTPSA id gfdnZFLROz-VxYe0Li1; Thu, 30 Apr 2015 20:31:59 +0300 (using TLSv1.2 with cipher AES128-GCM-SHA256 (128/128 bits)) (Client certificate not present) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yandex.com; s=mail; t=1430415120; bh=5m3sbOyJNvW0ZZqVGLN0QFChqQz/tz3HUfIK5cR5cR8=; h=Date:From:To:Subject:Message-ID:References:In-Reply-To: Mail-Followup-To:User-Agent:MIME-Version:Content-Type; b=AUvwFuLoD/jhS53czDa5Xh1OhX0ouTG3EZKLySm3v5xJ5ULRI6dQwk7uAkC6HvlRj 6mGVOthZgWNHO+Z1/luVxNiaPL16e/+42jlkbtp+hKXbl3FUWkquQFD5nduiVasxes xqmiI49GRovEvQ7ElYKd3MuBpr3wPitzcchKOmUA= Authentication-Results: smtp3h.mail.yandex.net; dkim=pass header.i=@yandex.com Date: Thu, 30 Apr 2015 19:31:58 +0200 From: Steffen Nurpmeso To: discuss@mdocml.bsd.lv Subject: Re: Redux: linking in mdoc(7)? Message-ID: <20150430173158.5wxc3dP2UnA=%sdaoden@yandex.com> References: <55424D7F.1010309@bsd.lv> In-Reply-To: <55424D7F.1010309@bsd.lv> Mail-Followup-To: discuss@mdocml.bsd.lv User-Agent: s-nail v14.7.11-414-g41649a5 X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Kristaps Dzonsons wrote: |I saw on groff another post about indexing, so I thought to bring this |up again. I'm wary of mdocmx because it's unreadably huge. Manpages Oh no, it really isn't. 23139 bytes for all that functionality, including (joking, maybe) HTML and PDF support? |should be simple. And simple it is. What do you mean by "wary", "huge" and "not simple"? These ~23000 bytes include a lot of comments, and of the rest a lot of circumvent missing groff(1) datatypes and groff(1) bugs. What can these poor troff(1) macros do otherwise, without a hashmap / tree and faced with those bugs. In fact i'm happy that it works -- and it *works*. Try to break the less(1) or grotty(1) parts by providing nonsense input: i think even the current AFL hype couldn't achieve that. |A few months ago, I floated an implementation of an mdoc(7) macro I really thought and think about using your patch to implement .Mx in mandoc(1) and offering the patch, of course. The original plan was to do so before i release the next version of the MUA i maintain, in order to be able to produce the online manual with mandoc(1); unfortunately this MUA turns me into a madcap, so the release is out without that. (I tested grohtml(1), and whereas i get all the mdoxmx(7) links and the TOC just right, the generated output is ridiculous beside that.) |(plus one more, for completion), `Ix', that's an invisible anchor to |which `Sx' can point. I implemented an active front-end in -Thtml |mode: there's no console mode because I'm not aware of link support in |stock less(1). In HTML, obviously, `Ix' is implemented as an empty Stock less(1), yes. At least still, i'm still hoping that it will be accepted upstream, at least as an optional (selectable) part. I personally hate HTML pretty much, but reading Unix manuals via HTML is *complete* nonsense. Really, what should that be good for, on a local box, for a locally installed program/xy? Note the mdocmx patch for less(1) is really super simple (basically we forward-, then possibly backward-search for a particular string). And you do not only get local referenceability, but .Xr references are also possible, temporarily replacing less(1) with man(1) to read the external manual. ~10000 bytes including manual update! If you got that mail i've posted, look into, e.g., the attached mdocmx.7 once like also posted: ( export MDOCMX_ENABLE=1 mdocmx.sh mdocmx.7 | groff -Tutf8 -mdoc -dmx-toc-force=tree | LESS= less --RAW-CONTROL-CHARS --ignore-case --no-init ) You will get a manual page with all-in-all 80 active references that can be sprung to via ^A in less(1), with a two-level table of contents. 80 references, 36 of which are document-local, the remaining reference external man(1)uals. HTML? What for? | to which subsequent can link. | |The concept of `Ix' arises from the desire to link not only to |sections and subsections, but also subsubsections and other textual |components. The mdoc(7) manual is an excellent example, which abuses |`Ss' to allow linking to descriptions of individual macros. | |The ``pro'' of `Ix' is that it's trivially easy to support in |mandoc(1) (patch was included) and can be just as easily ignored in |groff(1). (I go for ``ignore'' because that's what groff already does |with Sx and Ss and friends, which are the proto-Ix.) The patch is No longer with mdocmx(7). |dead easy to read. | |The ``con'' is that it's a new macro. To which I argue that, yes, it |is a new macro, but we already have a crippled form of the |functionality it provides (via `Sh' and `Ss'): this merely completes it. | |Is this a reasonable concept to move forward with? Thoughts? The |patch I provided is implementation-complete. I leave a PS/PDF |bookmark implementation as an exercise to the reader. So is there anything *i* could do for that? I would love to see just one extension that gets adapted and then just works! If you need an additional anchor that can be sprung to: like i've said the last time, the TTY output can't do that unless there is "some meat" we can use to inject the necessary backspace sequence (*unless* mdoc(7) has been rewritten completely, just like i've posted (solution also in mdocmx.tmac i think)). If it is ok for you that the TTY mode won't work, why not add ".Mx -anchor BLA", shorter alias ".Mx -a BLA", or whatever you want, i would however suggest ".Mx WHATEVER CATEGORY NAME", so that the lists can be subdivided based on CATEGORY (to avoid linear list searches, which are *really* slow in groff(1)). If i recall correctly something similar was your desire anyway? It is just fine as long as CATEGORY and NAME can both be used to ".ds" a troff(1) string. ".Mx -sxanchor CAT NAME"? If done like that, and referenced via .Sx, it'll get slow -- mdocmx(7) first tries .Sh, then .Ss, then would try each CATEGORY in order... To improve that, .Sx had to gain a parameter, which is not compatible. Alternatively yet another .Mx mode had to be added, say, ".Mx -sxlink CATEGORY" or whatever, which could set an internal flag that would be inspected when looking up the next .Sx parameter. I think any .Mx usage (directly or indirectly) should reset that flag again. So that could be done, of course i'm absolutely open and willing to add the final solution to mdocmx/.Mx. All i'm interested in is that manuals become more interactive (especially on the TTY where i use them), and i'd be hoping for improved keyword searches and manual section TOCs. I.e., what made texinfo attractive (but with external man(1)ual references). One restriction: it should be compatible with *roff(1), and with acceptable performance. --steffen -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv