wiki.ipfire.org

The community-maintained documentation platform of IPFire

User Tools

Site Tools


projects:docs:quick_syntax_overview

Quick Syntax Overview

Basic Layout

There needs to be a certain basic standard in the wiki, which relates to the appearance and design. Each page should start with the name of the page inside an “H1” tag. Each section is then given a heading from H2 through h5, allowing nesting. In other words, if you have a section with an H2, then you have a subsection, you would give it an H3 heading. Then, a different section on the same level as the previous H2 would have another H2.

A detailed overview can be found here.

Example:

====== Wiki Quick Overview ====== 
(6x '=' Before and after the title)



Each additional heading then is graded from “H2”. So, for example, installation, configuration, and so called.

Example:

Heading H2

===== Heading H2 =====  (5x '=' Before and after the title)

Should subdivide a topic, this “H3” heading then can be made ​​with a.

Example:

Heading H3

==== Heading H3 ====  (4x '=' Before and after the title)

A multiple subdivision can work with a “H4” heading.

Example:

Heading H4

=== Heading H4 ===  (3x '=' Before and after the title)

For example, a list of related links, which should be at the bottom on a page, headline can then be used with a “H5”.

Example:

Heading H5
== Heading H5 ==  (2x '=' Before and after the title)

Text Formatting

Text formatting supports, among others, the presentation of the text in bold, italics, underline, monospaced, and strikethrough, as well as, color representation of text

Bold Text Text

Bold Text is designated with two asterisks (stars) before and after the text

Syntax:

**Bold Text**

Italicized Text

Italicized Text is designated with two slashes before and after the text

Syntax:

  //Italicized Text//

Underlined Text

Underlined Text is designated with 2 underscores before and after the text

Syntax:

  __Underscore Text__

Monospace Text

Monospace is designated with 2 single quotes before and after the text

Syntax:

  ''Monspace Text''

Strikethrough Text

Strikethrough Text is designated with the “” tag. Syntax: <code> <del>Strikethrough Text </code>

Changing Font Colors

The color of text can be changed using the “” tag. Syntax: <code> <color blue>Blue Text </code>

Some other color options are:

  <color red>red</color> 
  <color blue>blue</color> 
  <color yellow>yellow</color>
  <color orange>orange</color>

There are many more colors. A list of colors is available at the Dokuwiki Site


There are differences in the wiki syntax for “internal” and “external” links. Furthermore, the namespace of the links plays an important part in the creation of new pages.

Links are designated by enclosing them in two sets of square brackets ([).

Internal Links MUST pay attention to the name space. For example, if creating a new page, the link must include the namespace the page goes into.

When creating a new page is to be noted that the page name or the name space are labeled in ENGLISH Example: (:namenspace:sitename)

Internal links begin with an opening two square brackets ([) and ending with two closing square brackets (]). Additionally, a colon (:) is the first character after the opening square brackets, and designates an internal link.

Under most circumstances, you will place a pipe symbol (|) after the link, then insert the text you want the link to display. If you do not do this, the article title is displayed.

Internal links should never contain the complete URL. The link should always consist of language, namespace and page name, each preceeded by a colon. An example of an internal link is.

Syntax:

  [[:dns:public-servers|List of free DNS Server]]

This means the page is in the dns namespace (:dns), and the actual page name is public-servers (:public-servers). The text to be displayed is after the pipe symbol (|)

This link will then look like this:

List of free DNS Server

For the external links, the copyright must be observed (direct links, version numbers, etc.).

An external link is placed in square brackets, but with no leading colons. Use the full URL. You may optionally follow the URL with a pipe symbol (|) and place text to be displayed after it. If you do not do this, the actual URL displayed.

Syntax:

  [[https://www.ipfire.org/|IPFire an OpenSource Firewall]]

This will display as

IPFire an OpenSource Firewall

Links to Wikipedia have their own syntax, which creates a small icon next to the link. Thus, you can see the text is a link to Wikipedia. You can call the Wikipedia article by name and, optionally, include a preferred language.

The link begins with the special characters wp>, followed by the name of the article. If the wp is followed by a language, that language will be preferred.

A link to the Wikipedia article on IPFire would look like:

  [[wp>IPFire|IPFire at Wikipedia]]
<code>

For the German article on IPFire
<code>
  [[wpde>IPFire|IPFire bei Wikipedia]]

and, in English:

   [[wpen>IPFire|IPFire on Wikipedia]]

They would look like this:

[[wp>IPFire|IPFire at Wikipedia]]
[[wpde>IPFire|IPFire bei Wikipedia]]
[[wpen>IPFire|IPFire on Wikipedia]]

Inserting Images

Images are inserted using double curly braces ({). This is a more complex issue. You must first upload the image to the wiki, then use them in articles.

  • When saving images, be sure to save them to the correct namespace. The images should not be randomly stored in the wiki, but at their intended location.

To upload an image, use the Add Images button at the top of the edit screen. After clicking the button, an list of namespaces will appear in the left part of the window. Select the correct namespace, then chosoe the file you want to upload.

Again, our policy is directories and files names will be “All in English”.

Images should have a good resolution and be in the .png Format for this site.

  • File names should be lower case English words, and should include the full path.

Example:

The file name would look like this. (configuration_status_networkext_picturename.png)

  • Pictures should show what is important. No complete screenshots; edit the images to show the important part. Be sure to erase any personal data.
  • Image Size: Limit images to around 600 pixels in a dimension.
  • If an image will contain a form, fill out the form BEFORE taking the screenshot
  • Images on this site should be in PNG format ONLY.
  • Images are ALWAYS centered. This is achieved by two sets of curly braces before the name.

Example:

  {{{{}} links.png  }}

  {{  withSizeIndictor.png?250  }}

Tables and Boxes

Tables without titles

Table rows are all on one line and begin and end with a “bar” or “pipe” symbol (|). Individual cells within a table are delimited with the pipe symbol also.

Example:

Left Aligned Text Centered Text Right Aligned Text
|Left Aligned Text  |   |  Centered Text  |  |  Right Aligned Text|

Adding a Header

Headers use the same syntax as table rows, but the delimiter is the caret (^). Replicate the column pattern of your table, just replace the pipe with the caret.

Left Aligned Heading Centered Heading Right Aligned Heading
^Left Aligned Heading  ^  ^  Centered Heading  ^  ^  Right Aligned Heading ^^

Boxes for Notes

We mainly use the WRAP Plugin for boxes. In the IPFire wiki, a box should only be used for notes. A box is generated as follows:

Example:

Syntax:

<WRAP center 80% important>Important Text!</WRAP>

Which looks like:

Important Text!

  • Boxes should always be centered (center keyword in the WRAP line above
  • The size of the box is indicated via the % entry. In the above example, it takes up 80% of the page width, which is a good normal practice.
  • The box syntax can give indication of the content. In the above syntax, the “important” before the > of the opening tag determines the symbol used and the color. Type tags may also be info, alert, tip, help, todo, download, danger, warning, caution, notice and safety.
  • On our site, the boxes should all have rounded corners, indicated by the round word in the opening tag above.

Example of an alert Box:

Syntax:

<WRAP center round 80% alert>Alarm!</WRAP> 

Look like:

Alarm!


Entering Code

Source or input from the console are shown in a dashed frame. The frame is generated by placing two spaces at the beginning of a line

Example:

Source code or a command from the console

For longer code, you can use the code tag.

Syntax:

<code>
Content
coming
here
soon
</code>

which would look like:

  Content
  coming
  here
  soon

Code tags can be used inside a WRAP tag, making the example very prominent.

Syntax:

<WRAP center round 80% tip>
<code>
here
is
the
content
</code>
</WRAP>

which looks like:

here
is
the
content

Lists

Lists can be created by using stars (unordered) or dashes (ordered) with two spaces before them. Multiple levels are created by indenting an additional two spaces.

Example:

Syntax:

  * This is a list
  * The second item
    * You may have different levels
  * Another item

  - The same list but ordered
  - Another item
    - Just use indention for deeper levels
  - That's it

Creates:

  • This is a list
  • The second item
    • You may have different levels
  • Another item
  1. The same list but ordered
  2. Another item
    1. Just use indention for deeper levels
  3. That's it

Bugzilla-Entries

bugz#4

bugz#3

bugz#6


Syntax highlighting and File Download

Dokuwiki has Syntax Highlighting. Different programming languages, when place in a code or file tag, will show up with syntax highlighting. You tell Docuwiki which type of code it is by placing the programming language name after the word code in the opening tag. A list of lanugages known by DocuWiki can be found at https://www.dokuwiki.org/plugin:syntaxhighlighter.

Adding an optional file name after the code type will give you a link the user can click on to download the code.

Syntax for a bash script looks like this:

<file bash httpscert>
content
</file>
  • file - specifies this is a file, so no wiki formatting is used. You can also use code.
  • bash - specifies this is a BASH script
  • httpscert - the script name. This will create a link at the top of the section which the user can click on to download

The effect can be seen below.

httpscert
#!/bin/sh
#
# new : generate new certificate
# read: read issuer in certificate and verify if it is the same as hostname
 
# See how we were called.
case "$1" in
  new)
	# set temporary random file
	export RANDFILE=/root/.rnd
	if [ ! -f /etc/httpd/server.key ]; then
		echo "Generating https server key."
		/usr/bin/openssl genrsa -rand \
			/boot/vmlinuz:CONFIG_ROOT/ethernet/settings -out \
			/etc/httpd/server.key 1024
	fi
	echo "Generating CSR"
	/bin/cat /etc/certparams | sed "s/HOSTNAME/`hostname -f`/" | /usr/bin/openssl \
		req -new -key /etc/httpd/server.key -out /etc/httpd/server.csr
	echo "Signing certificate"
	/usr/bin/openssl x509 -req -days 999999 -in \
		/etc/httpd/server.csr -signkey /etc/httpd/server.key -out \
		/etc/httpd/server.crt
	# unset and remove random file
	export -n RANDFILE
	rm -f /root/.rnd
 	;;
  read)
	if [ -f /etc/httpd/server.key -a -f /etc/httpd/server.crt -a -f /etc/httpd/server.csr ]; then
		ISSUER=`openssl x509 -in /etc/httpd/server.crt -text -noout | grep Issuer | /usr/bin/cut -f2 -d '='`
		HOSTNAME=`/bin/hostname -f`
		if [ "$ISSUER" != "$HOSTNAME" ]; then
			echo "Certificate issuer '$ISSUER' is not the same as the hostname '$HOSTNAME'"
			echo "Probably host or domain name has been changed in setup"
			echo "You could remake server certificate with '/usr/local/bin/httpscert new'"
			exit 1
		else
			echo "https certificate issuer match $HOSTNAME"
		fi
	else
		echo "Certificate not found"
		exit 1
	fi
	;;
  *)
	/bin/echo "Usage: $0 {read|new}"
	exit 1
	;;
esac

Documenters. If you see any changes to this document, please edit this, but please be neat :).

projects/docs/quick_syntax_overview.txt · Last modified: 2018/09/20 22:31 by Jon