Difference between revisions of "WikEmacs:Guidelines"

From WikEmacs
Jump to: navigation, search
(Creating new pages)
(Creating new pages: fix link. Would be better to remove /index.php/ entirely from the URL!)
 
(40 intermediate revisions by 17 users not shown)
Line 1: Line 1:
Start with http://meta.wikimedia.org/wiki/Help:Wikitext_examples if you are new to MediaWiki markup.
+
'''How can we maintain and improve quality of this Wiki?'''
 +
* Stick to Emacs-24 and Emacs-23.
 +
* Keep things short and sweet.  Mark things that should stand out in '''bold'''.
 +
* Use [http://en.wikipedia.org/wiki/Active_voice Active voice]
 +
* Give tips. Document things that are difficult to find or share your wisdom.
 +
* Don't reproduce existing documentation. Instead link to them.
 +
* It's OK to write long tutorial Pages. Use '''Tutorial:Tutorial Namespace''' for it. Assign categories for easily finding the tutorial.
 +
* If you are a regular blogger, consider donating your articles to this Wiki.
 +
* For discussions, use the '''Discussion page''' instead of posting to the article pages. Sign your comments using  <nowiki>~~~~</nowiki>.
 +
* We cannot host code extensions and elisp packages here. Use [https://github.com GitHub] or similar code hosting site.
 +
* {{Note}} this is not a QA site. Emacs questions are better answered at [http://stackoverflow.com/questions/tagged/emacs Stackoverflow site]. However, if you have an answer to a good question or problem, add in the appropriate page.
 +
* '''Code snippets''' are most welcome. But comment about what precisely the snippet does. Document any limitations as well.
 +
 
 +
== Mediawiki Help ==
 +
* [http://meta.wikimedia.org/wiki/Help:Wikitext_examples Help with Mediawiki markup]
  
 
== Creating new pages ==
 
== Creating new pages ==
 
 
To create a new page, do this:
 
To create a new page, do this:
# Visit [http://wikemacs.org/w/index.php?title=Template:NewPage&action=edit Template:NewPage] and copy the text area to clipboard.
+
# Visit [http://wikemacs.org/index.php/Template:NewPage?action=edit Template:NewPage] and copy the text area to clipboard. Feel free to modify the template.  
 
# Goto [[WikEmacs:Scratch Buffer]]
 
# Goto [[WikEmacs:Scratch Buffer]]
 
# Add this <nowiki>[[Test Page]]</nowiki> and save the scratch buffer.
 
# Add this <nowiki>[[Test Page]]</nowiki> and save the scratch buffer.
Line 10: Line 23:
 
# Save the newly created page.
 
# Save the newly created page.
 
# Now you have a basic template which you can expand upon. Add content to the new page as you please.
 
# Now you have a basic template which you can expand upon. Add content to the new page as you please.
 
== General ==
 
 
* Articles should be geared toward the current and development versions of Emacs, 23 and 24 at time of writing. References to older Emacs releases should generally be avoided.
 
* Articles should not reproduce documentation already available from another source. Many packages and extensions are well-documented on their own project sites; and Emacs itself includes extensive documentation. Link to official documentation where possible.
 
* Comments and questions belong on the Discussion pages, not in articles themselves. Always sign your comments using  <nowiki>~~~~</nowiki>. This expands to your username (if logged in) and adds a timestamp. Unsigned comments make the discussion hard to follow.
 
* Extensions and packages will '''not''' be hosted here. If you are looking for a place to host your extension try [https://github.com GitHub] or one of the other many hosting / source control platforms out there!
 
  
 
== Templates ==
 
== Templates ==
 
+
There are templates defined for referencing ''variables'', ''function'', ''command'', ''keys'', ''manual'' etc.  Use them for uniformity.  See [[:Category:Templates]]. Each template page should describe how to use that template. A few common examples:
There are templates defined for referencing ''variables'', ''function'', ''command'', ''keys'', ''manual'' etc.  Use them for uniform experience.  See [[Special:UncategorizedTemplates]].
+
 
+
Some examples:
+
  
 
{| border="1" cellpadding="5" cellspacing="0" width="75%"
 
{| border="1" cellpadding="5" cellspacing="0" width="75%"
Line 29: Line 32:
 
!What you type
 
!What you type
 
|-
 
|-
| {{Command|apropos}} || <pre>{{Command|apropos}}</pre>  
+
| <h2>Headline text</h2>
 +
| <pre>== Headline text ==</pre>
 +
|-
 +
| {{Manual|emacs|Major-Modes|Major Modes}}
 +
| <pre>{{Manual|emacs|Major-Modes|Major Modes}}</pre>
 
|-
 
|-
| {{Function|search-forward}} || <pre>{{Function|search-forward}}</pre>
+
| {{CommandKeys|C-x C-f|find-file}}
 +
| <pre>{{CommandKeys|C-x C-f|find-file}}</pre>
 
|-
 
|-
| {{Variable|auto-mode-alist}} || <pre>{{Variable|auto-mode-alist}}</pre>
+
| {{Keys|C-x C-c}}
 +
| <pre>{{Keys|C-x C-c}}</pre>
 
|-
 
|-
| {{Keys|C-x C-c}} || <pre>{{Keys|C-x C-c}}</pre>
+
| {{Keys|C-x f|set-fill-column}}
 +
| <pre>{{Keys|C-x f|set-fill-column}}</pre>
 
|-
 
|-
| {{KeyBinding|C-x C-f|find-file}} || <pre>{{KeyBinding|C-x C-f|find-file}}</pre>
+
| {{Command|find-file}}  
 +
| <pre>{{Command|find-file}}</pre>  
 
|-
 
|-
| {{Manual|emacs|Major-Modes|Major Modes}} || <pre>{{Manual|emacs|Major-Modes|Major Modes}}</pre>
+
| {{CustomizeVariable|c-default-style}}  
 +
| <pre>{{CustomizeVariable|c-default-style}}</pre>
 
|-
 
|-
 +
| {{Snippet|(global-set-key (kbd "C-c c") 'org-capture)}}
 +
| <pre>{{Snippet|(global-set-key (kbd "C-c c") 'org-capture)}}</pre>
 
|}
 
|}
  
 
== Categories ==
 
== Categories ==
  
There are special categories defined for ''Operating system'', ''Emacs releases'', ''Programming languages'' etc. Use these when possible or introduce new ones as required. See [[Special:Categories]].
+
Special categories, such as ''Operating system'', ''Emacs releases'', ''Programming languages'', should be used to introduce new categories. See [[Special:Categories]].
  
 
[[Category:WikEmacs Contributor]]
 
[[Category:WikEmacs Contributor]]

Latest revision as of 22:33, 24 April 2013

How can we maintain and improve quality of this Wiki?

  • Stick to Emacs-24 and Emacs-23.
  • Keep things short and sweet. Mark things that should stand out in bold.
  • Use Active voice
  • Give tips. Document things that are difficult to find or share your wisdom.
  • Don't reproduce existing documentation. Instead link to them.
  • It's OK to write long tutorial Pages. Use Tutorial:Tutorial Namespace for it. Assign categories for easily finding the tutorial.
  • If you are a regular blogger, consider donating your articles to this Wiki.
  • For discussions, use the Discussion page instead of posting to the article pages. Sign your comments using ~~~~.
  • We cannot host code extensions and elisp packages here. Use GitHub or similar code hosting site.
  • Note Note: this is not a QA site. Emacs questions are better answered at Stackoverflow site. However, if you have an answer to a good question or problem, add in the appropriate page.
  • Code snippets are most welcome. But comment about what precisely the snippet does. Document any limitations as well.

Mediawiki Help[edit]

Creating new pages[edit]

To create a new page, do this:

  1. Visit Template:NewPage and copy the text area to clipboard. Feel free to modify the template.
  2. Goto WikEmacs:Scratch Buffer
  3. Add this [[Test Page]] and save the scratch buffer.
  4. Click on the new Wiki link to create a blank page and paste the contents of clipboard there.
  5. Save the newly created page.
  6. Now you have a basic template which you can expand upon. Add content to the new page as you please.

Templates[edit]

There are templates defined for referencing variables, function, command, keys, manual etc. Use them for uniformity. See Category:Templates. Each template page should describe how to use that template. A few common examples:

What it looks like What you type

Headline text

== Headline text ==
Major Modes (`(info "(emacs) Major Modes")')
{{Manual|emacs|Major-Modes|Major Modes}}
[C-x C-f] (or M-x find-file)
{{CommandKeys|C-x C-f|find-file}}
[C-x C-c]
{{Keys|C-x C-c}}
[C-x f]
{{Keys|C-x f|set-fill-column}}
M-x find-file
{{Command|find-file}}
M-x customize-variable RET c-default-style
{{CustomizeVariable|c-default-style}}
(global-set-key (kbd "C-c c") 'org-capture)
{{Snippet|(global-set-key (kbd "C-c c") 'org-capture)}}

Categories[edit]

Special categories, such as Operating system, Emacs releases, Programming languages, should be used to introduce new categories. See Special:Categories.