= Do not use Edit(GUI) button. =

[[TableOfContents(4)]]

Copyright 2007, 2008  Osamu Aoki GPL, (Please agree to GPL, GPL2, and any version of GPL which is compatible with DSFG if you update any part of wiki page)

= Guide for contributing to Debian Reference =

Debian Reference upstream source is http://wiki.debian.org/DebianReference .

== Rules ==

Here are the rules.

 * Do not use Edit(GUI) button of MoinMoin.
 * You can update anytime for:
  * grammar errors
  * spelling errors
  * moved URL location
  * package name transition adjustment (emacs23 etc.)
  * clearly broken script.
 * Before updating real contents:
  * You have to discuss it on debian-doc@lists.debian.org (1 week wait for response please)
  * You have to read the whole document to avoid duplication.
  * Follow the existing style.
  * Make sure you are reachable via e-mail.
  * Think twice before doing anything.
  * Do your own research on the latest Debian system by experimenting.
  * Make contents as generic suitable for slow content update cycle (including future translation work).
  * It is usually good to place only the pointer to the original information.
  * Even if new contents are required, please shorten the description to half its original draft length.
  * Make alternative page proposals as wiki and post message to debian-doc@lists.debian.org

I use this moinmoin platform for its ability for table and XML export.

This wiki will be post-processed by XSLT/XML tools and should be written accordingly:
  * The content in the index section at the top of each wiki page will be dropped when converted to XML.
  * {{{@ { @ tag @ } @}}} (without spaces between @s) markup on wiki pages is converted to an internal link.
  * Do not use overly fancy wiki features not supported by XML conversion backend, available from the git repo. (Your help to remove fancy features in moinmoin is welcome.)
   * Do not make a complicated table with connected cells spanning rows or columns.
   * Do not use !FootNote nor face marks such as {{{:)}}} for :) .
  * Follow the wiki style:
  * The codenames are always in the lower case (sid, etch, lenny, ...)
   * Indent only for {{{*}}} and {{{1.}}} -started lines, one space per level of nesting.
   * Do not indent lines started with : {{{||}}}, {{{ { { {}}} (without spaces).
   * Some graphic marks such as {{{/!\}}} for /!\ are converted to marking for para. (See test page.)
    * Do not indent for lines started with these graphic marks.
  * Wiki table markup is processed in special ways:
   * The first line of a table is used as: <title> [, package column, popcon column].
   * popcon and package sizes are autogenerated by a script if specified in the first line.  (Values in wiki are ignored)
   * The second line of a table is used as: <thead>.
  * {{{@ @ @tag@ @ @}}} (without spaces between @s) in wiki are converted to {{{&tag;}}} in XML.
   * The final tag contents in HTML is determined by the HTML generation script.
  * All internal wiki links will be removed when converted to XML.
  * For the same text with URL link, external URL link should match if it repeats.
   * one word reference should chose mostly wikipedia
   * No {{{%}}} or {{{&}}} usage in URL address reference until I fix moin2urls.xsl.
  * Try to keep contents in
{{{
 ... commands examples ...
}}}
    language neutral so translation will not affect them.
 * Do not bloat this document.
  * It is already getting too big for me (osamu) to maintain .
  * If you want to make an XML document for a particular topic from the wiki, please use the code I use and start a new document. (GPL).

This ensures (eventually) clean conversion to !DocBook XML and makes my work easy. :-)

----

If funny things happen, look for single quote repeats, etc. in wiki source.

Code sections marked as "{ { { \n } } }" without using spaces will cause XML export errors; thus, always use spaces around \n.

List export has <para> markup bugs; after conversion, review and correct them, please.

== Hints for tools to help updating this document ==

 * Public server: http://wiki.debian.org/DebianReference
 * You may create your own mirror: {{{http://localhost/Wiki/DebianReference}}}
 * See Makefile and use targets: diff gedit ...

Build scripts and xml sources are available via Git repository at:
 * {{{ssh://git.debian.org/git/users/osamu/debian-reference.git}}}
 * {{{git://git.debian.org/git/users/osamu/debian-reference.git}}}
 * http://git.debian.org/?p=users/osamu/debian-reference.git (for browsing) 

For example, this wiki page is converted step-by-step as follows:
 1. [http://wiki.debian.org/DebianReference/Test?action=raw wiki source in raw text mode]
 2. [http://people.debian.org/~osamu/pub/getwiki/en/test-all.en.xml Docbook XML (cover page)]
 3. [http://people.debian.org/~osamu/pub/getwiki/en/test.en.xml Docbook XML (contents)]
 4. [http://people.debian.org/~osamu/pub/getwiki/html/test.en.html HTML created from Docbook XML files]

== Examples ==

This section contains examples and scratch pad contents.

=== Table ===

Always assumes the first line is {{{<title>}}}, the second line is {{{<thead>}}} and the rest lines are {{{<tbody>}}} {{{<row>}}}s.  (hello)

|| Example of table 1 || ||
|| '''TITLE1''' || '''TITLE2''' ||
|| DATA 11 || DATA 12 ||
|| DATA 21 || DATA 22 ||

=== Special paragraphs ===

Here are examples of Wiki marking used.

/!\  {{{ /!\ }}}  for "Warning" (alert)

<!>  {{{ <!> }}}  for "Caution" (attention)

{*}  {{{ {*} }}}  for "Important" (star_on)

{i}  {{{ {i} }}}  for "Tip" (icon-info)

(!)  {{{ (!) }}}  for "Note" (idea)

{OK}  {{{ {OK} }}}  for "Note" (thumbs-up)

(./)  {{{ (./) }}}  for "Note" (check-mark)

=== Line foldings ===

line1 starting line break examples
line2 w/o space from previous line

line3 w 1 line space from previous line


line2 w 2 space from previous line



line2 w 3 space from previous line
line with ampersand & &amp;

=== Data for popcon data and package size ===

The calculated popcon and size can be checked at: [http://people.debian.org/~osamu/pub/getwiki/html/test.en.html#dataforpopcondataandpackagesize Data for popcon data and package size].

The following packages are referred in the main text.

|| List of packages whose popcon and/or package size were referred in the main text || 1 || 2 || 3 ||
|| '''package''' || '''popcon''' || '''package size''' || '''dummy''' ||
|| {{{gksu}}} || - || - || - ||
|| {{{screen}}} || - || - || - ||
|| {{{rutebook}}} || - || - || - ||

The following packages are meant to evaluate backup utilities.

|| List of packages possibly mentioned in the main text for backup || 1 || 2 || 3 ||
|| '''package''' || '''popcon''' || '''package size''' || '''dummy''' ||
|| {{{sbackup}}} || - || - || - ||
|| {{{amanda-common}}} || - || - || - ||
|| {{{amanda-client}}} || - || - || - ||
|| {{{amanda-server}}} || - || - || - ||
|| {{{cdrw-taper}}} || - || - || - ||
|| {{{par2}}} || - || - || - ||
|| {{{parchive}}} || - || - || - ||
|| {{{backup-manager}}} || - || - || - ||
|| {{{backup2l}}} || - || - || - ||
|| {{{backupninja}}} || - || - || - ||
|| {{{bacula}}} || - || - || - ||
|| {{{bacula-common}}} || - || - || - ||
|| {{{bacula-client}}} || - || - || - ||
|| {{{bacula-console}}} || - || - || - ||
|| {{{bacula-server}}} || - || - || - ||
|| {{{cdbackup}}} || - || - || - ||
|| {{{cedar-backup2}}} || - || - || - ||
|| {{{faubackup}}} || - || - || - ||
|| {{{flexbackup}}} || - || - || - ||
|| {{{mondo}}} || - || - || - ||
|| {{{afbackup}}} || - || - || - ||
|| {{{afbackup-client}}} || - || - || - ||
|| {{{afbackup-common}}} || - || - || - ||
|| {{{backuppc}}} || - || - || - ||
|| {{{boxbackup-client}}} || - || - || - ||
|| {{{boxbackup-server}}} || - || - || - ||
|| {{{chiark-backup}}} || - || - || - ||
|| {{{storebackup}}} || - || - || - ||
|| {{{keep}}} || - || - || - ||

The following packages are meant to evaluate office utilities.

|| List of GUI packages possibly mentioned in the main text for office || 1 || 2 || 3 || ||
|| '''package''' || '''popcon''' || '''package size''' || '''description''' ||'''type''' ||
|| {{{scribus-ng}}} || - || - || desktop page layout editor || KDE ||
|| {{{scribus}}} || - || - || desktop page layout editor || KDE ||

The following assorted packages are meant to evaluate inclusion to the main text.

|| List of assorted packages possibly mentioned in the main text || 1 || 2 || 3 ||
|| {{{traceroute}}} || - || - || Traces the route taken by packets over an IPv4/IPv6 network (included) ||
|| {{{tcptraceroute}}} || - || - || Traces the route taken by packets over an IPv4/IPv6 network using TCP SYN packets (excluded) ||

See http://wiki.debian.org/UTF8BrokenApps

=== Escape confusion ===

MoinMoin conversion bug for "{{{ \n }}}" needs to be worked around by placing space around it.

### srslash-n: {{{ \n}}} rslash-ns: {{{\n }}} rslash-n: {{{\n}}} : this

=== internal links ===

can be referred as @{@internallinks@}@ which will create correct reference in HTML.

 * All characters converted to lower cases.
 * 0-9 converted to a-j
 * Drop all special characters and spaces.  
 * For longer reference name, it trim center parts and make it first and last 16 characters each.  
 * See HTML link name as quick check after generation.
Do not use "{{{ [[Anchor(internalLinks)]] }}}" for now in the main text used by building final HTML files.  (It may be a good idea but you need to do it for entire document.)  

The normal anchor feature of MoinMoin wiki is not supported by the XML conversion tool now.