Erights:Editorial guidelines

From Erights

(Difference between revisions)
Jump to: navigation, search
m (Reverted edits by Kb9Aad (Talk); changed back to last version by Kevin Reid)
(add guidelines I've been following)
 
(13 intermediate revisions not shown)
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 6: Line 21:
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 the wiki source of each page:
-
<pre><nowiki>
+
<nowiki>{{:Standard updoc prelude}}</nowiki>
-
{{:Standard updoc prelude}}
+
which appears as the following text:
-
</nowiki></pre>
+
{| style="border: 1px solid black;" |
-
which appears as the text between the horizontal bars below. (If you know of a better way to delimit this, please do.)
+
|| {{:Standard updoc prelude}}
-
----
+
|}
-
{{: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.
-
Further updoc passages should appear within a <code>&lt;code&gt; ... &lt;/code&gt;</code> section. It seems the lines between &lt;code&gt; tags need to be indented so that they'll be rendered into html with &lt;pre&gt; tags.
+
-
== Updoc Preludes ==
+
=== Updoc Preludes ===
[[Standard updoc prelude]]
[[Standard updoc prelude]]

Latest revision as of 17:32, 25 February 2011

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.

Contents

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 <var> elements, not <code> or <tt>.

Messages

Whenever you mention a message (verb & arity), refer to it using the template {{msg|verb/arity}}. This creates automatic cross-references. To refer to a verb with arbitrary arity, use {{msg|verb/*}}.

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 the wiki source of each page:

{{:Standard updoc prelude}}

which appears as the following text:

The following line

? pragma.syntax("0.9")

declares to updoc that further updoc passages on this page are in E 0.9 syntax.

All updoc sections should be indented one space, to trigger <pre> formatting. Note that wiki markup is still permitted in such sections; it may be better to use <pre><nowiki> in some cases.

Updoc Preludes

Standard updoc prelude

Standard updoc prelude for awt and swing

Standard updoc prelude for swt

Old 0.8 updoc prelude

Personal tools
more tools