[drupal-docs] [task] Broken links on handbook's module pages

Tue Sep 27 15:37:09 UTC 2005

Issue status update for 
http://drupal.org/node/32078
Post a follow up: 
http://drupal.org/project/comments/add/32078

 Project:      Documentation
 Version:      <none>
 Component:    User Guide
 Category:     tasks
 Priority:     normal
 Assigned to:  webchick
 Reported by:  webchick
 Updated by:   stefan nagtegaal
 Status:       active

Why do you do:

<?php
    case 'admin/help#aggregator':
      $helptext = '';
      $helptext .= '<p>'. t('The news aggregator is a powerful on-site RSS syndicator/news reader that can gather fresh content from news sites and weblogs around the web.') .'</p>';
?>

You can also use:

<?php
    case 'admin/help#aggregator':
       $helptext  = '<p>'. t('The news aggregator is a powerful on-site RSS syndicator/news reader that can gather fresh content from news sites and weblogs around the web.') .'</p>';
       $helptext .= 'resume';
?>

And:

<?php
      return($helptext);
?>

Should be

<?php
      return $helptext;
?>

Furthermore I do really, really like this patch!

stefan nagtegaal

Previous comments:
------------------------------------------------------------------------

Sat, 24 Sep 2005 04:20:37 +0000 : webchick

As was pointed out on the documentation mailing list, the "action links"
on each module handbook page are all relative links (for example
"admin/settings") and thus lead to 403 errors (if the user viewing them
doesn't have proper permissions) or 404 errors (if the module given is
not installed on Drupal.org).

The relative links are required because core/contrib admin help
documentation is generated from these handbook pages (so eventually,
http://www.drupal.org/ gets replaced by http://www.example.com/).
However, in the meantime, all of these handbook pages look like they
have errors in them. See the User module handbook page [1] for an
example. Clicking on any of the "You can:" links results in a 403 error
(unless of course you're Dries ;)).

My suggestion to solve this issue was to "tag" the links in the
handbook, using a naming convention something like:

*<strong id="drupal-link_admin-settings">administer >>
settings</strong>*

This would result in these links showing up as bold items, indicating
the menu paths a user should use, but NOT active hyperlinks that, when
clicked, would generate errors. They would also be uniquely tagged with
an ID which would be invisible to the browser, but which could be used
to regenerate the links later.

Upon export to admin help documentation, these pages could be run
through a script which would parse them with some regex magic, more or
less performing the steps:

1. Find an occurrence of the string: *(linkdescription)*
2. In linkpath, replace the '-'s with '/'s to build the relative link
path.
3. Replace the whole ... string with *<a
href="(linkpath)">(linkdescription)</a>*
4. Repeat for entire page.

What do you think? 

[1] http://drupal.org/handbook/modules/user

------------------------------------------------------------------------

Sat, 24 Sep 2005 18:20:36 +0000 : webchick

Attachment: http://drupal.org/files/issues/docparse.php (3.33 KB)

Here is a VERY rough script just to show as proof of concept.

to use:

1. Make a folder called "docparse" or whatever on your web server and
place this script inside it
2. Make the folder writable
3. Save http://drupal.org/book/export/docbook/279 as modules.xml in the
same folder as this script

What it does is first parse the contents of modules.xml (direct dump
from handbook) and creates modules_updated.xml. This simulates a dump
from the handbook after all of the links have been encoded in 
tags.

Then, it reverses the process and replaces the encoded links
with anchors and saves this as modules_replaced.xml. This simulates
taking the dump from the handbook and formatting it for admin/help use.

I haven't tested this overly thoroughly, but hopefully it will give you
an idea of the logic, etc.

------------------------------------------------------------------------

Sat, 24 Sep 2005 18:54:37 +0000 : Amazon

Here is an example of a Drupal core module patched with administration
help
http://svn.civicspacelabs.org/trunk/modules/aggregator.module
Here is an example of the desired output:

case 'admin/help#aggregator':
      return t('The news aggregator is a powerful on-site RSS
syndicator/news reader that can gather fresh content from news sites
and weblogs around the web.

Users can view the latest news chronologically in the main news
aggregator display [2] or by source [3]. Administrators can add, edit
and delete feeds and choose how often to check for newly updated news
for each individual feed. Administrators can also tag individual feeds
with categories, offering selective grouping of some feeds into
separate displays. Listings of the latest news for individual sources
or categorized sources can be enabled as blocks for display in the
sidebar through the block administration page [4]. The news aggregator
requires cron to check for the latest news from the sites to which you
have subscribed. Drupal also provides a machine-readable OPML file [5]
of all of your subscribed feeds.

You can

* administer your list of news feeds administer >>  aggregator [6].
* add a new feed administer >> aggregator >> add feed [7].
* add a new category administer >> aggregator >> add category   [8].
* configure global settings for the news aggregator administer >>
settings >> aggregator [9].
* control access to the aggregator module through access permissions
 administer >> access control >> permissions [10].

For more information, read the configuration and customization handbook
 aggregator page.

', array('%aggregator' => url('aggregator'), '%aggregator-sources' =>
url('aggregator/sources'), '%admin-block' =>url('admin/block'),
'%aggregator-opml' =>url('aggregator/opml'), '%admin-aggregator' =>
url('admin/aggregator'), '%admin-aggregator-add-feed' =>
url('admin/aggregator/add/feed'), '%admin-aggregator-add-category' =>
url('admin/aggregator/add/category'), '%admin-settings-aggregator' =>
url('admin/settings/aggregator'), '%admin-access' =>
url('admin/access')));

All relative links have been replace with variables and then added to
an array as pairs.  I am reviewing the output of your code right now.

Cheers,
Kieran

[2] http://drupal.org/%aggregator
[3] http://drupal.org/%aggregator-sources
[4] http://drupal.org/%admin-block
[5] http://drupal.org/%aggregator-opml
[6] http://drupal.org/%admin-aggregator
[7] http://drupal.org/%admin-aggregator-add-feed
[8] http://drupal.org/%admin-aggregator-add-category
[9] http://drupal.org/%admin-settings-aggregator
[10] http://drupal.org/%admin-access

------------------------------------------------------------------------

Sun, 25 Sep 2005 06:08:00 +0000 : webchick

Attachment: http://drupal.org/files/issues/makeadminhelp.php (3.98 KB)

Ok, here is another rough script that will output an expected *case
'admin/help#path':* for each core module. It also wraps each line in
its own t() function, per http://drupal.org/node/26139. To try it:

1. Put this script in a writable folder on your web server
2. Save http://drupal.org/book/export/docbook/279 as modules.xml in the
same folder as this script
3. The output is saved to a file called adminhelp.txt.

It's not quite "there" yet as there are still a couple bugs... For
instance, profile doesn't get picked up at all (you'll see a warning to
this effect when you load this), and there's at least one wrapping link
(on the taxonomy module page) which it doesn't pick up either. But
otherwise, this is working probably about 90%, and I'll try and sort
these other problems out tomorrow if I get a chance.

------------------------------------------------------------------------

Sun, 25 Sep 2005 18:11:53 +0000 : webchick

Attachment: http://drupal.org/files/issues/adminhelp.txt (47.78 KB)

Just as a helper.. this is the output of the above script, so you don't
have to go through all the setup routines to review it. :)

------------------------------------------------------------------------

Sun, 25 Sep 2005 18:22:36 +0000 : Amazon

This is one of those simple things that will make a huge difference.

The Docs team now has the ability to update the source documentation
here: http://drupal.org/handbooks/modules and with this script we can
just hand a file to the development team to roll a patch.

A big thanks to webchick for cranking this out.

Kieran

------------------------------------------------------------------------

Tue, 27 Sep 2005 09:08:05 +0000 : webchick

Attachment: http://drupal.org/files/issues/makeadminhelp_0.php (5.52 KB)

Ok, probably about 99% there now, I hope. :) Here is the updated script
(getting REALLY ugly now *lol*). Will post the updated output in a
second.

After talking to killes on IRC, he brought up the point that t() blocks
should be like:

'<p>'. t('...') .'</p>';

and for lists:

'<ul>' .t('<li>....</li>');
t('<li>...</li>') .'</ul>');

So the current script does that.

I still have two outstanding issues that I'm aware of (possibly more,
it's 5am :P):

1. When there are multiple links on one line (see: BlogAPI), it only
seems to find the first link/description and repeats it for all other
links on that line.

2. I cannot figure out how to generate a "normal" link with a Drupal
function call! l() and url() both appear to do basically the same
thing--format an internal link. However, Drupal module for example has
a link that is just cron.php... Which of course is not the same thing
as ?q=cron.php. Similarly, all external links (BlogAPI) get appended to
the querystring (?q=http://www.flickr.com/).

Any ideas on these (particularly the last one... the first one is
likely a fubar'ed regex)?

------------------------------------------------------------------------

Tue, 27 Sep 2005 09:08:40 +0000 : webchick

Attachment: http://drupal.org/files/issues/adminhelp_0.txt (54.09 KB)

And here is the output.