No changes between revisions
/photogallery/docs/Advanced.html
0,0 → 1,200
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>singapore - Advanced features</title>
<link rel="stylesheet" type="text/css" href="docstyle.css" />
</head>
 
<body>
 
 
<h1>singapore - Advanced features</h1>
 
<ul>
<li><a href="#iifn">Info in filename</a></li>
<li><a href="#override">Overriding settings</a></li>
<li><a href="#hiding">Hiding galleries</a></li>
<li><a href="#modrewrite">Using Apache mod_rewrite</a></li>
<li><a href="#including">Including singapore into another page</a></li>
<li><a href="#popup">Opening images in a popup</a></li>
<li><a href="Readme.html">General readme</a></li>
<li><a href="Development.html">Developer documentation</a></li>
<li><a href="Translation.html">Translating singapore</a></li>
</ul>
 
<h2><a name="iifn">Info in file name</a></h2>
 
<p>If singapore doesn't find a metadata file in a gallery it will try to
extract some sensible information from the image file and directory names as
follows:</p>
 
<p>Underscores (_) are converted to spaces and the file extension is discarded
by removing all characters after the last . (dot) in the filename. If a filename or
directory name contains the sequence '<code>_-_</code>' (underscore hyphen underscore)
or '<code> - </code>' (space hyphen space) then the name will be split on this
separator. The first half will be interpreted as the artist name and the second
half will be interpreted as the gallery or image name depending on context. If
a separator is not found then the file or directory name is interpreted as the
image or gallery name, respectively.</p>
 
<p>For example <code>Holiday_Snaps/Bob_Fenderson_-_Pretty_picture_of_Sunset.jpg</code>
will be translated into an image called "Pretty picture of Sunset" by "Bob
Fenderson" in a gallery called "Holiday Snaps".</p>
 
 
<h2><a name="override">Overriding settings</a></h2>
 
<p>All configuration options may be overridden on a per-gallery and/or
per-template basis. This means that a particular gallery may use, for example,
a different template or language to the rest of the site. Also, templates may
introduce their own configuration settings if they so wish.</p>
 
<p>Gallery config options are stored in files named <code>gallery.ini</code> in
the chosen gallery directory. Settings are not inherited by subgalleries; they
affect only the current gallery and its images.</p>
 
<p>Template config options are stored in files named <code>template.ini</code>
in the chosen template directory. Some of these settings are not present in the
default config file; they are only found in the template config file.</p>
 
<p>Settings are loaded in this order: default settings (<code>singapore.ini</code>)
&gt; gallery settings (<code>gallery.ini</code>) &gt; template settings
(<code>template.ini</code>). This may be changed in the future to allow gallery
settings to override template settings.</p>
 
<p>Note that there is no restriction on which options may be overridden.
Overriding some settings may lead to unpredictable operation (e.g. changing
<code>pathto_galleries</code> in <code>gallery.ini</code>).</p>
 
 
<h2><a name="hiding">Hiding galleries</a></h2>
 
<p>Any gallery (except the root gallery) may be hidden from the listing view
by prefixing the directory name with a dot (<code>.</code>). However it is still
accessible by using its exact URL. For example consider the following directory
structure:</p>
 
<pre>
galleries/
|- my_pretty_pictures/
| |- trees/
| `- flowers/
|- .a_hidden_gallery/
| |- some_embarrassing_pictures/
| `- .this_is_also_hidden/
`- some_other_things/
</pre>
 
<p>A user browsing the root gallery (e.g. <code>www.example.com/?gallery=.</code>)
will see <code>my_pretty_pictures</code> and <code>some_other_things</code>;
<code>.a_hidden_gallery</code> and all its contents will be hidden from view. If,
however, the user is supplied with the exact URL (e.g. <code>www.example.com/?gallery=./.a_hidden_gallery</code>)
they will be able to see the contents as usual (in this case only
<code>some_embarrassing_pictures</code> because <code>.this_is_also_hidden</code>
is hidden as above).</p>
 
<p>Since a user could guess the exact URL or discover it by some other means,
this feature is not to be used for concealing sensitive information.</p>
 
<p>NOTE: see the <a href="#modrewrite">mod_rewrite</a> section for instructions
on renaming files starting with a . on Windows.</a></p>
 
 
<h2><a name="modrewrite">Using Apache mod_rewrite</a></h2>
 
<p>Firstly you need to ensure that mod_rewrite is available. You must be running
<a href="http://httpd.apache.org/">Apache</a>, have mod-rewrite installed and
enabled and furthermore be allowed to override Apache configuration directives
on a per-directory basis with the use of .htaccess files.</p>
 
<p>If you don't know the answer to the above then probably the easiest way to
find out is to try the following instructions.</p>
 
<p>First copy <code>tools/mod_rewrite.htaccess</code> to the singapore base
directory and rename it to simply <code>.htaccess</code>. Note: Windows shines
here as a Totally Idiotic Operating System&reg; as it will not let you type
filenames starting with a . kindly saying "You must type a filename". The only
way that I know of to get around this totally pointless message is to drop into
the command line and use <code>ren</code> to rename it. Aaaaaaaarrrrgggghhhh!</p>
 
<p>Moving swiftly on...</p>
 
<p>You now need to edit singapore.ini and turn on <code>use_mod_rerwite</code>.
You also need to specify the <code>base_url</code> option. Set this to the full
web absolute path to your installation (e.g. the bit after the .com, .org or
whatever). For example if your gallery is accessed by typing
www.example.com/singapore/ then the <code>base_url</code> is
<code>/singapore/</code>.</p>
 
<p>Lastly you need to edit the .htaccess file. On each of the two lines starting
<code>RewriteRule</code>, about half way along the line there is a
<code>/singapore/</code>. Change this to whatever you put as the <code>base_url</code>
above.</p>
 
<h3>If it doesn't work</h3>
 
<p>If you get <em>404 File Not Found</em> errors then either mod_rewrite or .htaccess
files are not enabled. If you get singapore <em>Gallery not found</em> errors
then there might be a problem with the rewrite rules. If you get unstyled
singapore pages with no images then then your base_path is probably wrong. If do
get images but the pages are still unstyled then your template probably needs
adapting to use the base_url config option. See the default template for an
example. If you still can't work out what's wrong then just give up :P</p>
 
<h2><a name="including">Including singapore into another page</a></h2>
 
<p>Since v0.9.10 it has been possible to include singapore into your web design
using external.php. Just place this code where you want singapore to appear:
<code>&lt;?php include("path/to/singapore/external.php");?&gt;</code> (supplying
the correct relative or absolute path to singapore instead of
'/path/to/singapore'). There are, however, a few things that need to be noted:</p>
 
<ul>
<li>You will almost certainly need to edit your chosen template in order that
the HTML generated is still valid. For example you do not want two &lt;html&gt;
start tags, two &lt;head&gt; sections etc. Alternatively you can use the
<em>external</em> template (available to download from the website) which is
the default template with the unnecessary (X)HTML removed.</li>
<li>If the file into which you are including singapore is named something
other than index.php or it requires additional GET variables (such as page etc.)
then you will need to change index_file_url to reflect this. For example if
the page you are including singapore into is <code>site.php?page=gallery</code>
you will need to change index_file_url to <code>site.php?page=gallery&amp;amp;</code></li>
<li>If you want to keep both the included singapore installation and the
original simultaneously functional then you can place a file named
<code>singapore.local.ini</code> in the same directory as the including file.
If found, this file will be loaded after singapore.ini but before gallery.ini
and template.ini. It can thus be used to provide local settings such as index_file_url
mentioned above. Note that base_file and base_url are automatically calculated
and should not need to be specified.</li>
<li>If there is any content on the including page <em>before</em> external.php is
included then singapore will not be able to send any headers which will
prevent you from using languages with non-default character sets. The
recommended solution is to turn on output buffering before any content is
output and do not flush it until after external.php is included. Essentially
a call to <code>ob_start()</code> at the beginning of the including file is
all that is needed. <a href="http://uk.php.net/manual/en/ref.outcontrol.php">About
output control</a>.</li>
<li>Currently mod_rewrite doesn't work with such included installations of singapore.</li>
</ul>
 
<h2><a name="popup">Opening images in a popup</a></h2>
 
<p>Firstly I must say how much I disapprove of popups. If someone wants to open
something in a new window THEY WILL DO IT THEMSELVES! Why do you think so many
people have popup blockers? POPUPS ARE BAD! However I have been asked how to
make singapore open images in popup windows so often that I finally yielded and
wrote a little bit of JavaScript to do it neatly.</p>
 
<p>Open album.tpl.php in the directory of your current template (e.g.
templates/default/album.tpl.php) and replace <code>$sg-&gt;gallery-&gt;images[$index]-&gt;thumbnailLink()</code>
with <code>$sg-&gt;gallery-&gt;images[$index]-&gt;thumbnailPopupLink()</code>. But don't do it. It's bad.<p>
 
<p>Evil I tell you...</p>
 
<p><em>$Date: 2006/08/06 13:50:20 $</em></p>
 
</body>
</html>
/photogallery/docs/Development.html
0,0 → 1,114
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>singapore - Development</title>
<link rel="stylesheet" type="text/css" href="docstyle.css" />
</head>
 
<body>
 
<h1>singapore - Development</h1>
 
<p>The information in this file is for people who wish to contribute to
singapore, modify it or understand how it works.</p>
 
<ul>
<li><a href="#csvformat">CSV database format</a></li>
<li><a href="Readme.html">General readme</a></li>
<li><a href="Advanced.html">Advanced features</a></li>
<li><a href="Translation.html">Translating singapore</a></li>
</ul>
 
<h2><a name="csvformat">CSV database format</a></h2>
 
<p>If you choose to use metadata files then each gallery must
contain a CSV (comma separated values) file called metadata.csv
containing the information about images in the gallery and the gallery itself.
CSV files can be edited manually (in a text editor such as Notepad)
or using a spreadsheet application (such as MS Excel). Care must be taken when using
Excel to save using commas as the separator character and not tabs or semi-colons.</p>
 
<p>The first line of each file stores human-readable descriptions of the fields
and is ignored by singapore. The second line stores information about this
gallery:</p>
 
<pre>
field 0
the filename of the image used to represent the gallery in the gallery list
field 1
(not used)
field 2
the owner of the gallery
field 3
space-separated list of usergroups
field 4
gallery permission flags
field 5
space-separated list of categories the gallery belongs in (not used)
field 6
gallery name/title
field 7
artist name (optional)
field 8
artist email (optional)
field 9
copyright holder (optional)
field 10
description of the gallery (optional)
field 11
short summary of the gallery (optional)
field 12
human-readable date (optional)
field 13 onwards
(not used)
</pre>
 
<p>Each of the following lines (3 - ...) represents an image in the gallery.
The format is as follows:</p>
 
<pre>
field 0
the filename of the image
field 1
the filename of the thumbnail image
field 2
the owner of the image
field 3
space-separated list of usergroups
field 4
image permission flags
field 5
space-separated list of categories the image belongs in (not used)
field 6
image name/title
field 7
artist name (optional)
field 8
artist email (optional)
field 9
copyright holder (optional)
field 10
description of the image (optional)
field 11
location that the image was taken/made/represents (optional)
field 12
date taken/made (optional)
field 13
make and model of camera used (optional)
field 14
make and model of lens used (optional)
field 15
make and type of film used (optional)
field 16
darkroom manipulation (optional)
field 17
digital manipulation (optional)
</pre>
 
<p><em>$Date: 2004/10/15 18:53:36 $</em></p>
 
</body>
</html>
/photogallery/docs/License.txt
0,0 → 1,340
GNU GENERAL PUBLIC LICENSE
Version 2, June 1991
 
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
 
Preamble
 
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users. This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it. (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.) You can apply it to
your programs, too.
 
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.
 
To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.
 
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have. You must make sure that they, too, receive or can get the
source code. And you must show them these terms so they know their
rights.
 
We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.
 
Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software. If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.
 
Finally, any free program is threatened constantly by software
patents. We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary. To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.
 
The precise terms and conditions for copying, distribution and
modification follow.
GNU GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
 
0. This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License. The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language. (Hereinafter, translation is included without limitation in
the term "modification".) Each licensee is addressed as "you".
 
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.
 
1. You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.
 
You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.
 
2. You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
 
a) You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.
 
b) You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.
 
c) If the modified program normally reads commands interactively
when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you provide
a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this
License. (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.
 
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.
 
In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
 
3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:
 
a) Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software interchange; or,
 
b) Accompany it with a written offer, valid for at least three
years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,
 
c) Accompany it with the information you received as to the offer
to distribute corresponding source code. (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)
 
The source code for a work means the preferred form of the work for
making modifications to it. For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable. However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.
 
If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.
4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.
 
5. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Program or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.
 
6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.
 
7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all. For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.
 
If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.
 
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
 
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded. In such case, this License incorporates
the limitation as if written in the body of this License.
 
9. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
 
Each version is given a distinguishing version number. If the Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation. If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.
 
10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission. For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this. Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.
 
NO WARRANTY
 
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.
 
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
 
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
 
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
 
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
 
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
 
This program 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.
 
This program 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 this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 
 
Also add information on how to contact you by electronic and paper mail.
 
If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:
 
Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
 
The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License. Of course, the commands you use may
be called something other than `show w' and `show c'; they could even be
mouse-clicks or menu items--whatever suits your program.
 
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary. Here is a sample; alter the names:
 
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
`Gnomovision' (which makes passes at compilers) written by James Hacker.
 
<signature of Ty Coon>, 1 April 1989
Ty Coon, President of Vice
 
This General Public License does not permit incorporating your program into
proprietary programs. If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library. If this is what you want to do, use the GNU Library General
Public License instead of this License.
/photogallery/docs/Readme.html
0,0 → 1,599
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>singapore - Readme</title>
<link rel="stylesheet" type="text/css" href="docstyle.css" />
</head>
 
<body>
 
 
<h1>singapore v0.10.1 - Readme</h1>
 
<ul>
<li><a href="#release">Release notes</a></li>
<li><a href="#history">Version history</a></li>
<li><a href="#license">License information</a></li>
<li><a href="#install">Installation</a></li>
<li><a href="#upgrade">Upgrading</a></li>
<li><a href="#managing">Gallery management</a></li>
<li><a href="#permissions">Help with file permissions</a></li>
<li><a href="#adminpermissions">The deal with admin permissions</a></li>
<li><a href="#users">Managing users</a></li>
<li><a href="#nomenclature">Naming of parts (glossary)</a></li>
<li><a href="Advanced.html">Advanced features</a></li>
<li><a href="Development.html">Developer documentation</a></li>
<li><a href="Translation.html">Translating singapore</a></li>
</ul>
 
 
<h2><a name="license">Licensing information</a></h2>
 
<pre>
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *\
* <a href="http://www.sgal.org/">singapore</a> - Copyright 2002-6 Tamlyn Rhodes &lt;tam@zenology.co.uk&gt; *
* *
* singapore is free software; you can redistribute it and/or modify *
* it under the terms of the <a href="License.txt">GNU General Public License</a> as published *
* by the Free Software Foundation; either version 2 of the License, *
* or (at your option) any later version. *
* *
* singapore 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 this; if not, write to the Free Software Foundation, *
* Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA *
\* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
</pre>
 
<p>You are kindly requested to display a link such as the following on all
pages generated by singapore. However in cases where this is not desirable,
a project donation of 20USD is considered a suitable alternative.</p>
 
<p class="boxed">Powered by <a href="http://www.sgal.org/">singapore</a></p>
 
 
<h2><a name="release">Release notes</a></h2>
 
<p>This is a recommended update as it addresses a critical bug in the
template handling that could allow an attacker to view the contents of system
files on the web server. Several other less severe bugs have been fixed
including acces control settings inheritance in the admin which should now
work correctly. The latest version of the 'modern' template is also included.</p>
 
 
<h2><a name="install">Installation</a></h2>
 
<ol>
<li>Extract all the files in the archive, conserving the directory hierarchy.</li>
<li>If you wish to change any path settings or use one of the SQL backends,
make the necessary changes to <code>singapore.ini</code>. If you don't know
why you might want to do this then you don't need to do it.</li>
 
<li>Upload everything to your web server.</li>
<li>Set file permissions. The directories that need to be made writable are:
<ul>
<li><code>data/</code> and all subdirectories and files</li>
<li><code>galleries/</code> and all subdirectories and files</li>
</ul>
<a href="#permissions">Help with file permissions</a>.
</li>
<li>Point your browser to the <code>install/</code> directory and follow the instructions.</li>
<li>Delete the <code>install/</code> directory to prevent unauthorised access.</li>
<li>Log into the admin section and change the password. The username is
<code>admin</code> and the default password is <code>password</code>.</li>
<li>You're ready to roll! <a href="#managing">More info on how to roll...</a></li>
</ol>
 
<p>Optional but recommended:</p>
<ul>
<li>Have a browse through <code>singapore.ini</code> and look at the
available options. Each option has comments explaining its function. For most
purposes the default values will be fine but you may be able to tweak them
to your benefit. See also <a href="Advanced.html#override">overriding default
settings</a>.</li>
<li>Make your own header image (<code>templates/default/images/header.gif</code>)
with the name of your site.<br />
-or-<br />
Edit the default style sheet (<code>templates/default/main.css</code>)
to integrate it with your site.<br />
-or-<br />
Browse the pre-existing templates available for singapore on the
<a href="http://www.sgal.org/wiki/files/templates">templates</a> page.
-or-<br />
Create your own template by editing an existing one. There is currently no
documentation on this topic but anyone with a basic grasp of PHP should be
able to work it out. Visit the
<a href="http://www.sgal.org/forum/viewforum.php?id=2">templates forum</a>
for help and advice.</li>
</ul>
 
 
<h2><a name="upgrade">Upgrading</a></h2>
 
<p>Always back-up first!</p>
 
<p>A patch is also available for people wishing only to fix the security problem.</p>
 
<p>Upgrading is usually just a matter of unzipping the new version over the old.
Your galleries, images, metadata will not be affected but the
admin password will be reset and the root ini file (singapore.ini) will be
overwritten. The location of log files and thumbnail cache has changed in this
version. See the forum for
<a href="http://www.sgal.org/forum/viewtopic.php?id=1267">instructions on
copying your old logs over to their new location</a>.
You can keep your old users.csv.php file.
When new configuration options are added you will need to either add these
to your old singapore.ini or re-edit the new singapore.ini in order to keep your
personal settings. You may want to use a file difference utility such as
<a href="http://winmerge.sourceforge.net">WinMerge</a> to merge the differences.</p>
 
<p>The default templates will also be overwritten in an upgrade. For this reason
it is advisable to copy the default template to a new directory when making
customisations.</p>
 
 
<h2><a name="uninstall">Uninstallation</a></h2>
 
<p>Server generated content may be owned by the web server and it may therefore
not be possible to delete these files via ftp. Use the
<a href="../tools/cleanup.php">cleanup script</a> to make all server-generated
files world writable. This should allow you to delete them like any other file.</p>
 
 
<h2><a name="managing">Managing your galleries</a></h2>
 
<p>If using the <a href="Advanced.html#iifn">info in file name</a> system then
all management can be done
directly on the files using, for example, an ftp client. To create new galleries
simply create a new subdirectory of <code>galleries/</code>. To add, move or delete
images in a gallery simply add, move or delete the image files in the
appropriate directory.</p>
 
<p>If you use the admin mode to edit your galleries or images it will
automatically create the relevant metadata files. If these files are deleted
singapore will revert to using <em>info in file name</em>. The username is
<code>admin</code> and the default password is <code>password</code>.</p>
 
<p>Galleries may contain <em>either</em> images or further galleries. This
means that if you create one or more child galleries in a gallery that already
contains images, these images will be 'hidden'. Removing these child galleries
will make the images visible again. Galleries containing only images are called
albums.</p>
 
 
<h3>Bulk image uploading</h3>
 
<p class="note">NOTE: this feature is experimental. It works on some servers but
does not on others (including the sf.net servers) and I don't know why. It may
or may not work for you.</p>
 
<p>You may upload several images at the same time by first storing them in a
PKWARE compatible ZIP file. Most archiving utilities are able to produce such
files also sometimes referred to as <em>compressed folders</em> on Windows. You
need an unzipping utility on your server to use this feature. Most Linux/Unix
machines come with the free <em>unzip</em> utility by Info-Zip preinstalled but
precompiled binaries for nearly all operating systems ever conceived can be
found on the <a href="http://www.info-zip.org/">Info-Zip website</a>. <!--A Win32
version is also available here:
<a href="http://singapore.sourceforge.net/binaries/singapore-unzip-Win32.zip">http://singapore.sourceforge.net/binaries/singapore-unzip-Win32.zip</a>.-->
Simply place the executable in your PATH or in the singapore root directory.</p>
 
<p>Upload the archive using the 'new image' option in the singapore admin and
select 'Upload multiple files'</p>
 
<p>If the archive contains only images, these will be added to the current
gallery just as if they had been uploaded individually. If an archive contains
subdirectories, these will be copied into the current gallery. Any images in
the archive root directory will be imported as above. This mechanism
may be used to upload complete directory structures including metadata.csv
and gallery.ini files. If the archive root directory contains no images and a
single directory, singapore will navigate into this directory and proceed to
import the contents into the current gallery as though they were in the root
directory.</p>
 
<p>NOTE: There is a maximum size of file that PHP will allow you to upload.
This defaults to 2MB and cannot be changed by singapore. Consult the PHP manual
or you server's administrator for more information.</p>
 
<h2><a name="permissions">Help with file permissions</a></h2>
 
<p>How to make a file writable is dependent on your operating system and
web server setup and can seem quite daunting for a beginner. One option that
will work on nearly all Unix/Linux servers is to chmod the relevant
files/directories to 777 (consult your FTP software documentation for help on
using the chmod command). However this option is not considered very secure as
anyone who has write access the web server (such as the owners of other web
sites hosted on the same computer) can potentially write to or delete these
directories. There may be a better way to make your files writable by your
server but this is something you must take up with your server administrator.</p>
 
 
<h2><a name="adminpermissions">The deal with admin permissions</a></h2>
 
<p>First thing to point out is that singapore admin permissions are not related
to unix/windows filesystem permissions. If you get a "permission denied" message
from php about a certain file, that's the filesystem permissions discussed in a
<a href="#permissions">separate section</a>. For the purposes of this section an
'object' is anything that can have admin permissions associated with it; i.e. an
image or a gallery.</p>
 
<p>There are two types of users: administrators and users. Administrators can do
everything and are not bound by permission settings. Only administrators may
create and edit users and change ownership of objects. Ownership is set at the
time of creation of the object to the user creating the object. The owner of an
object may do anything to it except change the owner. Only the owner or an
administrator may alter the permissions of an object, including changing its
group(s).</p>
 
<p>There are four kinds of action that may be either allowed or disallowed:
read, edit, add and delete. Read permissions allow an object to be viewed. Edit
permissions allow a user to edit (i.e. change) aspects of the object. Add
permissions allow a user to add sub objects (i.e. images and subgalleries). This
is obviously meaningless when applied to images but it may be used later to
allow image comments. Finally Delete permissions allow a user to delete the
object concerned (and any sub objects).</p>
 
<p>These four permissions come in two flavours: group and world. World
permissions apply to all users so if, for example, a gallery has the world add
permission set then any user can add objects to it. The groups system is
slightly less intuitive but very powerful. A user may belong to any number of
groups. These groups are simply alphanumeric names separated by spaces. An
object may also belong to any number of groups. If a user belongs to at least
one group to which the object concerned also belongs then the group permissions
are considered. For example a user has this for their groups field "team23
photographers friends" and an image belongs to the following groups "friends
family" and has the group delete permission set then that user may delete the
object since both belong to the group 'friends'.</p>
 
<p>Permissions are NOT inherited from parent objects.</p>
 
<p class="note">NOTE: read permissions are not currently enforced, a future
version will prevent anyone from seeing objects that do not have sufficient read
permissions. Note also that there is no mechanism to set image permissions this
will be amended in a later release. Finally, since there is no database
concurrency handling, odd things might happen if two users are making changes
to the same gallery or image simultaneously.</p>
 
 
<h2><a name="users">Managing users</a></h2>
 
<p>As mentioned above there are two types of users: administrators and users.
Administrators can do everything and are not bound by permission settings. Only
administrators may create and edit users. Administrators may also edit existing
users' details including changing their passwords though, of course, they cannot
view their existing passwords.</p>
 
<p>Users may also be suspended. This preserves all the user's details but
prevents them from loggin in until their account is unsuspended by an
administrator.</p>
 
<p>There are two built-in accounts that cannot be deleted. The "admin" account
is an administrator. The "guest" account is special. It is like a user account
except that guests have no password, cannot change their details and cannot own
objects. This means guests can only affect objects with the appropriate world
permissions set. Any object created by a guest is owned by the special user
"__nobody__" and has full read, edit, add and delete permissions for both world
and group. You may disable guest access to your gallery by suspending the guest
user.</p>
 
 
<h2><a name="nomenclature">Naming of parts</a></h2>
 
<dl>
 
<dt>Installation</dt>
<dd>an installation of singapore is contained within a website. It is usually
in its own separate directory and contains one gallery: the root gallery.</dd>
<dt>Root gallery</dt>
<dd>There is only one root gallery and it is not contained within any other
galleries. It is located directly in the directory specified by the
<code>pathto_galleries</code> option. It is usually referred to in URLs with a
single dot (as in <code>?gallery=.</code>).</dd>
<dt>Gallery</dt>
<dd>a gallery is contained within another gallery (except the root gallery
which is contained in an installation). Galleries may contain more galleries
and also images.</dd>
 
<dt>Album</dt>
<dd>an album is a special case of gallery that contains exactly zero
galleries and zero or more images. In other words a gallery is called an
album when it does not have any child galleries. So an album is a gallery
but a gallery is not an album in much the same way that a kitchen is a room
but a room is not a kitchen.</dd>
 
<dt>Image</dt>
<dd>an image is contained within an album or a gallery. Due to the way
singapore operates, images will only be displayed if they are in albums since
any images in non-album galleries will be hidden.</dd>
 
<dt>Child gallery (also known as subgallery)</dt>
<dd>this is a relative term. A child gallery is one contained within the
gallery currently being viewed or edited. There may be zero or more.</dd>
<dt>Parent gallery</dt>
<dd>this is a relative term. The parent gallery is the one which contains the
gallery currently being viewed or edited. There is always exactly one (except
in the case of the root gallery which has no parent).</dd>
</dl>
 
<h2><a name="history">Version history</a></h2>
 
<pre>Key to symbols:
+ added
- removed
* fixed
o changed
</pre>
 
<p>A complete and up-to-date CVS changelog is
<a href="http://www.sgal.org/cvsdemo/ChangeLog">available online</a>.</p>
 
<h3>0.10.1 - 2006-09-20</h3>
 
<pre>
* fixed template security issue
+ access control settings are inherited by child galleries
* fixed image hits total
o updated modern template (see separate changelog)
</pre>
 
<h3>0.10.0 - 2006-05-17</h3>
 
<pre>
o code is now more object oriented and easier to understand
+ added safe_mode hack using FTP
+ can move &amp; copy galleries in admin
+ can batch delete images and galleries in admin
o thumbnails and logs stored in each gallery
+ thumbnails created on page load and statically linked
+ ancestor metadata is parsed for crumb line
o removed leading ./ from gallery id in urls
+ next and previous gallery links
+ 'up' links to correct page of parent gallery
* base_path and base_url are no longer overwritten by external.php
* fixed eastern european characters in data fields
* fixed new lines in summary field
* fixed image resizing bug when image size equals maxsize
* fixed imagemagick v6.x support
* fixed session.auto_start bug (aka login loop)
* fixed XSS vulnerability in template &amp; language flippers
+ added sort by date field to galleries
o rewritten hit logging code
o added explicit chmod's instead of relying on umask
o new admin error handling in preparetion for our new admin backend
</pre>
 
<h3>0.9.11 - 2004-12-15</h3>
 
<pre>
+ added SQL abstraction backend with support for MySQL and SQLite
o changed IO class hierarchy
o streamlined install process
+ separated editprofile from edituser
* fixed multiple vulnerabilities (thanks to SIG^2)
+ added allow_dir_upload config option
</pre>
 
<h3>0.9.10 - 2004-10-20</h3>
 
<pre>
+ implemented full multi-user support with permissions
+ reindex metadata feature in admin for importing ftp'd images
+ language and template are now user-selectable on-the-fly
+ language may be auto-detected from user agent headers
+ summary field now used instead of description field
o introduced new streamlined admin template with quicklinks
o tidied up css classes and annotated the default stylesheet
* fixed md5 dictionary attack vulnerability by hiding user account details
* fixed security issue with back-references in arguments to thumb.php
o made thumb.php reject files with extensions not in recognised_extensions
o changed base_file config option to index_file_url
o changed language config option to default_language
o changed template_name config option to default_template
+ new external.php file for integrating singapore into existing layouts
</pre>
 
<h3>0.9.9b - 2004-08-08</h3>
 
<pre>
* fixed image size calculation (again)
</pre>
 
<h3>0.9.9a - 2004-06-11</h3>
 
<pre>
* fixed multi-page galleries bug in templates
* fixed XHTML compliance
* fixed image size calculation
* possibly other things
</pre>
 
<h3>0.9.9 - 2004-05-15</h3>
 
<pre>
+ added multi-image upload using ZIP files
+ added fixed size and aspect ratio thumbnail creation
* fixed umask functionality (thanks to afuhrmann)
+ added navigation by clickable image map
+ added upload_overwrite config option
o moved url generation into separate function(s) (acsissman)
+ enabled use of mod_rewrite with appropriate .htaccess (acsissman)
+ added progressive jpeg option (thanks to joeforker)
o moved i18n functions into separate class
* made site navigation links xhtml compatible
* fixed special characters in filenames under ImageMagick *again*?
o introduced consistent 'gallery>album>image' naming scheme
o GD2 used as default thumbnail_software (GD1 support unaffected)
</pre>
 
<h3>0.9.8 - 2004-01-06</h3>
 
<pre>
+ automatic recognition of most URLs in 'description' field
+ do not process directories starting with dot (.)
+ enabled navigation bar in supporting browsers (e.g. mozilla, opera)
o made 'artist - name' iifn parsing optional
* fixed bizarre sort order in admin mode
* use htmlspecialchars instead of htmlentities
* fixed using special chars in filenames when magic_quotes_gpc is on (again)
* fixed code that produced 'Notice' level errors with PHP 5
</pre>
 
<h3>0.9.7 - 2003-11-17</h3>
 
<pre>
+ added forced image resizing to fixed size
+ added rudimentary image and gallery sort ordering
* fixed multi-page galleries listings
* fixed zero-width thumbnails for failed uploads
+ added a few functions useful for templates
+ added .jpe extension
o changed details array format
+ added basePath parameter to allow removed instantiation of singapore class
o fixed some untranslated strings in admin mode
* maybe fixed using special chars in filenames when magic_quotes_gpc is on
+ added back-reference check to prevent file-system walking
o merged __g functionality into _g and _ng
</pre>
 
<h3>0.9.6 - 2003-08-15</h3>
 
<pre>
o code entirely reorganised and largely re-written into classes
+ multilanguage (i18n) support
o interface is template driven
+ per-gallery and per-template configuration files
+ nested gallery support (unlimited depth)
+ crumb line for easier navigation
* all image and gallery names are now urlencoded
+ many new config options
</pre>
 
<h3>0.9.5 - 2003-05-31</h3>
 
<pre>
* fixed GD2 support in thumb.php (0.9.4a always used GD1)
- removed secret string option
+ added config options for admin session name (allows multiple installs on same server),
path to convert (ImageMagick), remove jpeg profile (ImageMagick),
character encoding &amp; site name (page title)
o execution_timer off by default and default galleries per page set to 10
+ thumb.php always uses fopen on remote files (now works on windows)
+ more checks in test.php including ImageMagick support and bugfix #743954 (upload_tmp_dir)
</pre>
 
<h3>0.9.4a - 2003-05-16</h3>
 
<pre>
+ added PNG and GIF support under GD (GIF only with compatible versions of GD)
+ added PNG, GIF, TIFF, BMP, and support from pretty much every
other file type under ImageMagick
+ more checks in test.php
* fixed image counting in iifn mode
* fixed show_image_name_in_thumbnail_view
+ images link back to correct page of gallery (second link)
</pre>
 
<h3>0.9.4 - 2003-05-13</h3>
 
<pre>
o changed config to ini file + global config object
o changed directory structure (moved documentation into docs/, moved writable files into data/)
+ gallery (thumbnail) view shows more information
+ gallery (thumbnail) view can show image name under thumbnail (off by default)
+ gallery (list) view shows number of images in gallery
+ implemented random thumbnail image in gallery (list) view
+ added test.php and setup.php (not very useful yet)
* fixed handling of gallery_thumb_number config option
* password change bug
* remote file thumbnail generation with ImageMagick
</pre>
 
<h3>0.9.3 - 2003-05-10</h3>
 
<pre>
+ web admin can add and delete images and galleries
+ added GD 2 and ImageMagic thumbnail generation support
* does not generate any E_NOTICE errors anymore
+ added config option for generated thumbnail JPEG quality
* handles extended characters in gallery and image names (Piotr)
* fixed 'images link back to correct page of gallery'
+ added directory_mode and file_mode options
* track_views and show_views now work independently
o admin bar now visible everywhere when logged in
</pre>
 
<h3>0.9.2 - 2003-04-27</h3>
 
<pre>
* fixed non-expiration of admin sessions in some cases
+ added purge cached thumbnails option
+ new 'XP' theme
* fixed hit logging functions
+ added image hit log viewing in admin mode
+ images link back to correct page of gallery
o optimised config.php
* fixed some css issues
</pre>
 
<h3>0.9.1 - 2003-04-23</h3>
 
<pre>
o changed database format
+ added visible database fields for artist email, darkroom manipulation and
digital manipulation
+ added invisible (control) database fields for thumbnail, owner, groups and categories
o put header and footer code into separate files
+ implemented limited themeing support
+ added config options for custom paths to cache, galleries, logs, themes,
header, footer and custom css
o improved navigation in admin mode
+ added optional script execution timer
* fixed proliferation of newlines in 'desc' field
* fixed wrongly escaped characters when saving info
</pre>
 
<h3>0.9a - 2003-04-13</h3>
 
<pre>
+ added much better documentation
</pre>
 
<h3>0.9 - 2003-03-30</h3>
 
<pre>
+ admin section (allows editing image and gallery info)
+ nicer gallery list layout
+ filename parser for if no metadata file found
o split into separate include files for io operations, ui generation etc
* fixed some css issues
+ lots of other little things
</pre>
 
<h3>0.0 (unnumbered version) - 2003-03-29</h3>
 
<pre>
o first release under GPL
+ everything
</pre>
 
<p><em>$Date: 2006/05/18 16:14:20 $</em></p>
 
</body>
</html>
/photogallery/docs/Translation.html
0,0 → 1,526
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>singapore - Translation</title>
<link rel="stylesheet" type="text/css" href="docstyle.css" />
</head>
 
<body>
 
<h1>singapore - Translation</h1>
 
<ul>
<li><a href="#intro">Introduction</a></li>
<li><a href="#requirements">Requirements</a></li>
<li><a href="#update">Updating a translation</a></li>
<li><a href="#new">Starting a new translation</a></li>
<li><a href="#header">Filling in the header section</a></li>
<li><a href="#plurals">Plural forms</a></li>
<li><a href="#links">Useful links</a></li>
<li><a href="Readme.html">General readme</a></li>
<li><a href="Advanced.html">Advanced features</a></li>
<li><a href="Development.html">Developer documentation</a></li>
</ul>
 
 
<h2><a name="intro">Introduction</a></h2>
 
<p>Thank you for taking an interest in open source development!
Translating singapore is a matter of editing a single file and
then running a script on it. What could be simpler?</p>
 
<p>Language strings are stored in standard GNU Gettext PO (portable object)
files which means you can (at least in theory <a href="#foot1" name="note1"><sup>1</sup></a>)
use all currently available PO editors such as
<a href="http://poedit.sourceforge.net/">poEdit</a> to make your
translations.</p>
 
<p>For added convenience strings for each language are split into two sections:
one for normal gallery operation and another for strings that are only used in
admin mode. This means that admin strings are not needlessly loaded for every
page and also that translators have the choice of only translating the standard
strings or going the whole way and translating the admin strings too.</p>
 
<p>It is a good idea for all translators and potential translators to join the
<a href="http://lists.sourceforge.net/lists/listinfo/singapore-devel">development
mailing list</a>. Use this, the
<a href="http://singapore.sourceforge.net/forum/viewforum.php?f=6">internationalisation forum</a>
and the
<a href="http://sourceforge.net/tracker/?atid=611769&group_id=77687">translations tracker</a>
to interact with other translators and developers.</p>
 
<p class="boxed"><a href="#note1" name="foot1">1</a>The reason for the "in theory"
is that many PO editors do not support the plural forms that singapore makes use
of - even though they are defined and supported by GNU Gettext. poEdit does
support plural forms since v1.3 and is highly recommended. Alternatively it is
just as easy to use a standard text editor to make your translations.</p>
 
<h2><a name="requirements">Requirements</a></h2>
 
<p>No further software is required for using the multilanguage capabilities of
singapore. However the extract and merge tools use xgettext and msgmerge
respectively. Both these programs are part of GNU Gettext which is already
installed on most Linux distributions. A package of the relevant gettext
binaries for Windows is available here:
<a href="http://singapore.sourceforge.net/binaries/singapore-gettext-Win32.zip">http://singapore.sourceforge.net/binaries/singapore-gettext-Win32.zip</a>.
The path to xgettext is stored in <code>tools/extract.php</code> and the path to
msgmerge is stored in <code>tools/merge.php</code>. However if the gettext programs
are in your PATH or in the <code>tools/</code> directory itself then you do not
need to edit anything.</p>
 
 
<h2><a name="update">Updating a translation</a></h2>
 
<p>Each singapore release requires the language files to be updated slightly.
First make sure you have the latest available translation (the
<a href="http://sourceforge.net/tracker/?atid=611769&group_id=77687">translations tracker</a>
is a good place to check for this). Now you need to merge in the new untranslated
strings and remove the obsolete ones (this may have already been done
but there's no harm in doing it again). Place the old PO file in the locale
directory of an installation of the latest version of singapore and use the
<a href="../tools/merge.php">merge</a> script provided.</p>
 
<p>Now proceed translating the strings as described below. Finally, attach the
updated PO file to the appropriate tracker item making sure to state which
version of singapore it is for.</p>
 
 
<h2><a name="new">Starting a new translation</a></h2>
 
<p>The very first thing to do is submit a tracker item on the
<a href="http://sourceforge.net/tracker/?atid=611769&group_id=77687">translations tracker</a>
to inform people of your intentions so that two or more people do not needlessly
spend time translating the same files for the same language. Once you have
completed your translations you can attach the files to the tracker item.</p>
 
<p>All language files are kept in a single directory (<code>locale/</code> by
default). They are named as follows:</p>
 
<ul>
<li><code>singapore.pot</code> -
untranslated standard language strings template in PO format</li>
<li><code>singapore.admin.pot</code> -
untranslated admin language strings template in PO format</li>
<li><code>singapore.<em>LANG</em>.po</code> -
translated standard language strings in PO format</li>
<li><code>singapore.admin.<em>LANG</em>.po</code> -
translated admin language strings in PO format</li>
<li><code>singapore.<em>LANG</em>.pmo</code> -
translated standard strings as compiled PHP serialized object</li>
<li><code>singapore.admin.<em>LANG</em>.pmo</code> -
translated admin strings as compiled PHP serialized object</li>
</ul>
 
<p>where <code><em>LANG</em></code> represents the ISO639 language code of the chosen
language (e.g. <code>de</code> for German, <code>en</code> for English,
<code>en-gb</code> for English (United Kingdom)). A more comprehensive list of
language codes may be found here:
<a href="http://www.rickbull.co.uk/tutorials/HTML/Useful%20Information/language_codes.php">http://www.rickbull.co.uk/tutorials/HTML/Useful%20Information/language_codes.php</a></p>
 
<p>Start by copying a PO template file (<code>singapore.pot</code> if you
are translating the standard strings or <code>singapore.admin.pot</code> if you
are translating the admin strings) and naming it appropriately for your language
as described above. Now open the file in your chosen PO editor or a plain text
editor and set about translating the strings.</p>
 
<p>You also need to fill in certain parts of the <a href="#header">PO file
header</a>. You may do this at any stage of the translation.</p>
 
<p>NOTES:</p>
 
<ol>
<li>Strings in the form "crumb line|You are here:"<br />
In these cases the text up to and including the vertical bar, |, should NOT
be included in the translation. They are simply hints for the translator.</li>
<li>Strings in the form "Showing %s-%s of %s"<br />
In these cases each %s will be replaced at runtime by a number or string in
order from left to right according to the rules of <code>printf()</code>.
Essentially each %s is a placeholder and so needs to be present at the
appropriate place in the translated string.<br />
However some languages may require the order of the arguments to be changed.
For example if instead of "Showing 1-10 of 15" you want to say
"Out of 15 objects 1-10 are shown" then you must use the argument swapping
syntax of <code>printf()</code>. More details on this may be found here:
<a href="http://www.php.net/sprintf">http://www.php.net/sprintf</a></li>
<li>Strings with plurals<br />
You must correctly specify the <a href="#plurals">Plural-forms</a> header field
in order to make use of plural forms. Put each plural in its own
<code>msgstr[<em>x</em>]</code> where x is a number between 0 (inclusive) and
the nplurals number you specified in the header (see examples below).</li>
 
<li>Using a text-editor<br />
When translating an entry you must leave the English language strings
(those on lines starting <code>msgid</code>) untouched and insert the
translated strings between the double-quotes on the following lines (those
starting <code>msgstr</code> or <code>msgstr[<em>x</em>]</code> in the case of
plurals).</li>
<li>Obsolete entries<br />
When updating a PO file, obsolete entries (i.e. those strings which appeared
in the previous version but do not in the current version) are placed at the
end of the PO file and prepended by <code>#~</code>. There is no need to
translate these entries as they are ignored by the compiler.</li>
</ol>
 
<p>Once you have translated all the strings and filled in the header, you need
to compile the PO file into a PHP serialized object file for use with
singapore. Do this using the <a href="../tools/compile.php">compile</a> script
provided in the <code>tools/</code> directory of the singapore distribution.</p>
 
<p>And that's it!</p>
 
<p>Now go and attach your translated PO file(s) to the tracker item you created
before starting the translation so that everyone else can make use of it.</p>
 
<h2>Examples</h2>
 
<p>The following string
<pre class="boxed">
# File: ../includes/singapore.class.php, line: 247
#, c-format
msgid "Page created in %s seconds"
msgstr ""
</pre>
when translated into French becomes
<pre class="boxed">
# File: ../includes/singapore.class.php, line: 247
#, c-format
msgid "Page created in %s seconds"
msgstr "Page créée en %s secondes"
</pre>
 
and the following string
<pre class="boxed">
# File: ../includes/admin.class.php, line: 173
msgid "admin bar|Edit image"
msgstr ""
</pre>
when translated into Italian becomes
<pre class="boxed">
# File: ../includes/admin.class.php, line: 173
msgid "admin bar|Edit image"
msgstr "Modifica l'immagine"
</pre>
 
and the following string
<pre class="boxed">
# File: ../includes/singapore.class.php, line: 530
#, c-format
msgid "%s gallery"
msgid_plural "%s galleries"
msgstr[0] ""
</pre>
when translated into Spanish becomes
<pre class="boxed">
# File: ../includes/singapore.class.php, line: 530
#, c-format
msgid "%s gallery"
msgid_plural "%s galleries"
msgstr[0] "%s galería"
msgstr[1] "%s galerías"
</pre>
 
</p>
 
<h2><a name="header">Filling in the header section</a></h2>
 
<p class="note">NOTE: This section is mainly copied from the
<a href="http://www.gnu.org/manual/gettext/html_chapter/gettext_5.html#SEC35">section 5.2</a>
of the GNU Gettext manual.</p>
 
<p>The initial comments "SOME DESCRIPTIVE TITLE", "YEAR" and
"FIRST AUTHOR &lt;EMAIL@ADDRESS&gt;, YEAR" ought to be replaced by
sensible information.</p>
 
<h3>The following fields must be filled in correctly:</h3>
 
<dl>
<dt>Content-Type</dt>
<dd>Replace <samp>ISO-8859-1</samp> with the
character encoding used for your language, in your locale, or
UTF-8. This field is needed for correct operation of the
<code>msgmerge</code> program, as well
as for users whose locale's character encoding differs from yours.
<p>The following encodings are frequently used for the corresponding
languages.</p>
<ul>
<li><code>ISO-8859-1</code> for Afrikaans, Albanian, Basque,
Catalan, Dutch, English, Estonian, Faroese, Finnish, French,
Galician, German, Greenlandic, Icelandic, Indonesian, Irish,
Italian, Malay, Norwegian, Portuguese, Spanish, Swedish,</li>
<li><code>ISO-8859-2</code> for Croatian, Czech, Hungarian,
Polish, Romanian, Serbian, Slovak, Slovenian,</li>
<li><code>ISO-8859-3</code> for Maltese,</li>
<li><code>ISO-8859-5</code> for Macedonian, Serbian,</li>
<li><code>ISO-8859-6</code> for Arabic,</li>
<li><code>ISO-8859-7</code> for Greek,</li>
<li><code>ISO-8859-8</code> for Hebrew,</li>
<li><code>ISO-8859-9</code> for Turkish,</li>
<li><code>ISO-8859-13</code> for Latvian, Lithuanian,</li>
<li><code>ISO-8859-15</code> for Basque, Catalan, Dutch, English,
Finnish, French, Galician, German, Irish, Italian, Portuguese,
Spanish, Swedish,</li>
<li><code>KOI8-R</code> for Russian,</li>
<li><code>KOI8-U</code> for Ukrainian,</li>
<li><code>CP1251</code> for Bulgarian, Byelorussian,</li>
<li><code>GB2312</code>, <code>GBK</code>, <code>GB18030</code>
for simplified writing of Chinese,</li>
<li><code>BIG5</code>, <code>BIG5-HKSCS</code> for traditional
writing of Chinese,</li>
<li><code>EUC-JP</code> for Japanese,</li>
<li><code>EUC-KR</code> for Korean,</li>
<li><code>TIS-620</code> for Thai,</li>
<li><code>UTF-8</code> for any language, including those listed
above.</li>
</ul>
<p>The character encoding name can be written in either upper or
lower case. Usually upper case is preferred.</p>
</dd>
<dt>Plural-Forms</dt>
<dd>See the <a href="#plurals">plural forms</a> section.</dd>
 
</dl>
 
<h3>The following fields should be filled in:</h3>
 
<dl>
<dt>Project-Id-Version</dt>
<dd>This is the name and version of the package.</dd>
<dt>Last-Translator</dt>
<dd>Fill in your name and email address (without double
quotes).</dd>
<dt>Language-Team</dt>
<dd>Fill in the English name of the language followed by the native name
of the language in brackets. E.g. <i>"Language-Team: German (Deutsch)\n"</i><br />
Note this is different from the GNU specification but is required in order
for the language flipper function to work.
</dd>
</dl>
 
<h3>The following fields may be left alone:</h3>
 
<dl>
<dt>POT-Creation-Date</dt>
<dd>This has already been filled in by <code>xgettext</code>.</dd>
<dt>PO-Revision-Date</dt>
<dd>You don't need to fill this in. It should be filled by the editor when
you save the file.</dd>
<dt>Content-Transfer-Encoding</dt>
<dd>Set this to <code>8bit</code>.</dd>
</dl>
 
<h2><a name="plurals">Plural forms</a></h2>
 
<p class="note">NOTE: This section is mainly copied from the
<a href="http://www.gnu.org/manual/gettext/html_chapter/gettext_10.html#SEC150">section 10.2.5</a>
of the GNU Gettext manual.</p>
 
 
<p>The Plural-forms field in the PO header is used to calculate which plural
form of a word to use. In English there are only two plural forms but other
languages have only one or as many as four.</p>
 
<p>Please check the list below to see if your language is listed. If it is
then use the corresponding string. If not then you can either write it yourself
(details below and in the gettext manual) or email a member of the team
describing how your langauge works (e.g. (not real) 0 car, 1-2 cars, 3 caren, 5+ carii)
and we will write one for you.
 
<dl>
<dt>Only one form:</dt>
<dd>Some languages only require one single form. There is no
distinction between the singular and plural form. An appropriate
header entry would look like this:
<pre>Plural-Forms: nplurals=1; plural=0;</pre>
<p>Languages with this property include:</p>
<dl>
<dt>Finno-Ugric family</dt>
<dd>Hungarian</dd>
<dt>Asian family</dt>
<dd>Japanese, Korean</dd>
<dt>Turkic/Altaic family</dt>
<dd>Turkish</dd>
</dl>
</dd>
<dt>Two forms, singular used for one only</dt>
<dd>This is the form used in most existing programs since it is
what English is using. A header entry would look like this:
<pre>Plural-Forms: nplurals=2; plural=n==1 ? 0 : 1;</pre>
<p>Languages with this property include:</p>
<dl>
<dt>Germanic family</dt>
<dd>Danish, Dutch, English, German, Norwegian, Swedish</dd>
<dt>Finno-Ugric family</dt>
<dd>Estonian, Finnish</dd>
<dt>Latin/Greek family</dt>
<dd>Greek</dd>
<dt>Semitic family</dt>
<dd>Hebrew</dd>
<dt>Romanic family</dt>
<dd>Italian, Portuguese, Spanish</dd>
<dt>Artificial</dt>
<dd>Esperanto</dd>
</dl>
</dd>
<dt>Two forms, singular used for zero and one</dt>
<dd>Exceptional case in the language family. The header entry would be:
<pre>Plural-Forms: nplurals=2; plural=n&gt;1;</pre>
<p>Languages with this property include:</p>
<dl>
<dt>Romanic family</dt>
<dd>French, Brazilian Portuguese</dd>
</dl>
</dd>
<dt>Three forms, special case for zero</dt>
<dd>The header entry would be:
<pre>Plural-Forms: nplurals=3; plural=n%10==1 &amp;&amp; n%100!=11 ? 0 : n != 0 ? 1 : 2;</pre>
<p>Languages with this property include:</p>
<dl>
<dt>Baltic family</dt>
<dd>Latvian</dd>
</dl>
</dd>
<dt>Three forms, special cases for one and two</dt>
<dd>The header entry would be:
<pre>Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;</pre>
<p>Languages with this property include:</p>
<dl>
<dt>Celtic</dt>
<dd>Gaeilge (Irish)</dd>
</dl>
</dd>
<dt>Three forms, special case for numbers ending in 1[2-9]</dt>
<dd>The header entry would look like this:
<pre>Plural-Forms: nplurals=3; plural=n%10==1 &amp;&amp; n%100!=11 ? 0 : n%10&gt;=2 &amp;&amp; (n%100&lt;10 || n%100&gt;=20) ? 1 : 2;</pre>
<p>Languages with this property include:</p>
<dl>
<dt>Baltic family</dt>
<dd>Lithuanian</dd>
</dl>
</dd>
<dt>Three forms, special cases for numbers ending in 1 and 2, 3,
4, except those ending in 1[1-4]</dt>
<dd>The header entry would look like this:
<pre>Plural-Forms: nplurals=3; plural=n%10==1 &amp;&amp; n%100!=11 ? 0 : n%10&gt;=2 &amp;&amp; n%10&lt;=4 &amp;&amp; (n%100&lt;10 || n%100&gt;=20) ? 1 : 2;</pre>
<p>Languages with this property include:</p>
<dl>
<dt>Slavic family</dt>
<dd>Croatian, Czech, Russian, Slovak, Ukrainian</dd>
</dl>
</dd>
<dt>Three forms, special case for one and some numbers ending in
2, 3, or 4</dt>
<dd>The header entry would look like this:
<pre>Plural-Forms: nplurals=3; plural=n==1 ? 0 : n%10&gt;=2 &amp;&amp; n%10&lt;=4 &amp;&amp; (n%100&lt;10 || n%100&gt;=20) ? 1 : 2;</pre>
<p>Languages with this property include:</p>
<dl>
<dt>Slavic family</dt>
<dd>Polish</dd>
</dl>
</dd>
<dt>Four forms, special case for one and all numbers ending in
02, 03, or 04</dt>
<dd>The header entry would look like this:
<pre>Plural-Forms: nplurals=4; plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;</pre>
<p>Languages with this property include:</p>
<dl>
<dt>Slavic family</dt>
<dd>Slovenian</dd>
</dl>
</dd>
</dl>
 
<h3>How the Plural-forms header works:</h3>
 
<p>The <code>nplurals</code> value must be a decimal number which
specifies how many different plural forms exist for this
language. The string following <code>plural</code> is an
expression which is using the C language syntax. Exceptions are
that no negative numbers are allowed, numbers must be decimal,
and the only variable allowed is <code>n</code>. This expression
will be evaluated whenever one of the plural functions is called.
The numeric value passed to
these functions is then substituted for all uses of the variable
<code>n</code> in the expression. The resulting value then must
be greater or equal to zero and smaller than the value given as
the value of <code>nplurals</code>.</p>
 
<h2><a name="links">Useful links</a></h2>
 
<ul>
<li><a href="http://singapore.sourceforge.net/forum/viewforum.php?f=6">singapore i18n forum</a></li>
<li><a href="http://www.gnu.org/software/gettext/">GNU Gettext homepage</a></li>
<li><a href="http://www.gnu.org/manual/gettext/">GNU Gettext manual</a> - lots
of technical information about the PO format</li>
<li><a href="http://poedit.sourceforge.net/">poEdit</a> - an open source cross-platform PO editor</li>
<li><a href="http://www.gtranslator.org/">gTranslator</a> - a PO editor for GNOME</li>
<li><a href="http://i18n.kde.org/tools/kbabel/">KBabel</a> - a PO editor for KDE</li>
</ul>
 
 
<p><em>$Date: 2004/11/01 08:17:33 $</em></p>
 
</body>
</html>
/photogallery/docs/docstyle.css
0,0 → 1,106
body {
margin: 1em;
font: small sans-serif;
color: #000;
background-color: #fff;
}
 
p, td, th, li, dd, dt {
font: small sans-serif;
}
 
h1, h2, h3, h4{
color: #f60;
}
 
h1, h2 {
font-size: medium;
border-bottom: 1px solid #ccc;
letter-spacing: 0.3em;
text-transform: uppercase;
}
 
code, pre {
color: #444;
}
 
p, td, th, li, dt, h3, h4, pre {
margin-left: 2em;
}
 
dd {
margin-left: 3em;
}
 
dt {
margin-top: 0.5em;
}
 
a:link {
color: #09f;
text-decoration: underline;
}
 
a:visited {
color: #05a;
text-decoration: underline;
}
 
a:hover {
text-decoration: none;
}
 
input, textarea, select, .inputbox {
border: 1px solid #f60;
color: #000;
background-color: #fff;
}
 
input.radio {
border: none;
background-color: #fff;
}
 
input.button {
font-weight: bold;
border: 1px outset #fff;
color: #fff;
background-color: #f60;
}
 
ul.things > li {
margin-top: 0.75em;
}
 
.note {
color: #d00;
}
 
.error {
color: #f00;
}
 
.boxed, .note, #progressBox {
border: 1px dashed #ccc;
padding: 0.5em;
}
 
#progressBox {
float: right;
background-color: inherit;
}
 
#progressBox li.currentStep {
color: #f60;
font-size: medium;
}
 
#progressBox p, #progressBox li, #progressBox ol {
font-weight: bold;
margin: 0em;
}
 
a.button {
margin-top: 2em;
display: block;
}
/photogallery/docs/index.html
0,0 → 1,27
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>singapore documentation</title>
<link rel="stylesheet" type="text/css" href="docstyle.css" />
</head>
 
<body>
 
<h1>singapore documentation</h1>
 
<ul>
<li><a href="Readme.html">General readme including installation instructions</a></li>
<li><a href="Advanced.html">Advanced features and how to use them</a></li>
<li><a href="Translation.html">Translating singapore</a></li>
<li><a href="Development.html">Developer documentation</a></li>
<li><a href="http://singapore.sourceforge.net/">Home page</a></li>
<li><a href="http://singapore.sourceforge.net/forum/">Support forum</a></li>
<li><a href="http://sourceforge.net/project/showfiles.php?group_id=77687&package_id=78646">Download latest version</a></li>
</ul>
 
<p><a href="../">Return</a> to singapore.</p>
 
</body>
</html>
/photogallery/singapore_gallery_files/docs/Development.html
File deleted
/photogallery/singapore_gallery_files/docs/Advanced.html
File deleted
/photogallery/singapore_gallery_files/docs/index.html
File deleted
/photogallery/singapore_gallery_files/docs/docstyle.css
File deleted
/photogallery/singapore_gallery_files/docs/Readme.html
File deleted
/photogallery/singapore_gallery_files/docs/License.txt
File deleted
/photogallery/singapore_gallery_files/docs/Translation.html
File deleted
\ No newline at end of file