[[!toc ]]

# On textual conventions

Remember that this is a [[!wikipedia wiki]]; its base syntax, [[!wikipedia Markdown]], is more limited than the one you have when writing down man pages using packages like [[!template id=man name=mdoc section=7]], where data types (variables, pathnames, flags, functions, return values, ...) have each their associated types, or document markup language like [[!wikipedia LaTeX]]. 

This does not mean that we should not care about conventions, though. For convenience, prefer using the ones that are chosen by the HTML output of the .

## Quoting

When quoting text from an outside source, use double quotes "...", and explicitly indicate its reference.

When you want to quote specific character(s), use single quotes. For example: all sentences end with a '.'.

## Files and directories

Files and directories (and in a wider sense, *paths*) should be *emphasized*, e.g. *fstab* and *rc.conf* are found under */etc/*.

## Commands, options names and flags

When a command, or an executable, are referenced, they should be **strongly emphasized**; same goes for their optional flags and arguments, e.g. **ls** can be used to list the content of a directory, and, together with its **-a** flag, will output entries that start with a dot.

## Functions, or specific part of code

Functions reference should be *simply emphasized*. It is preferable to give the associated file explicitly, to avoid confusions; in that case, use a colon `:' to separate file name from function name. Same goes when you want to pinpoint to specific zone in source files, like lines.

For example, the *src/bin/print.c:printlong* function is responsible for printing the long output from [[!template id=man name=ls section=1]].

# On the usage of links

You can find multiple types of links within the wiki:

1. links to other pages of this [[wiki|sitemap]]:
    2. [[Epson]]
    2. [[wiki/start]]
1. explicit URLs:
    2. with a label: 
    2. or without: 
1. last but not least, various services regarding NetBSD:
    2. problem reports: [[!template id=pr number=1]]
    2. man pages: [[!template id=man name=intro section=1]], [[!template id=man name=hier section=7]]
    2. pkgsrc packages: [[!template id=pkg category=www name=apache]], [[!template id=pkg category=security name=netpgp]]

Always prefer using [[templates]] rather than hard-coding paths for external URLs. This helps both maintainability and readability.

# Specific layouts

The wiki support different commands, [[shortcuts]] and [[templates]] that can help controlling the layout.

## Code

TBC 

## Terminal/console-like output

If you want to write series of commands, eventually with their output, you can use the [[programlisting_template|templates/programlisting]].

[[!template id=programlisting text="""
$ uname
NetBSD
$ cat /etc/fstab
# See /usr/share/examples/fstab/ for more examples.
/dev/wd0a	/	  ffs      rw,log	1 1
/dev/wd0b	none	  swap	   sw		0 0
kernfs		/kern	  kernfs   rw
ptyfs		/dev/pts  ptyfs    rw
procfs		/proc	  procfs   rw
/dev/cd0a	/cdrom    cd9660   ro,noauto
"""]]

## File content

If you want to display the content of a file, and make a proper distinction with terminal output, use the [[filecontent_template|templates/filecontent]].

[[!template id=filecontent name="/etc/fstab" text="""
# See /usr/share/examples/fstab/ for more examples.
/dev/wd0a	/	  ffs      rw,log	1 1
/dev/wd0b	none	  swap	   sw		0 0
kernfs		/kern	  kernfs   rw
ptyfs		/dev/pts  ptyfs    rw
procfs		/proc	  procfs   rw
/dev/cd0a	/cdrom    cd9660   ro,noauto
"""]]

## Warnings and notes

### Warnings

TBC Provide a "warning" template, with a nice-looking icon and appropriate framing (light red fieldset, for example). Investigate Tango icons. Needs some CSS tweaking.

### Notes

TBC Provide a "note" template, similar to the "warning" one (yellow-greyish maybe).

***

# References

Last, some references:

* TBD
* TBD