discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: discuss@mdocml.bsd.lv
Subject: Re: Linking in mdoc(7)
Date: Mon, 9 Mar 2015 12:46:48 +0100	[thread overview]
Message-ID: <20150309114648.GA18431@athene.usta.de> (raw)
In-Reply-To: <20150309110908.gN5E-QPE%sdaoden@yandex.com>

Hi Kristaps and Steffen,

Steffen Nurpmeso wrote on Mon, Mar 09, 2015 at 12:09:08PM +0100:
> 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
>> jump to.  Thus, `Sh' and `Ss' work as they always did and `Sx' works
>> as it always did, but we can also jump to arbitrary locations from
>> `Sx' as defined with `Ix', which is otherwise silent.  Obviously, this
>> is only useful in -Thtml.  On the console, nothing happens at all.  I
>> also propose an `Lkx', which is like `Lk' but for inter-page links.
>> This is when the argument to `Sx' should be different from the index name.

My initial reaction is:  It is about time to do something like that.
However, introducing new macros is not be taken lightly, and the
design must not be rushed.  Before committing to something specific,
we should make sure that it is as powerful as possible, as extensible
as possible, and as simple as possible.  I'm not yet convinced the
proposed design is the most general and simple one.  In particular,
it isn't obvious to me yet how implicit linking - i.e. internal
linking that doesn't require any new markup - integrates into
Kristaps concept, and lack of an idea how terminal output can profit
is a very serious downside too, give that terminal output is by far
the most important output mode.

Then again, we have a tradition of having good designs override
bad ones soon afterwards (no insult intended :).

> I have proposed something similar back in September 2014 on groff@

Exactly what i wanted to say.  :-)

The thread is here:

  http://lists.gnu.org/archive/html/groff/2014-09/msg00145.html

> and implemented a complete package that can do this and much more
> with an interface that follows Ingo's suggestions since then.
> The macro is .Mx, the documentation, troff(1) awk(1) preprocessor,
> mdoc(1) macro extensions etc., and a patch for less(1) v471 that
> allows internal (including .Sh and .Ss, but many more) and
> external anchors (for .Xr) to be followed are available.  Use it
> or leave it.

I didn't look at either implementation yet, i focussed on different
topics (man(1), eqn(7), UTF-8, messages, afl mopup, pod2mdoc(1)).

Even though Steffen rightfully says that i influenced the design
he finally chose, and even though that design seemed better to me
than what was initially proposed, and even though Steffen was
positively enthusiastic about it, i wasn't quite satisfied yet.

So my hope is that what we finally arrive at will at least be as
powerful as the union of your two implementations and at most as
complex as the intersection of both of them, or maybe even better...

Kristaps, if you want to commit to minimize risk of loss of work,
maybe create a branch for it for now?  I'm planning to prepare
the 1.13.3 release soon, and this is clearly post-release material.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

  reply	other threads:[~2015-03-09 11:46 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 [this message]
2015-03-09 12:25       ` Kristaps Dzonsons
2015-03-09 15:36         ` Kristaps Dzonsons
2015-03-10 16:30           ` Steffen Nurpmeso
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=20150309114648.GA18431@athene.usta.de \
    --to=schwarze@usta.de \
    --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).