WikiHelp: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
Line 1: Line 1:
'''English''' [[WikiHelpFrench|Français]] [[WikiHelp German|Deutsch]] [[WikiPomoc|Polski]] [[WikiHelp Ukrainian|Українська]] [[WikiHelpPortuguese|Português]] [[WikiHelp Russian|Русский]] [[WikiHelp_Italian|Italian]] [[WikiHelp Hungarian|Magyar]] [[WikiAyuda |Spanish]] [[WikiHelp_Korean|한국어]] [[WikiHelpArabic|عربي]] [[WikiHelpJapanese|日本語]] [[WikiHelpSimplifiedChinese|简体中文]]<br />[toc align_right=&quot;yes&amp;quot; depth=&quot;3&amp;quot;]
'''English''' [[WikiHelpFrench|Français]] [[WikiHelp German|Deutsch]] [[WikiPomoc|Polski]] [[WikiHelp Ukrainian|Українська]] [[WikiHelpPortuguese|Português]] [[WikiHelp Russian|Русский]] [[WikiHelp_Italian|Italian]] [[WikiHelp Hungarian|Magyar]] [[WikiAyuda |Spanish]] [[WikiHelp_Korean|한국어]] [[WikiHelpArabic|عربي]] [[WikiHelpJapanese|日本語]] [[WikiHelpSimplifiedChinese|简体中文]]
[toc align_right="yes" depth="3"]


= Working on the wiki =
= Working on the wiki =
Line 9: Line 10:
# If someone already created a page on that topic, you will see it in the search results.
# If someone already created a page on that topic, you will see it in the search results.
# You can edit all of the contents on most pages. (page [[WikiSyntax]] helps with the markup)
# You can edit all of the contents on most pages. (page [[WikiSyntax]] helps with the markup)
# If there is no such page you can create one by clicking &quot;Create new page&amp;quot;.
# If there is no such page you can create one by clicking "Create new page".
# Use spaces or underscores for titles in '''both''' articles and categories. — &quot;see the related thread on the forum&amp;quot;:http://forum.qt.io/viewthread/2262/ in a [[ForumHelp|forum poll]] where can vote.
# Use spaces or underscores for titles in '''both''' articles and categories. — "see the related thread on the forum":http://forum.qt.io/viewthread/2262/ in a [[ForumHelp|forum poll]] where can vote.
# Don't pollute the history of a page by doing markup tests, use the [[Playground]] instead.
# Don't pollute the history of a page by doing markup tests, use the [[Playground]] instead.


Line 17: Line 18:
The editor provides you with the most common functions collected in a kitchen sink. That should get you quite somewhere.
The editor provides you with the most common functions collected in a kitchen sink. That should get you quite somewhere.


If you prefer to write wiki code directly you can have a look at &quot;this cheat sheet&amp;quot;:http://warpedvisions.org/projects/textile-cheat-sheet/ and practice your skills &quot;at Textism.com&amp;quot;:http://textism.com/tools/textile/ They provide a tool that turns Textile - the markup language our wikis use - into HTML for preview.
If you prefer to write wiki code directly you can have a look at "this cheat sheet":http://warpedvisions.org/projects/textile-cheat-sheet/ and practice your skills "at Textism.com":http://textism.com/tools/textile/ They provide a tool that turns Textile - the markup language our wikis use - into HTML for preview.


Please, use the preview option to check your edits before you save unless you are 120% sure that you '''never''' make mistakes.
Please, use the preview option to check your edits before you save unless you are 120% sure that you '''never''' make mistakes.
Line 39: Line 40:
When readers find your article, they will scan the first page to figure out if it's what they're looking for. If your article is not much longer than one page, all you need to do is write it. If it's much longer than that, use a table of content to show the reader what's to come. Your opening paragraph plus table of content should be all the reader needs to know whether to click down or click away.
When readers find your article, they will scan the first page to figure out if it's what they're looking for. If your article is not much longer than one page, all you need to do is write it. If it's much longer than that, use a table of content to show the reader what's to come. Your opening paragraph plus table of content should be all the reader needs to know whether to click down or click away.


All you need to do is add this tag &quot;[&quot;toc align_right=&quot;yes&amp;quot; depth=&quot;3&amp;quot;] (remove quotes surround first bracket) and the wiki engine will create the TOC for you. The tag can appear anywhere, but is helps maintainability if it appears at the beginning of your article.
All you need to do is add this tag "["toc align_right="yes" depth="3"] (remove quotes surround first bracket) and the wiki engine will create the TOC for you. The tag can appear anywhere, but is helps maintainability if it appears at the beginning of your article.


=== Add Categories ===
=== Add Categories ===
Line 49: Line 50:
Here are some popular category tags:
Here are some popular category tags:


&amp;#91;&amp;#91;Category:Bugs]]<br />&amp;#91;&amp;#91;Category:Developing_with_Qt::Qt Quick]]<br />&amp;#91;&amp;#91;Category:Developing with Qt::QtMobility]]<br />&amp;#91;&amp;#91;Category:HowTo]]<br />&amp;#91;&amp;#91;Category:LanguageBindings::PySide]]<br />&amp;#91;&amp;#91;Category:Learning]]<br />&amp;#91;&amp;#91;Category:Tools::QtCreator]]
&amp;#91;&amp;#91;Category:Bugs]]
&amp;#91;&amp;#91;Category:Developing_with_Qt::Qt Quick]]
&amp;#91;&amp;#91;Category:Developing with Qt::QtMobility]]
&amp;#91;&amp;#91;Category:HowTo]]
&amp;#91;&amp;#91;Category:LanguageBindings::PySide]]
&amp;#91;&amp;#91;Category:Learning]]
&amp;#91;&amp;#91;Category:Tools::QtCreator]]


== How to translate a page ==
== How to translate a page ==


If you translated a wiki page keep in mind that it has to be accessible from existing language versions. This is quite easy by adding or expanding the navigation at the top of the page. The navigation should follow this pattern:<br />'''Language_of_the_page''' Language1 Language2 … side by side with their corresponding links.
If you translated a wiki page keep in mind that it has to be accessible from existing language versions. This is quite easy by adding or expanding the navigation at the top of the page. The navigation should follow this pattern:
'''Language_of_the_page''' Language1 Language2 … side by side with their corresponding links.


For example in this page (remove the space between the brackets &quot;[ [&quot;) the following is used:<br /><code>'''English''' [ [WikiHilfe|Deutsch]] [ [WikiPomoc|Polski]]<code>
For example in this page (remove the space between the brackets "[ [") the following is used:
<code>'''English''' [ [WikiHilfe|Deutsch]] [ [WikiPomoc|Polski]]<code>


In most cases you should name your page by adding the language to the end of the original title (assuming the article was originally written in English. For example, the page '''How to Foo''', translated into Italian would be named '''How to Foo Italian'''.
In most cases you should name your page by adding the language to the end of the original title (assuming the article was originally written in English. For example, the page '''How to Foo''', translated into Italian would be named '''How to Foo Italian'''.
Line 65: Line 74:
=== How to categorize a translated page ===
=== How to categorize a translated page ===


All translated pages should be initially categorized in the same category as the original. ('''How to Foo''' gets a ''&lt;code&amp;gt;Category: How To&amp;lt;/code&amp;gt;'' tag.) By doing this a developer browsing for example the How To category would see an alphabetized list of all translations of the How to Foo article.
All translated pages should be initially categorized in the same category as the original. ('''How to Foo''' gets a ''<code>Category: How To</code>'' tag.) By doing this a developer browsing for example the How To category would see an alphabetized list of all translations of the How to Foo article.


After this initial categorization, feel free to add more — this is a collaborative wiki. If you want, for example, a top-level category that captures all articles translated into Kannada, or for the articles categorized in the ''&lt;code&amp;gt;Category:How To&amp;lt;/code&amp;gt;'' you can add a ''&lt;code&amp;gt;Category:Kannada::How To&amp;lt;/code&amp;gt;'' tag too, that's probably a great benefit for those looking for such content.
After this initial categorization, feel free to add more — this is a collaborative wiki. If you want, for example, a top-level category that captures all articles translated into Kannada, or for the articles categorized in the ''<code>Category:How To</code>'' you can add a ''<code>Category:Kannada::How To</code>'' tag too, that's probably a great benefit for those looking for such content.


== Collaboration ==
== Collaboration ==
Line 73: Line 82:
Wikis are meant for collaborative editing. To make it as easy as possible for everybody please follow some basic rules.
Wikis are meant for collaborative editing. To make it as easy as possible for everybody please follow some basic rules.


* '''Discuss your pages in the &quot;Wiki forum&amp;quot;:/forums/viewforum/16/'''
* '''Discuss your pages in the "Wiki forum":/forums/viewforum/16/'''
* Write in an understandable, informative, but not too formal language.
* Write in an understandable, informative, but not too formal language.
* Structure your pages with subheadings and a healthy amount of paragraphs for easier understanding and better reading.
* Structure your pages with subheadings and a healthy amount of paragraphs for easier understanding and better reading.
Line 83: Line 92:
== Syntax highlighting ==
== Syntax highlighting ==


In the toolbar you will find a code tag (an &quot;at&amp;quot; sign) to make code highlighted like this:
In the toolbar you will find a code tag (an "at" sign) to make code highlighted like this:


</code><br />#include &lt;QtGui&amp;gt;<br />#include &quot;window.h&amp;quot;
</code>
#include <QtGui>
#include "window.h"


int main(int argv, char **args)<br /> {<br /> QApplication app(argv, args);
int main(int argv, char **args)
{
QApplication app(argv, args);


Window window;<br /> window.show();
Window window;
window.show();


return app.exec&amp;amp;#40;&amp;#41;;<br />}<br /><code>
return app.exec();
}
<code>


Inline code can be tagged like this: &amp;lsaquo;code&amp;amp;rsaquo;someCode(here);&amp;lsaquo;/code&amp;amp;rsaquo; to look like this &lt;code&amp;gt;someCode(here);&lt;/code&amp;gt;
Inline code can be tagged like this: &amp;lsaquo;code&amp;amp;rsaquo;someCode(here);&amp;lsaquo;/code&amp;amp;rsaquo; to look like this <code>someCode(here);</code>


Qt classes are of course supported.
Qt classes are of course supported.
Line 103: Line 119:
== Need help? ==
== Need help? ==


Please, take a look at the &quot;help forum&amp;quot;:/forums/viewforum/16/ or our &quot;FAQ (Qt DN FAQ)&quot;:/faq
Please, take a look at the "help forum":/forums/viewforum/16/ or our "FAQ (Qt DN FAQ)":/faq

Revision as of 09:53, 25 February 2015

English Français Deutsch Polski Українська Português Русский Italian Magyar Spanish 한국어 عربي 日本語 简体中文 [toc align_right="yes" depth="3"]

Working on the wiki

Getting started

  1. If you have some knowledge to share about Qt, then wiki is the place to share it. But restrict your articles to Qt related topics
  2. Please make sure that the page you're thinking of creating doesn't already exist. Use the search field on the top right of the wiki box for this purpose.
  3. If someone already created a page on that topic, you will see it in the search results.
  4. You can edit all of the contents on most pages. (page WikiSyntax helps with the markup)
  5. If there is no such page you can create one by clicking "Create new page".
  6. Use spaces or underscores for titles in both articles and categories. — "see the related thread on the forum":http://forum.qt.io/viewthread/2262/ in a forum poll where can vote.
  7. Don't pollute the history of a page by doing markup tests, use the Playground instead.

How to edit a page

The editor provides you with the most common functions collected in a kitchen sink. That should get you quite somewhere.

If you prefer to write wiki code directly you can have a look at "this cheat sheet":http://warpedvisions.org/projects/textile-cheat-sheet/ and practice your skills "at Textism.com":http://textism.com/tools/textile/ They provide a tool that turns Textile - the markup language our wikis use - into HTML for preview.

Please, use the preview option to check your edits before you save unless you are 120% sure that you never make mistakes.

C++ code will be automatically highlighted on wiki pages!

How to make your pages easy to use

Help fellow developers find the great insights you're sharing by following a few simple guidelines:

Write like you're coding

Good wikis, like good code, are easy to scan and maintain. Each article should cover one topic (much like a class). Each paragraph should contribute one aspect to the topic (like a function). If you change thoughts it helps to change paragraphs so you don't bury great insights where they're hard to find.

Use headers for scannability

Long articles are easier to read if you add some informative headers. Please use h1 level for your introduction and then h2 and h3 levels to outline your discussion. (The editor includes buttons for them.) Try to write your headers so they outline what you have to say all by themselves, because you can then …

Add a table of content

When readers find your article, they will scan the first page to figure out if it's what they're looking for. If your article is not much longer than one page, all you need to do is write it. If it's much longer than that, use a table of content to show the reader what's to come. Your opening paragraph plus table of content should be all the reader needs to know whether to click down or click away.

All you need to do is add this tag "["toc align_right="yes" depth="3"] (remove quotes surround first bracket) and the wiki engine will create the TOC for you. The tag can appear anywhere, but is helps maintainability if it appears at the beginning of your article.

Add Categories

Add category tags to insert a link to your article in the appropriate summary pages. By adding your article to existing categories you help readers find your content.

If you want to create a new category and summary page, just tag your article to a category that does not yet exist.

Here are some popular category tags:

&#91;&#91;Category:Bugs]] &#91;&#91;Category:Developing_with_Qt::Qt Quick]] &#91;&#91;Category:Developing with Qt::QtMobility]] &#91;&#91;Category:HowTo]] &#91;&#91;Category:LanguageBindings::PySide]] &#91;&#91;Category:Learning]] &#91;&#91;Category:Tools::QtCreator]]

How to translate a page

If you translated a wiki page keep in mind that it has to be accessible from existing language versions. This is quite easy by adding or expanding the navigation at the top of the page. The navigation should follow this pattern: Language_of_the_page Language1 Language2 … side by side with their corresponding links.

For example in this page (remove the space between the brackets "[ [") the following is used:

'''English''' [ [WikiHilfe|Deutsch]] [ [WikiPomoc|Polski]]<code>

In most cases you should name your page by adding the language to the end of the original title (assuming the article was originally written in English. For example, the page '''How to Foo''', translated into Italian would be named '''How to Foo Italian'''.

=== Right-to-Left languages ===

For languages that are right-to-left just add '''&amp;#91;right_aligned]''' to the top of the page and it will align to the right, including bullets.

=== How to categorize a translated page ===

All translated pages should be initially categorized in the same category as the original. ('''How to Foo''' gets a ''<code>Category: How To

tag.) By doing this a developer browsing for example the How To category would see an alphabetized list of all translations of the How to Foo article. After this initial categorization, feel free to add more — this is a collaborative wiki. If you want, for example, a top-level category that captures all articles translated into Kannada, or for the articles categorized in the

Category:How To

you can add a

Category:Kannada::How To

tag too, that's probably a great benefit for those looking for such content.

Collaboration

Wikis are meant for collaborative editing. To make it as easy as possible for everybody please follow some basic rules.

  • Discuss your pages in the "Wiki forum":/forums/viewforum/16/
  • Write in an understandable, informative, but not too formal language.
  • Structure your pages with subheadings and a healthy amount of paragraphs for easier understanding and better reading.
  • Explain acronyms, at least at first use.
  • Use meaningful but straight to the point page names.
  • Don't mindlessly throw away other people's work.
  • Use Tagging to group pages by topic.

Syntax highlighting

In the toolbar you will find a code tag (an "at" sign) to make code highlighted like this:

  1. include <QtGui>
  2. include "window.h"

int main(int argv, char **args)

{
QApplication app(argv, args);

Window window;

window.show();

return app.exec(); }

Inline code can be tagged like this: &amp;lsaquo;code&amp;amp;rsaquo;someCode(here);&amp;lsaquo;/code&amp;amp;rsaquo; to look like this <code>someCode(here);

Qt classes are of course supported.

Category pages

Whenever you create a new category for your page the wiki software will create a landing page for it. This page is editable just like any other page. Just click on the link displayed on your page and edit away. All pages within the respective category will be displayed on this page. Why not start it with an introduction to the topic?

Need help?

Please, take a look at the "help forum":/forums/viewforum/16/ or our "FAQ (Qt DN FAQ)":/faq