Difference between revisions of "Wiki Contributor Guidelines"
Davidmbrooke (Talk | contribs) (Added notes on diagram link formatting and refined requirement for LEAF project membership) |
Davidmbrooke (Talk | contribs) (→WikiMarkup: Added Hints and Tips) |
||
| (2 intermediate revisions by the same user not shown) | |||
| Line 26: | Line 26: | ||
==Content of Wiki Pages== | ==Content of Wiki Pages== | ||
| + | ===LEAF Terminology=== | ||
| + | Write "Module", "Package" and "Image" (rather than "module", "package" and "image") to emphasize that these are being used as specific [[LEAF]] terms. | ||
| + | |||
===WikiMarkup=== | ===WikiMarkup=== | ||
Use WikiMarkup in preference to HTML markup. | Use WikiMarkup in preference to HTML markup. | ||
| + | ====Hints and Tips==== | ||
| + | * The normal way of inserting "code" examples (starting a line with a space) doesn't work properly within lists. In particular, within numbered lists it resets the numbering. The workaround is to use <nowiki><pre>code text goes here</pre></nowiki> | ||
| + | * For multi-line code examples, need to separate the lines with <nowiki> & # 1 0 ; </nowiki> (without the spaces) | ||
| + | ** See [[Bering-uClibc 4.x - User Guide - Advanced Topics - Setting Up a VOIP Server]] for an example | ||
===Diagrams=== | ===Diagrams=== | ||
| Line 38: | Line 45: | ||
When including diagram files in pages, the preferred formatting syntax is: | When including diagram files in pages, the preferred formatting syntax is: | ||
<nowiki>[[Image:filename.png|center|frame|alt=Alternative text|Caption]]</nowiki> | <nowiki>[[Image:filename.png|center|frame|alt=Alternative text|Caption]]</nowiki> | ||
| + | |||
| + | ===Converting DocBook Pages=== | ||
| + | A lot of the existing [[Bering]] and [[Bering-uClibc]] documentation is in [http://www.docbook.org/ DocBook] format. | ||
| + | In general this is of high quality but it often needs to be updated for [[Bering-uClibc 4.x]]. | ||
| + | |||
| + | A good way to create a Wiki page based on an existing DocBook page is to use the [http://search.cpan.org/~diberri/HTML-WikiConverter/lib/HTML/WikiConverter.pm Wiki::Converter] Perl module (more specifically, the related <tt>html2wiki</tt> Perl script). | ||
| + | On Fedora, this can be installed with: | ||
| + | yum install html2wiki | ||
| + | For some reason, at least on Fedora 14, this does '''NOT''' install the MediaWiki "dialect" module, and that does not seem to be available as a separate RPM package in any of the standard repositories. | ||
| + | A workaround is to install this with the "cpan" command: | ||
| + | cpan install D/DI/DIBERRI/HTML-WikiConverter-MediaWiki-0.59.tar.gz | ||
| + | |||
| + | Once the converter is installed, the recommended way to convert a DocBook page is as follows: | ||
| + | # Download (or generate) the HTML version of the DocBook page. | ||
| + | #* Either "Save as..." from a Browser or use <tt>wget</tt> | ||
| + | # Convert to "MediaWiki" format with a command like the following<pre>html2wiki --dialect=MediaWiki file.html > file.wiki</pre> | ||
| + | # Browse the generated <tt>.wiki</tt> file and paste the contents into a MediaWiki "edit" page | ||
Latest revision as of 19:27, 22 October 2011
Contents
Access Management
Everyone on the Internet can read the contents of this Wiki. In order to contribute content various pre-requisites have to be satisfied:
- You must have a SourceForge account by signing up here.
- You must be a member of the LEAF project. Click here.
- You need to be listed on the Users page for this Wiki.
- In particular you need to be listed as a member of user class "editor" - the text (editor) will appear after your username.
- In order to be added as an "editor" an "admin" of this Wiki needs to grant you access. The "admin" users are listed on the Users page.
- TODO - How do we advise users to contact an "admin" to request access?
Structure of Wiki Pages
The LEAF development team are keen to see this Wiki maintained as a trustworthy and up-to-date source of information for LEAF users and developers. In support of this, the policy is to have relatively few pages, each of which is managed as part of a well-defined structure. Since the Wiki concept does not enforce a good structure it is necessary to maintain this manually.
In particular:
- Most of the content should form part of "books" which have a logical structure of Chapters and (optionally) Sub-Chapters.
- The main page for each "book" shall contain a "Table of Contents", with links to the separate pages for Chapters and (optionally) Sub-Chapters.
When choosing names for new pages:
- Remember that the scope of this Wiki is all of the LEAF project, not only e.g Bering-uClibc 4.x. Pages which are specific to a particular Branch, or to a Version of a Branch, should be prefixed with the Name (and Version) of that Branch.
- For example: Bering-uClibc 4.x - User Guide, Bering-uClibc 4.1 - Release Notes.
- Somebody else might want to create a different page to describe the same aspects of a different Branch.
Content of Wiki Pages
LEAF Terminology
Write "Module", "Package" and "Image" (rather than "module", "package" and "image") to emphasize that these are being used as specific LEAF terms.
WikiMarkup
Use WikiMarkup in preference to HTML markup.
Hints and Tips
- The normal way of inserting "code" examples (starting a line with a space) doesn't work properly within lists. In particular, within numbered lists it resets the numbering. The workaround is to use <pre>code text goes here</pre>
- For multi-line code examples, need to separate the lines with & # 1 0 ; (without the spaces)
- See Bering-uClibc 4.x - User Guide - Advanced Topics - Setting Up a VOIP Server for an example
Diagrams
A picture paints a thousand words. Diagrams should be included where they assist with understanding, or even just because they look nice.
The preferred format for screenshots is PNG. The preferred format for diagram files is SVG. The recommended tool for creating/editing SVG files is TODO (Inkscape, maybe? Davidmbrooke 20:34, 12 November 2010 (UTC))
When including diagram files in pages, the preferred formatting syntax is:
[[Image:filename.png|center|frame|alt=Alternative text|Caption]]
Converting DocBook Pages
A lot of the existing Bering and Bering-uClibc documentation is in DocBook format. In general this is of high quality but it often needs to be updated for Bering-uClibc 4.x.
A good way to create a Wiki page based on an existing DocBook page is to use the Wiki::Converter Perl module (more specifically, the related html2wiki Perl script). On Fedora, this can be installed with:
yum install html2wiki
For some reason, at least on Fedora 14, this does NOT install the MediaWiki "dialect" module, and that does not seem to be available as a separate RPM package in any of the standard repositories. A workaround is to install this with the "cpan" command:
cpan install D/DI/DIBERRI/HTML-WikiConverter-MediaWiki-0.59.tar.gz
Once the converter is installed, the recommended way to convert a DocBook page is as follows:
- Download (or generate) the HTML version of the DocBook page.
- Either "Save as..." from a Browser or use wget
- Convert to "MediaWiki" format with a command like the following
html2wiki --dialect=MediaWiki file.html > file.wiki
- Browse the generated .wiki file and paste the contents into a MediaWiki "edit" page
