Style guide

From ARMwiki
Revision as of 12:15, 8 August 2012 by Admin (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Contents

Naming pages

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.

Number formats

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&#58;" to defeat the wiki's attempts to convert the URL to a link.

Code samples

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]entry:
[space][space][space][space][space]mov     r0, #1                  @ 1 = stdout
[space][space][space][space][space]adr     r1, message             @ pointer to message

looks like:

  entry:
    mov     r0, #1                  @ 1 = stdout
    adr     r1, message             @ pointer to message

Assembler support

The officially supported assemblers are, in order of preference, are:

  • RISC OS 'objasm' [quick test, uses ';' for comments]
  • RISC OS BBC BASIC [quick test, looks like BASIC!]
  • GNU assembler [quick test, uses '@' for comments]

Other formats can be used, but these should be clearly marked as to which compiler the code relates.

Whitespace

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 before saving the page (because lots of save/modify will show up in the revision log).

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.

Language neutrality

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.

Rights

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.

Liability

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...

Personal tools
Namespaces

Variants
Actions
Navigation
Contents
Toolbox