Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Easier links in Markdown #506

Merged
merged 1 commit into from Sep 20, 2016
Merged

Easier links in Markdown #506

merged 1 commit into from Sep 20, 2016

Conversation

@gaborcsardi
Copy link
Collaborator

@gaborcsardi gaborcsardi commented Sep 16, 2016

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
Copy link
Collaborator Author

@gaborcsardi gaborcsardi commented Sep 16, 2016

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
Copy link
Member

@hadley hadley commented Sep 16, 2016

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

@gaborcsardi
Copy link
Collaborator Author

@gaborcsardi gaborcsardi commented Sep 16, 2016

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
Copy link
Member

@hadley hadley commented Sep 16, 2016

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

@gaborcsardi
Copy link
Collaborator Author

@gaborcsardi gaborcsardi commented Sep 16, 2016

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
Copy link
Collaborator Author

@gaborcsardi gaborcsardi commented Sep 16, 2016

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

@hadley
Copy link
Member

@hadley hadley commented Sep 16, 2016

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
Copy link
Collaborator Author

@gaborcsardi gaborcsardi commented Sep 16, 2016

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
Copy link
Member

@hadley hadley commented Sep 16, 2016

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
Copy link
Collaborator Author

@gaborcsardi gaborcsardi commented Sep 16, 2016

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
Copy link
Collaborator Author

@gaborcsardi gaborcsardi commented Sep 16, 2016

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
Copy link
Member

@hadley hadley commented Sep 16, 2016

Yeah, that's what I was thinking

@gaborcsardi
Copy link
Collaborator Author

@gaborcsardi gaborcsardi commented Sep 16, 2016

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

The old syntax is not supported. 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}
@gaborcsardi
Copy link
Collaborator Author

@gaborcsardi gaborcsardi commented Sep 18, 2016

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 hadley merged commit 7f227b6 into r-lib:master Sep 20, 2016
3 checks passed
@hadley
Copy link
Member

@hadley hadley commented Sep 20, 2016

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

2 participants