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

[webchick]

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:   webchick
 Status:       active
 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 <strong>
tags.


Then, it reverses the process and replaces the <strong> 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.




webchick



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: *<strong
id="drupal-link_(linkpath)">(linkdescription)</strong>*
2. In linkpath, replace the '-'s with '/'s to build the relative link
path.
3. Replace the whole <strong>...</strong> string with *<a
href="(linkpath)">(linkdescription)</a>*
4. Repeat for entire page.


What do you think? 


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