You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by Steven A Rowe <sa...@syr.edu> on 2008/11/06 21:33:17 UTC
Broken javadocs->site docs links
When the Lucene Java website transitioned to versioning some of the documentation, links from some javadocs were not modified to follow the resources. I found broken links to gettingstarted.html, queryparsersyntax.html, and fileformats.html from the javadocs, in both the 2.4.0 and the trunk javadocs. Here is one example, to gettingstarted.html (the link text is "demo"):
<http://lucene.apache.org/java/2_4_0/api/org/apache/lucene/document/package-summary.html>
<http://hudson.zones.apache.org/hudson/job/Lucene-trunk/javadoc//org/apache/lucene/document/package-summary.html>
The javadocs for o.a.l.search.Similarity fixes this for queryparsersyntax.html in the versioned site docs by using a relative URL, but since the versioned documentation does not appear to be included in the Hudson build, the link is broken for the trunk javadocs (link text: "query syntax"):
<http://hudson.zones.apache.org/hudson/job/Lucene-trunk/javadoc/org/apache/lucene/search/Similarity.html>
How should this be fixed?
For the versioned javadocs, the links clearly should be to the versioned site documentation. If all of the absolute URLs were changed to be relative URLs, as in o.a.l.search.Similarity's javadocs, then the versioned javadocs issue would be resolved. The trunk javadocs links, however, would remain broken.
For the trunk javadocs, the links would ideally be to trunk versions of the site documentation, but I can't find trunk versions of the versioned site documentation on Hudson. Is this intentional?
Steve
RE: Broken javadocs->site docs links
Posted by Steven A Rowe <sa...@syr.edu>.
On 11/07/2008 at 1:35 PM, Doug Cutting wrote:
> Steven A Rowe wrote:
> > This would not entirely fix the issue; each version's
> > javadocs should link to the same version of the site docs,
> > rather than to the latest version (which is what I assume you
> > mean here).
>
> Right. The javadocs should use a relative link to point to versioned
> docs.
I just discovered that simply changing the URLs to be relative won't do the trick either, since the javadocs exist in two forms: combined core+contrib, and separate core and contrib.
The javadocs for o.a.l.search.Similarity has a working link to link to queryparsersyntax.html (link text: "query syntax"), as a result of using a relative URL, in the combined core+contrib form (the first URL below); however, the link is broken in the separate core form (the second URL below), because the number of parent path elements differs between the two:
<http://lucene.apache.org/java/2_4_0/api/org/apache/lucene/search/Similarity.html>
<http://lucene.apache.org/java/2_4_0/api/core/org/apache/lucene/search/Similarity.html>
Similarly, the MemoryIndex javadocs (which contain a link to queryparsersyntax.html) would have a broken link in one or the other of the two forms, if the absolute URL were changed to a relative URL:
<http://lucene.apache.org/java/2_4_0/api/org/apache/lucene/index/memory/MemoryIndex.html>
<http://lucene.apache.org/java/2_4_0/api/contrib-memory/org/apache/lucene/index/memory/MemoryIndex.html>
A possible fix: the core+combined javadocs could add another path element, resulting in URLs like:
<http://lucene.apache.org/java/2_4_0/api/all/org/apache/lucene/search/Similarity.html>
<http://lucene.apache.org/java/2_4_0/api/all/org/apache/lucene/index/memory/MemoryIndex.html>
That way relative URLs would work for both the combined and separated forms, since they would have the same number of parent path elements.
> But, back to the issue at hand, fixing broken links in the
> javadocs on Hudson seems like a low priority.
Makes sense. Perhaps a rewriting strategy similar to the .htaccess technique you mentioned earlier could eventually be employed.
Steve
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: Broken javadocs->site docs links
Posted by Doug Cutting <cu...@apache.org>.
Steven A Rowe wrote:
> This would not entirely fix the issue; each version's javadocs should link to the same version of the site docs, rather than to the latest version (which is what I assume you mean here).
Right. The javadocs should use a relative link to point to versioned
docs. But, if releases have been made and broken links to absolute urls
are in the wild, we can patch that with .htaccess.
> Are you arguing that the trunk javadocs should not be published anywhere at all?
I've mostly given up on that battle... Developers by definition can
build their own javadocs, and a link, even from the developer part of
the site, gives nightly builds more legitimacy. If folks really want,
they can find and bookmark the nightly link on Hudson.
But, back to the issue at hand, fixing broken links in the javadocs on
Hudson seems like a low priority.
Doug
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
RE: Broken javadocs->site docs links
Posted by Steven A Rowe <sa...@syr.edu>.
Hi Doug,
On 11/06/2008 at 4:22 PM, Doug Cutting wrote:
> Broken links in released docs might be fixed by adding
> redirects to the website, by editing:
>
> http://svn.apache.org/repos/asf/lucene/.htaccess
This would not entirely fix the issue; each version's javadocs should link to the same version of the site docs, rather than to the latest version (which is what I assume you mean here).
For example, the 2.3.2 version of the the o.a.l.document package summary should link to the 2.3.2 version of gettingstarted.html, instead of to the 2.4.0 version (currently the latest).
> The trunk javadocs should not be published on the website. We should
> only publish released documentation.
The trunk javadocs are published on hudson.zones.apache.org, and are linked to from the Developers page on the site. Are you arguing that the trunk javadocs should not be published anywhere at all?
Steve
> Steven A Rowe wrote:
> > When the Lucene Java website transitioned to versioning
> > some of the documentation, links from some javadocs were not
> > modified to follow the resources. I found broken links to
> > gettingstarted.html, queryparsersyntax.html, and
> > fileformats.html from the javadocs, in both the 2.4.0 and the
> > trunk javadocs. Here is one example, to gettingstarted.html
> > (the link text is "demo"):
> >
> >
> <http://lucene.apache.org/java/2_4_0/api/org/apache/lucene/document/package-summary.html>
> >
> <http://hudson.zones.apache.org/hudson/job/Lucene-trunk/javadoc//org/apache/lucene/document/package-summary.html>
> >
> > The javadocs for o.a.l.search.Similarity fixes this for
> > queryparsersyntax.html in the versioned site docs by using a
> > relative URL, but since the versioned documentation does not
> > appear to be included in the Hudson build, the link is broken
> > for the trunk javadocs (link text: "query syntax"):
> >
> <http://hudson.zones.apache.org/hudson/job/Lucene-trunk/javadoc/org/apache/lucene/search/Similarity.html>
> >
> > How should this be fixed?
> >
> > For the versioned javadocs, the links clearly should be to
> > the versioned site documentation. If all of the absolute
> > URLs were changed to be relative URLs, as in
> > o.a.l.search.Similarity's javadocs, then the versioned
> > javadocs issue would be resolved. The trunk javadocs links,
> > however, would remain broken.
> >
> > For the trunk javadocs, the links would ideally be to trunk
> > versions of the site documentation, but I can't find trunk
> > versions of the versioned site documentation on Hudson. Is
> > this intentional?
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: Broken javadocs->site docs links
Posted by Doug Cutting <cu...@apache.org>.
Broken links in released docs might be fixed by adding redirects to the
website, by editing:
http://svn.apache.org/repos/asf/lucene/.htaccess
The trunk javadocs should not be published on the website. We should
only publish released documentation.
Doug
Steven A Rowe wrote:
> When the Lucene Java website transitioned to versioning some of the documentation, links from some javadocs were not modified to follow the resources. I found broken links to gettingstarted.html, queryparsersyntax.html, and fileformats.html from the javadocs, in both the 2.4.0 and the trunk javadocs. Here is one example, to gettingstarted.html (the link text is "demo"):
>
> <http://lucene.apache.org/java/2_4_0/api/org/apache/lucene/document/package-summary.html>
> <http://hudson.zones.apache.org/hudson/job/Lucene-trunk/javadoc//org/apache/lucene/document/package-summary.html>
>
> The javadocs for o.a.l.search.Similarity fixes this for queryparsersyntax.html in the versioned site docs by using a relative URL, but since the versioned documentation does not appear to be included in the Hudson build, the link is broken for the trunk javadocs (link text: "query syntax"):
> <http://hudson.zones.apache.org/hudson/job/Lucene-trunk/javadoc/org/apache/lucene/search/Similarity.html>
>
> How should this be fixed?
>
> For the versioned javadocs, the links clearly should be to the versioned site documentation. If all of the absolute URLs were changed to be relative URLs, as in o.a.l.search.Similarity's javadocs, then the versioned javadocs issue would be resolved. The trunk javadocs links, however, would remain broken.
>
> For the trunk javadocs, the links would ideally be to trunk versions of the site documentation, but I can't find trunk versions of the versioned site documentation on Hudson. Is this intentional?
>
> Steve
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org