File:  [NetBSD Developer Wiki] / wikisrc / wiki / graphic_chart.mdwn
Revision 1.2: download - view: text, annotated - select for diffs
Sat Oct 24 16:38:43 2015 UTC (2 years, 11 months ago) by leot
Branches: MAIN
CVS tags: HEAD
Try to fix other template usage problems.

    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]]
   47:     2. : [[!template id=man name=intro section=1]], [[!template id=man name=hier section=7]]
   48:     2. 's packages: [[!template id=pkg category=www name=apache]], [[!template id=pkg category=security name=netpgp]]
   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