0byt3m1n1
Path:
/
data
/
applications
/
aps.bak
/
coppermine
/
1.5.12-0
/
standard
/
htdocs
/
docs
/
es
/
[
Home
]
File: dev_documentation.htm
<!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" xml:lang="en" lang="en" dir="ltr"> <head> <title>Editing the documentation - Coppermine Photo Gallery - Documentation & Manual</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta name="language" content="en" /> <meta name="copyright" content="Coppermine dev team" /> <meta name="description" content="Editing the documentation: This part of the documentation is not meant for end users of Coppermine, but only for developers. There is no support for this section, it comes as-is." /> <meta http-equiv="Content-Style-Type" content="text/css" /> <meta name="MSSmartTagsPreventParsing" content="true" /> <meta http-equiv="imagetoolbar" content="no" /> <!-- SVN version info: Coppermine version: 1.5.12 $HeadURL: https://coppermine.svn.sourceforge.net/svnroot/coppermine/trunk/cpg1.5.x/docs/es/dev_documentation.htm $ $Revision: 8154 $ $Date: 2011-01-02 20:44:22 +0100 (So, 02 Jan 2011) $ --> <link rel="stylesheet" type="text/css" href="../style/style.css" media="all" /> <link rel="stylesheet" type="text/css" href="../style/screen.css" media="screen" /> <link rel="stylesheet" type="text/css" href="../style/print.css" media="print" /> <link rel="shortcut icon" href="../favicon.ico" /> <script src="../js/jquery.js" type="text/javascript"></script> <script src="../js/jquery.treeview.js" type="text/javascript"></script> <script src="script.js" type="text/javascript"></script> </head> <body> <h1 id="docheader">Coppermine Photo Gallery v1.5.x: Documentation and Manual</h1> <div id="toc"> <a href="toc.htm">Table of Contents</a> </div> <div id="doc_en_only">No translation available</div> <a name="dev_documentation_edit"></a><h1>Editing the documentation<a href="#dev_documentation_edit" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h1> <a name="dev_documentation_target_audience"></a><h2>Target audience<a href="#dev_documentation_target_audience" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2> <p>This part of the documentation is not meant for end users of Coppermine, but only for developers. There is no support for this section, it comes as-is.</p> <a name="dev_documentation_edit_existing"></a><h2>Edit existing documents<a href="#dev_documentation_edit_existing" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2> <p>To edit existing documents, simply use your favorite plan text editor - it is all plain HTML plus the JavaScript navigation</p> <a name="dev_documentation_add"></a><h2>Add new documents<a href="#dev_documentation_add" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2> <p>To add new documents, follow the steps below: <ul> <li>just use an existing document as template to copy from. Save it within the docs folder giving it a unique, web-safe name that is meaningful.</li> <li>Edit out the content of the new document after the header section, i.e. between <pre class="smallcode"><body> <script type="text/javascript"> cpgDocHeader(); </script> <div id="toc"> <script type="text/javascript"> cpgDocToc(); </script> <noscript> <a href="toc.htm">Table of Contents</a> </noscript> </div></pre> and <pre class="smallcode"><script type="text/javascript"> cpgDocFooter(); dateRevision(' $<b></b>LastChangedDate<b></b>$<b></b> ', ' $<b></b>Revision<b></b>$<b></b> '); </script> </body> </html></pre> This is the section where your actual content should reside</li> <li>Edit the <tt class="code"><title></tt>-tag to reflect your document's content</li> <li>Edit script.js to add your document to the JavaScript navigation:<br /> Find <tt class="code">cpgDocToc</tt> and edit the section below it. The syntax is obviously just plain HTML that get's written into the document using JavaScript's <tt class="code">document.write</tt> syntax. Don't forget to escape single quotes properly!</li> <li>Edit toc.htm and add a link to the plain HTML table of contents. This is necessary to allow search engine spiders to crawl the documentation, so please do not skip this step. The structure should be pretty self-explanatory (as suggested: plain HTML).</li> <li>After taking care of creating the file and displaying it in the navigation, it's time to come up with your content. Make sure to use meaningful headlines (preserving the existing <tt class="code"><h1></tt>, <tt class="code"><h2></tt>, <tt class="code"><h3></tt> ... structure). Preferably add anchors as well, making an icon (<img src="images/anchor.gif" width="15" height="9" border="0" alt="" title="anchor-icon for easy linking">) appear next to each headline that allows easy linking (this should be particularly helpful on the support board - you can add references to particular documentation sections in no time). Take a look at the existing documents for an example</li> <li>Edit the description meta tag of the new page - come up with a short summary what the page is about. The description meta tag is taken into account by search engine spiders, especially when searching the entire site - see <a href="http://www.google.com/search?q=site%3Adocumentation.coppermine-gallery.net" rel="external" class="external">http://www.google.com/search?q=site%3Adocumentation.coppermine-gallery.net</a></li> <li>Finally, save your changes and add/commit your file(s) to the subversion repository.</li> </ul> </p> <a name="dev_documentation_move"></a><h2>Moving content from one document to the other<a href="#dev_documentation_move" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2> <p>When moving content from an existing document to the other (or into a new one), you have to make sure that the links that point to it get moved as well. To do so, search the entire documentation and the coppermine core code for the anchor name and change them to reflect your changes in the documentation.</p> <a name="dev_documentation_hidden_feature"></a><h2>Hidden features<a href="#dev_documentation_hidden_feature" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2> <p>To display the content of a particular page of the documentation without the page header, logo, table of contents, search form and footer, add the URL parameter <tt class="code">hide_nav=1</tt> to the URL. This is meant to allow displaying content within an iframe or similar. Currently, this feature is being used in the installer only.</p> <a name="dev_documentation_database_structure"></a><h2>Database structure<a href="#dev_documentation_database_structure" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2> <p>The documentation file <a href="dev_database.htm">dev_database.htm</a> contains documentation about Coppermine's database structure. It's important to keep that piece of the documentation in sync with the actual database changes, i.e. if a dev changes something at database level by editing <tt class="code">sql/basic.sql</tt>, <tt class="code">sql/schema.sql</tt> or <tt class="code">sql/update.sql</tt> that has an impact on the database schema, the documentation has to be updated as well, preferably with the same commit.</p> <a name="dev_documentation_header_block"></a><h2>Header & footer blocks<a href="#dev_documentation_header_block" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2> Each "regular" file in the documentation needs to contain the header and footer blocks that will be replaced using JavaScript with additional chrome. If you're interessted how this is done, please review <tt class="code">./docs/en/script.js</tt>. The only important thing to keep in mind is that the section <pre><h1 id="docheader">Coppermine Photo Gallery v1.5.x: Documentation and Manual</h1> <div id="toc"> <a href="toc.htm">Table of Contents</a> </div></pre> needs to be preserved right after the <tt class="code"><body></tt>-tag.<br /> In a similar manner, the footer section <pre><div id="doc_footer"> <div class="doc_info_wrapper"> <span id="doc_last_changed">$LastChangedDate: 2009-05-27 20:18:54 +0200 (Mi, 27 Mai 2009) $</span> <span id="doc_revision">$Revision: 6003 $</span> </div> </div></pre> right in front of the closing <tt class="code"></body></tt>-tag mustn't be edited nor removed. <a name="dev_documentation_i18n"></a><h2>Documentation internationalization<a href="#dev_documentation_i18n" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2> <p>To help translators come up with valid translations of the docs some extra JavaScript goodies have been added: if a file in a non-english branch of the docs (e.g. "de" -> German) get's added initially in English as a preparation for the translation, the translator or maintainer is encoraged to edit that file (e.g. <tt class="code">./docs/de/example.htm</tt>) and add <tt class="code"><div id="doc_en_only">No translation available</div></tt> into the body right after the div blocks that compose the header and menu. This block will be replaced using JavaScript/jquery with a more advanced text that explains the document's temporary stage and that translations are welcome. That text can be edited per language in <tt class="code">./docs/yourlanguage/script.js</tt> in the function definition for <tt class="code">cpgDocTranslationWarning</tt>. The maintainer of that language is welcome to add a link to a corresponding thread on the support board.</p> <p>To mark such documents in the localized, non-English menu, you can use the class <tt class="code">en</tt>, e.g. like this:</p> <div class="cpg_example"> <pre><li><a href="example.htm" class="en">Foo bar</a></li></pre> will result in <div class="border1"> <ul> <li><a href="example.htm" class="en" style="text-decoration:none;" rel="nofollow"><img src="../../images/flags/us.png" width="16" height="10" border="0" alt="" style="margin-right:5px" />Foo bar</a></li> </ul> </div> </div> <p>To enable translators to come up with the navigation structure in advance, you can use the CSS class <tt class="code">nolink</tt> to make a link go "blind", i.e. make it do nothing when clicked, as in this example:</p> <div class="cpg_example"> <pre><li><a href="example.htm" class="nolink">Foo bar</a></li></pre> will result in <div class="border1"> <ul> <li><a href="example.htm" class="nolink" style="text-decoration:none;">Foo bar</a></li> </ul> </div> Go ahead and click the link to see what happens then: nothing. Keep in mind that this will only work if JavaScript is enabled. If it is disabled, the link will of course lead to it's target no matter what. </div> <p>If particular anchor targets haven't been finished yet, you can use the CSS class <tt class="code">cancel</tt> to display a cancel icon like this:</p> <div class="cpg_example"> <pre><li><a href="example.htm" class="cancel">Foo bar</a></li></pre> will result in <div class="border1"> <ul> <li><a href="example.htm" class="cancel" style="text-decoration:none;" rel="nofollow"><img src="../../images/icons/cancel.png" width="16" height="16" border="0" alt="" style="margin-right:5px" />Foo bar</a></li> </ul> </div> </div> <p>To make sure that temporary content doesn't ruin the google page rank or clutters the search result, you should instruct the robots not to index temporary pages - this is done by adding the corresponding meta tag to the file's HTM header:</p> <div class="cpg_example"> <pre><meta name="robots" content="noindex" /></pre> </div> <p>Subsequently, if a temporary document get's permanent, the meta tag should be removed.</p> <a name="dev_documentation_detail"></a><h2>Expandable/collapsible "detail"-blocks<a href="#dev_documentation_detail" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2> <p>As the documentation is using the jquery framwork and some little plugins for ease of use, it's possible to come up with expandable/collapsible blocks that the end user can click on to read details. This can help to maintain a clear document structure.</p> <p>The used technology falls back nicely if JavaScript is disabled: the block are expanded out of the box and get collapsed on page load by JavaScript - if JavaScript is disabled, the blocks stay expanded no matter what.</p> <p>To create such a block, you need to come up with two container elements that need to be one after the other (no tags between them):</p> <pre><span class="detail_head_collapsed">Details</span> <div class="detail_body border1"> Content that is collapsed on page load and will get expanded if the visitor clicks on the "details" container above. </div></pre> <p>You can have several of those blocks on a page. To obtain a control that can manipulate all of them, you can use</p> <pre><button type="button" class="button detail_expand_all" name="expandalltop" id="expandalltop" onclick="return false"> <img src="../../images/tree/plus.gif" width="9" height="9" border="0" alt="" title="Expand All" />Expand all details </button> <button type="button" class="button detail_collapse_all" name="collapsealltop" id="collapsealltop" style="display:none;" onclick="return false"> <img src="../../images/tree/minus.gif" width="9" height="9" border="0" alt="" title="Collapse all" />Collapse all details </button></pre> <p>You need to pay attention to anchors that you might want to use within blocks that are collapsed on page load. Let's assume you have this content on a page named <tt class="code">example.htm</tt>:</p> <pre><span class="detail_head_collapsed">Details</span> <div class="detail_body border1"> <a name="foo"></a>Some content that can be accessed using an anchor. </div></pre> <p>Such a construct will not work if accessed using a link like this: <tt class="code"><a href="example.htm#foo"></tt>. That's why a GET parameter named "expand_all" has been added that will expand all collapsed blocks on a page if set to 1. Subsequently, the example link would have to be <tt class="code"><a href="example.htm?expand_all=1#foo"></tt></p> <a name="dev_documentation_help"></a><h2>Help<a href="#dev_documentation_help" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2> <p>Obviously, the content of the docs folder within coppermine is the place where the documentation is being kept. But apart from that, the docs serve as core for the help system that resides in Coppermine itself (help for the actual application, embedded into the actual application). This being said, here's how the help system currently works: from any PHP-driven file within Coppermine, the help is being populated using the function <tt class="code">cpg_display_help</tt> that is being defined in <tt class="code">include/functions.inc.php</tt>. This function creates the needed output and determines wether the gallery admin has enabled help or not.</p> <div class="cpg_example">The minimum code to display help would be <pre>$my_help = cpg_display_help('f=empty.htm&h=' . urlencode('Hello world') . '&t=' . urlencode('This is the detailed text of the help window'), 200, 100); echo <<< EOT Foo bar {$my_help} EOT;</pre> In case the amount of of characters might get bigger we should disguise the URL a little, using this code <pre>$my_help = cpg_display_help('f=empty.htm&base=64&h=' . urlencode(base64_encode(serialize('Hello world'))) . '&t=' . urlencode(base64_encode(serialize('This is the detailed text of the help window'))), 200, 100); echo <<< EOT Foo bar {$my_help} EOT;</pre> should do the trick.<br /> This is of course not a real life example, as there mustn't be hard-coded text in the code, so the result would look like this: <pre>$my_help = cpg_display_help('f=empty.htm&base=64&h=' . urlencode(base64_encode(serialize($lang_example['hello_world']))) . '&t=' . urlencode(base64_encode(serialize($lang_example['hello_world_details']))), 200, 100); echo <<< EOT {$lang_example['bla']} {$my_help} EOT;</pre> With this coding, the help text would come from the language file, so this option only applies for very short help section. </div> The second (and recommended) way to display help is by refering to the documentation - the function <tt class="code">cpg_display_help</tt> and the subsequent file <tt class="code">help.php</tt> are designed for exactly that purpose. All you have to do in your function call is refering to the file name of the documentation section that you want to refer to and the anchor tags that you refer to: <pre>$help = ' ' . cpg_display_help('f=your_file.htm&as=foo_start&ae=foo_end&top=1', '600', '300');</pre> Would refer to the file <tt class="class">./docs/en/your_file.htm</tt> and inside that file to the section between <pre><a name="foo_start"></a></pre> and <pre><a name="foo_end"></a></pre> You don't have to take care of <abbr title="internationalization">i18n</abbr> in this case - if the end user's language preference is French and there is a file <tt class="class">./docs/fr/your_file.htm</tt>, the end user will see the content taken from that file. The english version of the docs is the default that the help function fallbacks to if there is no help available in the user's prefered language. <a name="dev_documentation_help_start_end"></a><h3>Start and end anchors needed<a href="#dev_documentation_help_start_end" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h3> <p>From what has been said so far it should be obvious that every section of the documentation that could be used as help section from within the Coppermine interface needs to be wrapped into a start and end anchor tag. It's not advisable to rely on the order of sections on a documentation page to be preserved - chapters might be added or removed.</p> <h4>Examples</h4> <div class="cpg_example"> Good example: <fieldset class="code"><legend>docs/en/your_file.htm</legend> <a name="food"></a><br /> <h1>Food</h1><br /> <p>Here's a list of things that you can eat.</p><br /> <a name="food_fruit"></a><br /> <h2>Fruit</h2><br /> <p>Apples, bananas and cherries are all fruit.</p><br /> <a name="food_fruit_end"></a><br /> <a name="food_veggies"></a><br /> <h2>Vegetables</h2><br /> <p>Cucumber, carrots and peas are vegetables.</p><br /> <a name="food_veggies_end"></a><br /> <a name="food_end"></a></fieldset> <br /> <fieldset class="code"><legend>example.php</legend> $help = cpg_display_help('f=your_file.htm&amp;as=food_fruit&amp;ae=food_fruit_end&amp;top=1', '600', '300');</fieldset> </div> <div class="cpg_example"> Bad example: <fieldset class="code"><legend>docs/en/your_file.htm</legend> <a name="food"></a> <h1>Food</h1> <p>Here's a list of things that you can eat.</p> <a name="food_fruit"></a> <h2>Fruit</h2> <p>Apples, bananas and cherries are all fruit.</p> <a name="food_veggies"></a> <h2>Vegetables</h2> <p>Cucumber, carrots and peas are vegetables.</p></fieldset> <br /> <fieldset class="code"><legend>example.php</legend> $help = cpg_display_help('f=your_file.htm&amp;as=food_fruit&amp;ae=food_veggies&amp;top=1', '600', '300');</fieldset> </div> <a name="dev_documentation_heading_anchors"></a><h2>Adding anchors to headings<a href="#dev_documentation_heading_anchors" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2> <p>In the documentation for cpg1.5.x, nearly every heading (from <tt class="code"><h1></tt> to <tt class="code"><h6></tt>) should contain a leading anchor tag and a trailing link to that section. This way, supporters can easily spot the anchor that they need to refer to - just click on the trailing link icon in a heading and then copy the URL from the address bar and paste it into the support posting.</p> <p>That's why it's advisable to add anchors to all sub-sections of the documentation that could serve as online help or that a supporter might want to refer to.</p> <div class="cpg_example"> <pre><a name="anchor"></a> <h2> Heading text <a href="#anchor" title="Link to this section"> <img src="images/anchor.gif" width="15" height="9" border="0" alt="" /> </a> </h2></pre> or (for space saving and easier search/replace actions) rolled into one line: <pre><a name="anchor"></a><h2>Heading text<a href="#anchor" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2></pre> </div> <a name="dev_documentation_code"></a><h2>Code<a href="#dev_documentation_code" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2> There are several ways to display code snippets inside the docs: <ul> <li> <a name="dev_documentation_code_css_code"></a><h3>CSS class "code"<a href="#dev_documentation_code_css_code" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h3> For single words or just a few words, you can use the CSS class <strong>code</strong>, usually with a non-block tag like <tt class="code"><tt></tt> or <tt class="code"><span></tt>.<br /> Usually, single HTML tags inside the documentation are being highlighted by wrapping them into something like <tt class="code"><tt class="code"></tt> and <tt class="code"></tt></tt> (although the HTML tag <tt class="code"><tt></tt> is considered as deprecated and will be replaced in future versions) <div class="cpg_example">Example:<br /><tt class="code">foo</tt></div> </li> <li> <a name="dev_documentation_code_html_pre"></a><h3>HTML-tag "pre"<a href="#dev_documentation_code_html_pre" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h3> For smaller sections over multiple lines, use <tt class="code"><pre></tt> <div class="cpg_example">Example:<br /><pre>foo</pre></div> </li> <li> <a name="dev_documentation_code_css_cpg_code"></a><h3>CSS class "cpg_code"<a href="#dev_documentation_code_css_cpg_code" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h3> For block elements and longer passages of code, use the class <strong>cpg_code</strong> (usually in combination with the block element <tt class="code"><div></tt> <div class="cpg_example">Example:<br /><div class="cpg_code">foo</div></div> </li> <li> <a name="dev_documentation_code_css_smallcode"></a><h3>CSS class "smallcode"<a href="#dev_documentation_code_css_smallcode" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h3> For code samples in narrow spaces (e.g. within tables), use the class <strong>smallcode</strong> <div class="cpg_example">Example:<br /><span class="smallcode">foo</span></div> </li> <li> <a name="dev_documentation_code_html_textarea"></a><h3>HTML-tag "textarea"<a href="#dev_documentation_code_html_textarea" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h3> For sections that users might want to copy and paste from, use <tt class="code"><textarea></tt>-tags <div class="cpg_example">Example:<br /><textarea cols="10" rows="2">foo</textarea></div> </li> </ul> <a name="dev_documentation_code_combining"></a><h3>Combining HTML tags and CSS classes<a href="#dev_documentation_code_combining" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h3> The CSS classes and HTML tags that make sense (e.g. <tt class="code"><textarea></tt> and <tt class="code">smallcode</tt>) can and should of course be combined. <div class="cpg_example">Example:<br /><textarea cols="10" rows="2" class="smallcode">foo</textarea></div> <a name="dev_documentation_code_syntaxhighlighting"></a><h3>No syntax highlighting<a href="#dev_documentation_code_syntaxhighlighting" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h3> <p class="cpg_message_warning">For the sake of easier <abbr title="internationalisation">i18n</abbr>, you should <strong>not</strong> use syntax highlighting, as that causes too much extra work for translators!</p> <div id="doc_footer"> <div class="doc_info_wrapper"> <span id="doc_last_changed">$LastChangedDate: 2011-01-02 20:44:22 +0100 (So, 02 Jan 2011) $</span> <span id="doc_revision">$Revision: 8154 $</span> </div> </div> </body> </html>