Annotation of wikisrc/wiki/graphic_chart.mdwn, revision 1.3
1.1 wiki 1: [[!toc ]]
2:
3: # Introduction
4:
5: 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.
6:
7: ***
8:
9: # On textual conventions
10:
11: 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]].
12:
13: 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 .
14:
15: ## Quoting
16:
17: When quoting text from an outside source, use double quotes "...", and explicitly indicate its reference.
18:
19: When you want to quote specific character(s), use single quotes. For example: all sentences end with a '.'.
20:
21: ## Files and directories
22:
23: Files and directories (and in a wider sense, *paths*) should be *emphasized*, e.g. *fstab* and *rc.conf* are found under */etc/*.
24:
25: ## Commands, options names and flags
26:
27: 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.
28:
29: ## Functions, or specific part of code
30:
31: 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.
32:
33: For example, the *src/bin/print.c:printlong* function is responsible for printing the long output from [[!template id=man name=ls section=1]].
34:
35: # On the usage of links
36:
37: You can find multiple types of links within the wiki:
38:
39: 1. links to other pages of this [[wiki|sitemap]]:
40: 2. [[index]]
41: 2. [[wiki/graphic_chart]] (this page)
42: 1. explicit URLs:
43: 2. with a label:
44: 2. or without:
45: 1. last but not least, various services regarding NetBSD:
46: 2. problem reports: [[!template id=pr number=1]]
1.3 ! leot 47: 2. man pages: [[!template id=man name=intro section=1]], [[!template id=man name=hier section=7]]
! 48: 2. pkgsrc packages: [[!template id=pkg category=www name=apache]], [[!template id=pkg category=security name=netpgp]]
1.1 wiki 49:
50: Always prefer using [[templates]] rather than hard-coding paths for external URLs. This helps both maintainability and readability.
51:
52: # Specific layouts
53:
54: The wiki support different commands, [[shortcuts]] and [[templates]] that can help controlling the layout.
55:
56: ## Code
57:
58: TBC
59:
60: ## Terminal/console-like output
61:
62: If you want to write series of commands, eventually with their output, you can use the [[programlisting_template|templates/programlisting]].
63:
64: [[!template id=programlisting text="""
65: $ uname
66: NetBSD
67: $ cat /etc/fstab
68: # See /usr/share/examples/fstab/ for more examples.
69: /dev/wd0a / ffs rw,log 1 1
70: /dev/wd0b none swap sw 0 0
71: kernfs /kern kernfs rw
72: ptyfs /dev/pts ptyfs rw
73: procfs /proc procfs rw
74: /dev/cd0a /cdrom cd9660 ro,noauto
75: """]]
76:
77: ## File content
78:
79: If you want to display the content of a file, and make a proper distinction with terminal output, use the [[filecontent_template|templates/filecontent]].
80:
81: [[!template id=filecontent name="/etc/fstab" text="""
82: # See /usr/share/examples/fstab/ for more examples.
83: /dev/wd0a / ffs rw,log 1 1
84: /dev/wd0b none swap sw 0 0
85: kernfs /kern kernfs rw
86: ptyfs /dev/pts ptyfs rw
87: procfs /proc procfs rw
88: /dev/cd0a /cdrom cd9660 ro,noauto
89: """]]
90:
91: ## Warnings and notes
92:
93: ### Warnings
94:
95: 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.
96:
97: ### Notes
98:
99: TBC Provide a "note" template, similar to the "warning" one (yellow-greyish maybe).
100:
101: ***
102:
103: # References
104:
105: Last, some references:
106:
107: * TBD
108: * TBD
CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb