/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>) |
> gallery settings (<code>gallery.ini</code>) > 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® 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><?php include("path/to/singapore/external.php");?></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 <html> |
start tags, two <head> 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;</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->gallery->images[$index]->thumbnailLink()</code> |
with <code>$sg->gallery->images[$index]->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 <tam@zenology.co.uk> * |
* * |
* 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 & 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 & 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 & 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 <EMAIL@ADDRESS>, 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>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 && 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 && n%100!=11 ? 0 : n%10>=2 && (n%100<10 || n%100>=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 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=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>=2 && n%10<=4 && (n%100<10 || n%100>=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/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 |
/photogallery/singapore_gallery_files/docs/Development.html |
---|
File deleted |
/photogallery/singapore_gallery_files/docs/Advanced.html |
---|
File deleted |