* Redux: linking in mdoc(7)? @ 2015-04-30 15:42 Kristaps Dzonsons 2015-04-30 17:31 ` Steffen Nurpmeso 0 siblings, 1 reply; 5+ messages in thread From: Kristaps Dzonsons @ 2015-04-30 15:42 UTC (permalink / raw) To: discuss -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA512 Hi, 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 should be simple. A few months ago, I floated an implementation of an mdoc(7) macro (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 <span id=""> to which subsequent <a href="#"> 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 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. Best, Kristaps -----BEGIN PGP SIGNATURE----- Comment: GPGTools - https://gpgtools.org iQIcBAEBCgAGBQJVQk1/AAoJEMT2SUY9XBESHC4QALIlN5bruIt9bZ+muHt1+QuI yjsccCwcxsJTk4adxFxYv/I4TAbeY7EAHFIJe+TpVsCeGuYx34ftKbbm2SdTx6Al w4njGy7H0nXfNlBUo4n5z2QgVBIkzmgeGDXTpDdjFnlKD3xeFCMIxmZkQ8YSSY53 ADPnVqtSOAvrMgWkv+xR3lAhLF7si2ZpOC6Pe5EMF9iYnHdhh4R97E2crI+aRUkn aAVddRvt4bwq5p3JH2SYtI+BfzrWLd6hkAJg+2Rzma1ZLtTtctYVSa8Zntiy7WRF mKn7EwIWOHpWUe3nEJPyDbrs+QBrnN3unQmogVPik3YakwhDItabILSi9bH1BMtd CN3MuFKtGLTpYohXEEUOL1lW9WKYDVDiih3YX/5eDz3K7SqTwjNWbS5/AOHw3UkX JJPrJ95TV50mkoOh20tLW4nD9k0h2eyP2BrLT+1B+WHt85POhcmLadYpECfjGicV 23czGrxYiD24ZNXARXZZjbnY47SY+cdrLA5kej6RC5DSEKVwXAKbk6skYkb7xPx6 P+ptEl1rKfkQazcaLf7Ui+t2wwfP8KFSg8P44zb28hv/ekeVdKTfsrCzH3TSu6Gn gJ7mHGA3DOwhQSYgjgMCZqIcQyOI3Bxs4wlK4+QdhztUgAA+g8yImbCK6t+IIIkp QAvPfwQkQYXsnTkV2geP =+/TN -----END PGP SIGNATURE----- -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Redux: linking in mdoc(7)? 2015-04-30 15:42 Redux: linking in mdoc(7)? Kristaps Dzonsons @ 2015-04-30 17:31 ` Steffen Nurpmeso 2015-04-30 23:06 ` Kristaps Dzonsons 0 siblings, 1 reply; 5+ messages in thread From: Steffen Nurpmeso @ 2015-04-30 17:31 UTC (permalink / raw) To: discuss Kristaps Dzonsons <kristaps@bsd.lv> 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? |<span id=""> to which subsequent <a href="#"> 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Redux: linking in mdoc(7)? 2015-04-30 17:31 ` Steffen Nurpmeso @ 2015-04-30 23:06 ` Kristaps Dzonsons 2015-05-01 20:04 ` Steffen Nurpmeso 0 siblings, 1 reply; 5+ messages in thread From: Kristaps Dzonsons @ 2015-04-30 23:06 UTC (permalink / raw) To: discuss -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA512 Folks, Let's please focus on mdoc(7) and mandoc(1). I'm only interested in groff(1) insofar as it's able to cope easily with any mdoc(7) additions. - From what I understand from mdocmx(7), `Mx' is an indexer. This sounds relevant for a text processor, but indexes aren't part of the manpage tradition. I don't see what problem `Mx' solves--I don't know of any manpages having or in need of an index. Most importantly, here's no mandoc(1) `Mx' patch. So not only do I not understand the problem that's being solved, I don't know how you plan on solving it with mandoc(1). `Ix' exists for a concrete reason: allowing mdoc(7) to be compatible with the existing (and many) Texinfo and DocBook documents, both of which allow and use intra-document linking. `Ix' implements these constructs using the mechanism already in place in mdoc(7): `Sx'. (I added an `Lkx' to allow `Sx' to arbitrary names. It should probably have another name.) The `Ix' concept benefits mdoc(7) a lot: with it and texinfo2mdoc(1), real, existing, and useful manuals can be remapped into mdoc(7). Think GSL, CVS, GCC, GMP, etc. Not in theory, and not after a monumental patch. The patch exists, texinfo2mdoc(1) can do the work already. (docbook2mdoc(1) needs to be patched...) I'm yet to hear anybody nay-say the idea or the implementation: I just don't have a tmac patch that disregards the `Ix' for groff(1) to float by the groff list. Best, Kristaps -----BEGIN PGP SIGNATURE----- Comment: GPGTools - https://gpgtools.org iQIcBAEBCgAGBQJVQrWPAAoJEMT2SUY9XBESLGIQALST5vOpQMhbvsOK+jiYlq2s EilHGxzXpyeL1EuaSSdH8ZvXJW2FivVaAYYvh3/J9VJCFRCaEOXO+oiIM5aygLur evSvCPGrzeHsB1Tz0Yui7sp0O9MGQTFrPzxvvX4c64P1dx2mNrawN2iOUWYrNKk2 omklYG4YJUCIuTQFRDjG1ASOGcMWkleFj7VHjH4dWCOEfwV22BzQ6C3UR3BwSTXG j8DpOKjO6jEvPxDpThAgRx+bnvMdF8uKK3CVKNBqyRqUUHTNuc68bMqYDIYsah96 5FGpS7uuQ02W0rjSkFhgMOazJO1Z/T8Y7Tj1obbb103+G+Bo/iOjkhXPYp/DH+Zj 1Czjfu7D5q7XrADQFB9GJEp8CHMMyMj+4RXCJOxJqoiAkfsZsTc//NDvdBX2fk3e dn4jAAV5bts3HFTrYpXtOFdb4TgFteNiXgrCy1GJEtHwmcWIMZTvejP9uyZ2F21w //8ofWulCNZKGJLS6PLpazqF+G8MhmYJoGL16v6EObzMQMjDXU1t85sjTVU1PTAN Q2pK/8r+gGMmaSLkUQ4lJPgvxbHRuVY4VktsPFBwfzEVFRRsNZjfCXbkDDGw/xD2 mXT46nXmlPYJ8i0RK3bVrUXKMHIOmpVvKG5JnU7lhwVLAIVGw0fRGLnU3gzKEOd/ xQoHr/iWUX8/Sb2Vf+a5 =xkx5 -----END PGP SIGNATURE----- -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Redux: linking in mdoc(7)? 2015-04-30 23:06 ` Kristaps Dzonsons @ 2015-05-01 20:04 ` Steffen Nurpmeso 2015-05-05 13:47 ` Steffen Nurpmeso 0 siblings, 1 reply; 5+ messages in thread From: Steffen Nurpmeso @ 2015-05-01 20:04 UTC (permalink / raw) To: discuss Happy 1st of May :o, Kristaps Dzonsons <kristaps@bsd.lv> wrote: |with the existing (and many) Texinfo and DocBook documents, both of |which allow and use intra-document linking. How about that? It is missing mdocmx.sh preprocessor support yet (so that only references to anchors already defined work). ..... commit 7b77631 (HEAD, refs/heads/crawl) Author: Steffen Nurpmeso <sdaoden@users.sf.net> Date: 2015-05-01 21:51:10 +0200 FIXME [mdocmx] Add ".Mx -ix [CAT] KEY" and ".Mx -sx [CAT]" \ (Kristaps Dzonsons).. Kristaps Dzonsons (kristaps at bsd dot lv) prodded multiple times for freely definable anchors on (discuss at mdocml dot bsd dot lv) in order to be able to implement texi2mdoc etc. This is my proposed solution, and it'll do fine if the anchor is placed carefully, which should be no problem for automated converters. ..... Note that in the next anchors[57] refers to the freely defined "usage forms anchors" in the first text line (you would see it with -dmx-debug=1). ..... Freely definable anchors and references[15] Via the ‘.Mx -ix category key’ and ‘.Mx -ix key’ usage forms anchors can be defined almost anywhere, e.g., ‘.Mx -ix subsubsection "An interesting topic"’ defines the anchor ‘An interesting topic’ for the “key” ‘subsubsection’. The form without a specified category will use the builtin name ‘ixsx’ instead. References to anchors[57] that have been created via -ix can be made by activating the .Sx search extension via ‘.Mx -sx category’ (or ‘.Mx -sx’ for the builtin ‘ixsx’ category) followed by a normal local reference lookup: .Mx -sx subsubsection .Sx "An interesting topic" It should be noted that these usage forms are mostly ment for automated conversion tools rather than for human manual creators: their use is non- trivial (which is owed to the implementation of mdoc(7)[58]) and the resulting visual output should always be verified! As a rule of thumb anchors should always created inside some “normal” text so that they can be attached to something “physical”. --steffen -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Redux: linking in mdoc(7)? 2015-05-01 20:04 ` Steffen Nurpmeso @ 2015-05-05 13:47 ` Steffen Nurpmeso 0 siblings, 0 replies; 5+ messages in thread From: Steffen Nurpmeso @ 2015-05-05 13:47 UTC (permalink / raw) To: discuss FYI, i've completed the mdocmx(7) side of the road. Ciao. Freely definable anchors and references[15] Via the ‘.Mx -ix category key’ and ‘.Mx -ix key’ usage forms anchors can (Btw., does anone knows how to do that as .Mx -ix [category] key i.e., using .Op for category --- while still having the entire thing inside of, and quoted by, .Ql? mdoc(7) no-go i guess?) be defined almost anywhere, e.g., ‘.Mx -ix subsubsection "An interesting topic"’ defines the anchor ‘An interesting topic’ for the “key” ‘subsubsection’. The form without a specified category will use the builtin name ‘ixsx’ instead. References to anchors that have been created via -ix can be made by acti‐ vating the .Sx search extension via ‘.Mx -sx category’ (or ‘.Mx -sx’ for the builtin ‘ixsx[58]’ category) followed by a normal local reference lookup: .Mx -sx subsubsection .Sx "An interesting topic" It should be noted that these usage forms are mostly ment for automated conversion tools rather than for human manual creators: their use is non- trivial (which is owed to the implementation of mdoc(7)[59]) and the resulting visual output should always be verified! As a rule of thumb anchors should always be created inside some “normal” text so that they can be attached to something “physical”. --steffen -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2015-05-05 13:47 UTC | newest] Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2015-04-30 15:42 Redux: linking in mdoc(7)? Kristaps Dzonsons 2015-04-30 17:31 ` Steffen Nurpmeso 2015-04-30 23:06 ` Kristaps Dzonsons 2015-05-01 20:04 ` Steffen Nurpmeso 2015-05-05 13:47 ` Steffen Nurpmeso
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).