It would be good to have a link on Form generation to the Form API Reference. Maybe in a See Also section or something?

CommentFileSizeAuthor
#5 202404.patch905 bytesjhodgdon
#5 202404_D6.patch920 bytesjhodgdon
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

IncrediblyKenzi’s picture

This looks to be a problem with the api generation. The link is on the form generation page, but it's not getting linked properly. Instead it shows up as:

For information on the format of the structured arrays used to define forms, and more detailed explanations of the Form API workflow, see the @link http://api.drupal.org/api/file/developer/topics/forms_api_reference.html/5 reference @endlink and the @link http://api.drupal.org/api/file/developer/topics/forms_api.html/5 quickstart guide. @endlink

This applies to both 5.x and 6.x versions of the api docs.

IncrediblyKenzi’s picture

Category: feature » bug
betz’s picture

Project: Documentation » Drupal core
Version: » 7.x-dev
Component: Documentation in CVS » documentation

Changed the component to reflect the new component categorization. See http://drupal.org/node/301443

jhodgdon’s picture

Links in the above issue are broken... let's see.

If I go to api.drupal.org, click on Drupal 7, and click on Form Generation, I get to http://api.drupal.org/api/group/form_api/7 and this page has valid links to both the Quick Start guide http://api.drupal.org/api/file/developer/topics/forms_api.html and the Reference http://api.drupal.org/api/file/developer/topics/forms_api_reference.html. The Reference also has a link to the Quick Start Guide, but the Quick Start Guide does not have a link to the Reference.

One issue: All of the D7 links are missing the /7 suffix on the URLs, so currently if you click on a D7 link, you end up in the D6 version of the guide.

D6 has all the links exactly the same as D7. So does D5, except that the links have the correct suffixes, so they stay in D5 if you start in D5 (note that the starting point is http://api.drupal.org/api/group/form/5 in D5).

So I think what should be done:
a) Fix the D7 and D6 links to have suffixes, so you will always stay within the right section of the doc.
b) Add links from the Quick Start guides to the Reference in D5 - D7.

Note that the Form Generation pages are generated from the doc header in includes/form.inc. The other pages are in the contrib repository.

jhodgdon’s picture

Status: Active » Needs review
FileSize
920 bytes
905 bytes

Here are patches for D7 and D6 to put suffixes on the links to the form reference/quick start guides on the Form Generation pages.

I'll make changes to the contrib docs shortly.

Dries’s picture

I'm not sure this needs to be fixed. When Drupal 7 is released, the default might go from D6 to D7 and the links would work. Adding /7 to all links seems to be a royal pain.

jhodgdon’s picture

I've made the updates to the contrib docs as well for D6 and D7. See http://drupal.org/cvs?commit=229272 and http://drupal.org/cvs?commit=229270

Status: Needs review » Needs work

The last submitted patch failed testing.

jhodgdon’s picture

Status: Needs work » Needs review

The problem with not putting /7 on the links and /6 on the D6 links is that when D7 becomes current, the D6 pages will not work correctly (the same way the D7 pages are not working correctly now). So I agree it's a pain, but unfortunately I think it is necessary.

There are really only a very small number of links that need the /7 or /6 suffix, and they are all at the top of the pages.

Looks like the tester bot was malfunctioning... setting back to needs review...

cburschka’s picture

Status: Needs review » Reviewed & tested by the community

This generally seems like a good idea - links should go to the proper branch right away.

webchick’s picture

Status: Reviewed & tested by the community » Closed (won't fix)

While I agree this'd be a nice thing to do for convenience, it's also creating a maintenance headache and IMO we are totally never going to remember to update this between versions, so it will repeatedly come up as a bug as we go version to version. If/when api.drupal.org starts parsing contrib, this becomes even more of a maintenance issue, since their version numbers change much more rapidly than core's.

I think a better approach here might be a feature request to API module to inspect the referrer and auto-fix the version number if they're coming from a page with one specified. Then this would happen across /all/ links, not just odd-ball ones we happened to stumble across and file patches for.

I've posted such a request here: #699604: Use file name rather than full URL for links to Form API Reference page. Marking this issue won't fix.