Use file name rather than full URL for links to Form API Reference page

Actually, 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:

  * workflow, see the
  * @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html Form API reference @endlink
 

It should just say

 * workflow, see forms_api_reference.html

(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:

  * workflow, see the Form API reference (forms_api_reference.html)

(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.

Could not find any other link in file.
Patch is attached after removing @link & just putting filename as mentioned.

Thanks

For D7.

Please 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):

+ * workflow, see the Form API reference (forms_api_reference.html)
  * and the

Probably this "and the" can be moved up to the previous line?

Also, there are some other links. A quick grep found:

includes/ajax.inc: *   @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html/7 Form API Reference @endlink
includes/form.inc: * @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html Form API reference @endlink
includes/form.inc: *     @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html/7#tree #tree @endlink
modules/field/field.api.php: * @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html Form API @endlink

yes that's what I was wondering why bot is checking against version-7.
Update patch.

review.

still needs to fix the other links in #6

Updated as in #6, please review.

Thanks

Thanks!

This one needs some thought:

@@ -214,10 +212,9 @@ function drupal_get_form($form_id) {
  *     set.
  *   - values: An associative array of values submitted to the form. The
  *     validation functions and submit functions use this array for nearly all
- *     their decision making. (Note that
- *     @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html/7#tree #tree @endlink
- *     determines whether the values are a flat array or an array whose
- *     structure parallels the $form array.)
+ *     their decision making. (Note that the Form API reference
+ *     (forms_api_reference.html) determines whether the values are a flat
+ *     array or an array whose structure parallels the $form array.)

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:

@@ -667,11 +667,10 @@ function hook_field_is_empty($item, $field) {
  * which widget to use. Widget types are defined by implementing
  * hook_field_widget_info().
  *
- * Widgets are
- * @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html Form API @endlink
- * elements with additional processing capabilities. Widget hooks are typically
- * called by the Field Attach API during the creation of the field form
- * structure with field_attach_form().
+ * Widgets are, see the Form API reference (forms_api_reference.html) elements

Updated according to #11.

Thanks.

If that patch is good to go, I would be working on d7 one?

Thanks

On 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.

API 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.

That 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).

Updated according to #15.

So... 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

 @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html/7 Form API Reference @endlink

and change it to

 @link forms_api_reference.html Form API Reference @endlink

Thoughts?

What about using markdown link syntax? Something like

This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.

Robin: 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.

+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)

@link forms_api_reference.html Form API Reference @endlink

But where to find forms_api_reference.html ??

@droplet
It would link to http://api.drupal.org/api/drupal/developer%21topics%21forms_api_referenc... as discussed in #15, #16, #19

@nmudgal,

API module will do this job but your IDE won't. so How to find it quickly? Google?

if no links, it maybe better..

@link API SITE: forms_api_reference.html Form API Reference @endlink

As 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.

#26 will not work with the API module.

Our choices are either #28 or the most recent patch.

I see several votes (mine too) for #28. Let's get a new patch.

This looks like it was resolved with this issue-

http://drupal.org/node/1552412

Moving this back to 7.x.

Here'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.

Looks good, thanks! I'll get it committed shortly.

Committed to 7.x. Thanks!

No love for D6? :)

One love, always :D

- * @link http://api.drupal.org/api/file/developer/topics/forms_api_reference.html/6 reference @endlink
- * and the @link http://drupal.org/node/204270 Form API guide. @endlink
+ * @link forms_api_reference.html @endlink and the
+ * @link http://drupal.org/node/204270 Form API guide. @endlink

The 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?

Ok. You're right too, I found another reference:

    $output .= '<li>'. t('register_globals is <strong>turned off</strong>. If you need to use forms, understand and use the functions in <a href="@formapi">the Drupal Form API</a>.', array('@formapi' => url('http://api.drupal.org/api/group/form_api/6'))) .'</li>';

No, that is a reference to http://api.drupal.org/api/group/form_api/6 -- which is a different page.

[6.x] $ grep -rI 'forms_api_reference' .
./includes/form.inc: * @link http://api.drupal.org/api/file/developer/topics/forms_api_reference.html/6 reference @endlink

That's all I found.

OK, good! Then let's get that one fixed correctly (see #37). :)

Done.

+++ b/includes/form.incundefined
@@ -41,8 +41,8 @@
- * @link http://api.drupal.org/api/file/developer/topics/forms_api_reference.html/6 reference @endlink
- * and the @link http://drupal.org/node/204270 Form API guide. @endlink
+ * @link forms_api_reference.html Form API Reference @endlink and the
+ * @link http://drupal.org/node/204270 Form API guide. @endlink

Should 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".

Thanks -- the patch in #43 looks good.

Thanks! At long last, committed to 6.x.