On textual conventions

Remember that this is a wiki; its base syntax, Markdown, is more limited than the one you have when writing down man pages using packages like mdoc(7), where data types (variables, pathnames, flags, functions, return values, ...) have each their associated types, or document markup language like 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 ls(1).

On the usage of links

You can find multiple types of links within the wiki:

1. links to other pages of this wiki:
   1. ?Epson
   2. start
2. explicit URLs:
   1. with a label:
   2. or without:
3. last but not least, various services regarding NetBSD:
   1. problem reports: PR #1
   2. man pages: intro(1), hier(7)
   3. pkgsrc packages: www/apache, security/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.

$ 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.

# 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