Bug 32059

Summary:	How to run scripts found under https://perldoc.koha-community.org/
Product:	Koha	Reporter:	Michael Kuhn <mik>
Component:	Documentation	Assignee:	Bugs List <koha-bugs>
Status:	Needs documenting ---	QA Contact:	Testopia <testopia>
Severity:	enhancement
Priority:	P5 - low
Version:	Main
Hardware:	All
OS:	All
Change sponsored?:	---	Patch complexity:	---
Documentation contact:		Documentation submission:
Text to go in the release notes:		Version(s) released in:
Circulation function:

Description Michael Kuhn 2022-11-01 14:32:50 UTC

Documentation pages like https://perldoc.koha-community.org/misc/migration_tools/bulkmarcimport.html do not give the proper command to run the script. In the example section "Usage" says:

$ export KOHA_CONF=/etc/koha.conf
$ perl misc/migration_tools/bulkmarcimport.pl -d -commit 1000 -file /home/jmf/koha.mrc -n 3000

When using Debian package installation one way to actually run the program is:

As user "root":

# export KOHA_CONF=/etc/koha/sites/instancename/koha-conf.xml
# export PERL5LIB=/usr/share/koha/lib
# /usr/share/koha/bin/migration_tools/bulkmarcimport.pl -b -m marcxml
-framework=frameworkname -file TITEL.marcxml -v 2

But it seems the following way is recommended:

As user "koha":

$ sudo koha-shell -c
"/usr/share/koha/bin/migration_tools/bulkmarcimport.pl -b -m marcxml
-framework=frameworkname -file TITEL.marcxml -v 2" instancename

Better documentation how to run this kind of scripts would be useful. https://perldoc.koha-community.org/ shows many more such scripts.

Comment 1 Katrin Fischer 2022-11-01 14:40:22 UTC

I feel like the instructions are not wrong in itself, the instructions work, they just assume that in a package installation you run the 'sudo koha-shell instance' command first, no matter which script you run. 

Also it depends, if you are not using a package based installation, but using tarball, you'd have to run them under the koha-user without having the koha-shell command option.

This might be better for the manual instead of altering all the man pages.

Comment 2 Michael Kuhn 2022-11-01 14:46:41 UTC

"...the instructions work, they just assume that in a package installation you run the 'sudo koha-shell instance' command first, no matter which script you run. Also it depends, if you are not using a package based installation, but using tarball, you'd have to run them under the koha-user without having the koha-shell command option."

But that's exactly the problem I wanted to submit - the documentation page doesn't say so. So if you're not already knowing what's assumed or how it works you're stuck.

Comment 3 Katrin Fischer 2022-11-01 14:51:38 UTC

I agree we should document, just thinking that the auto-generated perl-doc might not be the right place. As this is dependent on how you installed Koha, notes in the wiki or manual in a general 'how to' chapter might better.