[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gforge-commits] gforge/docs/docbook/docbook/contribution_guide/include
|
From: |
gsmet |
|
Subject: |
[Gforge-commits] gforge/docs/docbook/docbook/contribution_guide/include howto_localization.xml, NONE, 1.1 coding_standards.xml, NONE, 1.1 howto_xhtml.xml, NONE, 1.1 howto_contribute.xml, NONE, 1.1 howto_documentation.xml, NONE, 1.1 templating.xml, NONE, 1.1 |
|
Date: |
Tue, 02 Mar 2004 10:58:42 -0600 |
Update of /cvsroot/gforge/gforge/docs/docbook/docbook/contribution_guide/include
In directory
db.perdue.net:/tmp/cvs-serv22607/docs/docbook/docbook/contribution_guide/include
Added Files:
howto_localization.xml coding_standards.xml howto_xhtml.xml
howto_contribute.xml howto_documentation.xml templating.xml
Log Message:
converted doc from Maven xdoc to XML Docbook
--- NEW FILE: howto_localization.xml ---
<section id="cg_howto_localization">
<title>Localization howto</title>
<section>
<title>Localizing Gforge</title>
<para>
This short HOWTO explains how you can customize your
local installation of Gforge.
</para>
</section>
<section>
<title>Adding a new language</title>
<para>
These are the steps to add a new language:
</para>
<orderedlist>
<listitem>
<para>
Add a row in the <database
class="table">supported_languages</database> table in the
<database>gforge</database> database:
</para>
<programlisting>
INSERT INTO supported_languages
(language_id, name, filename, classname, language_code)
VALUES (NEXTVAL('"supported_langu_language_id_seq"'::text),
'German (Austria)',
'Austrian.class',
'Austrian',
'AT'
);
</programlisting>
<note>
<para>
The language_code should follow
the international language codings.
</para>
</note>
</listitem>
<listitem>
<para>
Copy the file
<filename>Base.tab</filename> to <filename>Austrian.tab</filename> and place it
in the <filename>www/languages/include</filename> folder.
</para>
</listitem>
<listitem>
<para>Translate the document</para>
<warning>
<para>If you are not going to translate
the entire document, please just override strings you translate.</para>
</warning>
</listitem>
<listitem>
<para>Submit the translation to the gforge
project</para>
</listitem>
</orderedlist>
</section>
<section>
<title>What is there to customize?</title>
<para>
I'm afraid there isn't much space for customisation in
Gforge yet. For now, two main areas exist:
</para>
<itemizedlist>
<listitem><para>look</para></listitem>
<listitem><para>text content</para></listitem>
</itemizedlist>
<para>
The look of your Gforge site is customisable via the
theme system (read the README.Themes file fo more information on this).
</para>
<para>
The text content can be somewhat customized. The Gforge
internationalisation system already provides a way to have different texts
depending on user choice.
</para>
</section>
<section>
<title>How do I customize texts?</title>
<para>
First, a quick course on the internationalisation
system present in Gforge.
</para>
<para>
The texts you can read on the web pages are not
hard-coded. Well, some of them are, but we're working on them. Instead, they
are displayed as results of a function of several parameters. One of these
parameters is the language in which you wish to display a piece of information,
and another is some handle to identify the information you want to display.
</para>
<para>
In Gforge, this handle is made up of the <quote>page
name</quote> and the <quote>category</quote> strings. Knowing all the needed
info, the function displays the appropriate text. How appropriate is this
text? Well, that depends. First, a basic set of texts is loaded.
Historically, this set is loaded in English. This set of texts makes the Base
class, storing texts for all known <quote>handles</quote>. This set of texts
can then be partially or completely overloaded, e.g. for other languages: the
handles present in the language overwrite the Base handles, and the ones not
found keep their values from the Base class.
</para>
<para>
The language files are located in the
<filename>www/include/languages</filename> directory.
</para>
<para>
To localize Gforge in a new language, copy
<filename>Base.tab</filename> in
<filename><userinput>yourlanguage</userinput>.tab</filename>. If you wish to
add Foobaric language, run the following command <command>cp Base.tab
Foobaric.tab</command>.
</para>
</section>
<section>
<title>Format of the *.tab files</title>
<para>
The *.tab files are in a fairly straightforward format.
Lines starting with a '#' character are ignored, other lines must be in the
following format:
</para>
<programlisting><![CDATA[
,----
| <pagename> TAB <category> TAB <data>
`---
]]></programlisting>
<para>
The <data> field can use variables in the form
$1, $2, etc. These variables are defined by the script and there's no simple
way of knowing what they are apart from looking at the script itself. To find
out exactly what these variables are filled out with, search for the
<methodname>getText('<pagename>','<category'>)</methodname> string
in the scripts contained in the <filename>www/</filename> and
<filename>common/</filename>. This is not always easy to do.
</para>
<para>
Your best bet is to guess the meaning of the $1, $2,
etc. variables from the non-customized text (either Base.tab or Foobaric.tab if
it is defined).
</para>
</section>
<section>
<title>How to do it - really</title>
<para>
The way I usually go when I have to customize some text
is simply the following:
</para>
<orderedlist>
<listitem><para>Find the bit of text I want to
customize (in either Base.tab or Foobaric.tab);</para></listitem>
<listitem><para>Copy and paste the appropriate line
(including the <quote>handle</quote> -- the first two fields) in
Foobaric.tab;</para></listitem>
<listitem><para>Read it to find out about the $n
variables;</para></listitem>
<listitem><para>Replace the third field with my own
customized version.</para></listitem>
</orderedlist>
</section>
<section>
<title>Why customize</title>
<para>
There are two main reasons you would want to use the
process described in this section.
</para>
<para>
First, local policy. You might want to change page
footers, or contact pages, or host names, or whatever you need to integrate
your Gforge your target audience (company, organisation, or even your own
personal GForge). This document is for you.
</para>
<para>
Second, localization. This is not something completely
done in Gforge yet, and you might (will?) find huge gaps in the translation of
Gforge into your language. The English language, being the original one in
which Gforge was written, is obviouslycomplete. Soon-Son Kwon has provided a
full Korean translation, and I strive to make the French translation complete
too, but other languages are far from finished. You might then consider
translating Gforge into your language. If you do so, please also consider
submitting your translated file to us so that future releases of Gforge include
your translated file by default. Please refer to <ulink
url="http://gforge.org/";>gforge.org</ulink> for info on how to do that.
</para>
</section>
</section>
--- NEW FILE: coding_standards.xml ---
<section id="cg_coding_standards">
<title>PHP Coding Standards</title>
<section>
<title>Introduction</title>
<para>
Coding Standards. Live them, love them.
</para>
<para>
Then come up with a new introduction...
</para>
</section>
<section>
<title>Comments</title>
<section>
<title>Guidelines</title>
<para>
Non-documentation comments are strongly
encouraged. A general rule of thumb is that if you look at a section of code
and think "Wow, I don't want to try and describe that", you need to
comment it before you forget how it works.
</para>
<itemizedlist>
<listitem><para>C++ style comments (/* */) and
standard C comments (//) are both acceptable.</para></listitem>
<listitem><para>Use of perl/shell style
comments (#) is prohibited.</para></listitem>
</itemizedlist>
</section>
<section>
<title>PHPdoc Tags</title>
<para>
Inline documentation for classes should follow
the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be
found here: <ulink url="http://www.phpdoc.de/";>http://www.phpdoc.de/</ulink>
</para>
</section>
<section>
<title>File comments</title>
<para>
Every file should start with a comment block
describing its purpose, version, author and a copyright message. The comment
block should be a block comment in standard JavaDoc format along with a CVS Id
tag. While all JavaDoc tags are allowed, only the tags in the examples below
will be parsed by PHPdoc.
</para>
<para>
GForge contains a mixed copyright. For files
that have been changed since the GForge fork, the following header should be
used:
</para>
<programlisting><![CDATA[
/**
*
* brief description.
* long description. more long description.
*
* Portions Copyright 1999-2001 (c) VA Linux Systems
* The rest Copyright 2002 (c) their respective authors
*
* @version $Id: coding_standards.xml,v 1.1 2004/03/02 16:58:39 gsmet Exp $
*
*/
]]></programlisting>
</section>
<section>
<title>Function and Class Comments</title>
<para>
Similarly, every function should have a block
comment specifying name, parameters, return values, and last change date.
</para>
<programlisting><![CDATA[
/**
* brief description.
* long description. more long description.
*
* @author firstname lastname email
* @param variable description
* @return value description
* @date YYYY-MM-DD
* @deprecated
* @see
*
*/
]]></programlisting>
</section>
<section>
<title>Note</title>
<para>
The placement of periods in the short and long
descriptions is important to the PHPdoc parser. The first period always ends
the short description. All future periods are part of the long description,
ending with a blank comment line. The long comment is optional.
</para>
</section>
</section>
<section>
<title>Formatting</title>
<section>
<title>Indenting</title>
<para>
All indenting is done with TABS. Before
committing any file to CVS, make sure you first replace spaces with tabs and
verify the formatting.
</para>
</section>
<section>
<title>PHP Tags</title>
<para>
The use of <markup><?php ?></markup> to
delimit PHP code is required. Using <markup><? ?></markup> is not valid.
This is the most portable way to include PHP code on differing operating
systems and webserver setups. Also, XML parsers are confused by the shorthand
syntax.
</para>
</section>
</section>
<section>
<title>Templating</title>
<para>
In the GForge system, PHP itself is used as the
template language. To make the templating clearer, template files should be
separated out and included once objects and database results are established.
Detailed examples are in the docs repository and <link
linkend="cg_templating">here</link>.
</para>
<para>
Variables in the templates are presented surrounded by
<markup> <?php ?></markup> tags instead of the {} tags that some other
template libraries would use. The end result is the same, with less bloat and
more efficient code.
</para>
</section>
<section>
<title>Expressions</title>
<itemizedlist>
<listitem>
<para>Use parentheses liberally to resolve
ambiguity.</para>
</listitem>
<listitem>
<para>Using parentheses can force an order of
evaluation. This saves the time a reader may spend remembering precedence of
operators.</para>
</listitem>
<listitem>
<para>Don't sacrifice clarity for
cleverness.</para>
</listitem>
<listitem>
<para>Write conditional expressions so that
they read naturally aloud.</para>
</listitem>
<listitem>
<para>Sometimes eliminating a not operator (!)
will make an expression more understandable.</para>
</listitem>
<listitem>
<para>Keep each line simple.</para>
</listitem>
<listitem>
<para>The ternary operator (x ? 1 : 2) usually
indicates too much code on one line. if... else if... else is usually more
readable.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Functions</title>
<section>
<title>Function Calls</title>
<para>
unctions shall be called with no spaces between
the function name, the opening parenthesis, and the first parameter; spaces
between commas and each parameter, and no space between the last parameter, the
closing parenthesis, and the semicolon. Here's an example:
</para>
<programlisting><![CDATA[
$var = foo($bar, $baz, $quux);
]]></programlisting>
<para>
As displayed above, there should be one space
on either side of an equals sign used to assign the return value of a function
to a variable. In the case of a block of related assignments, more space may be
inserted to promote readability:
</para>
<programlisting><![CDATA[
$short = foo($bar);
$long_variable = foo($baz);
]]></programlisting>
</section>
<section>
<title>Function Definitions</title>
<para>
Function declarations follow the unix
convention:
</para>
<programlisting><![CDATA[
function fooFunction($arg1, $arg2 = '') {
if (condition) {
statement;
}
return $val;
}
]]></programlisting>
<para>
Arguments with default values go at the end of
the argument list. Always attempt to return a meaningful value from a function
if one is appropriate. Here is a slightly longer example:
</para>
<programlisting><![CDATA[
function connect(&$dsn, $persistent = false) {
if (is_array($dsn)) {
$dsninfo = &$dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}
if (!$dsninfo || !$dsninfo['phptype']) {
return $this->raiseError();
}
return true;
}
]]></programlisting>
</section>
</section>
<section>
<title>Objects</title>
<para>
Objects should generally be normalized similar to a
database so they contain only the attributes that make sense.
</para>
<para>
Each object should have <classname>Error</classname> as
the abstract parent object unless the object or its subclasses will never
produce errors.
</para>
<para>
Each object should also have a
<methodname>create()</methodname> method which does the work of inserting a new
row into the database table that this object represents.
</para>
<para>
An <methodname>update()</methodname> method is also
required for any objects that can be changed. Individual
<methodname>set()</methodname> methods are generally not a good idea as doing
separate updates to each field in the database is a performance bottleneck.
</para>
<para>
<methodname>fetchData()</methodname> and
<methodname>getId()</methodname> are also standard in most objects. See the
tracker codebase for specific examples.
</para>
<para>
Common sense about performance should be used when
designing objects.
</para>
</section>
<section>
<title>Naming</title>
<itemizedlist>
<listitem>
<para>
Constants should always be uppercase,
with underscores to separate words. Prefix constant names with the name of the
class/package they are used in. For example, the constants used by the DB::
package all begin with <quote>DB_</quote>.</para>
</listitem>
<listitem>
<para>
True and false are built in to the php
language and behave like constants, but should be written in lowercase to
distinguish them from user-defined constants.
</para>
</listitem>
<listitem>
<para>
Function names should suggest an action
or verb: <function>updateAddress</function>,
<function>makeStateSelector</function>
</para>
</listitem>
<listitem>
<para>
Variable names should suggest a
property or noun: <varname>UserName</varname>, <varname>Width</varname>
</para>
</listitem>
<listitem>
<para>
Use pronounceable names. Common
abbreviations are acceptable as long as they are used the same way throughout
the project.
</para>
</listitem>
<listitem>
<para>
Be consistent, use parallelism. If you
are abbreviating <quote>number</quote> as <quote>num</quote>, always use that
abbreviation. Don't switch to using <quote>no</quote> or <quote>nmbr</quote>.
</para>
</listitem>
<listitem>
<para>
Use descriptive names for variables
used globally, use short names for variables used locally.
</para>
<programlisting><![CDATA[
$AddressInfo = array(...);
for($i=0; $i < count($list); $i++)
]]></programlisting>
</listitem>
</itemizedlist>
</section>
<section>
<title>Control Structures</title>
<para>
These include if, for, while, switch, etc. Here is an
example if statement, since it is the most complicated form:
</para>
<programlisting><![CDATA[
if ((condition1) || (condition2)) {
action1;
} elseif ((condition3) && (condition4)) {
action2;
} else {
defaultaction;
}
]]></programlisting>
<para>
Control statements shall have one space between the
control keyword and opening parenthesis, to distinguish them from function
calls.
</para>
<para>
You should use curly braces even in situations where
they are technically optional. Having them increases readability and decreases
the likelihood of logic errors being introduced when new lines are added.
</para>
<para>
For switch statements:
</para>
<programlisting><![CDATA[
switch (condition) {
case 1: {
action1;
break;
}
case 2: {
action2;
break;
}
default: {
defaultaction;
break;
}
}
]]></programlisting>
</section>
<section>
<title>Including PHP Files</title>
<para>
Anywhere you are unconditionally including a class
file, use require_once. Anywhere you are conditionally including a class file
(for example, factory methods), use include_once. Either of these will ensure
that class files are included only once. They share the same file list, so you
don't need to worry about mixing them - a file included with require_once will
not be included again by include_once.
</para>
<note>
<para>
Note: include_once and require_once are
statements, not functions. You don't need parentheses around the filename to be
included, however you should do it anyway and use ' (apostrophes) not "
(quotes):
</para>
</note>
<programlisting><![CDATA[
include('pre.php');
]]></programlisting>
</section>
</section>
--- NEW FILE: howto_xhtml.xml ---
<section id="cg__howto_xhtml">
<title>How to obtain XHTML compliance for GForge</title>
<para>
The complete XHTML specification is available at <ulink
url="http://www.w3.org/TR/xhtml1/";>XHTML specification</ulink> at <ulink
url="http://www.w3.org";>www.w3c.org</ulink>.
</para>
<para>
Here is listed a summary of what is needed to be XHTML
compliant:
</para>
<variablelist>
<varlistentry>
<term>XML declaration</term>
<listitem>
<para>All pages should have the following xml
declaration:</para>
<programlisting><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd";>
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
]]></programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>Document must be well-formed</term>
<listitem>
<para>All open tags must be closed, all tags
must stay between < and >.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>All tags must be lowercase</term>
<listitem>
<para><markup><HTML></markup> must be
converted to <markup><html></markup>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Empty tags must be closed</term>
<listitem>
<para>No standalone <markup><br></markup>
tag is allowed; <markup><br/></markup> must be used.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Attributes must always be quoted</term>
<listitem>
<para><markup><td rowspan=3></markup>
must be converted to <markup><rowspan="3"></markup>.</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The differences listed here are the most significant
differences between HTML and XHTML, there are other, minor differences. For a
complete list, refer to the XHTML specification.
</para>
</section>
--- NEW FILE: howto_contribute.xml ---
<section id="cg_howto_contribute">
<title>How to contribute</title>
<para>
There are several ways to contribute to the Gforge project.
</para>
<itemizedlist>
<listitem>
<para>The first one is to give us a feedback about the
software: what you like, what you don't like, features you like to be added in
new versions, comments on documentation, etc.</para>
</listitem>
<listitem>
<para>You are willing to help develop new features.
Give a look at the PM/Task Manager. The three subprojects (Todo, Documentation,
Localization) lists the open tasks. You can pick up one of the open tasks and
start working on it.</para>
</listitem>
<listitem>
<para>If you find a bug, submit a bug to the Bug
tracker at <ulink
url="http://gforge.org/tracker/?group_id=1";>http://gforge.org/tracker/?group_id=1</ulink>.
If you already solved the bug and are willing to share the fix with us, please
add a patch to the bug.</para>
</listitem>
<listitem>
<para>If you have developed some new feature, submit a
patch to the patch manager of gforge. The submitted patch should follow the
Coding and Templating standards described in this document.</para>
</listitem>
<listitem>
<para>Documentation: there are some parts of Gforge
that are not well documented. Refer to the Task Manager, Documentation
subproject for a list of open tasks. You should write the documentation in the
xdoc format as described in this section.</para>
</listitem>
<listitem>
<para>Localization: The user interface of gforge is now
nearly completely localized. We need translators for the different
languages.</para>
<para>If you like to translate gforge to a new, not
listed language, you can refer to the Localization Howto document to see how to
add a new language</para>
</listitem>
</itemizedlist>
</section>
--- NEW FILE: howto_documentation.xml ---
<section id="cg_howto_documentation">
<title>Documentation</title>
<para>
We now use XML Docbook to write documentation instead of Maven.
You can read the <ulink url="http://www.docbook.org/tdg/index.html";>Docbook
Definitive Guide</ulink> online if you want more information about XML Docbook.
</para>
<para>
Documentation is generated by <ulink
url="http://sourceforge.net/projects/docbook/";>Docbook XSL stylesheets</ulink>
(html output) and <ulink url="http://db2latex.sourceforge.net/";>DB2Latex XSL
stylesheets</ulink> (PDF output).
</para>
</section>
--- NEW FILE: templating.xml ---
<section id="cg_templating">
<title>Templating Standards</title>
<section>
<title>Coding Example</title>
<para>
The following code examples demonstrate how all coding
on GForge is going to be done in the future. The first example shows the
<quote>switchbox</quote> page (taken from
<filename>www/tracker/index.php</filename>) - where the various objects are
included, instantiated and checked for errors every step of the way.
</para>
<para>
Once the objects are instantiated, the template file
can be included. In this example, the template file is detail.php (example2).
</para>
<variablelist>
<varlistentry>
<term>Template page</term>
<listitem>
<programlisting><![CDATA[
<?php
//
// SourceForge: Breaking Down the Barriers to Open Source Development
// Copyright 1999-2000 (c) The SourceForge Crew
// http://sourceforge.net
//
// $Id: templating.xml,v 1.1 2004/03/02 16:58:39 gsmet Exp $
echo $ath->header(array
('title'=>'Detail: '.$ah->getID(). ' '.$ah->getSummary()));
?>
<H2>[#<?php echo $ah->getID(); ?>] <?php echo $ah->getSummary(); ?></H2>
<TABLE CELLPADDING="0" WIDTH="100%">
<FORM ACTION="<?php echo $PHP_SELF; ?>
?group_id=<?php echo $group_id; ?>
&atid=<?php echo $ath->getID(); ?>" METHOD="POST">
<INPUT TYPE="HIDDEN" NAME="func" VALUE="monitor">
<INPUT TYPE="HIDDEN" NAME="artifact_id"
VALUE="<?php echo $ah->getID(); ?>">
<TR>
<TD COLSPAN=2">
<?php
if (!session_loggedin()) {
?>
<B>Email:</B>
<INPUT TYPE="TEXT" NAME="user_email"
SIZE="20" MAXLENGTH="40">
<?php
}
?>
<INPUT TYPE="SUBMIT" NAME="SUBMIT" VALUE="Monitor">
</FORM>
</TD>
</TR>
<TR>
<TD>
<B>Date:</B><BR>
<?php echo date( $sys_datefmt,
$ah->getOpenDate() ); ?></TD>
<TD><B>Priority:</B><BR>
<?php echo $ah->getPriority(); ?></TD>
</TR>
<TR>
<TD><B>Submitted By:</B><BR>
<?php echo $ah->getSubmittedRealName(); ?>
(<?php echo $ah->getSubmittedUnixName(); ?>)</TD>
<TD><B>Assigned To:</B><BR>
<?php echo $ah->getAssignedRealName(); ?>
(<?php echo $ah->getAssignedUnixName(); ?>)</TD>
</TR>
<TR>
<TD><B>Category:</B><BR>
<?php echo $ah->getCategoryName(); ?></TD>
<TD><B>Status:</B><BR>
<?php echo $ah->getStatusName(); ?></TD>
</TR>
<TR><TD COLSPAN="2">
<H3>DO NOT enter passwords or confidential information
in your message!</H3>
<INPUT TYPE="SUBMIT" NAME="SUBMIT" VALUE="SUBMIT">
</FORM>
</TD></TR>
</TABLE>
</FORM>
<?php
$ath->footer(array());
?>]]></programlisting>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Gforge-commits] gforge/docs/docbook/docbook/contribution_guide/include howto_localization.xml, NONE, 1.1 coding_standards.xml, NONE, 1.1 howto_xhtml.xml, NONE, 1.1 howto_contribute.xml, NONE, 1.1 howto_documentation.xml, NONE, 1.1 templating.xml, NONE, 1.1,
gsmet <=