Erights:Editorial guidelines

From Erights

(Difference between revisions)
Jump to: navigation, search
(add guidelines I've been following)
(started section on code conventions)
Line 1: Line 1:
-
This site is intended to be an authoritative resource for the E language and object-capability security in general.  Please keep this in mind as you are editing.
+
This site is intended to be an authoritative resource for the '''''E''''' language and object capability security in general.  Please keep this in mind as you are editing.
-
 
+
-
Particularly, anything in [[:Category:E specification]] is draft material for the E language and library specification, and should be written with precision in mind. Including usage advice is encouraged, but it should be made reasonably clear whether a paragraph is normative or informative.
+
-
 
+
-
== Markup and templates ==
+
-
 
+
-
===General formatting===
+
-
 
+
-
{{XXX|Add more general guidelines here}}
+
-
 
+
-
Do not use monospace except when referring to snippets of E ''language'' syntax (or other languages).
+
-
In particular, when referring to variables such as in documenting a method, wrap them in <nowiki><var></nowiki> elements, '''not''' <nowiki><code></nowiki> or <nowiki><tt></nowiki>.
+
-
 
+
-
===Messages===
+
-
 
+
-
Whenever you mention a message (verb & arity), refer to it using the template <code><nowiki>{{</nowiki>msg|<var>verb</var>/<var>arity</var>}}</code>. This creates automatic cross-references. To refer to a verb with arbitrary arity, use <code><nowiki>{{</nowiki>msg|<var>verb</var>/*}}</code>.
+
== Code Conventions ==
== Code Conventions ==
Line 20: Line 5:
We are in the process of installing syntax highlighting for this wiki.  So the tags used to indicate code are not yet settled.
We are in the process of installing syntax highlighting for this wiki.  So the tags used to indicate code are not yet settled.
-
All wiki pages that contain code should pass [[Updoc]].  For now, this means that each page needs to have this near the top of the wiki source of each page:
+
All wiki pages that contain code should pass [[Updoc]].  For now, this means that each page needs to have this near the top of each page:
-
<nowiki>{{:Standard updoc prelude}}</nowiki>
+
-
which appears as the following text:
+
-
{| style="border: 1px solid black;" |
+
-
|| {{:Standard updoc prelude}}
+
-
|}
+
-
 
+
-
All updoc sections should be indented one space, to trigger <nowiki><pre></nowiki> formatting. Note that wiki markup is still permitted in such sections; it may be better to use <nowiki><pre><no</nowiki><nowiki>wiki></nowiki> in some cases.
+
-
 
+
-
=== Updoc Preludes ===
+
-
[[Standard updoc prelude]]
+
-
 
+
-
[[Standard updoc prelude for awt and swing]]
+
-
[[Standard updoc prelude for swt]]
+
<pre>
 +
? pragma.syntax("0.9")
 +
</pre>
-
[[Old 0.8 updoc prelude]]
+
You'll want to place the pragma line in a <code>&lt;pre&gt; ... &lt;/pre&gt;</code> section.

Revision as of 16:30, 10 December 2006

This site is intended to be an authoritative resource for the E language and object capability security in general. Please keep this in mind as you are editing.

Code Conventions

We are in the process of installing syntax highlighting for this wiki. So the tags used to indicate code are not yet settled.

All wiki pages that contain code should pass Updoc. For now, this means that each page needs to have this near the top of each page: 

? pragma.syntax("0.9")

You'll want to place the pragma line in a <pre> ... </pre> section.

Retrieved from "http://wiki.erights.org/wiki/Erights:Editorial_guidelines"
Personal tools
more tools