See #202404: Put link to Forms API Reference in Form Generation.
Basically, in core we link to the Form API reference on api.drupal.org. It'd be nice if it could tell we were coming from form.inc/7 and automatically fix the link to form_reference.html/7.
Comments
Comment #1
jhodgdonActually, what we should be doing here is just using the bare file name for the link, instead of the full URL. That should turn into the proper link with the right version suffix. So, we have in includes/form.inc currently:
It should just say
(without the @link stuff). I realize that this will not be quite as friendly, since it won't have the link title... so I guess it could say:
(may need some line re-wrapping after that).
Should be a good Novice task. Should be backported to D7 and 6 as well. If there is any other existing full URL link in the code to the same URL in the code, that should be fixed too. And I also noticed that on the Drupal 6/7/8 landing pages on api.drupal.org, the link to Form API reference is broken there, so that needs to be fixed too (but that is in the Documentation repository, so let's get this other stuff fixed first).
And as a note to self: When a patch is submitted here, I should test it out on my API test site and verify that the links work.
Comment #2
nmudgal CreditAttribution: nmudgal commentedCould not find any other link in file.
Patch is attached after removing @link & just putting filename as mentioned.
Thanks
Comment #3
nmudgal CreditAttribution: nmudgal commentedFor D7.
Comment #4
nmudgal CreditAttribution: nmudgal commentedComment #5
jhodgdonPlease leave this at 8.x until we get a good patch for 8.x committed. Then we can worry about the D7 port. Thanks!
So regarding the patch in #2, aside from the fact that the testbot can't apply it (not sure why):
Probably this "and the" can be moved up to the previous line?
Comment #6
jhodgdonAlso, there are some other links. A quick grep found:
Comment #7
nmudgal CreditAttribution: nmudgal commentedyes that's what I was wondering why bot is checking against version-7.
Update patch.
Comment #8
nmudgal CreditAttribution: nmudgal commentedreview.
Comment #9
jhodgdonstill needs to fix the other links in #6
Comment #10
nmudgal CreditAttribution: nmudgal commentedUpdated as in #6, please review.
Thanks
Comment #11
jhodgdonThanks!
This one needs some thought:
The original reads "Note that #tree determines whether...". With your patch, it would now read "Note that the Form API reference () determines ...". That doesn't make much sense. Probably it needs to say:
Note that #tree determines whether the values are... See the Form API reference (filename) for more information.
This one also needs some similar attention:
Comment #12
nmudgal CreditAttribution: nmudgal commentedUpdated according to #11.
Thanks.
Comment #13
nmudgal CreditAttribution: nmudgal commentedComment #14
nmudgal CreditAttribution: nmudgal commentedIf that patch is good to go, I would be working on d7 one?
Thanks
Comment #15
jhodgdonOn D8/7 and when to work on the next patch - please see http://drupal.org/node/1488414#comment-5748422
Meanwhile... This patch is much closer, thanks! A few little items:
a) In the ajax.inc part of the patch, the new sentence needs a . at the end.
b) The form.inc section looks good.
c) In the field.api.php section, the original said "Widgets are Form API elements...". Let's keep that text.
Actually... I just tested this in my test version of the api.drupal.org site. Sigh. These links will not work anyway unless we do something different in the API module. Back to the drawing board... Sorry to send everyone on a wild chase to fix this.
Comment #16
jhodgdonAPI issue to support this:
#1489000: Need a way to make a reliable link to an HTML file
When that is resolved, we can come back here and fix the links. Until then, it's a bit pointless.
Comment #17
jhodgdonThat issue is now resolved, and the new code is on api.drupal.org. So it's time to go back and fix this. See comments in #15 (a-c).
Comment #18
nmudgal CreditAttribution: nmudgal commentedUpdated according to #15.
Comment #19
jhodgdonSo... I actually just fixed up the API module so that we can do any of the following:
.... filename.html ...
.... (filename.html) ...
.... @link filename.html Link text @endlink
That software fix should be deployed on api.drupal.org in a day or two (actually maybe later today).
Do you think that @link would be better than what we're doing now in this patch (which is using () around the filename)? That is, we can take
and change it to
Thoughts?
Comment #20
Robin Millette CreditAttribution: Robin Millette commentedWhat about using markdown link syntax? Something like
Comment #21
jhodgdonRobin: Sorry, that is not going to happen. We are using @ tags. This is just a small refinement of what we already have, and we're not going to completely change it at this point.
Comment #22
nmudgal CreditAttribution: nmudgal commented+1 for this as this documentation is always meant to be for devs & it looks more decent rather than putting (see for more information ... thing)
Comment #23
droplet CreditAttribution: droplet commentedBut where to find forms_api_reference.html ??
Comment #24
nmudgal CreditAttribution: nmudgal commented@droplet
It would link to http://api.drupal.org/api/drupal/developer%21topics%21forms_api_referenc... as discussed in #15, #16, #19
Comment #25
droplet CreditAttribution: droplet commented@nmudgal,
API module will do this job but your IDE won't. so How to find it quickly? Google?
Comment #26
droplet CreditAttribution: droplet commentedif no links, it maybe better..
@link API SITE: forms_api_reference.html Form API Reference @endlink
Comment #27
nmudgal CreditAttribution: nmudgal commentedAs I said in #22, it is intended for devs & they already know where to find FAPI reference, so think it is sufficient. But #26 sounds ok to me too.
Comment #28
Anonymous (not verified) CreditAttribution: Anonymous commentedI would rather see
@link forms_api_reference.html Form API Reference @endlink
as it stands out better.Comment #29
jhodgdon#26 will not work with the API module.
Our choices are either #28 or the most recent patch.
Comment #30
jhodgdonI see several votes (mine too) for #28. Let's get a new patch.
Comment #31
Albert Volkman CreditAttribution: Albert Volkman commentedThis looks like it was resolved with this issue-
http://drupal.org/node/1552412
Moving this back to 7.x.
Comment #32
Cameron Tod CreditAttribution: Cameron Tod commentedHere's a backport to D7. Note that I had to change the 'values' comment for drupal_get_form() to make sense in context - hope this is ok and not too much like scope creep.
Comment #33
jhodgdonLooks good, thanks! I'll get it committed shortly.
Comment #34
jhodgdonCommitted to 7.x. Thanks!
Comment #35
Albert Volkman CreditAttribution: Albert Volkman commentedNo love for D6? :)
Comment #36
Cameron Tod CreditAttribution: Cameron Tod commentedOne love, always :D
Comment #37
jhodgdonThe first link is missing the link text (which in the original says "reference".
And is this really the only place in all of the D6 source where forms_api_reference.html appears?
Comment #38
Cameron Tod CreditAttribution: Cameron Tod commentedOk. You're right too, I found another reference:
Comment #39
jhodgdonNo, that is a reference to http://api.drupal.org/api/group/form_api/6 -- which is a different page.
Comment #40
Albert Volkman CreditAttribution: Albert Volkman commentedThat's all I found.
Comment #41
jhodgdonOK, good! Then let's get that one fixed correctly (see #37). :)
Comment #42
Albert Volkman CreditAttribution: Albert Volkman commentedDone.
Comment #43
Cameron Tod CreditAttribution: Cameron Tod commentedShould this be "reference" instead of "Form API Reference"? That's how it was previously.
Also, apologies for my sloppy comment above, I was interrupted on my way out the door and probably shouldn't have clicked "Save".
Comment #44
Cameron Tod CreditAttribution: Cameron Tod commentedComment #45
jhodgdonThanks -- the patch in #43 looks good.
Comment #46
jhodgdonThanks! At long last, committed to 6.x.