399068 - Remove the 'docs_urlbase' parameter

Status: RESOLVED FIXED

(Bugzilla :: Administration, task)

Description

[Frédéric Buclin]

Per our discussions at our last 2 Bugzilla meetings, this param should go away. Bugzilla should check whether docs/html/index.html exists and use it, else it should point to bugzilla.org. One question: how should we determine which branch to look at on bugzilla.org?

Comment 1

[Max Kanat-Alexander]

We can determine which branch to look at using a branch() function that reads off the first two digits and does some clever things with them. Also, on bugzilla.org, we can provide symlinks for things like "2.24" -> "3.0" and during development, "3.6" -> "tip". So that way people's installations will always link to the right thing, and we handle it all on the server side.

Comment 2

[A. Shimono [:himorin]]

For sites using localization pack, I'd love to have some parameter (might be ok with string in variable.none.tmpl) for the url not in English, which is the only language provided in bugzilla.org.

Comment 3

[Max Kanat-Alexander]

(In reply to comment #2)
> For sites using localization pack, I'd love to have some parameter (might be ok
> with string in variable.none.tmpl) for the url not in English, which is the
> only language provided in bugzilla.org.

  Sure, I think initialize.none.tmpl might be an acceptable place to put it?

Comment 4

[Frédéric Buclin]

I don't think we need anything of that kind. If the user visits your Bugzilla installation with his preferred language to be japanese, Bugzilla should automatically look at the following URLs, in this order:

1) docs/ja/html/index.html
2) docs/en/html/index.html
3) www.bugzilla.org/docs/....

So if bugzilla-ja is installed and it contains documentation as well, it will be displayed, else it falls back to the local english version and if no documentation has been compiled locally, it falls back to the doc on bugzilla.org.

Comment 5

[Max Kanat-Alexander]

And we can have redirects on bugzilla.org itself to point to the most accurate multi-language docs, also, if we want.

Comment 6

[A. Shimono [:himorin]]

(In reply to comment #4)
> So if bugzilla-ja is installed and it contains documentation as well, it will
> be displayed, else it falls back to the local english version and if no
> documentation has been compiled locally, it falls back to the doc on
> bugzilla.org.

How many languages are providing 'compiled' documents, I doubt.
# or, it's only my skive.. :p

(In reply to comment #5)
> And we can have redirects on bugzilla.org itself to point to the most accurate
> multi-language docs, also, if we want.

If this is possible, I prefer this. We, localized projects, can control the URL of the documents.. Yes, of cource, it IS better to make them as URI, but the site address of localizations may change..

Comment 7

[Gervase Markham [:gerv]]

Attachment: Patch v.1

This should do the trick, I think.

Gerv

Comment 8

[Frédéric Buclin]

Comment on attachment 8537909 [details] [diff] [review]
Patch v.1

Looks good. A few things to fix, though.


>diff --git a/Bugzilla/Template.pm b/Bugzilla/Template.pm

>+                if (-d "docs/en/html") {
>+                    $docs_urlbase = "docs/en/html/";
>+                    if (-d "docs/$lang/html") {
>+                        $docs_urlbase = "docs/$lang/html/";
>+                    }
>+                }

Instead of the nested if blocks, why not:

if (lang) {
}
elsif (en) {
}

Do you do it for performance reasons? If not, it would be cleaner to not use nested blocks, IMO. Also, please look for docs/*/html/index.html instead of docs/*/html/, in case the directory is empty.


>+                    if ($2 % 2 != 0) {

Or simply ($2 % 2) alone, or ($2 % 2 == 1).


>+                        # second number is odd; development version
>+                        $version = 'latest';

If the installation uses an old development snapshot (e.g. 3.7), it will point to the wrong documentation. Maybe $2++ would be better.



>--- a/template/en/default/global/common-links.html.tmpl

>-    [% IF doc_section && Param('docs_urlbase') %]
>+    [% IF doc_section && docs_urlbase %]

docs_urlbase is now always defined as it falls back to RTD if necessary. So you only need to test doc_section.



>--- a/template/en/default/global/docslinks.html.tmpl

>-[% IF Param('docs_urlbase') &&
>+[% IF docs_urlbase &&
>       docslinks.keys.size || (admindocslinks.keys.size && user.in_group('admin')) %]

Same here.



>--- a/template/en/default/index.html.tmpl

>-      [% IF Param("docs_urlbase") %]
>+      [% IF docs_urlbase %]

This test can go away entirely.

Comment 9

[Frédéric Buclin]

(In reply to Frédéric Buclin from comment #8)
> If the installation uses an old development snapshot (e.g. 3.7), it will
> point to the wrong documentation. Maybe $2++ would be better.

Ah, I forgot we no longer have control on the server (was bugzilla.org), and so it may be problematic to redirect e.g. 3.7 to 4.0 (as 3.8 doesn't exist). In that case, you can ignore this comment.

Comment 10

[Gervase Markham [:gerv]]

Attachment: Patch v.2

Review comments addressed.

Gerv

Comment 11

[Frédéric Buclin]

Comment on attachment 8537939 [details] [diff] [review]
Patch v.2

>--- a/template/en/default/index.html.tmpl

>+        <a id="help" href="[% docs_urlbase FILTER html %]using.html"><span>Documentation</span></a>

using.html no longer exists. It must be replaced by using/index.html.


r=LpSolit with this fix on checkin.

Comment 12

[Frédéric Buclin]

Comment on attachment 8537939 [details] [diff] [review]
Patch v.2

>--- a/Bugzilla/Template.pm

>+                if (-f "docs/$lang/html/index.html") {

Nit: if ($lang ne 'en' && -f ...)

To avoid trying to access twice the same local file if $lang eq 'en' and the local doc is not compiled.

Comment 13

[David Lawrence [:dkl]]

Please remove all newly introduced whitespace in Bugzilla/Template.pm on checkin.

Comment 14

[:glob ✱]

the 5.0 branch has been feature frozen for a while now; this isn't a bug fix so it shouldn't be committed there.

retargetting for 6.0.

Comment 15

[Gervase Markham [:gerv]]

To ssh://[e-mail]/bugzilla/bugzilla.git
   1365815..323acaa  master -> master

Gerv

Comment 16

[:glob ✱]

(In reply to Byron Jones ‹:glob› from comment #14)
> the 5.0 branch has been feature frozen for a while now; this isn't a bug fix
> so it shouldn't be committed there.

however in bug 1113161 gerv said:
> [now] by default all Help links in 5.0 will be broken.

that means this bug _is_ a bug fix, and can land on 5.0.

Comment 17

[Gervase Markham [:gerv]]

To ssh://[e-mail]/bugzilla/bugzilla.git
   5d0b206..1d1bb36  5.0 -> 5.0

Gerv

Comment 18

[Frédéric Buclin]

Added to relnotes for 5.0rc1.