Hi there!

First of all I have to praise you for this module. Nice idea and execution...
I noticed that during normalization trailing slashes are appended to a URL, but only if it's just a hostname. More specified URLs do not get the slash:

http://drupal.org gets http://drupal.org/ but
http://drupal.org/project stays as it is.

Shouldn't such longer addresses get the slash, too?

Greetings,
Henry

PS: Is there some API documentation? On first sight, I can't tell which functions are part of the API and which functions are meant only for internal use.

Comments

syscrusher’s picture

syscrusher commented
Assigned: Unassigned » syscrusher
Status: Active » Closed (works as designed)

Greetings!

Thanks for the kind words about the module.

The API documentation is in the file API.html, and in the comments in links.inc. I hope you find that helpful; feedback welcome, of course. API.html is meant as an overview of the API, rather than comprehensive documentation. The "canonical" documentation for each function is in the function's own comment headers, which are also doxygen-compatible if you prefer to run that utility.

Your question about which functions are part of the API is very easy to answer: Anything that is in links.inc is part of the API. It's basically that simple. The functions in links.module that do not begin with underscore are also peripherally part of the API, but are not quite as "cast in stone". Likewise, you can generally use (read-only, please!) configuration variables that are set by links.module, but again these are not guaranteed stable.

Anything in links.inc, including variables that it sets or reads, will be "as stable as I can possibly make it, within reason". That is, these things will only change if I feel there is a compelling reason, not just a whim. Functions may be *added* to links.inc, but I'll make every reasonable effort not to break anything that's there. If new parameters are added, for example, I try very hard to give them defaults that make the function behave in the legacy way.

Anything that is defined only in links_related.module, links_weblink.module, or links_admin.module should be considered outside the API, and potentially volatile in future releases.

Finally, your question about the trailing slashes is a good one, but unfortunately the answer is "working as designed". A trailing slash on a URL is a way to explicitly request the "index document" (usually index.html, index.php, index.htm, default.htm, etc., depending on what HTTP server is running and its config settings). In the case of content managers, such as Drupal, a URL with no trailing slash may not be a directory and may have no subordinate index document. Many Drupal administrators make paths like http://www.example.com/foo/bar that are not virtual directories (that is, the HTTP server will not find /foo/bar/index.html, for example).

I'm prepared to be open-minded about this -- if you or someone else feels my reasoning is wrong here, please feel free to argue. :-) I'm marking the issue "by design" until someone convinces me otherwise, but I'm open to that possibility.

Kind regards,

Syscrusher

henmue’s picture

henmue commented

Hi Syscrusher!

Thanks for the detailed answer. I think i must have had tomatoes on my eys: Anyway, who would expect the API documentation in the API.html? :-)
In seach of information I found the links.inc myself. Wow, each function is documented. That's the way it should be. If the comments are even doxygen compatible, I think it would be a good idea to bundle the module with the doxygen output or maybe link it on the modules homepage.

I have a question regarding the function links_normalize_url($url), which seems to be central in your scheme. The function skips four functions, which are commented out, and delegates normalization to links_parse_url($url). What is with the four functions, links_check_trailing_slash() for example. At first I thought, you could add or remove some functionality, but doesn't seem to be the case. Maybe the functions are deprecated and were replaced by links_parse_url($url)?

Regarding the trailing slashes, several things come to my mind: 1. Does it make any difference for Drupal, if there is a trailing slash at the end of a "functional link" like http://www.example.com/node/add for example? Up to now I thought .../node/add and .../node/add/ would be equivalent. 2. Trailing slashes for every URL without would be consistent with your slashes for simple hosts URLs. 3. I understand your solution to be redundance free, which is now not the case. I.e. the URLs http://drupal.org/support and http://drupal.org/support/ produce two database entries in the links table.
I would propose to introduce a trailing strategy component, so that a user can choose to between the startegy with trailing slashes and the strategy without. But although I'm no URL specialist or apache master, I have the impression that trailing slashes would be better.

Best regards,
Henry