- Koha-devel - lists.koha-community.org

order of koha versions on sourceforge
by Rachel Hamilton-Williams 20 Jun '05

20 Jun '05

Hi I went to see someone who'd accidentally downloaded the older version of Koha, I think because it's first in the list on the sourceforge site... http://sourceforge.net/project/showfiles.php?group_id=16466 Do we need both "koha' and "koha2.2" as what looks like seperate products? Could we not just have the 2.2 series under "koha" then it would go to the top? Cheers R -- ----------------------------- Rachel Hamilton-Williams General Manager Katipo Communications Ltd Phone: +64-4-934 1285 Mobile: 021 389 128 E-mail: rachel(a)katipo.co.nz Web: www.katipo.co.nz

3 2

koha 2.2.3 ?
by Rachel Hamilton-Williams 20 Jun '05

20 Jun '05

Hi guys, I've just been to visit a local school who'd managed to install koha 2.0 rather than 2.2.2 - and I was recommending she upgrade - but wondered if 2.2.3 was out/going to be out this week in which case she could hold off for a few more days cheers rachel -- ----------------------------- Rachel Hamilton-Williams General Manager Katipo Communications Ltd Phone: +64-4-934 1285 Mobile: 021 389 128 E-mail: rachel(a)katipo.co.nz Web: www.katipo.co.nz

2 1

Dependency versions and special patches
by Jared Camins-Esakov 19 Jun '05

19 Jun '05

Hello all. I have begun working on a FreeBSD port of Koha, and I had a couple of questions that I thought I would submit to your combined wisdom. 1) Are there any patches for the latest Koha release (2.2.2b) that might need to be applied depending on the version of any of Koha's dependencies? As an example, I seem to recall seeing in the mailing list archives that there was some discussion about improvements to the OPAC search that required MySQL 4.1; in that case, a patch might be required to make Koha work with MySQL<4.1. 2) Are there any patches for Koha that can be applied to the latest release (2.2.2b) for features that are often required, but not a part of the main Koha distribution? 3) Are there any security issues currently outstanding on the latest release, and are there any patches for them? Thanks in advance. -- Jared Camins-Esakov -- Jared Camins-Esakov E-mail: camins2(a)tcnj.edu

1 0

Koha 2.4 Searching Group Meeting
by Joshua Ferraro 17 Jun '05

17 Jun '05

Hi all, Francois-Laurent, Paul, slef, and chris and I have settled on a time for the Koha 2.4 Searching Group Meeting. Tuesday June 21 at 19:00GMT. To see the time in your area visit: http://tinyurl.com/79lgf If you'd like something to be included on the agenda please add it to the wiki under the meeting agenda section: http://www.saas.nsw.edu.au/koha_wiki/index.php?page=AgendAndNotes05jun21 Hope to read you at the meeting. -- Joshua Ferraro VENDOR SERVICES FOR OPEN-SOURCE SOFTWARE President, Technology migration, training, maintenance, support LibLime Koha ILS, Mambo Intranet, DiscrimiNet Filter jmf(a)liblime.com | Full Demos at http://liblime.com | 1(888)KohaILS

2 1

Re: Re[2]: [Koha-devel] Charsets: Moving to utf-8
by Mathew 16 Jun '05

16 Jun '05

> - all translations are stored within a database table, then have > the template lookup any static text (text generated from within > Perl, can be translated before being sent to the templates. I think this is not a good idea. Read why: > > - since templates lookup their own translations, you dont need a template-per-language. > > I'd prefer a template per language. Often the syntax is different in > different languages. With one template per language you can build > phrases, which mix static text with database generated text correctly > for every language. you could mix static text and database text, but why have seperate places for the text storage? > > - since translations are stored within a database, you can update > > the translations at run-time, without needing to restart / reload > > your updated translations > > We don't have to restart/reload right now. Most language translations are based on using .po files, such that when the file modification stamp is modified, the file gets reloaded. The problem with that is that each Apache instance will load a seperate copy of the translations, unless there is a mechanism to use a global map. > > - web access to the database translations allow multiple people > > to localise the translations, at the same time. > > What do you mean with "localise the translations"? When you give a template in one language, to the person do the translation, they are said to "localise the template to their langauge" which includes variations due to region, ie en_AU, en_US, en_GB, vs. jsut creating translations in the en language. > I think CVS does this job too. I'm suggesting that you can get a translator to translate the text strings, a) without them needing to understand how to use html, b) so that they use the same tool - the web browser - to update the text strings. > > - right-to-left text is also easily supported > > This is primary a point of coding. Not only. If you use an arabic website, the menu's are on the RHS side of the page - no primary within unicode, allows you to format you menus on the RHS of the browser. > The correct formatting of such text can be controlled better by one > template per language. Having done it both ways (we origonally had seperate templates per language), and now with a single template, we have seen exactly zero cases where a language specific template was needed. That said, we have need some variations with CSS styles. > > To do some of these, we modified HTML::Template to suport custom > > TMPL_xxx tags, so that we could implement a tag for the static text > > lookup. ie: our templates look like: > > You modified the original module? yes > What about upgrades? We merge the changes, then we put the new release on the website. I have email Sam Tregar a few times - most of the changes that we have developed, he is simply not interested in. For example, we enabled support for TMPL_ELSIF simply because we often use: <TMPL_IF ...> ... <TMPL_ELSE> <TMPL_IF ... ... <TMPL_ELSE> <TMPL_IF ... .... <TMPL_ELSE> ... </TMPL_IF> </TMPL_IF> </TMPL_IF> we can now do: <TMPL_IF ...> ... <TMPL_ELSIF ...> ... <TMPL_ELSIF ...> ... <TMPL_ELSE> </TMPL_IF> which is just so much cleaner - and the ELSIF's can be EXPR's too. > > We combine H::T with the Locale::MakePhrase module so that the > > output can handle singular / plural / etc based on the > > string/numeric value of some_var. > > This could be interesting for some words or phrases, but it can't > provide the flexibility of a template. Can I ask, did you have read through the Locale::MakePhrase documentation, and the documentation that it references? Sure, a template gives you ultimate flexibility. It also gives you the ability for templates to get out of sync, which is what our biggest problem was -> each time we made an enhancement, the templates needed to re-synced with the master, thus everly language other then english (our master languge) always lagged. cheers, Mathew

1 0

Re: [Koha-devel] Charsets: Moving to utf-8
by Mathew 16 Jun '05

16 Jun '05

Hi, I dont respond often on this list, but I thought the following information may be useful... > OK ... during the bugsquash session the issue of charsets came up. > (in response to 885:; Non-ISO8859-1 charset support broken in CSS > theme in 2.2). Our goal for 2.4 would be to move everything--db > storage, and templates -- to utf-8. The question is, how? [snip] > So we're looking for suggestions on how to make the switch. What do > we need to consider: > > HTML::Template limitations (should we be looking at Template::Toolkit) > Database Issues > Translation Issues > Other stuff At my work we provide a browser-based application which is translated into a number of languages. Some of the interesting points: - we only support UTF8 as the charset, as any other charset in simply insufficient (Google does this too). - all translations are stored within a database table, then have the template lookup any static text (text generated from within Perl, can be translated before being sent to the templates. - since templates lookup their own translations, you dont need a template-per-language. - since translations are stored within a database, you can update the translations at run-time, without needing to restart / reload your updated translations - web access to the database translations allow multiple people to localise the translations, at the same time. - right-to-left text is also easily supported To do some of these, we modified HTML::Template to suport custom TMPL_xxx tags, so that we could implement a tag for the static text lookup. ie: our templates look like: ... <TMPL_CATGETS "A phrase containing a template variable [_1], that gets inserted here",some_var> ... where some_var is a Perl generated TMPL_VAR value. We combine H::T with the Locale::MakePhrase module so that the output can handle singular / plural / etc based on the string/numeric value of some_var. For some extra information, go here: http://members.optusnet.com.au/mathew Hope this helps, Mathew PS. Some languages, particularily Asian languages, contain many pen-strokes within a glyph. Often these languages need the text point-size to be slightly larger than European languages... this is just a tidbit that I have found through experience, particularily if a single template is to be used for every language.

2 1

Draft (again) of coding guidelines
by Stephen Hedges 16 Jun '05

16 Jun '05

I notice that the coding guidelines document that I sent before is not formatted correctly in some mail clients, so I'm sending it again as an attachment. -- Stephen Hedges Skemotah Solutions, USA www.skemotah.com -- shedges(a)skemotah.com

1 0

Bug tracking for 2.3/2.4
by MJ Ray 14 Jun '05

14 Jun '05

I'm just out of the bug squash party in #koha and we got tripped up a little by some problems, with bugs.koha.org becoming unreachable at one point and sorting bugs in random order in the display. How should we handle this? Options: 1. Upgrade/bugfix bugzilla 2. Move to something else 2a Sourceforge 2b RT 2c Mantis 2d Something else 3. Something else Please say which of the above you like and what "something else" if that's your option. My analysis of them, with links, is below. The summary: If katipo are willing to upgrade/bugfix bugzilla and we can remove the "must register" limit, I think that's best for 2.4, unless there's a brilliant solution that I don't know? 1. Upgrade bugzilla Hopefully, the kind people at katipo are happy to continue hosting bugzilla. It looks like there's some new versions out, according to http://www.bugzilla.org/ which may help solve some of the bugs. It looks like bugzilla can already do most of what we need and it's more a case of learning how to use it. For example, today's problems with sorting and connections could have been minimised by taking a static copy of the "Long Format" bug list before the meeting. If the problems with connecting are due to ISPs, they're probably going to be a risk whatever we do. That said, there are some things which seem to be difficult to do even with the latest bugzilla. Every bugzilla I've seen requires people to register in order to report bugs and I can't see how we can support a koha-bugs summary email now, nor email commands. There are 5 open bugs for bugs.koha.org - is Chris willing to fix these? (I guess we mortal developers can't fix them alone... :-/ ) 2. Move to something else For 2.4, we could use a different bug tracker. What? 2a Sourceforge http://sourceforge.net/tracker/?group_id=16466 + It works, we already have one and it's familiar to many. + Users don't have to register to submit bugs. - Email notices only. - It's the same single point of failure as koha CVS. 2b RT http://www.bestpractical.com/rt/ + It's probably the closest perl-based competitor to Bugzilla. + Users don't have to register to submit bugs. + Email commands possible. - Last place I know that tried to install it claimed it was too complex. 2c Mantis http://www.mantisbt.org/ + Actively developed, originally by a small team for their own use. + Users don't have to register to submit bugs. - Email notices only - PHP/MySQL (different tech to koha, if nothing else) 2d Something else 3. Something else Make suggestions, please... -- MJ Ray (slef), K. Lynn, England, email see http://mjr.towers.org.uk/ http://www.ttllp.co.uk/koha/

3 4

Draft of coding guidelines
by Stephen Hedges 14 Jun '05

14 Jun '05

Attached to this message is a draft of a document called "Koha Coding Standards and Guidelines for Contributors." The release managers (past and present) and the Kaitiaki have had a chance to look this over and make comments -- now it's your turn! The xml source of this document is on Sourceforge under the koha-doc directory (http://cvs.sourceforge.net/viewcvs.py/koha/koha-doc/) so you can make minor changes there, if you want. Major changes should be discussed on the mailing list, however. Once we agree on the content of the document, we should get it translated into French, Spanish, and German. I think the final version(s) should be posted in CVS, on kohadocs.org, and in the Sourceforge Koha Document Manager (http://cvs.sourceforge.net/viewcvs.py/koha/koha-doc/) -- anywhere else? Stephen Hedges Koha Coding Standards and Guidelines for Contributors 1. Introduction 2. Code style 2.1. HTML 2.1.1. Templates location 2.1.2. Online help 2.1.3. Template content 2.2. DB access 2.3. Perl scripts 2.4. Naming conventions 2.4.1. Script names 2.4.2. Variable names 3. Commenting style 4. POD style (in modules) 1. Introduction As in other free and open source software projects, Koha contains code that has been contributed to the project by many different developers. Koha is now a complex piece of software, and we'd like continue to improve the overall code standards to make it easier for new developers to join the project, and to make existing code easier to maintain. These standards and guidelines are intended to give Koha a reasonably consistent style throughout the code and to ensure maintainability. When you commit new code to Koha, please do your best to comply with these guidelines -- it will increase the chances of your code become part of a stable Koha release. And if you find code in Koha that doesn't comply with these guidelines, please feel free to fix it, just as you would correct any bug. 2. Code style Koha code should conform to the guidelines defined in the perlstyle man page as they apply to code details (indenting, etc.). As for the general structure of the code, all Koha code must be separated into three types: • the Perl code; • the database (DB) access code; and • the HTML code. These three code types, as well as the Koha naming conventions, are explained in the following sections. 2.1. HTML All code controlling the "appearance layer" is contained in HTML::Template files. These files are located in the koha-tmpl directory in CVS (currently http://sourceforge.net/cvs/?group_id=16466) They must contain all the code controlling the presentation layer. There are at least two good reasons for this: • the look of Koha can be changed by rewriting only the templates, changing nothing in the Perl code itself; and • there is a tool to translate templates, so it's the only way to localise our preferred ILS. Almost all the actual Koha presentation pages use templates. Only a few exceptions (that can be considered bugs) remain at the time of writing. 2.1.1. Templates location The koha-tmpl directory contains two different sub-directories: opac-tmpl and intranet-tmpl. Under those two are the themes directories, and one directory for each language -- for example, intranet-tmpl/default/en for English default templates. The templates should be stored in a directory that parallels the location of the Perl scripts. For example, the Perl scripts located in the $KOHA/acqui.simple directory should use templates located in $KOHA/koha-tmpl/intranet-tmpl/<theme>/<language>/acqui.simple. Exceptions: • Scripts located in $KOHA/admin/ use templates located in $KOHA/intranet-tmpl/<theme>/<language>/parameters/ • Some scripts in $KOHA/members/ use templates located in $KOHA/intranet-tmpl/<theme>/<language>/ • Simple HTML "includes" files for placing standard headers and footers on Koha pages are located in $KOHA/intranet-tmpl/<theme>/<language>/includes/ When modifying templates, you should only modify the English one manually. All other languages are automatically generated from the English templates through a .po file and the script located in misc/translator/tmpl_process3.pl. 2.1.2. Online help The $KOHA/koha-tmpl/<theme>/<language>/help directory contains online help. Under the help directory is a complete copy of the Koha directory structure, with templates using the same name as the "true" templates. These templates must contain online help. The $KOHA/help.pl script is called when the user clicks on "Help," which opens/shows the templates in this directory. PLEASE write online help when you add features. 2.1.3. Template content There is usually only one template for a given .pl file. For example, the template related to circulation/returns.pl should be circulation/returns.tmpl. If there are different possible behaviours, they should be separated by a TMPL_IF. For example, $KOHA/koha-tmpl/intranet-tmpl/<theme>/<language>/parameters contains:  that controls what is shown when the user wants to add something (as determined by the Perl script): if ($op) { $template->param(script_name => $script_name, $op => 1); # We show only the TMPL_VAR names $op. } else { $template->param(script_name => $script_name, else => 1); # We show only the TMPL_VAR names $op. } Note that some scripts use two different templates, depending on what the user wants to do. This is sometimes a mistake in Koha design, sometimes not. For example, in $KOHA/opac/opac-search.pl, we can use the opac-search or opac-searchresults template, depending on the step of the search. Both templates are big, so merging them would not be a good idea for maintenance and readability of Koha code. 2.2. DB access No database (DB) access routines should ever be included in .pl files. All DB access routines should be in the C4 directory, in .pm modules. There is one .pm module for each logical "librarian activity." For example, everything related to circulation must be in C4/Circulation/Circ2.pm. All inclusion of Perl variables in SQL commands should be done through prepare() statements with ? placeholders, and then using bind() and/or execute() calls. This helps with security and other testing. The C4/Context.pm module contains everything related to technical variables (creating a DB handler, getting a systempreference, etc.). The C4/Koha.pm module contains everything related to things that are useful everywhere in Koha, such as getting a branch list or a branch detail. (At the time of writing, this module probably should be improved. Some subroutines, for instance, are located in other modules but would be better here.) Exception: parameters management scripts. For historic reasons, and because they don't do anything complex in the database, all scripts in $KOHA/admin/ deal directly with the database. This is not really a bug, even if it does seem to break the rule. (Think of it as "the exception that proves the rule.") 2.3. Perl scripts Perl scripts are the scripts that are run from cgi-bin (or mod_perl). They all have (almost) the same behaviour: • read parameters; • open an HTML::Template file (that checks the user rights to access the page if needed -- if the user doesn't have the correct permissions, show a "sorry no access" page and end); • depending on the parameters (often, in a $op variable, but not always), run subroutines from a C4/*.pm package to do something in the database; • using the parameters and the results of the previous operations, fill the template; and • send the template to the user. Some scripts are run on the command line. They all are located in the misc directory. The misc directory does not contain any scripts that can be run as cgi-bin. Command line scripts executed without any parameters should return a "help" listing of possible parameters and exit without doing anything. 2.4. Naming conventions 2.4.1. Script names The script names must be related to what they do, and they must be located in a directory that is related to a logical "librarian activity". For example, all scripts related to circulation are in $KOHA/circ/. Exceptions: • The acqui.simple directory contains all the code for MARC cataloguing. The directory name obviously is not related to the "librarian activity," but it's historic. • The bull directory is related to serials management. Most of the code in this directory was developed in France, and "serials management" is "bulletinage" in French -- but in general, script and directory names should be in English. • Some scripts related to borrowers are still in the $KOHA/ directory (pay.pl for example). 2.4.2. Variable names Variables can be of three types: • Perl variables; • template variables; or • hash entries from a SQL request. All three variables should have the same name. For example, if you get the field issuelength from the issuingrules table, then you should have a  in the template, and either a $issuelength or $issuingrules->{'issuelength'} variable in the Perl code. Sometimes you must use the same field/variable from two different points of view. In this case, use two variable names, with something distinctive before the "simple" name. For example if you need "librarian name" and "borrower name" from borrowers.surname, use librariansurname and borrowersurname. 3. Commenting style Scripts and modules in Koha are expected to contain clear and helpful comments to assist other developers who want to work on the code. Despite the availability of external documentation, source code listings should be able to stand on their own, because external documentation may not adequately describe the details and intent of the developer(s). Please make sure you include enough comments to keep your coding intentions understandable, and try to follow these guidelines: 1 Please write your comments in English or request translation. Write in complete sentences, capitalize the first word, and put two spaces after the end of each sentence (so that the Emacs sentence commands will work). Comments should start with a # and a single space. 2 Comment your code when you do something that someone else may not think is "trivial." In other words, comment anything that is not readily obvious in the code. 3 Each Koha file should begin with a block comment containing: a basic information about the file, such as file name, version, date, author: # addbiblio.pl, v 1.52.2.6, 2005/05/19, tipaul b the standard Koha copyright message: # Copyright 2000-2005 Katipo Communications # Copyright 2005 <author or employer> # # This file is part of Koha. # # Koha is free software; you can redistribute it and/or modify it under the # terms of the GNU General Public License as published by the Free Software # Foundation; either version 2 of the License, or (at your option) any later # version. # # Koha is distributed in the hope that it will be useful, but WITHOUT ANY # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR # A PARTICULAR PURPOSE. See the GNU General Public License for more details. # # You should have received a copy of the GNU General Public License along with # Koha; if not, write to the Free Software Foundation, Inc., 59 Temple Place, # Suite 330, Boston, MA 02111-1307 USA 4 All block comments should consist of one or more paragraphs built out of complete sentences, and each sentence should end in a period. Block comments generally apply to some (or all) code that follows them, and are indented to the same level as that code. Each line of a block comment starts with a # and a single space (unless it is indented text inside the comment). Paragraphs inside a block comment are separated by a line containing a single #. Block comments are best surrounded by a blank line above and below them. 5 Provide comments at the beginning of every function (unless the function is very short and its purpose is obvious) indicating the function's purpose, assumptions, and limitations. The comments should be a brief introduction to understand why the function exists and what it can do. Document how it does it, too, if that is not obvious. Place a blank line between a function and its description. Include information about the sorts of arguments it gets, and what the possible values of arguments mean and are used for. Also explain the significance of the return value, if there is one. 6 Use comments on code that consists of loops and logic branches. These are key areas that will assist the reader when reading source code. 7 Try to avoid adding comments at the end of a line of code; end-line comments make code more difficult to read. End-line comments are appropriate, however, when annotating variable declarations. In this case, try to align all end-line comments at a common tab stop. (End-line comments should be separated by at least two spaces from the statement.) 8 When modifying code, always keep the commenting around it up to date. Keeping the comments up-to-date when the code changes is a priority -- comments that contradict the code are worse than no comments! Identify the change with the date and your user name. 9 Avoid using clutter comments, such as an entire line of asterisks. Instead, use white space to separate comments from code. Avoid the use of superfluous or inappropriate comments, such as humorous sidebar remarks. 10 To prevent recurring problems, always use comments on bug fixes and work-around code, especially in this team environment. When you want to leave notes about functionalities to be added, put TODO: in front of the actual comments so developers can easily search for them. When you want to leave notes about bugs to be fixed, put FIXME: in front of the actual comments so developers can easily search for them. One other type of comment that developers may overlook is the cvs log message added when committing a file, but these comments are also very important. The messages should never be omitted and should give enough description to let other developers know what you are doing without having to read the code itself. In the case of bug fixes, it is also recommended that the messages include the bug number and the bug title, as well as a brief description of the fix. 4. POD style (in modules) Koha modules should be documented with extensive comments written in POD ("Plain Old Documentation") format. Instructions for the POD markup language can be found in the perlpod man page. POD comments should include as least the following headings: NAME The name of the module and a very brief description of the type of functions contained in the module. SYNOPSIS This may give an example of how to access the module from a script, but it may also contain any general discussion of the purpose or behavior of the module's functions, and discussion of changes made to the module. DESCRIPTION If not included in the SYNOPSIS, a general description of the module's purpose should appear here. FUNCTIONS Descriptions of each function in the module, beginning with an example of how the function is called and continuing with a description of the behavior of the function. AUTHOR This will generally be the "Koha Development Team," but may also be an individual developer who has made significant contributions to the module. Give a contact e-mail address. For two examples, see the POD comments in the Search.pm module (perldoc Search.pm) and the Biblio.pm module.

1 0

Summary 2005-06-13
by MJ Ray 14 Jun '05

14 Jun '05

What have the koha developers been putting in koha 2.3 this week? hdl fixed a css class error on titles. hellen continued translating the default intranet templates to de. oleanard synch'd the npl intranet templates with default and 2.2, changed id to supplierid in full acquisition's order screen (bug 990?), updated the npl opac templates to work with full serials display, and many other bugfixes. rangi fixed an "ordernumber not showing" bug in full acquisition. tipaul added a warning and check for creating an order with no budgets, other bugfixes for full acquisitions, ported the dictionary search from 2.2 to 2.3, updated the french translation and some other bugfixes. Detailed changelog at http://www.ttllp.co.uk/koha/20050613.changelog -- MJ Ray (slef), K. Lynn, England, email see http://mjr.towers.org.uk/ http://www.ttllp.co.uk/koha/

1 0