discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Steffen Nurpmeso <sdaoden@yandex.com>
To: discuss@mdocml.bsd.lv
Subject: Re: Linking in mdoc(7)
Date: Tue, 10 Mar 2015 17:30:53 +0100	[thread overview]
Message-ID: <20150310163053.I3TjLbTZ%sdaoden@yandex.com> (raw)
In-Reply-To: <54FDBE04.9030108@bsd.lv>

To the initial message and from the troff(1) / mdoc(7) on tty
output side, to the best of my understanding,

Kristaps Dzonsons <kristaps@bsd.lv> 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 (<a name|href=X>Y</a>, PDF..).

 |

Kristaps Dzonsons <kristaps@bsd.lv> 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

  reply	other threads:[~2015-03-10 16:31 UTC|newest]

Thread overview: 15+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <sfid-H20150308-171308-+043.19-1@spamfilter.osbf.lua>
2015-03-08 16:12 ` Kristaps Dzonsons
2015-03-09  6:29   ` Thomas Klausner
2015-03-09  6:38     ` Anthony J. Bentley
2015-03-09  8:46       ` Kristaps Dzonsons
2015-03-09 11:12         ` Joerg Sonnenberger
2015-03-09 11:34           ` Kristaps Dzonsons
2015-03-09 11:09   ` Steffen Nurpmeso
2015-03-09 11:46     ` Ingo Schwarze
2015-03-09 12:25       ` Kristaps Dzonsons
2015-03-09 15:36         ` Kristaps Dzonsons
2015-03-10 16:30           ` Steffen Nurpmeso [this message]
2015-03-11  8:05             ` Kristaps Dzonsons
2015-03-11  8:15               ` Anthony J. Bentley
2015-03-11 10:07               ` Steffen Nurpmeso
2015-03-09 13:11       ` Steffen Nurpmeso

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20150310163053.I3TjLbTZ%sdaoden@yandex.com \
    --to=sdaoden@yandex.com \
    --cc=discuss@mdocml.bsd.lv \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
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).