(Updated for article styles)
Revision as of 14:35, 21 May 2011
You should use an initial capital, then lower case, only capitalising those things that would normally be capitalised. For example, "Voice over Internet Protocol" and "Style guide"; not "Voice Over Internet Protocol", "Style Guide", or even "Voice over internet protocol". Instructions are always specified in upper case, i.e. LDR and AND, not Ldr and And.
There are two distinct number formats used on ARMwiki. They are:
- RISC OS style: Hex numbers are prefixed with an & and binary numbers are prefixed with a %.
This applies in all circumstances as RISC OS natively understands this format.
- Generic style: Hex numbers should be prefixed with "0x" (C-style).
It is suggested that you only use older formats ("$" prefix, "h" suffix, etc) if these are required in example code by a specific assembler.
User instruction and display
Commands and input that is intended to be typed by the user should be marked in bold typewriter style, thus the following:
<tt>'''arm-linux-gcc -o helloworld_tiny helloworld_tiny.s'''</tt>
looks like this:
arm-linux-gcc -o helloworld_tiny helloworld_tiny.s
Output that the user is expected to see on their screen should be marked in regular typewriter style.
If it is clear what is going on, you can include typed commands in display, as demonstrated in the following example:
~ $ wget http://azumi/helloworld_tiny
--2011-04-03 23:59:57-- http://azumi/helloworld_tiny
Connecting to 192.168.0.10:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 128 [application/octet-stream]
Saving to: 'helloworld_tiny'
100%[======================================>] 128 --.-K/s in 0.001s
Last-modified header invalid -- time-stamp ignored.
2011-04-03 23:59:57 (213 KB/s) - `helloworld_tiny' saved [128/128]
~ $ chmod 755 helloworld_tiny
~ $ ./helloworld_tiny
Hello World! :-)
Some things to note about the above example:
- You will need to use the <br> command to force newlines.
- If you have URLs in example code, replace "http:" with "http:" to defeat the wiki's attempts to convert the URL to a link.
Code samples, even if only one line, should be marked up in a highlight box by indenting with spaces. By convention, three spaces should be used.
For example (note further spaces are used for formatting):
[space][space][space][space][space]mov r0, #1 @ 1 = stdout
[space][space][space][space][space]adr r1, message @ pointer to message
entry: mov r0, #1 @ 1 = stdout adr r1, message @ pointer to message
Don't be afraid of whitespace. The two most important concepts at ARMwiki are accuracy and clarity. Sensible use of whitespace, linebreaks, etc, can aid clarity.
The Show preview button below the editor is free. Use it frequently to check everything is looking just as you want it to look.
Don't know how to implement something you see elsewhere on ARMwiki? Simply open that page in a new window (or tab) in your browser, then Edit or View source to see how it was done.
Phrases such as You should and I think are to be avoided, except in opinion pieces. Consider alternatives such as It is suggested...
Instruction definition layout
Instructions begin with a brief section that defines the purpose of the function, using a type 2 heading (==).
Following this, all as type 3 headings (===), should be the following sections:
- Syntax - gives a brief description of the instruction syntax in a code box for emphasis.
- Function - outlines what the instruction actually does, in a code box for emphasis. This is then followed by elaboration, notes if applicable, truth tables, and so on.
- Example - a brief example or two of the instruction itself in a code box.
- Concept code (optional) - little self-contained BBC BASIC programs that wrap the instruction in code to demonstrate how it behaves. Each program should be preceeded by a brief description.
BBC BASIC is used because there are numerous Archimedes system emulators (I use RedSquirrel), plus the ability to intertwine BASIC and assembler, thus making it an accessible way of providing working examples.
- Technical - provides the instruction bit pattern, and related notes, if any.
Please refer to AND for an example.
It goes without saying that you should only upload content you have written yourself, photos you have taken yourself, or content that you have permission to distribute.
It is perfectly acceptable to refer to reference material - I copied the bit pattern information from the relevant datasheets as I would imagine few people can remember such details - however whole-scale plagarising of content from other sources is a Bad Thing.
This is a user-contributed source, and as such it is difficult to patrol updates. If anything unkind is discovered, either edit it out yourself, or contact the administrator...