The purpose of the following document is to propose a graphic chart regarding the NetBSD htdocs site, including this wiki, and give some examples so they can be reused quickly anywhere else.
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 .
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 (and in a wider sense, paths) should be emphasized, e.g. fstab and rc.conf are found under /etc/.
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 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).
You can find multiple types of links within the wiki:
- links to other pages of this wiki:
- (this page)
- explicit URLs:
- with a label:
- or without:
- last but not least, various services regarding NetBSD:
Always prefer using templates rather than hard-coding paths for external URLs. This helps both maintainability and readability.
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
If you want to display the content of a file, and make a proper distinction with terminal output, use the filecontent template.
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.
TBC Provide a "note" template, similar to the "warning" one (yellow-greyish maybe).
Last, some references: