PHP-GTK Community : a community site for PHP-GTK

So you're willing to contribute documentation to the community site ? Great. But you're not sure how to do it well ? This page is here to guide you.

The single most important rule

The single most important rule is: " DO IT". Pages can always be corrected, and it is usually much easier to fix an existing page that to create it in the first place, so if you refrain from contributing because you don't know how, just stop refraining : create that page you think the community needs, and ask others to improve it once it exists. If you don't know how to ask, just contact the site maintainer for help.

Writing for a community web site

You must keep in mind that not all site readers have a nice 30" display : many of them still have resolutions of 1024x768 or even narrower. Given the use of a three-column layout on the site, this means that no code should be wider than 70 columns : wrap long lines where it makes sense, to avoid automatic wrapping that can ruin the readability of your code.

Wrapping every PHP-GTK symbol in the text in a <code> element makes them stand out and eases reading. At some point, it may also allows improved search features, so it is important to add these wrappings.

Of course, profanity and adult content would be out of place, and standards for appreciating the appropriateness of content vary wildly around the world, so it is always better to err on the side of caution to avoid alienating readers, and depriving PHP-GTK from them.

Pages contributed are meant to be edited in community, so do not expect your content to stay unchanged (that's why you probably have a blog, too, don't you ?) : pages may be edited over time by other contributors to improve their quality, reclassify them as the site structure changes, and so on. You will always be recorded as the original author, though.

Licensing : by registering to the site, you have agreed to only contribute content you rightfully owned the rights to, and grant a Creative Commons "CC-BY-SA 2.0" license to the site owners, who in turn grant the same license to any user. This means you are legally bound not to submit any content under another license, including GPL, MPL. You may, however, point to it : if the link is accurate and points to useful information, it won't be removed as spam.

Technically speaking

XHTML

The site strives to be XHMTL 1.0 strict. This can only be achieved if contributors type in proper XHTML fragments instead of any old HTML tag soup. Most errors are actually quite simple to avoid. Here is a short list of recommendations:

• closing tags: every element ("tag") must have a matching closing tag. That is, if you start a <p> paragraph, it must end with a </p> closing tag. Empty elements like line breaks or horizontal rows include their closure as <br /> and <hr />.
• tags are lower-case: element names ("tags") are lower case, like <ul>, not upper case like <UL> as they were in HTML.
• attributes are double-quoted and always have a value: while in HTML you could write things like: <OPTION SELECTED>foo, XHTML requires you to code like: <option selected="selected">foo</option>: lowercase, attribute without a value in HTML takes its name as a value in XHTML, and attribute values are wrapped in double quotes. And, of course, every element has a closing tag.
• images needs an alt attribute : this is needed for XHMTL validation but is also important to help search engines index your images.
• chimp attractors are dead: early HTML elements like font choices, marquee, and mostly anything visual has no place in XHTML: styling has to be done in CSS. For most needs, this means don't even worry about look: the site theme will take care of that for you. See exceptions below.
• paragraphs don't nest block content: although this may seem counter intuitive, you can't nest a paragraph (<p>), a preformatted block (<pre>) or a list, or for that matter any "block" content in the CSS sense, within a paragraph. Only "inline" content, like <code>, or <img ... /> is allowed within an paragraph.
• nested lists are a bit complicated: try to avoid them. Lists can be nested, but the syntax is a bit awkward. If you're unsure how to do it, just ask someone, or don't use nesting.

Skeletons

For some pages, like application pages, it is recommended that you derive your page content from an existing skeleton, in order for all pages of the same group to look the same, making it easier on the reader.

For this reason, the appropriate skeleton is automagically prefilled when you create an application page. You can also check the skeleton on the skeleton for application registration description page.

PHP coding style

Using a consistent coding style for all PHP fragments you submit makes it easier on site users : look at the existing hints in the handbooks to write your examples under the same conventions.

You can input PHP source code blocks by wrapping them in <?php ... ?> : the code will automatically have its syntax highlighted much like on php.net

You can input other languages as code blocks by wrapping them in a pre element. Like PHP blocks, there are blocks, so they do no got within a paragraph, but stand on their own. If you want to embed code inline, you can use the code element, which will automatically convert < and > so you don't have to fix them by hand.