Main Policy

This page gives an overview of the conventions in this Wiki.

1 Information submitted to this Wiki

The information in this Wiki is under the GNU Free Documentation License. This is the same license as the one used for the OpenFOAM manuals.

For more details and to learn about the consequences go to Project:Copyrights.

Please don't publish anything you don't have the rights for here. When in doubt include only a link to the material.

2 Semantic conventions

The general rule is:

structure the information in this Wiki in the same way it is structured in the OpenFOAM distribution
- The sections for solvers and other applications should have subsections that mirror the directory structure of their sources
- The annotations to the manuals are organized in a structure that mirrors the chapters of the printed versions
use the same nomenclature as the printed OpenFoam documentation (especially for symbols)

Reference the original source of information. One special case is if your source is a discussion from the OpenFOAM-message board: put a link to that discussion into your article.

2.1 Language

The language of this Wiki is English. If you want to write about OpenFOAM in German, Latin or any other language please do so at another Wiki. If you want to I'll put a link to it on this page (or you can do so yourself - it's a Wiki).

The next question everyone is going to ask: "British or American English?". The answer: I don't care whether your language is colorful or colourful.

If you are a native speaker (or a person who happens to speak English very good) and you find an obvious mistake in the use of your mother-tongue be so kind and discreetly correct it (and don't "make yourself me-nothing, you-nothing out of the dust" like the German-speaking would say).

It has been brought to my attention that this section contains grammatical errors. They were left in as some kind of joke although they were not intended for that.

2.2 What goes where

The main part of this Wiki is the FAQ. Therefor this section will explain what doesn't go into the FAQ, where it goes and why.

The basic rule is: the FAQ only should have articles that

are of general interest (more than 3 persons have already asked that question or expressed interest in the answer)
can be formulated as a short, precise questions
can be answered in a few sentence

Therefor the exceptions are:

if the question is about a solver or a utility and the answer is only applicable to that application then write it in the article in Solvers or Utilities
if the answer is too long consider writing an article in one of the categories (and reference that article in the FAQ). Too long would mean (these numbers are only approximations):
- More that 10 lines of C++-code (consider writing a Code Snipplet)
- More than 10 lines of text (consider writing in Tips and Tricks or the How-Tos)
if you are not aware of anybody else who is interested in that questions, write an article in Tips and Tricks. It can always be moved to the FAQ if other people express an interest in it

The FAQ is split into a number of sub-pages (like a page for general questions about OpenFOAM) which can be edited separately and are collected into a long version.

2.2.1 User contributed applications and examples

Applications that you want to make available to the public go into the correct section of Contributions on the Main Page.

2.2.2 Difference between Examples and Projects

If you're providing the files that are necessary to run the simulation it goes to Examples. If you're only showing pictures it goes to Projects.

2.3 Information on the pages

Some pages in this Wiki are more standardized than others. In order to make this Wiki usable certain kinds of pages should contain a minimum of standardized information.

2.3.1 Application pages

Pages about solvers and utilities should contain:

Short description: What this application does (for the original OpenFOAM applications this would be the descriptions that are in the User Manual in the chapters 3.5 and 3.6)
Usage: Describes the command line parameters and input files for that application. The main part of the page
Example: Not necessary. An example how the application was used (pictures would be nice)
Download: Where to get the source code. Either from the Wiki itself or from an external source. Also the installation procedure if more than a simple wmake is required.
History: Where this application originated (for instance a link to the discussion in the OpenFOAM-MessageBoard). Version history (if any)

Sign the page if you want people to contact you about that application

2.3.2 User pages

These pages should introduce OpenFOAM-users to each other (as proposed by Fabian Braennstroem in this discussion on the Message Board). This can contain anything from a link to more extensive information (but should not duplicate the information on your homepage: focus on the OpenFOAM-specific)

Information of interest is:

name of the institute/company (with a link)
your status as a user of OpenFOAM: evaluating/using/contributing/....
work done with Foam/OpenFoam (cross link to the Projects page if you have something there)
future/planed topics
writing code for solver, models (cross link to the contributed solvers or contributed utilities if you have something there)
wishes (solver, models, ...)
reason for using OpenFoam
which users of this Wiki are affiliated with your institution (and make a link back from the user pages)

Just attach your pages to the base page Users. If a sufficient number of contributions has been made I will think about a structure for this page (based on the contributions).

2.3.3 Project pages

These pages serve two purposes:

give people an opportunity to show the work they have done with OpenFOAM to the world
help to promote OpenFOAM

In the most basic version these pages provide only a link to the original pages.

In the ideal case these pages would contain:

name of the project
institution that did it (with a link to the page on Users or the homepage)
description
results
references to publications
how it was done
- solver used
- description of the modifications necessary (additional models etc)
- problems

Just attach your pages to the base page Projects. If a sufficient number of contributions has been made I will think about a structure for this page (based on the contributions).

If there is enough material I'm thinking about splitting Projects into two pages:

Real world examples
Benchmark cases: Comparisons of OpenFOAM simulations with published experimental data or results of other solvers (even if their unfavorable)

2.3.4 Code snipplets

These are short sections of C++ code that can be added to a solver/utility in order to achive something. They are not a library in that sense, that they can be used unmodified. They may have to be adopted for the special purposes of that application.

The form of the code snipplets is free form, but they should contain some basic information:

what it does
how to use it
are there any limitations?
alternative approaches

The code should be added in the text (not as separate files)

2.4 Etiquette

This section is of course not necessary, because CFD-people are widely known for their good manners and their sensitivity, but I'll write it anyway:

be polite
if an article is signed with a name then only change it after checking with the author if it is a major change (correcting typos and obvious mistakes is OK without asking)
comment the quality of an article only in the attached discussion-page (an be polite)
when using the work of others in a signed article make it clear where you got it from
by signing an article you tell the others that you think that you want to edit this page exclusively (usually because it's about an application that you developed)

3 Technical conventions

To make the maintainance of this Wiki easier please conform to these conventions.

3.1 Naming things

All the uploaded pictures (and to a degree the pages) in a Wiki share the same namespace. It is therefor obvious that a picture with the name temperature.jpg can only cause grief to all those who want to demonstrate some non-isothermal problem.

In other words everything that is accessed in the Wiki by it's name should have a name that

clearly describes it's purpose
makes it obvious to which page it belongs
takes every possible precaution to make it unique (without bloating it)

3.1.1 Naming pages

Page names are composed of two parts:

the first part describes the category (the possible values are listed in the table below)
the second part can be chosen by the user (but should be unique - for articles about applications the name of the application is recommended)

Table of prefixes
Prefix	Which pages get this prefix
main	Pages that are linked from the Main_Page. Usually the roots of other categories
faq	Sub pages of the FAQ.
uguide	Sub pages of the User Guide Addendum
pguide	Sub pages of the Programmer's Guide Addendum
app	Pages for the applications distributed with OpenFOAM. Sub pages of Main_OFSolvers and Main_OFUtilities
tut	Pages about the tutorials distributed with OpenFOAM. Sub pages of Main_Tutorials
uguide	Sub pages of the User Guide Addendum
sig	Sub pages of Special Interest Groups
src	Sub pages of Main_CodeStructure
snip	Sub pages of Main_CodeSnipplets
howto	Sub pages of the How-To's
tip	Sub pages of the Tips and Tricks
user	Page about a Institution using OpenFOAM. Subpage of Main_Users
project	Page about a project done with OpenFOAM. Subpage of Main_Projects
contrib	Page about an application contributed by a user. Subpage of Main_ContribUtilities or Main_ContribSolvers
example	Example case contributed by a user. Subpage of Main_ContribExamples
test	Testing page. Subpage of Main_TestSite

3.1.2 Naming files

Before you upload a file make sure that it's name is unique. The name should consist of two parts separated by an underscore:

the first part should be derived from the name of the page on which you want to use that image. For an application this would be the name of the application.
for the second part no restrictions apply (but try to make the name meaningful)

Examples of filenames would be: icoFoam_initialConditions.jpg, howtoTurbulenceModelling_screenshot1.jpg or calcThoseFunkyInitalConditions.tar.gz

3.2 Editing pages

The most important things about editing the Wiki are found on the Help:Editing page (a link to it can be found on the bottom of the page if you're editing). On that page is a list of the extensions installed into this Wiki (with explanations). So far the extensions are

possibility to enter equations in a LaTeX-Syntax
syntax coloring source code

3.2.1 Unfinished pages

If you're not finished with editing a page and plan to come back later then mark the missing part with the word 'TODO and a short description of what your intentions are.

On the other hand, if you're not certain when you'll be able to finish said page, add it to the category Category:Incomplete pages, by adding this piece of code to the end of the page:

[[:Category:Incomplete pages]]

3.3 Version Information

Use the templates described in Version Information on the Editing-Help to tag pages. This should indictate to the reader for which version of OpenFOAM this information is known to be valid (it may be valid for other versions than those indicated but nobody garantees this).

The Wiki-Software automatically groups all pages valid for one version on one category-page.

3.4 File types for uploading

The Wiki is quite restrictive about the file types it allows for uploading. Basically they fall into two categories

Pictures: png, gif, jpg,jpeg
Archives: gz, zip, tar, tgz

Should you want to upload a file that doesn't fall into one of the categories zip it (or use another one of the supported archive types) and upload that archive. Don't use this to upload binaries.

--Bgschaid 13:48, 31 May 2005 (CEST)