Comments #36-#41 suggest that some clarification is needed in the l() function docs. I've found docs and usage in the mentioned issue somewhat confusing myself. Taking a first stab at it and awaiting for feedback.
Comments #36-#41 suggest that some clarification is needed in the l() function docs. I've found docs and usage in the mentioned issue somewhat confusing myself. Taking a first stab at it and awaiting for feedback.
Comments
Comment #1
tstoecklerLooks good already. I have a small suggestion for improvement. Instead of:
I think the following would be clearer:
I.e. I think it would be nice to actually say what the best practice in this case is, and then give an example. As a added bonus, api.drupal.org will automatically link "t()" to the respective page.
Comment #2
jhodgdonAnd I would also note that "texts" should be "text" in "enclosed in translatable text". :)
Comment #3
amonteroMuch clearer that way, for sure. Rock'n'reroll.
Comment #4
amonteroDoh, example link was missing.
Comment #5
tstoecklerAlmost there. Two minor oversights:
This is missing the
<a href="@url">
part in the example code.... FOR translators. (missing "for"; this might mean you'll have to wrap the line, don't know)
Comment #6
amonteroComment #7
jhodgdonIf we want to be really nice, we would also say "administrative" and not "admin" in the text of the example. :)
Comment #8
jhodgdonActually, can we make a more realistic example from core?
Comment #9
amonteroIMO, the example should be left as is, because the simpler the example, the better. I doubt that a core example can be more understandable at all and that's precisely the point of the example. So keeping it as short/simple as possible is a plus for me.
Comment #10
jhodgdonWell, can it at least be a bit more realistic? I can't imagine anyone actually writing "Your admin page" in text. Maybe something like "Visit the [link]Mymodule settings page[endlink]" instead?
Comment #11
amonteroHow about "Visit the settings page" ?
It keeps it short and without wrapping and it's a more realistic example, as you suggested.
Comment #12
jhodgdonSure!
Comment #13
amonteroComment #14
jhodgdonThat looks good, thanks! The only thing (sorry for not noticing it earlier) is that the new text should start on the previous line (all docs comments should wrap as close to 80 characters per line as possible without going over). Or if you think it should be a new paragraph, leave a blank (*) line.
Comment #15
amonteroComment #16
amonteroComment #17
tstoecklerThat looks great. Thanks for sticking with this!
Comment #18
jhodgdonThanks! Committed to 8.x and 7.x. I also removed some extraneous tags from this issue (please read the issue tag guidelines! the link is under the Tags field in the help/description text).
Comment #19
xjmComment #20
amonteroAs a comment-only modification, looks both safe and worthwile improving also 6.x docs.
Comment #21
tstoecklerStraight backport. Looks good. :-)
Comment #22
jhodgdonGood idea -- committed this to 6.x.