documentation for l() missing language key

Good catch: options['language'] is indeed undocumented on http://api.drupal.org/api/function/l/7 as well as http://api.drupal.org/api/function/l/6 in Drupal 6.

I'm not sure what you are talking about with hook_links -- that doesn't exist?

Did you perhaps mean http://api.drupal.org/api/function/theme_links/7 ? If so, I think it should just say "Other array items are passed on" instead of "Array items are passed on", and not document all the array options in two places.

And the D6 version of theme_links should do the same thing.

Added a description for language in the list of appropriate keys for option. I used the same exact wording from the url function. I also brought the entire list of keys up to document standards.

trevjs: Excellent work on that patch -- thanks for cleaning up the formatting.

Here's my take on things to add/fix, from the above comments and looking through the code:
- In both url() and l(), add a note saying to omit 'language' to use the current page's language.
- Make a note in both url() and l() that the language is used to look up the path alias (if any).

I'm filing a separate issue on l() about the use of the global $language_url, which as far as I can tell, is used but never set in core (WTF?).

Looking at the code, it looks like if you just leave out the 'language' component of options, you will have a language-neutral link.

Hmmmm... What do you actually mean by a "language neutral link"?

As far as I can tell, the only things that the language option or current language affects are (a) whether the link is marked as "active", and (b) which URL alias is looked up. If that is even working (see #724504: global $language_url and similar globals need documentation)....

Ah, I see.... http://api.drupal.org/api/function/locale_url_outbound_alter/7, which will probably be calling http://api.drupal.org/api/function/locale_language_url_rewrite_url/7 to alter the URL...

It looks like for rewrite_url(), if $options['language'] is omitted, it won't alter the URL, given that it's using the global $language_url variable, which I think is never set (see issue 724504, link above).

It looks like that outbound alter function http://api.drupal.org/api/function/locale_language_url_rewrite_url/7 will not alter a link if you leave off $options['language'], unless the global $language_url is set. Which again, I have no idea when/how/if that is ever set anywhere.

But... if the URL is altered, the site should still process it correctly? If not, that's the real bug on that other issue.

We all forgot the status change.

I see what you mean.

So I think we are still figuring it out, but it sounds like it should be something like this:

+ *     - language: An optional language object. Used to build the URL to link
+ *       to and look up the proper alias for the link. If a language is not defined
+ *       in options then the function will check to see if the language is defined
+ *       in the url, otherwise it will default to the language of the site.

There is a probably an easier way to say this, and I don't think language is defined as a variable in the url, I think it might be part of the path. But I'm new here. I'll check back tommorow and see if we have a definate understanding of this.

RE: #17 -- should probably say "If $options['language'] is not set".

But anyway, what it's doing if that is not set is ... hmmm...

It turns out that the global $language_url is the language that was defined by the URL of the current page (someone responded to my other issue). So if your site uses domains like de.example.com, or URL prefixes like example.com/de/, whatever the current page URL request was, that will define $language_url.

Why that and not the fully negotiated language for the page is being used in l(), url(), and theme_links() is a mystery to me.

Anyway, that aside, how about:

- language: An optional language object. If the path being linked to is internal to the site, $options['language'] is used to look up the alias for the URL, and to determine whether the link is "active", or pointing to the current page (the language as well as the path must match). If $options['language'] is omitted, the language defined by the current page's URL will be used; this depends on the site's language negotiation settings (sub-domain or URL prefix).

Or something like that... This would be for l(). For url(), the part about determining whether the link is active should be omitted. Can you fix both of them?

patch for l and url. If this passes then we will need to look at what needs to be done for Drupal 6.

#19: l-url-19.patch queued for re-testing.

Assuming that the test bot agrees, (doc-only patch, it should), I think this is VERY close.

I saw one place where there was a space at the end of the line:

+ *     negotiation settings (sub-domain or URL prefix). 

That needs to be removed.

And there is one small clarification. In the url() doc [top part of patch], the default is actually the negotiated language, not the languge defined by the URL:

+ *   - 'language': An optional language object. If the path being linked to is
+ *     internal to the site, $options['language'] is used to look up the alias
+ *     for the URL. If $options['language'] is omitted, the language defined by
+ *     the current page's URL will be used; this depends on the site's language
+ *     negotiation settings (sub-domain or URL prefix). 

The default part could be simply stated:

"If $options['language'] is omitted, the global $language will be used."

With the suggested changes.

Well, let's see.

In l(), $options['language'] is used to determine if the link should be given the "active" class. That is done if $options['language'] is empty or if it matches the global $language_url.

Then $options is passed on to url(), without adding to it.

In url(), i$options['language'] is only used to pass to drupal_get_path_alias, which passes language on to drupal_lookup_path.

In drupal_lookup_path(), if language is not specified, it uses the global $language_content. And it looks up path aliases that are either marked with the chosen language or as language neutral.

That's what these functions do. I have ZERO idea why some are using $language_url, some are using $language_content, and some are using $language. I also don't think I understand really what you mean by "specify that a link is language-neutral".

Hmmm...

It looks like the link altering is done via http://api.drupal.org/api/function/locale_url_outbound_alter/7
(hook_url_outbound_alter()), which is called from url() via drupal_alter()....

Hmmm...

That will call http://api.drupal.org/api/function/locale_language_url_rewrite_url/7 or a similar function, unless $options['external'] is TRUE, and it will use the global $language_url if $language is omitted.

So I am not seeing any way except setting 'external' => TRUE to bypass this.

That's probably a separate issue though... in fact, I think I saw one about this somewhere, but I don't recall right now where...

I think I get what you are saying... If a person is on a page /en/foo and you want to specify a link that goes to page /bar that is in the default language of the site, how do you force it to switch out of /en.

What happens if you pass $options['language'] equals english, and this is the default language of the site? Does it take you to /en/bar or /bar?

That would depend on the settings you have for languages on the site.

Anyway, all of that aside, I think the latest patch is fine, except it needs a blank line between the @param sections and @return.

See third example here:
http://drupal.org/node/1354#functions

Other than that, I would say let's get this patch in.

The no space between the param and return sections seems to be a common problem throughout the file. Is this something to create an issue about?

Anyways here is my patch.

Looks good, thanks trevjs!

Regarding creating a new issue for all the missing lines between @param and @return -- well. It's an issue in almost all of Drupal. If you feel like patching a particular file, you can make an issue with a patch for that file. Otherwise, we're just fixing them piecemeal. Sigh.

And I think there are better ways to spend your time than putting blank lines before all the @returns in Drupal. :)

Bump... Could we get this one in?

Committed to CVS HEAD. Thanks.

Now that it is in 7 I believe I need to add it in for 6.

Correct!

Actually, let's not port this patch. Instead, let's wait until #303987: l() documentation needs to say something about url encoding is fixed in D7 and then port that instead, because it's changing ulr() and l() doc again.