Difference between revisions of "WikEmacs:Guidelines"

From WikEmacs
Jump to navigation Jump to search
m (→‎Templates: example of {{Manual}} with different 2nd and 3rd args)
m (clean)
 
(51 intermediate revisions by 20 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 the current and future versions of Emacs.
 +
* 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 the [http://emacs.stackexchange.com/ Emacs-specific StackExchange site] or on [http://stackoverflow.com/questions/tagged/emacs Stackoverflow]. 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.  
  
−
== General ==
+
== Mediawiki Help ==  
 +
* [http://meta.wikimedia.org/wiki/Help:Wikitext_examples Help with Mediawiki markup]
  
−
* 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.  
+
== Creating new pages ==
−
* 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.  
+
To create a new page, do this:
−
* 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.
+
# 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.  
−
* 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!
+
# Goto [[WikEmacs:Scratch Buffer]]
 +
# Add this <nowiki>[[Test Page]]</nowiki> and save the scratch buffer.
 +
# Click on the new Wiki link to create a blank page and paste the contents of clipboard there.
 +
# 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.
  
 
== 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 [http://wikemacs.org/wiki/index.php?title=Special%3AAllPages&from=&to=&namespace=10 Templates].
 
−
 
 
−
Some examples:
 
  
 
{| border="1" cellpadding="5" cellspacing="0" width="75%"
 
{| border="1" cellpadding="5" cellspacing="0" width="75%"
Line 19: 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>
 +
|-
 +
| {{CommandKeys|C-x C-f|find-file}}
 +
| <pre>{{CommandKeys|C-x C-f|find-file}}</pre>
 +
|-
 +
| {{Keys|C-x C-c}}
 +
| <pre>{{Keys|C-x C-c}}</pre>
 
|-
 
|-
−
| {{Function|search-forward}} || <pre>{{Function|search-forward}}</pre>
+
| {{Keys|C-x f|set-fill-column}}
 +
| <pre>{{Keys|C-x f|set-fill-column}}</pre>
 
|-
 
|-
−
| {{Keys|C-x C-c}} || <pre>{{Keys|C-x C-c}}</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]]

Latest revision as of 15:32, 8 March 2019

How can we maintain and improve quality of this Wiki?

  • Stick to the current and future versions of Emacs.
  • 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 the Emacs-specific StackExchange site or on Stackoverflow. 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

Creating new pages

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

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

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

Retrieved from "https://wikemacs.org/index.php?title=WikEmacs:Guidelines&oldid=50847"