Help:Editing

From FreeCAD Documentation
Revision as of 20:55, 15 January 2021 by Roy 043 (talk | contribs)

This page is a quick reference for Wikitext-code. A full help for Wiki markup can be found at Wikipedia.

WikiPages gives common guidelines on the best practices to be followed when writing FreeCAD documentation.


This Editing Overview has a lot of wikitext examples. You may want to keep this page open in a separate browser window for reference while you edit.

Editing basics

Start editing
To start editing a MediaWiki page, click the Edit this page (or just edit) link at one of its edges. This brings you to the edit page: a page with a text box containing the wikitext: the editable source code from which the server produces the webpage. If you just want to experiment, please do so in the sandbox, not here.
Type your changes
You can just type your text. However, also using basic wiki markup (described in the next section) to make links and do simple formatting adds to the value of your contribution.
Summarize your changes
Write a short edit summary in the small field below the edit-box. You may use shorthand to describe your changes, as described in the legend.
Download images
You can also import your images, screenshots. . . from the page, bottom left "Toolbox". You will be asked for a file name and a brief description of the imported file.
Download images in free formats .png (example with Gimp) and .svg (example with Inkscape)
Preview before saving
When you have finished, click Show preview to see how your changes will look -- before you make them permanent. Repeat the edit/preview process until you are satisfied, then click Save page and your changes will be immediately applied to the article.
You can also use the links of the tools in the form of Buttons or, in the form of Icons.


Basic text formatting

What it looks like What you type

You can italicize text by putting 2 apostrophes on each side.

3 apostrophes will bold the text.

5 apostrophes will bold and italicise the text.

(4 apostrophes don't do anything special -- there's just 'one left over'.)

You can ''italicize text'' by putting 2 
apostrophes on each side. 

3 apostrophes will bold '''the text'''. 

5 apostrophes will bold and italicize 
'''''the text'''''.

(4 apostrophes don't do anything special 
 -- there's just ''''one left over''''.)

A single newline has no effect on the layout. But an empty line

starts a new paragraph.

A single newline
has no effect
on the layout.
But an empty line

starts a new paragraph.

You can break lines
without a new paragraph.
Please use this sparingly.

You can break lines<br />
without a new paragraph.<br />
Please use this sparingly.

You should "sign" your comments on talk pages:
- Three tildes gives your user name: Dr. Schorsch
- Four tildes give your user name plus date/time: Dr. Schorsch 20:55, 1 November 2006 (CET)
- Five tildes gives the date/time alone: 21:01, 1 November 2006 (CET)

You should "sign" your comments 
on talk pages: <br />
- Three tildes gives your user
name: ~~~ <br />
- Four tildes give your user 
name plus date/time: ~~~~ <br />
- Five tildes gives the 
date/time alone: ~~~~~ <br />

You can use HTML tags, too, if you want. Some useful ways to use HTML:

Put text in a typewriter font. The same font is generally used for computer code.

Strike out or underlinetext, or write it in small caps.

Superscripts and subscripts: X2, H2O

Invisible comments to editors (<!-- -->) only appear while editing the page.

If you wish to make comments to the public, you should usually go on the talk page, though.

You can use <b>HTML tags</b>,
too, if you want. Some useful
ways to use HTML:

Put text in a <tt>typewriter
font</tt>. The same font is 
generally used for <code>
computer code</code>.

<strike>Strike out</strike>
or <u>underline</u> text,
or write it <span style=
"font-variant:small-caps">
in small caps</span>.

Superscripts and subscripts:
X<sup>2</sup>, H<sub>2</sub>O

Invisible comments to editors (&lt;!-- --&gt;) 
only appear while editing the page.
<!-- Note to editors: blah blah blah. -->

If you wish to make comments to the public, 
you should usually go on the 
[[wikipedia:wikipedia:talk page|talk page]], though.

For a list of HTML tags that are allowed, see HTML in wikitext. However, you should avoid HTML in favor of Wiki markup whenever possible.

Organizing your writing

What it looks like What you type
Section headings

Headings organize your writing into sections. The Wiki software can automatically generate a table of contents from them.

Subsection

Using more equals signs creates a subsection.

A smaller subsection

Don't skip levels, like from two to four equals signs.

Start with 2 equals signs not 1 because 1 creates H1 tags which should be reserved for page title.

== Subsection ==
Using more equals signs creates a subsection.

=== A smaller subsection ===

External links

You will often want to make clickable links to other pages.

Here's a link to a page named Compile on Linux/Unix. You can not say compileonunix but Compile on Linux/Unixes and the link will show up correctly.

Here's a link to a page named [[Compile on Linux/Unix]].
You can not say [[compileonunix]] but
[[Compile on Linux/Unix]]es and the link will
show up correctly.

You can put formatting around a link. Example: Compile on Linux/Unix.

You can put formatting around a link.
Example: ''[[Compile on Linux/Unix]]''.

The first letter of articles is automatically capitalized, so Compile on Linux/Unix goes to the same place as compile on Linux/Unix. Capitalization matters after the first letter.

The ''first letter'' of articles is automatically
capitalized, so [[Compile on Linux/Unix]] goes to the same place
as [[compile on Linux/Unix]]. Capitalization matters after the
first letter.

The weather in Riga is a page that doesn't exist yet. You could create it by clicking on the link.

[[The weather in Riga]] is a page that doesn't exist
yet. You could create it by clicking on the link.

You can link to a page section by its heading:

If multiple sections have the same heading, add a number. #Example section 3 goes to the third section named "Example section".

You can link to a page section by its heading:

*[[Help:Editing#Organizing your writing]].

If multiple sections have the same heading, add
a number. [[#Example section 3]] goes to the
third section named "Example section".

You can make a link point to a different place with a piped link. Put the link target first, then the pipe character "|", then the link text.

You can make a link point to a different place
with a piped link. Put the link
target first, then the pipe character "|", then
the link text.

*[[Compile on Linux/Unix|Compile on Linux/Unix]]

You can make a link to Wikipedia by typing: wikipedia:Python (programming language)

You can make an external link just by typing a URL: http://www.nupedia.com

You can give it a title: Nupedia

Or leave the title blank: [1]

You can make a link to Wikipedia by typing:
[[wikipedia:Python (programming language)]]

You can make an external link just by typing a URL:
http://www.nupedia.com

You can give it a title:
[http://www.nupedia.com Nupedia]

Or leave the title blank:
[http://www.nupedia.com]

Linking to an e-mail address works the same way: mailto:someone@domain.com or someone

Linking to an e-mail address works the same way:
mailto:someone@domain.com or 
[mailto:someone@domain.com someone]

You can redirect the user to another page.

#REDIRECT [[Official position]]

To put an article in a category, place a link like Category:Help into the article. Category links do not show up in line but at page bottom and cause the page to be listed in the category.

To link to a category page without putting the article into the category, use a colon prefix (":Category") in the link. Category:Help

To put an article in a category, 
place a link like Category:Help into the article.
Category links do not show up in line
but at page bottom ''and cause the page to be''
''listed in the category.''
[[Category:Help]]

To link to a category page without putting the article
into the category, use a colon prefix (":Category")
in the link. [[:Category:Help]]

You can include pictures . You can refer to MediaWiki Images Help for details about the possible options. A very useful one is 'none', allowing your picture to be positioned on the left, with no flowing text:

You can include pictures [[Image:Base_ExampleCommandModel.png]].
You can refer to [http://www.mediawiki.org/wiki/Help:
Images MediaWiki Images Help] for details about the possible
options. A very useful one is 'none', allowing your picture to
be positioned on the left, with no flowing text:
[[Image:Base_ExampleCommandModel.png|none]]

You can use ordered or unordered lists:

  1. Item1
    1. Sub-item 1.1
      1. Sub-item 1.1.1
    2. Sub-item 1.2
  2. Item2
  • Item1
    • Sub-item 1.1
      • Sub-item 1.1.1
    • Sub-item 1.2
  • Item2
You can use ordered or unordered lists:

# Item1
## Sub-item 1.1
### Sub-item 1.1.1
## Sub-item 1.2
# Item2

* Item1
** Sub-item 1.1
*** Sub-item 1.1.1
** Sub-item 1.2
* Item2

Collapsible element

Collapsible element complete page

Click to see the code

<div class="mw-collapsible mw-collapsed toccolours">

===Your Title===

<div class="mw-collapsible-content">

Your text and image FreeCAD.

</div>

</div>


Collapsible element 500 pixels

Click to see the code

<div class="mw-collapsible mw-collapsed toccolours" style="width:500px">

===Your Title===

<div class="mw-collapsible-content">

Your text and image FreeCAD.

</div>

</div>

Code blocks and syntax highlighting

To mark a code block a number of solutions are available. The Code template is the preferred solution.

Prepend a space to each line

Example:

 import math
 from pivy import coin
 cam = Gui.ActiveDocument.ActiveView.getCameraNode()
 rot.setValue(coin.SbVec3f(0,0,1),math.pi/2)
        self.lineEdit_1 = QtGui.QLineEdit(self.centralWidget)
        self.lineEdit_1.setGeometry(QtCore.QRect(320, 30, 151, 22))

Result:

import math
from pivy import coin
cam = Gui.ActiveDocument.ActiveView.getCameraNode()
rot.setValue(coin.SbVec3f(0,0,1),math.pi/2)
       self.lineEdit_1 = QtGui.QLineEdit(self.centralWidget)
       self.lineEdit_1.setGeometry(QtCore.QRect(320, 30, 151, 22))

Use <pre> tags

Example:

<pre>
import math
from pivy import coin
cam = Gui.ActiveDocument.ActiveView.getCameraNode()
rot.setValue(coin.SbVec3f(0,0,1),math.pi/2)
       self.lineEdit_1 = QtGui.QLineEdit(self.centralWidget)
       self.lineEdit_1.setGeometry(QtCore.QRect(320, 30, 151, 22))
</pre>

Result:

import math
from pivy import coin
cam = Gui.ActiveDocument.ActiveView.getCameraNode()
rot.setValue(coin.SbVec3f(0,0,1),math.pi/2)
       self.lineEdit_1 = QtGui.QLineEdit(self.centralWidget)
       self.lineEdit_1.setGeometry(QtCore.QRect(320, 30, 151, 22))

Use <syntaxhighlight> tags

As the name implies, these tags will highlight the syntax. The lang parameter is required.

Example:

<syntaxhighlight lang="python">
import math
from pivy import coin
cam = Gui.ActiveDocument.ActiveView.getCameraNode()
rot.setValue(coin.SbVec3f(0,0,1),math.pi/2)
       self.lineEdit_1 = QtGui.QLineEdit(self.centralWidget)
       self.lineEdit_1.setGeometry(QtCore.QRect(320, 30, 151, 22))
</syntaxhighlight>

Result:

import math
from pivy import coin
cam = Gui.ActiveDocument.ActiveView.getCameraNode()
rot.setValue(coin.SbVec3f(0,0,1),math.pi/2)
       self.lineEdit_1 = QtGui.QLineEdit(self.centralWidget)
       self.lineEdit_1.setGeometry(QtCore.QRect(320, 30, 151, 22))

Use the Code template

The Code template will also highlight the syntax. If the language is Python the lang parameter is optional.

Example:

{{Code|lang=python|code=
import math
from pivy import coin
cam = Gui.ActiveDocument.ActiveView.getCameraNode()
rot.setValue(coin.SbVec3f(0,0,1),math.pi/2)
       self.lineEdit_1 = QtGui.QLineEdit(self.centralWidget)
       self.lineEdit_1.setGeometry(QtCore.QRect(320, 30, 151, 22))
}}

Result:

import math
from pivy import coin
cam = Gui.ActiveDocument.ActiveView.getCameraNode()
rot.setValue(coin.SbVec3f(0,0,1),math.pi/2)
       self.lineEdit_1 = QtGui.QLineEdit(self.centralWidget)
       self.lineEdit_1.setGeometry(QtCore.QRect(320, 30, 151, 22))

Templates and transcluding pages

Templates are segments of wiki markup that are meant to be copied automatically ("transcluded") into a page. You add them by putting the template's name in {{double braces}}. By default, pages are transcluded from the default Template namespace. The namespace is the portion of a page name before the colon; for instance, in Help:Editing, Help is the namespace in which the page Editing lives.

It is also possible to transclude other pages from the default namespace (the null one) by using {{:colon and double braces}}.

There are three pairs of transclusion markup tags that can be used in wikitext to control how transclusion affects parts of a template or article. They determine whether or not wikitext renders, either in its own article, which we will call "here", or in another article where it is transcluded, which we will call "there".

  • <noinclude>: the content will not be rendered there. These tags have no effect here.
  • <includeonly>: the content will render only there, and will not render here (like invisible ink made visible by means of transclusion).
  • <onlyinclude>: the content will render here and will render there, but it will only render there what is between these tags.

There can be several such section. Also, they can be nested.

Remark: if a page is transcluded without any transclusion markup, it may cause an unintentional categorization. Any page transcluding it will contain the same category as the original page. Wrap the category markup with <noinclude> tags to prevent incorrect categorization.

What it looks like What you type

This text comes from the page named Template:Transclusion demo. It has been transcluded into this page.

{{Transclusion demo}}

This transclusion demo is a little bit of text from the page Help:Transclusion demo to be included into any file.

{{Help:Transclusion demo}}

Special Pages

Special pages are pages that cannot be edited, but are generated by the wiki engine. They provide very useful functions, and live in the Special namespace. A summary of all special pages is available from Special:SpecialPages.

Direct link to frequently used Special pages are:

Minor edits

A logged-in user can mark an edit as "minor". Minor edits are generally spelling corrections, formatting, and minor rearrangement of text. Users may choose to hide minor edits when viewing Recent Changes.

Marking a significant change as a minor edit is considered bad Wikiquette. If you have accidentally marked an edit as minor, make a dummy edit, verify that the "[ ] This is a minor edit" check-box is unchecked, and explain in the edit summary that the previous edit was not minor.

Translations

Available translations of this page: