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.

Edit existing documents

To edit existing documents, simply use your favorite plan text editor - it is all plain HTML plus the JavaScript navigation

Add new documents

To add new documents, follow the steps below:

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.

Edit out the content of the new document after the header section, i.e. between

<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>

and

<script type="text/javascript">
  cpgDocFooter();
  dateRevision(' $LastChangedDate$ ', ' $Revision$ ');
</script>

</body>
</html>

This is the section where your actual content should reside

Edit the <title>-tag to reflect your document's content
Edit script.js to add your document to the JavaScript navigation:
Find cpgDocToc and edit the section below it. The syntax is obviously just plain HTML that get's written into the document using JavaScript's document.write syntax. Don't forget to escape single quotes properly!
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).
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 <h1>, <h2>, <h3> ... structure). Preferably add anchors as well, making an icon () 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
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 http://www.google.com/search?q=site%3Adocumentation.coppermine-gallery.net
Finally, save your changes and add/push your file(s) to the Git repository.

Moving content from one document to the other

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.

Hidden features

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 hide_nav=1 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.

Database structure

The documentation file dev_database.htm 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 sql/basic.sql, sql/schema.sql or sql/update.sql that has an impact on the database schema, the documentation has to be updated as well, preferably with the same commit.

Header & footer blocks

Documentation internationalization

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. ./docs/de/example.htm) and add <div id="doc_en_only">No translation available</div> 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 ./docs/yourlanguage/script.js in the function definition for cpgDocTranslationWarning. The maintainer of that language is welcome to add a link to a corresponding thread on the support board.

To mark such documents in the localized, non-English menu, you can use the class en, e.g. like this:

To enable translators to come up with the navigation structure in advance, you can use the CSS class nolink to make a link go "blind", i.e. make it do nothing when clicked, as in this example:

If particular anchor targets haven't been finished yet, you can use the CSS class cancel to display a cancel icon like this:

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:

Subsequently, if a temporary document get's permanent, the meta tag should be removed.

Expandable/collapsible "detail"-blocks

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.

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.

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):

You can have several of those blocks on a page. To obtain a control that can manipulate all of them, you can use

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 example.htm:

Such a construct will not work if accessed using a link like this: <a href="example.htm#foo">. 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 <a href="example.htm?expand_all=1#foo">

Help

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 cpg_display_help that is being defined in include/functions.inc.php. This function creates the needed output and determines wether the gallery admin has enabled help or not.

The first way to display help is by refering to the available strings in the language files. With this coding, the help text would come from the language file, so this option only applies for very short help section.

To refer to an availabe language string, you have to pass the variable name to cpg_display_help

$my_help = cpg_display_help('f=empty.htm&h=lang_my_variable&t=lang_my_variable_details', 200, 100);
echo <<< EOT
{$lang_example['bla']} {$my_help}
EOT;

Of course you can also use language strings in arrays, like this

$my_help = cpg_display_help('f=empty.htm&h=lang_my_array[help_header]&t=lang_my_array[help_text]', 200, 100);
echo <<< EOT
{$lang_example['bla']} {$my_help}
EOT;

The parameter "h" will be the help header, the parameter "t" will be the actual help text body.

Note, that there are no dollar signs before the variable/array names and there mustn't be apostrophes around the array keys!

Start and end anchors needed

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.

Examples

Good example:

docs/en/your_file.htm <a id="food"></a>
<h1>Food</h1>
<p>Here's a list of things that you can eat.</p>
<a id="food_fruit"></a>
<h2>Fruit</h2>
<p>Apples, bananas and cherries are all fruit.</p>
<a id="food_fruit_end"></a>
<a id="food_veggies"></a>
<h2>Vegetables</h2>
<p>Cucumber, carrots and peas are vegetables.</p>
<a id="food_veggies_end"></a>
<a id="food_end"></a>

example.php $help = cpg_display_help('f=your_file.htm&as=food_fruit&ae=food_fruit_end&top=1', '600', '300');

Adding anchors to headings

In the documentation for cpg1.5.x, nearly every heading (from <h1> to <h6>) 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.

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.

<a id="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>

or (for space saving and easier search/replace actions) rolled into one line:

<a id="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>

Code

Combining HTML tags and CSS classes

No syntax highlighting

For the sake of easier i18n, you should not use syntax highlighting, as that causes too much extra work for translators!

Coppermine Photo Gallery v1.6.x: Documentation and Manual

Target audience