Wiki Editing Hints: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(Decode HTML entity names)
 
(19 intermediate revisions by 10 users not shown)
Line 1: Line 1:
__NOTOC__
[[Category:Help]]
{{LangSwitch}}
== Getting started ==


In order to make editing in the Qt Wiki a little more comfortable.
* If you have some knowledge to share about Qt, then this wiki is the place to share it. '''But restrict your articles to Qt related topics'''
* Please make sure that the page you want to create doesn't already exist. Use the search field on the top right for this purpose. If there is already a page on that topic, it will show up in the search results.
* Since this is a wiki, you can edit all of the contents on most pages.
* If there is no such page you can create one by clicking the link {{int:searchmenu-new|search term}}''' in the search results.
* Don't pollute the history of a page by doing tests; use the [[Sandbox]] instead.
 
== How to edit a page ==
 
The Qt wiki is powered by [[wikipedia:mw:|MediaWiki]], the wiki engine used by Wikipedia and many other wikis around the web.
 
When editing a page, there is a toolbar that allows the insertion of the most common syntax elements. The wiki code syntax is pretty straightforward and you can write it directly without using the toolbar. Have a look at the [[wikipedia:Help:Cheatsheet|MediaWiki cheatsheet]] for a quick reference.
 
Please, remember to always use the preview option to check your edits before you save, to prevent polluting the version history with needless entries fixing errors.
 
== 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 cover a single aspect of the topic (like a function).
 
=== Use headers for scannability ===
 
Long articles are easier to read if you add some informative headers. Please use the MediaWiki heading level (<nowiki>==</nowiki>) for your introduction and then <nowiki>===</nowiki> and <nowiki>====</nowiki> 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 Contents ===
 
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.
 
A table of contents is added automatically as soon as you included three headings, regardless of their depth. Sometimes you don't want to have a table of contents generated (e.g. because the page you create ''is'' a table of contents) you can put the magic word <tt><nowiki>__NOTOC__</nowiki></tt> at the beginning of you page.
 
=== 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 like so: <tt><nowiki>[[Category:Wiki Help]]</nowiki></tt>
 
== Collaboration ==
 
Wikis are meant for collaborative editing. To make it as easy as possible for everybody please follow some basic rules:
 
* Discuss your pages on the Talk subpage that can be reached via the top toolbar
* Write in an understandable, informative, but not too formal language.
* Structure your pages with subheadings and a healthy number 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 <nowiki>[[Category:...]]</nowiki> to group pages by topic.
 
== 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?


== Templates ==
== Templates ==
Line 13: Line 67:
|-
|-
| [[Template:DocLink]] creates a link to the doc.qt.io reference documentation
| [[Template:DocLink]] creates a link to the doc.qt.io reference documentation
| <nowiki>{{DocLink|QString}}</nowiki>
|style="white-space:nowrap;"|
| {{DocLink|QString}}
* <nowiki>{{DocLink|QWidget}}</nowiki>
|-
* <nowiki>{{DocLink|QWidget|properties}}</nowiki>
| [[Template:DocLinkAnchor]] creates a link to the doc.qt.io documentation with anchor to the member
* <nowiki>{{DocLink|QWidget|size-prop|size()}}</nowiki>
| <nowiki>{{DocLinkAnchor|QLabel|clear}}</nowiki>
* <nowiki>{{DocLink|QtWidgets-Index||Qt Widgets}}</nowiki>
| {{DocLinkAnchor|QLabel|clear}}
|
|-
* {{DocLink|QWidget}}
| [[Template:DocLinkAnchorLbl]] creates a link like DocLinkAnchor but with additional attribute for the link label in case you want to reference a QProperty that has the anchor name <tt>text-prop</tt> but you want to reference <tt>setText()</tt> or <tt>text()</tt> explicitly.
* {{DocLink|QWidget|properties}}
| <nowiki>{{DocLinkAnchorLbl|QLabel|text-prop|setText()}}</nowiki>
* {{DocLink|QWidget|size-prop|size()}}
| {{DocLinkAnchorLbl|QLabel|text-prop|setText()}}
* {{DocLink|QtWidgets-Index||Qt Widgets}} (note the empty anchor parameter)
|-
|-
| [[Template:LangLinks]] creates a list of predefined language links so that you can easily see what languages are available for the page specified
| [[Template:LangLinks]] creates a list of predefined language links so that you can easily see what languages are available for the page specified
Line 31: Line 85:
| <nowiki>{{LangSwitch}}</nowiki>
| <nowiki>{{LangSwitch}}</nowiki>
| {{LangSwitch}}
| {{LangSwitch}}
|-
| [[Template:Ambox]] inserts a notification box
| <nowiki>{{Ambox|text=Some notification text}}</nowiki>
| {{Ambox|text=Some notification text}}
|-
| [[Template:WarningBox]] inserts a warning box
| <nowiki>{{WarningBox|text=Some warning text}}</nowiki>
| {{WarningBox|text=Some warning text}}
|-
| [[Template:Cleanup]] inserts a notice that the article needs improvement, and puts the article in [[:Category:Articles needing cleanup]]. You can specify the reason for the tag.
| <nowiki>{{Cleanup|reason=The text is too repetitive.}}</nowiki>
| {{Ambox|text='''This article may require cleanup to meet the Qt Wiki's quality standards.''' Reason: The text is too repetitive.<br /><small>Please '''[{{fullurl:{{FULLPAGENAME}}|action=edit}} improve this article]''' if you can. Remove the <nowiki>{{cleanup}}</nowiki> tag and add this page to '''[[Updated pages]]''' list after it's clean.</small>}}
|-
| [[Template:Delete]] inserts a notice that the article is nominated for deletion, and puts the article in [[:Category:Delete]]. You can specify the reason for the tag.
| <nowiki>{{Delete|reason=This page is empty.}}</nowiki>
| {{WarningBox|text=This article is nominated for deletion. Reason: This page is empty.<br /><small>Please raise your support/opposition to this nomination in the article's Discussion page.</small>}}
|}
|}


== Multi Language Articles ==
== Multi-language articles ==


When creating new articles the first language should always be English (reference language). When translating an article you just append the [http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes ISO-639-1] language code separated by a slash to the URL and hit Enter. The Wiki now tells you that the page can be created.
When creating new articles the first language should always be English (reference language). When translating an article you just append the [[wikipedia:List of ISO 639-1 codes|ISO-639-1]] language code separated by a slash to the URL and hit Enter. The Wiki now tells you that the page can be created.


Example:
Example:


*[[Basic Qt Programming Tutorial]]
* [[Basic Qt Programming Tutorial]]
*[[Basic Qt Programming Tutorial/de]]
* [[Basic Qt Programming Tutorial/de]]


== Tables ==
== Tables ==
Line 46: Line 116:
The Mediawiki [https://www.mediawiki.org/wiki/Help:Tables help page on Tables] is useful reading to anyone who edits tables.
The Mediawiki [https://www.mediawiki.org/wiki/Help:Tables help page on Tables] is useful reading to anyone who edits tables.


== Syntax Highlighting ==
== Code highlighting ==
 
The wiki uses the standard [[mediawiki:Extension:SyntaxHighlight GeSHi|GeSHi syntax highlighter]].
 
The only customisation made, has been to add the <nowiki><code></nowiki> tag to the highlighted list handled by GeSHi. You can specify the language with the <code>lang=""</code> attribute.
 
For example, you can use these settings:
* Javascript/QML: <code><nowiki><syntaxhighlight lang="javascript"></nowiki></code>
* Qt .pro: <code><nowiki><syntaxhighlight lang="make"></nowiki></code>
* Command line: <code><nowiki><syntaxhighlight lang="bash"></nowiki></code>
* XML: <code><nowiki><syntaxhighlight lang="xml"></nowiki></code>
* C++: <code><nowiki><syntaxhighlight lang="cpp"></nowiki></code>
 
 
Notice that in order to have code highlighted '''inline''' in a paragraph, the "inline" attribute must be included:
... the following highlighted text <nowiki><syntaxhighlight </nowiki>'''inline'''<nowiki>>void mySuperFunkyFunc(const char*)</syntaxhighlight></nowiki> should stay in the same paragraph ...
 
Displays as:
 
... the following highlighted text <syntaxhighlight inline>void mySuperFunkyFunc(const char*)</syntaxhighlight> should stay in the same paragraph ...


The wiki uses the standard [https://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi GeSHi syntax highlighter].
Without '''inline''', it displays as:


The only customisation made, has been to add the <code> tag to the highlighted list handled by GeSHi. The default language is set to C++. Change the language with the lang="" attribute (for example <code lang="javascript">).
... the following highlighted text <syntaxhighlight>void mySuperFunkyFunc(const char*)</syntaxhighlight> creates a new paragraph ...

Latest revision as of 23:42, 22 November 2022

En Ar Bg De El Es Fa Fi Fr Hi Hu It Ja Kn Ko Ms Nl Pl Pt Ru Sq Th Tr Uk Zh

Getting started

  • If you have some knowledge to share about Qt, then this wiki is the place to share it. But restrict your articles to Qt related topics
  • Please make sure that the page you want to create doesn't already exist. Use the search field on the top right for this purpose. If there is already a page on that topic, it will show up in the search results.
  • Since this is a wiki, you can edit all of the contents on most pages.
  • If there is no such page you can create one by clicking the link Create the page "search term" on this wiki! in the search results.
  • Don't pollute the history of a page by doing tests; use the Sandbox instead.

How to edit a page

The Qt wiki is powered by MediaWiki, the wiki engine used by Wikipedia and many other wikis around the web.

When editing a page, there is a toolbar that allows the insertion of the most common syntax elements. The wiki code syntax is pretty straightforward and you can write it directly without using the toolbar. Have a look at the MediaWiki cheatsheet for a quick reference.

Please, remember to always use the preview option to check your edits before you save, to prevent polluting the version history with needless entries fixing errors.

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 cover a single aspect of the topic (like a function).

Use headers for scannability

Long articles are easier to read if you add some informative headers. Please use the MediaWiki heading level (==) for your introduction and then === and ==== 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 Contents

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.

A table of contents is added automatically as soon as you included three headings, regardless of their depth. Sometimes you don't want to have a table of contents generated (e.g. because the page you create is a table of contents) you can put the magic word __NOTOC__ at the beginning of you page.

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 like so: [[Category:Wiki Help]]

Collaboration

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

  • Discuss your pages on the Talk subpage that can be reached via the top toolbar
  • Write in an understandable, informative, but not too formal language.
  • Structure your pages with subheadings and a healthy number 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 [[Category:...]] to group pages by topic.

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?

Templates

One can make use of the MediaWiki Templates. This page summarizes the current state of available Templates:

Template Name You type You get
Template:DocLink creates a link to the doc.qt.io reference documentation
  • {{DocLink|QWidget}}
  • {{DocLink|QWidget|properties}}
  • {{DocLink|QWidget|size-prop|size()}}
  • {{DocLink|QtWidgets-Index||Qt Widgets}}
Template:LangLinks creates a list of predefined language links so that you can easily see what languages are available for the page specified {{LangLinks|base=Download Data from URL}} bg de el es fr it ja ko pt ru zh
Template:LangSwitch does the same as LangLinks but for the same page the template is inserted. It checks all available language subpages and inserts a link. For this template you don't need to specify any parameters. {{LangSwitch}}

En Ar Bg De El Es Fa Fi Fr Hi Hu It Ja Kn Ko Ms Nl Pl Pt Ru Sq Th Tr Uk Zh

Template:Ambox inserts a notification box {{Ambox|text=Some notification text}}
Some notification text
Template:WarningBox inserts a warning box {{WarningBox|text=Some warning text}}
Some warning text
Template:Cleanup inserts a notice that the article needs improvement, and puts the article in Category:Articles needing cleanup. You can specify the reason for the tag. {{Cleanup|reason=The text is too repetitive.}}
This article may require cleanup to meet the Qt Wiki's quality standards. Reason: The text is too repetitive.
Please improve this article if you can. Remove the {{cleanup}} tag and add this page to Updated pages list after it's clean.
Template:Delete inserts a notice that the article is nominated for deletion, and puts the article in Category:Delete. You can specify the reason for the tag. {{Delete|reason=This page is empty.}}
This article is nominated for deletion. Reason: This page is empty.
Please raise your support/opposition to this nomination in the article's Discussion page.

Multi-language articles

When creating new articles the first language should always be English (reference language). When translating an article you just append the ISO-639-1 language code separated by a slash to the URL and hit Enter. The Wiki now tells you that the page can be created.

Example:

Tables

The Mediawiki help page on Tables is useful reading to anyone who edits tables.

Code highlighting

The wiki uses the standard GeSHi syntax highlighter.

The only customisation made, has been to add the <code> tag to the highlighted list handled by GeSHi. You can specify the language with the

lang=""

attribute.

For example, you can use these settings:

  • Javascript/QML:
    <nowiki><syntaxhighlight lang="javascript"></nowiki>
    
  • Qt .pro:
    <nowiki><syntaxhighlight lang="make"></nowiki>
    
  • Command line:
    <nowiki><syntaxhighlight lang="bash"></nowiki>
    
  • XML:
    <nowiki><syntaxhighlight lang="xml"></nowiki>
    
  • C++:
    <nowiki><syntaxhighlight lang="cpp"></nowiki>
    


Notice that in order to have code highlighted inline in a paragraph, the "inline" attribute must be included:

... the following highlighted text <syntaxhighlight inline>void mySuperFunkyFunc(const char*)</syntaxhighlight> should stay in the same paragraph ...

Displays as:

... the following highlighted text void mySuperFunkyFunc(const char*) should stay in the same paragraph ...

Without inline, it displays as:

... the following highlighted text

void mySuperFunkyFunc(const char*)

creates a new paragraph ...