Bug 19817 - Merge local and online documentations
Summary: Merge local and online documentations
Status: CLOSED FIXED
Alias: None
Product: Koha
Classification: Unclassified
Component: Documentation (show other bugs)
Version: master
Hardware: All All
: P5 - low new feature (vote)
Assignee: Jonathan Druart
QA Contact: Katrin Fischer
URL:
Keywords:
: 11115 19381 (view as bug list)
Depends on: 20706
Blocks: 21481 21483 22687
  Show dependency treegraph
 
Reported: 2017-12-14 21:18 UTC by Jonathan Druart
Modified: 2020-06-04 20:33 UTC (History)
16 users (show)

See Also:
Change sponsored?: ---
Patch complexity: Medium patch
Documentation contact:
Documentation submission:
Text to go in the release notes:
Great strides have been taken to improve Koha's online documentation. This enhancement removes the outdated local help system from the software, opting instead to contextually link to the well maintained online manual.
Version(s) released in:


Attachments
Bug 19817: Redirect to the online manual (19.91 KB, patch)
2017-12-14 21:32 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Remove local help files + edit help feature (496.77 KB, patch)
2017-12-14 21:32 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Make the location of the manual configurable - KohaManualBaseURL (4.06 KB, patch)
2017-12-22 16:35 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Move code to Koha::Manual to make it testable and reusable (36.95 KB, patch)
2017-12-22 16:36 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Add new permission edit_help (1.76 KB, patch)
2017-12-22 16:36 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Redirect to the online manual (19.81 KB, patch)
2018-04-02 14:26 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Remove local help files + edit help feature (496.93 KB, patch)
2018-04-02 14:26 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Make the location of the manual configurable - KohaManualBaseURL (4.06 KB, patch)
2018-04-02 14:27 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Move code to Koha::Manual to make it testable and reusable (36.95 KB, patch)
2018-04-02 14:27 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Add new permission edit_help (2.64 KB, patch)
2018-04-02 14:27 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Add pref KohaManualLanguage (5.53 KB, patch)
2018-04-04 16:36 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Open the manual in a new window, not a popup (853 bytes, patch)
2018-04-04 16:36 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Use the language from the interface if valid (3.84 KB, patch)
2018-04-09 14:34 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Use the language from the interface if valid (3.76 KB, patch)
2018-04-09 15:44 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Redirect to the online manual (19.81 KB, patch)
2018-04-10 14:11 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Remove local help files + edit help feature (496.94 KB, patch)
2018-04-10 14:11 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Make the location of the manual configurable - KohaManualBaseURL (4.06 KB, patch)
2018-04-10 14:11 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Move code to Koha::Manual to make it testable and reusable (36.95 KB, patch)
2018-04-10 14:11 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Add pref KohaManualLanguage (4.34 KB, patch)
2018-04-10 14:11 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Open the manual in a new window, not a popup (853 bytes, patch)
2018-04-10 14:11 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Use the language from the interface if valid (3.76 KB, patch)
2018-04-10 14:11 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: use https instead of http (4.41 KB, patch)
2018-04-10 14:11 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Redirect to the online manual (19.81 KB, patch)
2018-04-19 14:42 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Remove local help files + edit help feature (496.23 KB, patch)
2018-04-19 14:43 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Make the location of the manual configurable - KohaManualBaseURL (4.06 KB, patch)
2018-04-19 14:43 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Move code to Koha::Manual to make it testable and reusable (36.95 KB, patch)
2018-04-19 14:43 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Add pref KohaManualLanguage (4.34 KB, patch)
2018-04-19 14:43 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Open the manual in a new window, not a popup (853 bytes, patch)
2018-04-19 14:43 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Use the language from the interface if valid (3.76 KB, patch)
2018-04-19 14:43 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: use https instead of http (4.41 KB, patch)
2018-04-19 14:43 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Redirect to the online manual (19.81 KB, patch)
2018-04-20 14:04 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Remove local help files + edit help feature (496.25 KB, patch)
2018-04-20 14:04 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Make the location of the manual configurable - KohaManualBaseURL (4.06 KB, patch)
2018-04-20 14:05 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Move code to Koha::Manual to make it testable and reusable (36.95 KB, patch)
2018-04-20 14:05 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Add pref KohaManualLanguage (4.34 KB, patch)
2018-04-20 14:05 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Open the manual in a new window, not a popup (853 bytes, patch)
2018-04-20 14:05 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Use the language from the interface if valid (3.76 KB, patch)
2018-04-20 14:05 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: use https instead of http (4.41 KB, patch)
2018-04-20 14:05 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Redirect to the online manual (19.81 KB, patch)
2018-05-16 14:37 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Remove local help files + edit help feature (496.21 KB, patch)
2018-05-16 14:37 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Make the location of the manual configurable - KohaManualBaseURL (4.06 KB, patch)
2018-05-16 14:38 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Move code to Koha::Manual to make it testable and reusable (36.95 KB, patch)
2018-05-16 14:38 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Add pref KohaManualLanguage (4.34 KB, patch)
2018-05-16 14:38 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Open the manual in a new window, not a popup (853 bytes, patch)
2018-05-16 14:38 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Use the language from the interface if valid (3.76 KB, patch)
2018-05-16 14:38 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: use https instead of http (4.41 KB, patch)
2018-05-16 14:38 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Redirect to the online manual (19.81 KB, patch)
2018-06-18 19:27 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Remove local help files + edit help feature (496.01 KB, patch)
2018-06-18 19:27 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Make the location of the manual configurable - KohaManualBaseURL (4.06 KB, patch)
2018-06-18 19:27 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Move code to Koha::Manual to make it testable and reusable (36.95 KB, patch)
2018-06-18 19:27 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Add pref KohaManualLanguage (4.34 KB, patch)
2018-06-18 19:27 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Open the manual in a new window, not a popup (853 bytes, patch)
2018-06-18 19:27 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Use the language from the interface if valid (3.76 KB, patch)
2018-06-18 19:28 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: use https instead of http (4.41 KB, patch)
2018-06-18 19:28 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Redirect to the online manual (19.87 KB, patch)
2018-08-14 15:12 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 19817: Remove local help files + edit help feature (494.99 KB, patch)
2018-08-14 15:13 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 19817: Make the location of the manual configurable - KohaManualBaseURL (4.09 KB, patch)
2018-08-14 15:13 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 19817: Move code to Koha::Manual to make it testable and reusable (37.00 KB, patch)
2018-08-14 15:13 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 19817: Add pref KohaManualLanguage (4.38 KB, patch)
2018-08-14 15:13 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 19817: Open the manual in a new window, not a popup (920 bytes, patch)
2018-08-14 15:13 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 19817: Use the language from the interface if valid (3.80 KB, patch)
2018-08-14 15:13 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 19817: use https instead of http (4.45 KB, patch)
2018-08-14 15:13 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 19817: Remove numbering from chapter file names (33.66 KB, patch)
2018-08-16 15:01 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 19817: Redirect to the online manual (19.93 KB, patch)
2018-08-16 19:19 UTC, Katrin Fischer
Details | Diff | Splinter Review
Bug 19817: Remove local help files + edit help feature (494.88 KB, patch)
2018-08-16 19:19 UTC, Katrin Fischer
Details | Diff | Splinter Review
Bug 19817: Make the location of the manual configurable - KohaManualBaseURL (4.15 KB, patch)
2018-08-16 19:20 UTC, Katrin Fischer
Details | Diff | Splinter Review
Bug 19817: Move code to Koha::Manual to make it testable and reusable (37.06 KB, patch)
2018-08-16 19:20 UTC, Katrin Fischer
Details | Diff | Splinter Review
Bug 19817: Add pref KohaManualLanguage (4.44 KB, patch)
2018-08-16 19:20 UTC, Katrin Fischer
Details | Diff | Splinter Review
Bug 19817: Open the manual in a new window, not a popup (971 bytes, patch)
2018-08-16 19:20 UTC, Katrin Fischer
Details | Diff | Splinter Review
Bug 19817: Use the language from the interface if valid (3.86 KB, patch)
2018-08-16 19:20 UTC, Katrin Fischer
Details | Diff | Splinter Review
Bug 19817: use https instead of http (4.51 KB, patch)
2018-08-16 19:20 UTC, Katrin Fischer
Details | Diff | Splinter Review
Bug 19817: Remove numbering from chapter file names (33.71 KB, patch)
2018-08-16 19:20 UTC, Katrin Fischer
Details | Diff | Splinter Review
Bug 19817: (QA follow-up) Add German manual and fix system preference help files (4.85 KB, patch)
2018-08-16 19:20 UTC, Katrin Fischer
Details | Diff | Splinter Review
Bug 19817: (follow-up) Remove local help files + edit help feature (487.31 KB, patch)
2018-09-16 17:26 UTC, Jonathan Druart
Details | Diff | Splinter Review
Fix Portuguese manual link (17.87 KB, patch)
2019-03-30 11:13 UTC, Humberto Chula
Details | Diff | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Jonathan Druart 2017-12-14 21:18:34 UTC
We are currently maintaining a local (help/* files) and online (https://koha-community.org/manual) documentations.
They must be merged to ease the maintainability and improve the relevance.
The online manual has been improved greatly the last months and the obvious solution would be to point to it from the different Koha installations.

Here is the different steps I have in mind:
- Remove existing local documentation
- Point to the relevant pages of the online documentation
- Make the online documentation configurable to add the ability to point to a local copy (for offline access)
- Re-add the ability to edit the manual

It would make sense to have a koha-manual package depending on sphinx and copy the related .rst files (depending on the Koha version). Then a script will be provided (koha-build-manual) to regenerate the manual (after an update for instance) in different languages.

For the local edition we could imagine to add add local commits when a change is made. Advanced users/administrators will then need to rebase and eventually fix the conflicts.
Comment 1 Jonathan Druart 2017-12-14 21:18:55 UTC
*** Bug 19381 has been marked as a duplicate of this bug. ***
Comment 2 Jonathan Druart 2017-12-14 21:32:48 UTC
Created attachment 69807 [details] [review]
Bug 19817: Redirect to the online manual
Comment 3 Jonathan Druart 2017-12-14 21:32:58 UTC
Created attachment 69808 [details] [review]
Bug 19817: Remove local help files + edit help feature
Comment 4 Jonathan Druart 2017-12-22 16:35:39 UTC
Created attachment 70131 [details] [review]
Bug 19817: Make the location of the manual configurable - KohaManualBaseURL
Comment 5 Jonathan Druart 2017-12-22 16:36:07 UTC
Created attachment 70132 [details] [review]
Bug 19817: Move code to Koha::Manual to make it testable and reusable
Comment 6 Jonathan Druart 2017-12-22 16:36:21 UTC
Created attachment 70133 [details] [review]
Bug 19817: Add new permission edit_help

Change in existing behaviour!
Comment 7 Jonathan Druart 2017-12-22 16:45:08 UTC
Next step is to re-add the ability to "edit the manual".
I would suggest to remove the possibility to edit the manual, but allow to create new pages (which will not be erased on update).

I need to know what are the different use cases and needs.

We need also to think about an ergonomic way to manage these additional help files.
For instance: in the top right of the staff pages we will have a "Help" group buttons with
  Link to the official manual | Add a new page
And when new pages are created:
  Link to the official manual | Additional pages 1..N | Add a new page

The additional pages would be linked to a specific page of the staff interface (see the mapping in Koha::Manual)

Does it make sense? Other ideas/opinions?
Comment 8 Katrin Fischer 2018-04-01 16:19:01 UTC
(In reply to Jonathan Druart from comment #7)
> Next step is to re-add the ability to "edit the manual".
> I would suggest to remove the possibility to edit the manual, but allow to
> create new pages (which will not be erased on update).
> 
> I need to know what are the different use cases and needs.

Possible use cases I could see for local help files:
- Being able to explain custom fields like authorised values, patron attributes etc.
- Being able to explain how to use collections, locations, item types
- Offer local help for cataloguing like explanations for fields and subfields, internal standards and agreements


> We need also to think about an ergonomic way to manage these additional help
> files.
> For instance: in the top right of the staff pages we will have a "Help"
> group buttons with
>   Link to the official manual | Add a new page
> And when new pages are created:
>   Link to the official manual | Additional pages 1..N | Add a new page
> 
> The additional pages would be linked to a specific page of the staff
> interface (see the mapping in Koha::Manual)
> 
> Does it make sense? Other ideas/opinions?

That makes sense to me. I think having a HTML based editor would be better than .rst for the local help files and that we should store them in the database.
Comment 9 Katrin Fischer 2018-04-01 16:25:40 UTC
Hi Jonathan, can you please rebase? I tried but it got a bit chaotic.

I think you are missing the change to koha-tmpl/intranet-tmpl/prog/en/includes/permissions.inc for the new permission.
Comment 10 Jonathan Druart 2018-04-02 14:26:52 UTC
Created attachment 73523 [details] [review]
Bug 19817: Redirect to the online manual
Comment 11 Jonathan Druart 2018-04-02 14:26:58 UTC
Created attachment 73524 [details] [review]
Bug 19817: Remove local help files + edit help feature
Comment 12 Jonathan Druart 2018-04-02 14:27:02 UTC
Created attachment 73525 [details] [review]
Bug 19817: Make the location of the manual configurable - KohaManualBaseURL
Comment 13 Jonathan Druart 2018-04-02 14:27:06 UTC
Created attachment 73526 [details] [review]
Bug 19817: Move code to Koha::Manual to make it testable and reusable
Comment 14 Jonathan Druart 2018-04-02 14:27:11 UTC
Created attachment 73527 [details] [review]
Bug 19817: Add new permission edit_help

Change in existing behaviour!
Comment 15 Jonathan Druart 2018-04-02 14:29:39 UTC
Done, note that the last patch does nothing (new permission is not used).
Comment 16 Katrin Fischer 2018-04-02 21:01:33 UTC
Hi Jonathan, 

some thoughts:

1) sub _get_base_url doesn't look quite right yet.
a) It hardcodes en. Ideally we should try to check for the existence of a translated manual and use that, with a fallback to en. If we can't do that, we'll maybe need to add a pref where you can add the lanugage codes to use.
b) For the local manual URL you combine:
C4::Context->preference('staffClientBaseURL') . $KohaManualBaseURL;
I think it might be good to allow for a full URL in KohaManualBaseURL. That way you could have the help on the same server or at another location.

2) If the permission doesn't work yet, I would not include it :)

3) The manual layout doesn't work well in the small pop up. I wonder if there is a way to leave off the side navigation, but probably we can just make the window a bit wider.
Comment 17 paxed 2018-04-04 09:08:01 UTC
The manual should first try to be in the currently used UI language, and then whatever other fallbacks there are (with "en" as the last, hardcoded one)

or

if fallbacks aren't feasible, the non-existing-manual page on koha-community could show something like "The manual does not exist for the language $foo. You can read the [manual in english], or [translate the manual]", with links to the actual manual in english and to the wiki article on how to start translation.
Comment 18 Jonathan Druart 2018-04-04 16:36:12 UTC
Created attachment 73651 [details] [review]
Bug 19817: Add pref KohaManualLanguage
Comment 19 Jonathan Druart 2018-04-04 16:36:17 UTC
Created attachment 73652 [details] [review]
Bug 19817: Open the manual in a new window, not a popup
Comment 20 Jonathan Druart 2018-04-04 16:38:03 UTC
(In reply to Katrin Fischer from comment #16)
> Hi Jonathan, 
> 
> some thoughts:
> 
> 1) sub _get_base_url doesn't look quite right yet.
> a) It hardcodes en. Ideally we should try to check for the existence of a
> translated manual and use that, with a fallback to en. If we can't do that,
> we'll maybe need to add a pref where you can add the lanugage codes to use.

I have added a patch to add a new pref KohaManualLanguage

> b) For the local manual URL you combine:
> C4::Context->preference('staffClientBaseURL') . $KohaManualBaseURL;
> I think it might be good to allow for a full URL in KohaManualBaseURL. That
> way you could have the help on the same server or at another location.

The concatenation is done only if the pref does not start with '/', so you can use a value starting with 'http://'

> 2) If the permission doesn't work yet, I would not include it :)

Patch removed.

> 3) The manual layout doesn't work well in the small pop up. I wonder if
> there is a way to leave off the side navigation, but probably we can just
> make the window a bit wider.

Done.
Comment 21 Katrin Fischer 2018-04-08 08:19:03 UTC
I think the pref is too limiting for a lot of multilingual instances still. Could we make it work like that? 

Make the manual pref a list of language codes to existing manuals. Try to open the manual in the current GUI language first using the list to verify if it exists. If it doesn't match one of the language codes, use the first code in the list as a fallback.

We could start the list off with all the existing manuals and first language en, but it would be easy to add new ones.
Comment 22 Jonathan Druart 2018-04-09 14:34:14 UTC
Created attachment 73872 [details] [review]
Bug 19817: Use the language from the interface if valid

Use the UI language for the manual, if exists. Use the pref as a
fallback.

With the call to get_template_and_user the value of preferred_language
switched from 'es' (spanish) to 'en' from one click to another (??)
Comment 23 Jonathan Druart 2018-04-09 15:44:12 UTC
Created attachment 73877 [details] [review]
Bug 19817: Use the language from the interface if valid

Use the UI language for the manual, if exists. Use the pref as a
fallback.

With the call to get_template_and_user the value of preferred_language
switched from 'es' (spanish) to 'en' from one click to another (??)
Comment 24 Mark Tompsett 2018-04-09 19:32:43 UTC
Comment on attachment 73523 [details] [review]
Bug 19817: Redirect to the online manual

Review of attachment 73523 [details] [review]:
-----------------------------------------------------------------

::: help.pl
@@ +1,3 @@
>  #!/usr/bin/perl
>  
> +# Copyright 2017 Koha Development team

I would prefer 2010-2017 or even 2010,2017 so we do not lose track of the original date in quickly obvious statement.
(https://www.plagiarismtoday.com/2011/11/08/how-to-write-a-copyright-notice/)
Comment 25 Mark Tompsett 2018-04-09 23:14:10 UTC Comment hidden (obsolete)
Comment 26 Mark Tompsett 2018-04-09 23:17:25 UTC Comment hidden (obsolete)
Comment 27 Mark Tompsett 2018-04-09 23:23:55 UTC Comment hidden (obsolete)
Comment 28 Mark Tompsett 2018-04-10 01:13:07 UTC Comment hidden (obsolete)
Comment 29 Mark Tompsett 2018-04-10 01:37:37 UTC
Preliminary testing was generally positive. Though, I think these points should be discussed, if not addressed, before considering sign off.

- https vs http in the urls used.
- choice vs multiple in the added KohaManualLanguage sys pref
- help.pl removed from 00-strict.t
- postfix slash the default URL creates a // in the URL.
  remove the '/' in the URL building in Koha::Manual?
  build smarter?

kshell
cd misc/translator
for i in `ls po | cut -f1-2 -d'-' | sed -e "s#-opac##g" | sed -e "s#-pref.po##g" | sed -e "s#-staff##g" | sed -e "s#-marc##g" | sort -u`; do echo $i;perl translate install $i;done
-- noisy! Though, I suspect correct.
perhaps help po files need to be deleted too?
Comment 30 Jonathan Druart 2018-04-10 14:11:17 UTC
Created attachment 73931 [details] [review]
Bug 19817: Redirect to the online manual
Comment 31 Jonathan Druart 2018-04-10 14:11:25 UTC
Created attachment 73932 [details] [review]
Bug 19817: Remove local help files + edit help feature
Comment 32 Jonathan Druart 2018-04-10 14:11:29 UTC
Created attachment 73933 [details] [review]
Bug 19817: Make the location of the manual configurable - KohaManualBaseURL
Comment 33 Jonathan Druart 2018-04-10 14:11:33 UTC
Created attachment 73934 [details] [review]
Bug 19817: Move code to Koha::Manual to make it testable and reusable
Comment 34 Jonathan Druart 2018-04-10 14:11:37 UTC
Created attachment 73935 [details] [review]
Bug 19817: Add pref KohaManualLanguage
Comment 35 Jonathan Druart 2018-04-10 14:11:41 UTC
Created attachment 73936 [details] [review]
Bug 19817: Open the manual in a new window, not a popup
Comment 36 Jonathan Druart 2018-04-10 14:11:45 UTC
Created attachment 73937 [details] [review]
Bug 19817: Use the language from the interface if valid

Use the UI language for the manual, if exists. Use the pref as a
fallback.

With the call to get_template_and_user the value of preferred_language
switched from 'es' (spanish) to 'en' from one click to another (??)
Comment 37 Jonathan Druart 2018-04-10 14:11:49 UTC
Created attachment 73938 [details] [review]
Bug 19817: use https instead of http

the https version was not working when I wrote the first patches
Comment 38 Jonathan Druart 2018-04-10 14:15:40 UTC
(In reply to M. Tompsett from comment #29)
> Preliminary testing was generally positive. Though, I think these points
> should be discussed, if not addressed, before considering sign off.

Thanks for catching those things. I have marked as obsolete the other comments (they are the verbose version of the next 5 lines)

> - https vs http in the urls used.

Yes, in the meanwhile I have asked rangi to enable https on the manual (was not there before).

> - choice vs multiple in the added KohaManualLanguage sys pref

It's a choice indeed.

> - help.pl removed from 00-strict.t

Re-added

> - postfix slash the default URL creates a // in the URL.
>   remove the '/' in the URL building in Koha::Manual?
>   build smarter?

I do not understand what you suggest here.

> kshell
> cd misc/translator
> for i in `ls po | cut -f1-2 -d'-' | sed -e "s#-opac##g" | sed -e
> "s#-pref.po##g" | sed -e "s#-staff##g" | sed -e "s#-marc##g" | sort -u`; do
> echo $i;perl translate install $i;done
> -- noisy! Though, I suspect correct.
> perhaps help po files need to be deleted too?

I do not think so, should be deleted on releasing (there are certainly other things to do in the release scripts).
Comment 39 Katrin Fischer 2018-04-19 07:03:31 UTC
The patches don't apply right now - can you take a look? Looking at the last comments:

1) Removing the po files on release date would make sense to me.

2)
>> - postfix slash the default URL creates a // in the URL.
>>   remove the '/' in the URL building in Koha::Manual?
>>   build smarter?

I think we expect people to get it right for BaseURLs already. so no need to be more strict here. (Do not enter trailing slash)

3) 
>> - choice vs multiple in the added KohaManualLanguage sys pref

>It's a choice indeed.

Hm, what I was thinking about was a multiple indeed. We usually have at least German and English installed for staff, often Spanish and French now too. I would like to use the pref to indicate existing manuals for staff activated languages. So when I open the help and it matches one of the selected languages I get the right language manual. Makes sense?
Comment 40 Jonathan Druart 2018-04-19 14:42:58 UTC
Created attachment 74567 [details] [review]
Bug 19817: Redirect to the online manual
Comment 41 Jonathan Druart 2018-04-19 14:43:07 UTC
Created attachment 74568 [details] [review]
Bug 19817: Remove local help files + edit help feature
Comment 42 Jonathan Druart 2018-04-19 14:43:12 UTC
Created attachment 74569 [details] [review]
Bug 19817: Make the location of the manual configurable - KohaManualBaseURL
Comment 43 Jonathan Druart 2018-04-19 14:43:17 UTC
Created attachment 74570 [details] [review]
Bug 19817: Move code to Koha::Manual to make it testable and reusable
Comment 44 Jonathan Druart 2018-04-19 14:43:22 UTC
Created attachment 74571 [details] [review]
Bug 19817: Add pref KohaManualLanguage
Comment 45 Jonathan Druart 2018-04-19 14:43:27 UTC
Created attachment 74572 [details] [review]
Bug 19817: Open the manual in a new window, not a popup
Comment 46 Jonathan Druart 2018-04-19 14:43:31 UTC
Created attachment 74573 [details] [review]
Bug 19817: Use the language from the interface if valid

Use the UI language for the manual, if exists. Use the pref as a
fallback.

With the call to get_template_and_user the value of preferred_language
switched from 'es' (spanish) to 'en' from one click to another (??)
Comment 47 Jonathan Druart 2018-04-19 14:43:36 UTC
Created attachment 74574 [details] [review]
Bug 19817: use https instead of http

the https version was not working when I wrote the first patches
Comment 48 Jonathan Druart 2018-04-19 14:47:43 UTC
(In reply to Katrin Fischer from comment #39)
> 3) 
> >> - choice vs multiple in the added KohaManualLanguage sys pref
> 
> >It's a choice indeed.
> 
> Hm, what I was thinking about was a multiple indeed. We usually have at
> least German and English installed for staff, often Spanish and French now
> too. I would like to use the pref to indicate existing manuals for staff
> activated languages. So when I open the help and it matches one of the
> selected languages I get the right language manual. Makes sense?

The pref is the default value.

If the pref is set to English and the interface is in Spanish, the manual will be in Spanish. If the interface is in Esperanto, the manual will be in English (the manual is not translated in Esperanto, yet).
Comment 49 Katrin Fischer 2018-04-20 06:00:42 UTC
What if the selected language doesn't have an existing manual?
Comment 50 Katrin Fischer 2018-04-20 06:01:21 UTC
My idea was to use the pref as a white list of existing manuals, because I was not sure we can tell and not have it end up on an error page.
Comment 51 Jonathan Druart 2018-04-20 14:02:05 UTC
To me it does not make sense to make it a free text.
We could retrieve the available languages from the syspref options, it will avoid to have it hardcoded in the code. And then a quick SQL query will allow to extend the list.
I do not think it should be a blocker anyway.
Comment 52 Jonathan Druart 2018-04-20 14:04:51 UTC
Created attachment 74644 [details] [review]
Bug 19817: Redirect to the online manual
Comment 53 Jonathan Druart 2018-04-20 14:04:59 UTC
Created attachment 74645 [details] [review]
Bug 19817: Remove local help files + edit help feature
Comment 54 Jonathan Druart 2018-04-20 14:05:04 UTC
Created attachment 74646 [details] [review]
Bug 19817: Make the location of the manual configurable - KohaManualBaseURL
Comment 55 Jonathan Druart 2018-04-20 14:05:08 UTC
Created attachment 74647 [details] [review]
Bug 19817: Move code to Koha::Manual to make it testable and reusable
Comment 56 Jonathan Druart 2018-04-20 14:05:13 UTC
Created attachment 74648 [details] [review]
Bug 19817: Add pref KohaManualLanguage
Comment 57 Jonathan Druart 2018-04-20 14:05:18 UTC
Created attachment 74649 [details] [review]
Bug 19817: Open the manual in a new window, not a popup
Comment 58 Jonathan Druart 2018-04-20 14:05:22 UTC
Created attachment 74650 [details] [review]
Bug 19817: Use the language from the interface if valid

Use the UI language for the manual, if exists. Use the pref as a
fallback.

With the call to get_template_and_user the value of preferred_language
switched from 'es' (spanish) to 'en' from one click to another (??)
Comment 59 Jonathan Druart 2018-04-20 14:05:27 UTC
Created attachment 74651 [details] [review]
Bug 19817: use https instead of http

the https version was not working when I wrote the first patches
Comment 60 Jonathan Druart 2018-05-16 14:37:47 UTC
Created attachment 75370 [details] [review]
Bug 19817: Redirect to the online manual
Comment 61 Jonathan Druart 2018-05-16 14:37:58 UTC
Created attachment 75371 [details] [review]
Bug 19817: Remove local help files + edit help feature
Comment 62 Jonathan Druart 2018-05-16 14:38:06 UTC
Created attachment 75372 [details] [review]
Bug 19817: Make the location of the manual configurable - KohaManualBaseURL
Comment 63 Jonathan Druart 2018-05-16 14:38:11 UTC
Created attachment 75373 [details] [review]
Bug 19817: Move code to Koha::Manual to make it testable and reusable
Comment 64 Jonathan Druart 2018-05-16 14:38:17 UTC
Created attachment 75374 [details] [review]
Bug 19817: Add pref KohaManualLanguage
Comment 65 Jonathan Druart 2018-05-16 14:38:21 UTC
Created attachment 75375 [details] [review]
Bug 19817: Open the manual in a new window, not a popup
Comment 66 Jonathan Druart 2018-05-16 14:38:26 UTC
Created attachment 75376 [details] [review]
Bug 19817: Use the language from the interface if valid

Use the UI language for the manual, if exists. Use the pref as a
fallback.

With the call to get_template_and_user the value of preferred_language
switched from 'es' (spanish) to 'en' from one click to another (??)
Comment 67 Jonathan Druart 2018-05-16 14:38:31 UTC
Created attachment 75377 [details] [review]
Bug 19817: use https instead of http

the https version was not working when I wrote the first patches
Comment 68 Jonathan Druart 2018-05-16 14:38:57 UTC
Rebased on top of bug 20706.
Comment 69 Owen Leonard 2018-05-31 16:21:57 UTC
Is there more of a test plan than "click the help link on a bunch of pages?"
Comment 70 Jonathan Druart 2018-05-31 17:14:23 UTC
(In reply to Owen Leonard from comment #69)
> Is there more of a test plan than "click the help link on a bunch of pages?"

Yes, definitely.
This change is more a philosophical changes, we are going to remove the local manual.

To test the whole patchset you will need to play with KohaManualBaseURL and KohaManualLanguage and make sure the links are still working and redirect to the correct url.
Comment 71 Caroline Cyr La Rose 2018-06-15 19:14:34 UTC
I had a bit of trouble applying the patch. I had to add member-flags.tt and then continue applying the patch. I don't know if that's normal or not.

I went to Global system preferences and clicked on the tab for circulation. When I clicked help, the manual was at the beginning of the sysprefs section. I don't know if it's possible at all to point to the right sub-section? It's just that are sooooo many system preferences...

My KohaManualLanguage is on Arabic by default. I'm guessing it's the first language in the list, but if I don't change it will this be the default? Should we put English by default instead of Arabic?

I also don't see the edit button mentioned in comment 7. Was that implemented or just an idea for a future development? It could be a second patch. People don't currently have the ability to modify from the staff interface, so it wouldn't necessarily be a step back. More advanced users can still use their own help files.

I wasn't able to test switching languages because my master is only installed in English.

It's a great development! It will be much easier to translate, no need to translate the help file, just the manual. It will also be more uniform.
Comment 72 Jonathan Druart 2018-06-18 19:26:50 UTC
(In reply to Caroline Cyr La Rose from comment #71)
> I had a bit of trouble applying the patch. I had to add member-flags.tt and
> then continue applying the patch. I don't know if that's normal or not.

Yes, conflict. I am going to re-attached a rebased version of these patches.

> I went to Global system preferences and clicked on the tab for circulation.
> When I clicked help, the manual was at the beginning of the sysprefs
> section. I don't know if it's possible at all to point to the right
> sub-section? It's just that are sooooo many system preferences...

It should be the same behaviour as prior to the patch. We can imagine a link close to each pref to point to the dedicated section of the manual.
TODO later ;)

> My KohaManualLanguage is on Arabic by default. I'm guessing it's the first
> language in the list, but if I don't change it will this be the default?
> Should we put English by default instead of Arabic?

I guess you did not execute the updatedatabase.pl script. The default value is "en".

> I also don't see the edit button mentioned in comment 7. Was that
> implemented or just an idea for a future development? It could be a second
> patch. People don't currently have the ability to modify from the staff
> interface, so it wouldn't necessarily be a step back. More advanced users
> can still use their own help files.

The original plan was to provide a full help system, local editing (on top of git repository), etc.
I have asked several time on the mailing lists and during IRC meetings to get feedbacks and ideas. I did not get answers and I am no longer willing to provide such enhancements. Maybe later...

> I wasn't able to test switching languages because my master is only
> installed in English.

You can install a couple with:
  sudo koha-translate --install fr-CA --dev kohadev
  sudo koha-translate --install it-IT --dev kohadev

> It's a great development! It will be much easier to translate, no need to
> translate the help file, just the manual. It will also be more uniform.
Comment 73 Jonathan Druart 2018-06-18 19:27:26 UTC
Created attachment 76151 [details] [review]
Bug 19817: Redirect to the online manual
Comment 74 Jonathan Druart 2018-06-18 19:27:33 UTC
Created attachment 76152 [details] [review]
Bug 19817: Remove local help files + edit help feature
Comment 75 Jonathan Druart 2018-06-18 19:27:38 UTC
Created attachment 76153 [details] [review]
Bug 19817: Make the location of the manual configurable - KohaManualBaseURL
Comment 76 Jonathan Druart 2018-06-18 19:27:44 UTC
Created attachment 76154 [details] [review]
Bug 19817: Move code to Koha::Manual to make it testable and reusable
Comment 77 Jonathan Druart 2018-06-18 19:27:49 UTC
Created attachment 76155 [details] [review]
Bug 19817: Add pref KohaManualLanguage
Comment 78 Jonathan Druart 2018-06-18 19:27:55 UTC
Created attachment 76156 [details] [review]
Bug 19817: Open the manual in a new window, not a popup
Comment 79 Jonathan Druart 2018-06-18 19:28:00 UTC
Created attachment 76157 [details] [review]
Bug 19817: Use the language from the interface if valid

Use the UI language for the manual, if exists. Use the pref as a
fallback.

With the call to get_template_and_user the value of preferred_language
switched from 'es' (spanish) to 'en' from one click to another (??)
Comment 80 Jonathan Druart 2018-06-18 19:28:05 UTC
Created attachment 76158 [details] [review]
Bug 19817: use https instead of http

the https version was not working when I wrote the first patches
Comment 81 Martin Renvoize 2018-08-14 14:58:17 UTC
*** Bug 11115 has been marked as a duplicate of this bug. ***
Comment 82 Martin Renvoize 2018-08-14 15:12:55 UTC
Created attachment 77791 [details] [review]
Bug 19817: Redirect to the online manual

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 83 Martin Renvoize 2018-08-14 15:13:02 UTC
Created attachment 77792 [details] [review]
Bug 19817: Remove local help files + edit help feature

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 84 Martin Renvoize 2018-08-14 15:13:08 UTC
Created attachment 77793 [details] [review]
Bug 19817: Make the location of the manual configurable - KohaManualBaseURL

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 85 Martin Renvoize 2018-08-14 15:13:14 UTC
Created attachment 77794 [details] [review]
Bug 19817: Move code to Koha::Manual to make it testable and reusable

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 86 Martin Renvoize 2018-08-14 15:13:23 UTC
Created attachment 77795 [details] [review]
Bug 19817: Add pref KohaManualLanguage

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 87 Martin Renvoize 2018-08-14 15:13:30 UTC
Created attachment 77797 [details] [review]
Bug 19817: Open the manual in a new window, not a popup

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 88 Martin Renvoize 2018-08-14 15:13:36 UTC
Created attachment 77798 [details] [review]
Bug 19817: Use the language from the interface if valid

Use the UI language for the manual, if exists. Use the pref as a
fallback.

With the call to get_template_and_user the value of preferred_language
switched from 'es' (spanish) to 'en' from one click to another (??)

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 89 Martin Renvoize 2018-08-14 15:13:42 UTC
Created attachment 77799 [details] [review]
Bug 19817: use https instead of http

the https version was not working when I wrote the first patches

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 90 Martin Renvoize 2018-08-14 15:15:22 UTC
All seems to work for me, signing off.
Comment 91 Katrin Fischer 2018-08-16 06:15:45 UTC
There is something not quite right with the default URL and mappings. We have since removed the chapter numbers from the file names in Sphinx, but the patches seem to link to an outdated version of the manual:

https://koha-community.org/manual/18.05/en/html/09_acquisitions.html#acquisition-searches

vs correct:

https://koha-community.org/manual/18.05/en/html/acquisitions.html#acquisition-searches

Have to stop working on this for now, hope to be back later today. If you beat me to fixing this. I'd not be unhappy about it :)
Comment 92 Katrin Fischer 2018-08-16 06:16:43 UTC
Also: t/db_dependent/00-strict.t fails for me, but because of Overdrive. How to fix? CPAN?
Comment 93 Jonathan Druart 2018-08-16 15:01:28 UTC
Created attachment 77932 [details] [review]
Bug 19817: Remove numbering from chapter file names

See commit 8ad495abf1e42c5e73c5cb62ec32e1a54d16f8e8
    Remove numbering from chapter file names
from koha-manual
Comment 94 Jonathan Druart 2018-08-16 15:02:26 UTC
(In reply to Katrin Fischer from comment #92)
> Also: t/db_dependent/00-strict.t fails for me, but because of Overdrive. How
> to fix? CPAN?

I guess so, yes. But for sure you get it against master as well, it's not related with those patches.
Comment 95 Katrin Fischer 2018-08-16 15:43:14 UTC
(In reply to Jonathan Druart from comment #94)
> (In reply to Katrin Fischer from comment #92)
> > Also: t/db_dependent/00-strict.t fails for me, but because of Overdrive. How
> > to fix? CPAN?
> 
> I guess so, yes. But for sure you get it against master as well, it's not
> related with those patches.

I know it's not related - but this patch set changes the test and the failure keeps me from testing that part. :)
Comment 96 Katrin Fischer 2018-08-16 19:19:48 UTC
Created attachment 77942 [details] [review]
Bug 19817: Redirect to the online manual

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>
Comment 97 Katrin Fischer 2018-08-16 19:19:57 UTC
Created attachment 77943 [details] [review]
Bug 19817: Remove local help files + edit help feature

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>
Comment 98 Katrin Fischer 2018-08-16 19:20:03 UTC
Created attachment 77944 [details] [review]
Bug 19817: Make the location of the manual configurable - KohaManualBaseURL

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>
Comment 99 Katrin Fischer 2018-08-16 19:20:10 UTC
Created attachment 77945 [details] [review]
Bug 19817: Move code to Koha::Manual to make it testable and reusable

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>
Comment 100 Katrin Fischer 2018-08-16 19:20:16 UTC
Created attachment 77946 [details] [review]
Bug 19817: Add pref KohaManualLanguage

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>
Comment 101 Katrin Fischer 2018-08-16 19:20:23 UTC
Created attachment 77947 [details] [review]
Bug 19817: Open the manual in a new window, not a popup

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>
Comment 102 Katrin Fischer 2018-08-16 19:20:31 UTC
Created attachment 77948 [details] [review]
Bug 19817: Use the language from the interface if valid

Use the UI language for the manual, if exists. Use the pref as a
fallback.

With the call to get_template_and_user the value of preferred_language
switched from 'es' (spanish) to 'en' from one click to another (??)

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>
Comment 103 Katrin Fischer 2018-08-16 19:20:38 UTC
Created attachment 77949 [details] [review]
Bug 19817: use https instead of http

the https version was not working when I wrote the first patches

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>
Comment 104 Katrin Fischer 2018-08-16 19:20:45 UTC
Created attachment 77950 [details] [review]
Bug 19817: Remove numbering from chapter file names

See commit 8ad495abf1e42c5e73c5cb62ec32e1a54d16f8e8
    Remove numbering from chapter file names
from koha-manual

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>
Comment 105 Katrin Fischer 2018-08-16 19:20:52 UTC
Created attachment 77951 [details] [review]
Bug 19817: (QA follow-up) Add German manual and fix system preference help files

- German language manuals were added since this patch was started
- The structure of the manual was changed slightly, system
  preferences were moved into their own chapter

To test:
- Test help files display correctly for system preferences display correctly
  Note: Local use uses a different page than the other tabs
- Test German shows up as option in KohaManualLanguage and links
  correctly
Comment 106 Nick Clemens 2018-09-06 17:38:46 UTC
Awesome work all! 

Pushed to master for 18.11
Comment 107 Martin Renvoize 2018-09-11 08:12:15 UTC
New feature, this will not be backported to 18.05.x series.
Comment 108 Jonathan Druart 2018-09-16 17:26:51 UTC
Created attachment 78953 [details] [review]
Bug 19817: (follow-up) Remove local help files + edit help feature

I have no idea what happened but RM did not rebase that one correctly
before pushing it ;)
Comment 109 Nick Clemens 2018-09-16 18:24:27 UTC
(In reply to Jonathan Druart from comment #108)
> Created attachment 78953 [details] [review] [review]
> Bug 19817: (follow-up) Remove local help files + edit help feature
> 
> I have no idea what happened but RM did not rebase that one correctly
> before pushing it ;)

What happened = The RM goofed

Follow-up pushed to master
Comment 110 Humberto Chula 2019-03-29 20:11:14 UTC
Setting KohaManualBaseURL to https://koha-community.org/manual and 
using user interface language pt~PT, the help link is redirected (for example) to https://koha-community.org/manual/18.11/pt_BZ/html/systempreferences.html displaying an error page.

I guess its related with a typo on line 22 in the file Manual.pm 
22    my @available_languages = qw( en ar cs es fr it pt_BZ tz zh_TW );

Tested replacing the value pt_BZ by pt_BR and the link now works.
Comment 111 Humberto Chula 2019-03-30 11:13:40 UTC
Created attachment 87238 [details] [review]
Fix Portuguese manual link
Comment 112 Martin Renvoize 2019-04-11 08:42:05 UTC
This should really be added as a new bug Humberto, otherwise it's extremely easy for the maintenance team to miss it.

I'll split it off for you this time.
Comment 113 Martin Renvoize 2019-04-11 09:30:35 UTC
See bug 22687