Easier links in Markdown

[gaborcsardi]

EDIT: see current syntax below, here: #506 (comment)

The old syntax is not supported. The current syntax:

• [function] becomes \code{\link{function}}
• [pkg::function] becomes \code{\link[pkg]{function}}
• [name][dest] becomes \link[=dest]{name}
• [name][pkg::bar] becomes \link[pkg:bar]{name}

[gaborcsardi]

For #505.

I also updated the roxygen2 docs, and there are no changes in the Rd files (except for one mistake that I fixed).

You can do everything with the new syntax, so it does not make sense to keep the old syntax.

[hadley]

And now you can do [fun]() right?

[gaborcsardi]

Good question, I did not think about that. So, why do you want to add the (), to denote that it is a function, or just as part of the markdown link?

[hadley]

I like to do that to denote that it's a function rather than a variable or argument.

[gaborcsardi]

Got it. Unfortunately [func]() does not work. I could make it work, but it'll be awkward, the () won't be part of the link.

How about just [func()]? This does not work currently, either, but I think it is

• easier to write,
• easier for me to implement, and
• the () is part of the link.

[gaborcsardi]

Btw. [func()] is \code by default, no need for backticks.

[hadley]

Just to confirm:

• [func] -> \link{func}
• [func()] -> \code{\link[func]{func()}}`

?

The reason I have put the parens outside the link in the past is that it's easier to write \code{\link{func}()}

[gaborcsardi]

We already have [func] -> \code{\link{func}}.

I am proposing to add [func()] -> \code{\link[=func]{func()}}

Hopefully the last one is OK with Rd, and it will be shown as code. If not, I'll do it your way: \code{\link{func}()}

But nevertheless the markdown will be [func()] I think.

[hadley]

Hmmmmm. I'm not sure about [fun] automatically adding code. Admittedly that is what you do 95% of the time, but occasionally you do want to link to a general topic (e.g. \link{Quotes}) that shouldn't be code formatted.

[gaborcsardi]

How about having another notation for that?

Btw you can already do [Quotes][Quotes] which is ugly but we can have some
shortcut for it. Eg [][Quotes] or [Quotes][]. Not very intuitieve though.

On 16 Sep 2016 15:41, "Hadley Wickham" notifications@github.com wrote:

Hmmmmm. I'm not sure about [fun] automatically adding code. Admittedly
that is what you do 95% of the time, but occasionally you do want to link
to a general topic (e.g. \link{Quotes}) that shouldn't be code formatted.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
#506 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAoTQA4u8smMit3QXLKpBpUW4Am8Wy09ks5qqqqHgaJpZM4J-rvz
.

[gaborcsardi]

Another idea. How about automatically adding \code for [fun()], but not for [object] or [class]? Maybe you would not want to \code for classes, anyway, I don't know.

[hadley]

Yeah, that's what I was thinking

[gaborcsardi]

Cool, I'll update soon(ish), maybe today.

[gaborcsardi]

Updated. The current syntax:

• [fun()] becomes \code{\link[=fun]{fun()}}
• [obj] becomes \link{obj}
• [pkg::fun()] becomes \code{\link[pkg:fun]{pkg::fun()}}
• [pkg::obj] becomes \link[pkg:obj]{pkg::obj}
• [text][fun()] becomes \link[=fun]{text}
• [text][obj] becomes \link[=obj]{text}
• [text][pkg::fun()] becomes \link[pkg:fun]{text}
• [text][pkg::obj] becomes \link[pkg:obj]{text}

It was not so trivial, but this should work fine I think.

[hadley]

Thanks!