Trouble with links and Markdown #180

Open
JoeWard opened this Issue Feb 14, 2012 · 7 comments

5 participants

@JoeWard

Simple links of the form ClassName and [ClassName methodName] appear to work fine, but when I try to use Markdown syntax to get "custom" link descriptions, I'm having trouble.

The format [Link text](Reference) works for links to the current class and its members, and to remote class names, but not remote class members.

This works:
[Another class](LinkReference)

But this does not:
[Another class method]([LinkReference referencedMethod])
Instead the link is malformed:
file:///Users/npl/testhelp/html/Classes/[[LinkReference%20referencedMethod]](../Classes/LinkReference.html#//api/name/referencedMethod

Similarly, I can't get the following Markdown cross ref syntax to work:

[To the class][1]

[1] LinkSource

This gives an error:
warning: Invalid [1]
[1] reference found near LinkSource.h@13, unknown object!
appledoc version: 2.0.5 (build 752)

The output is:
[To the class][1] [1] LinkSource

(The last "LinkSource" on the line is a link.)

I'm using the default command-line settings for link interpretation.

@tomaz
Owner

Will check into this. This was working, but may have been broken with recent updates.

@tomaz
Owner

Done some more testing and I know what's the problem, however it would require a bit more involved solution for which I don't have time at this point... This was working correctly while appledoc was doing its own Markdown processing, but after moving to third party library, I'd have to duplicate lots of functionality.

So for now, try and use "standard" cross referencing. I'll mark this as known bug for future reference.

@tomaz
Owner

Will be fixed as part of 3.0 release.

@tomaz tomaz added a commit that referenced this issue Dec 6, 2012
@tomaz Implemented cross references detection inside normal Markdown links. …
…References #180.

This handles cases where users would use appledoc cross reference as link part of Markdown link. For example: `[desc](MyClass)` etc. Also links with titles: `[desc](MyClass "title")`. It also works for remote members: `[desc](-[MyClass method:])`.
b968e27
@NassarS

We're seeing the same problem... http://docs.namomedia.com

You mentioned using "standard" cross referencing. How do we do that? Also, is there any way to turn off cross referencing altogether?

@tomaz
Owner

There was some development in this direction so make sure you use the latest version from GitHub (+latest templates).

And yes, you can turn cross referencing off by either setting --crossref-format to something unusual (--crossref-format "~~~%@~~~" for example) or using --explicit-crossref which will only cross reference a word contained in <>.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment