Skip to content

A way to get in control which word is a link and which isn't #8

Closed
tomaz opened this Issue Dec 14, 2010 · 6 comments

3 participants

@tomaz
Owner
tomaz commented Dec 14, 2010

At present all words that are also valid class, category, protocol or member names are converted to cross reference to that object. If generic names are used for objects, all occurences of these words are considered as cross reference within appledoc. And this is not what the user intended.

For example protocols word used that is used a lot within documentation for appledoc's own GBAdoptedProtocolsProvider class is many times used as a "normal" word protocols, not as a reference to class' protocols property, however appledoc all occurences of the work treats as cross reference.

As appledoc already allows links being optionally embedded within <>, it could optionally require all parts that should be treated as potential cross references embedded within these chars. Perhaps with a command line switch that can change this behavior. On the other hand source code may become less readable, especially when coupled with styling directives - <protocols> vs protocols for example.

Any suggestion is welcome....

@danielctull

I was thinking of nice ways to do this today as well. Just looking at some of Apple's documentation, all of the cross linking for symbols are in fixed-width font and all of my cases, I've wanted to use the fixed-width font. Could the solution be to only link text found inside code spans?

@tomaz
Owner
tomaz commented Dec 19, 2010

Thanks for idea - this was one of my first thoughts too. But it didn't sound right to force users to format a section of text to make it eligible for cross reference generation. Although I also use code span every time I want to reffer to a symbol, someone might preffer other ways. Haven't crossed out this solution yet though - perhaps with a command line switch so that both options remain.

I agree that it can really be annoying to have "normal" words converted to links, so definetly something needs to be done. I'll keep the issue open for a while and see other suggestions.

@sroebert

I guess a command switch would be ok for now at least. Maybe add a special character in front of a word to allow it to be cross referenced. Like: #nameOfAFunction

@tomaz
Owner
tomaz commented Jan 28, 2011

That would be another option. It would add another convention though, besides <> for the same thing. But perhaps still better than just creating unexpected links out of normal words. It would definitely need to be selectable from command line. I guess this should also get higher priority as it would affect commenting style.

@tomaz
Owner
tomaz commented Jan 29, 2011

Working on this right now.

Haven't decided of how to implement the actual command line switch yet - the simplest way would be boolean switch, but underneath the option is handled quite openly: basically it would change the regex template for cross references. Default is <?%@>? where %@ is replaced by the actual regex and <> markers are optional. So to enable required markers, the regex template would simply need to be changed to <%@>.

This would actually allow usage of arbitrary markers, for example BloodDragon's proposal can be implemente with #%@, but this would require command line switch that takes a string containing the desired template. The underlying mechanism is already implemented, I will just play with different cmd switch ideas to see what works best.

On the negative side, this would affect ALL cross references: URLs, remote and local members and objects, so it would need to be something that would be presentable for all cases.

This is somewhat related to PrimaryFeather's proposal from #41; syntax in the form [crossref](url) where (url) part is optional might work as well.

@tomaz
Owner
tomaz commented Jan 29, 2011

Implemented optional required escaping for cross references. Closed by 52f5e8b.

The issue was that user had no way of being explicit about which word should be considered cross reference and which not. Result was that any word that was also valid cross reference was converted to one. This lead to unexpected references being created from normal words - like "paragraphs" and similar.

The user now has two choices regarding cross references: power users can provide their own cross references markers template regex, while simpler choice is to turn on explicit cross references detection. Actually this sets default markers template under the hood, so the two options should not be used together.

@tonklon tonklon pushed a commit to tonklon/appledoc that referenced this issue Mar 8, 2012
@tomaz Implemented optional required escaping for cross references. Closes #8.
The issue was that user had no way of being explicit about which word should be considered cross reference and which not. Result was that any word that was also valid cross reference was converted to one. This lead to unexpected references being created from normal words - like "paragraphs" and similar.

The user now has two choices regarding cross references: power users can provide their own cross references markers template regex, while simpler choice is to turn on explicit cross references detection. Actually this sets default markers template under the hood, so the two options should not be used together.
52f5e8b
This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.