Bug 18817 - Update links in the help files for the new 17.11 manual
Summary: Update links in the help files for the new 17.11 manual
Status: RESOLVED FIXED
Alias: None
Product: Koha
Classification: Unclassified
Component: Documentation (show other bugs)
Version: master
Hardware: All All
: P5 - low minor (vote)
Assignee: Jonathan Druart
QA Contact: Marcel de Rooy
URL:
Whiteboard:
Keywords: Manual
Depends on:
Blocks:
 
Reported: 2017-06-16 17:19 UTC by Karen
Modified: 2017-10-02 13:05 UTC (History)
8 users (show)

See Also:
Change sponsored?: ---
Patch complexity: Trivial patch
Bot Control: ---
When did the bot last check this:
Who signed the patch off:
Text to go in the release notes:


Attachments
Screenshots not displaying in manual connected to the staff client (77.27 KB, image/png)
2017-06-16 17:19 UTC, Karen
Details
Bug 18817 Correct Manual URL (1.10 KB, patch)
2017-06-19 14:46 UTC, Joy Nelson
Details | Diff | Splinter Review
[SIGNED-OFF] Bug 18817 Correct Manual URL (1.16 KB, patch)
2017-06-29 23:00 UTC, M. Tompsett
Details | Diff | Splinter Review
Bug 18817: Update links with anchor automatically (139.08 KB, patch)
2017-08-14 19:26 UTC, Jonathan Druart
Details | Diff | Splinter Review
Bug 18817: Update links manually (75.21 KB, patch)
2017-08-14 19:26 UTC, Jonathan Druart
Details | Diff | Splinter Review
[SIGNED OFF] Bug 18817 Correct Manual URL (1.21 KB, patch)
2017-08-15 12:17 UTC, Katrin Fischer
Details | Diff | Splinter Review
[SIGNED OFF] Bug 18817: Update links with anchor automatically (138.29 KB, patch)
2017-08-15 12:17 UTC, Katrin Fischer
Details | Diff | Splinter Review
[SIGNED OFF] Bug 18817: Update links manually (74.83 KB, patch)
2017-08-15 12:17 UTC, Katrin Fischer
Details | Diff | Splinter Review
Bug 18817 Correct Manual URL (1.30 KB, patch)
2017-08-25 06:57 UTC, Marcel de Rooy
Details | Diff | Splinter Review
Bug 18817: Update links with anchor automatically (138.37 KB, patch)
2017-08-25 06:57 UTC, Marcel de Rooy
Details | Diff | Splinter Review
Bug 18817: Update links manually (74.91 KB, patch)
2017-08-25 06:57 UTC, Marcel de Rooy
Details | Diff | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Karen 2017-06-16 17:19:32 UTC
Created attachment 64407 [details]
Screenshots not displaying in manual connected to the staff client

No screenshots are displaying in the manual that is connected to the Help link in the staff client. They are displaying in other versions of the manual, just not the one connected to the staff client. I've attached a screenshot of this.
Comment 1 Joy Nelson 2017-06-19 14:46:33 UTC
Created attachment 64427 [details] [review]
Bug 18817 Correct Manual URL

Corrected the manual url in the help screen for 17.05 onward.
Comment 2 Jonathan Druart 2017-06-19 15:19:05 UTC
What is the difference between manual.k-c.org and k-c.org/manual?
Should not they be the same?
Comment 3 Katrin Fischer 2017-06-19 16:29:21 UTC
I talked to Chris this morning and I think he prefers the k-c.org so this patch should be fine. I will try to test.
Comment 4 Michael Kuhn 2017-06-19 17:07:17 UTC
The patch will solve the problem only on one single page (the mainpage). But since the Koha help is context-sensitive all the hundreds of other pages linking to the manual are still linking to the old manual with the broken image links.

This was already the case in Koha 16.11. And I'm afraid it applies to every single help page in EVERY additional language (not only English) which do all link to the respective pages of the English manual.
Comment 5 Joy Nelson 2017-06-19 18:17:49 UTC
The link was found 212 times in the system. I suppose we could updated each one individually.  But is this the most efficient way?

Additionally, I cannot find how the translations are done for the new 17.05 manual.  for example, what is the url for the spanish translation?
Comment 6 Chris Cormack 2017-06-19 18:21:23 UTC
It doesn't exist yet, but if it did it would be /es/ instead of /en/
Comment 7 Larry Baerveldt 2017-06-19 20:03:43 UTC
Some comments on this:

The current manual links on the help page, up through 17.05, are pointing to 'manual.koha-community.org'. That site is maintained by ByWater, but the actual manual pages are generated using this git repository:
git://git.koha-community.org/kohadocs.git

On that repository, the branch for manual16.05.x includes images in directory en/images. However I just checked and discovered that for the 16.11 and 17.05 branches, the images are now in en/source/images. I've updated the links on the manual.koha-community.org site, and now images are showing up in the manual pages.

It sounds like the Community wants to get away from using the manual.k-c site. We will leave the manual.k-c site up until such time as the links for the help pages have all been changed over to use the new address. Let me know when that has been done, and we'll shut down the manual.k-c site. 

- Larry
Comment 8 Chris Cormack 2017-06-19 20:23:11 UTC
Hi All

The main difference is 17.05 and up do not use docbook XML anymore, but use sphinx

This is a markdown style syntax that is way way easier to edit (we already have more different people submitting doc than we did in the last 5 years, docbook xml was just too hard)

The readme is here
http://git.koha-community.org/gitweb/?p=kohadocs.git;a=blob;f=README.md;h=5d18feacd50c2414b59447cc1aa45c1ad9c0767d;hb=e442b169a940fbf09a9a56d4dfbc4633a8eed15f

The upshot is, 17.05 generated from docbook is old and out of date and missing a chunk. 

So if we can leave the old manuals on manual.koha-community.org and new ones on koha-community.org  that should be the simplest
Comment 9 M. Tompsett 2017-06-29 23:00:03 UTC
Created attachment 64731 [details] [review]
[SIGNED-OFF] Bug 18817 Correct Manual URL

Corrected the manual url in the help screen for 17.05 onward.

Signed-off-by: Mark Tompsett <mtompset@hotmail.com>
Comment 10 Katrin Fischer 2017-07-04 05:36:17 UTC
The screenshots/images on manual.koha-community.org have been fixed, so this is no longer major.

Maybe we should switch all links on master for the 17.11 release - as it can't be done automatically (changed headings/achors) and it's a lot of help files to fix. This here will only link from the start page to the new manual.
Comment 11 Jonathan Druart 2017-08-14 19:26:36 UTC
Created attachment 65973 [details] [review]
Bug 18817: Update links with anchor automatically

I generate a mapping files (old anchor > new anchor) from the doc files.
Here are the links that have been updated automatically
Comment 12 Jonathan Druart 2017-08-14 19:26:42 UTC
Created attachment 65974 [details] [review]
Bug 18817: Update links manually

Without the anchor it is not possible to retrieve the html page, so
these occurrences have been updated manually (and yes it was painful)
Comment 13 Jonathan Druart 2017-08-14 19:27:43 UTC
(In reply to Katrin Fischer from comment #10)
> The screenshots/images on manual.koha-community.org have been fixed, so this
> is no longer major.
> 
> Maybe we should switch all links on master for the 17.11 release - as it
> can't be done automatically (changed headings/achors) and it's a lot of help
> files to fix. This here will only link from the start page to the new manual.

Manual changes were not imaginable, I script things.
I will update the manual first, then come back here.
Comment 14 Jonathan Druart 2017-08-14 19:28:45 UTC
Automatic replacement has been done with:

use Modern::Perl;
use File::Slurp;

# examplelistemail:18_miscellaneous.html#example-email-from-list
my $mappings;
for my $line ( split "\n", read_file('mappings.txt') ) {
    chomp $line;
    next unless $line;
    my ( $old_anchor, $link ) = split ':', $line;
    $mappings->{$old_anchor} = $link;
}


my @files = `git grep -l manual.koha-community.org`;
for my $file ( @files ) {
    chomp $file;
    next if $file =~ 'misc/release_notes'; # FIXME What do we do with release notes?
    say $file;
    my $content = read_file( $file );
    my @content;
    for my $line ( split "\n", $content ) {
        chomp $line;
        # http://manual.koha-community.org/[% helpVersion %]/en/aboutkoha.html
        if ( $line =~ m|manual.koha-community.org/\[% helpVersion %\]/en/.*\.html#([^"]+)"| ) {
            my $old_anchor = $1;
            if ( exists $mappings->{$old_anchor} ) {
                my $new_anchor = $mappings->{$old_anchor};
                $line =~ s|manual.koha-community.org/\[% helpVersion %\]/en/[^"]+"|koha-community.org/manual/[% helpVersion %]/html/$new_anchor"|g;
            } else {
                warn "$old_anchor DOES NOT HAVE A MAPPING";
            }
        }
        push @content, $line;
    }
    write_file( $file, join( "\n", @content ) . "\n" );
}


Just for the record.
Comment 15 Katrin Fischer 2017-08-15 12:17:49 UTC
Created attachment 66007 [details] [review]
[SIGNED OFF] Bug 18817 Correct Manual URL

Corrected the manual url in the help screen for 17.05 onward.

Signed-off-by: Mark Tompsett <mtompset@hotmail.com>

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>
Comment 16 Katrin Fischer 2017-08-15 12:17:53 UTC
Created attachment 66008 [details] [review]
[SIGNED OFF] Bug 18817: Update links with anchor automatically

I generate a mapping files (old anchor > new anchor) from the doc files.
Here are the links that have been updated automatically

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>
Comment 17 Katrin Fischer 2017-08-15 12:17:57 UTC
Created attachment 66009 [details] [review]
[SIGNED OFF] Bug 18817: Update links manually

Without the anchor it is not possible to retrieve the html page, so
these occurrences have been updated manually (and yes it was painful)

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>
Comment 18 Katrin Fischer 2017-08-15 12:20:32 UTC
Thx Jonathan, you are a hero!
Comment 19 Marcel de Rooy 2017-08-25 06:57:01 UTC
Created attachment 66453 [details] [review]
Bug 18817 Correct Manual URL

Corrected the manual url in the help screen for 17.05 onward.

Signed-off-by: Mark Tompsett <mtompset@hotmail.com>

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>

Signed-off-by: Marcel de Rooy <m.de.rooy@rijksmuseum.nl>
Comment 20 Marcel de Rooy 2017-08-25 06:57:05 UTC
Created attachment 66454 [details] [review]
Bug 18817: Update links with anchor automatically

I generate a mapping files (old anchor > new anchor) from the doc files.
Here are the links that have been updated automatically

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>

Signed-off-by: Marcel de Rooy <m.de.rooy@rijksmuseum.nl>
Comment 21 Marcel de Rooy 2017-08-25 06:57:10 UTC
Created attachment 66455 [details] [review]
Bug 18817: Update links manually

Without the anchor it is not possible to retrieve the html page, so
these occurrences have been updated manually (and yes it was painful)

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>

Signed-off-by: Marcel de Rooy <m.de.rooy@rijksmuseum.nl>
Comment 22 Marcel de Rooy 2017-08-25 06:57:45 UTC
Aarg those labels again ;)
Comment 23 Jonathan Druart 2017-08-25 14:01:44 UTC
Pushed to master for 17.11, thanks to everybody involved!
Comment 24 Fridolin SOMERS 2017-09-29 10:35:25 UTC
Pushed to 17.05.x, will be in 17.05.05.
Comment 25 Katrin Fischer 2017-09-30 12:30:05 UTC
I think we had agreed to use the old manual still for 17.05 and do the final switch with 17.11 - which means this shouldn't be pushed to 17.11.
Comment 26 Katrin Fischer 2017-10-01 22:16:08 UTC
Not applying to 16.11.x (still the old manual there)
Comment 27 Fridolin SOMERS 2017-10-02 13:05:07 UTC
(In reply to Katrin Fischer from comment #25)
> I think we had agreed to use the old manual still for 17.05 and do the final
> switch with 17.11 - which means this shouldn't be pushed to 17.11.

Ah ok i revert and set resolved.