Oberon/Contributing

All progress is welcome. Correct errors in grammar and in algorithms. Present unrefined ideas in the talk pages.

A source in the wikibook can be edited directly using a browser capable of HTTPS. Alternatively it can be edited on an Oberon system, translated using MediaWiki.Markup and applied to replace the existing version, as when adding a new module. If replacing, take care to avoid over-writing a previous edit. The latest version of the page should be retrieved to a working Oberon system and compared using Diff.Do. Alternatively, a registered user can put a new version in the user sandbox and apply the MediaWiki comparison facility. Be aware that the non-zero time interval between retrieval from the book and installation of the new version allows edit conflict.

• Initialize a Module or Tool page from a published release. Preferably the latest. Oberon.Sort.Mod, for example, is taken from the Oberon subsystem in UnixA2. Indicate the source in the wiki edit subject line.
• Use Oberon naming conventions.
• Avoid page duplication. If two systems share a source module, a page redirect is preferable to duplicate pages.
• If an edit conflict is inadvertently created, fix it, please.
• Avoid breaking compilation.
• Avoid breaking interfaces. If an interface is changed, adjust all modules which connect to it. An idea clearly expressed in a discussion page is preferable to broken interfaces.
• Avoid breaking functionality.
• Avoid introducing a bug. If a bug is introduced, the change might be reverted, however brilliant the intended improvement.
• Prefer more recent syntax over older syntax. Remove LOOP. Where possible remove RETURN.

Addition of a Text is the first two steps in the dataflow diagram for a Text. The first step is performed by the contributor. The second is performed automatically by the MediaWiki server. Retrieve the MediaWiki module (ETH Oberon, Oberon subsystem of A2) to your Oberon system and compile it. Open a viewer with the module to be contributed and * mark the Text. Translate to MediaWiki markup with "MediaWiki.Markup * " and save the <Module>.Mod.mw with Edit.StoreAscii or ET.StoreAscii.

To add the page to the book, a browser capable of HTTPS is necessary; Desktops.OpenDoc in ETH Oberon is inadequate. Being logged in to a Wikimedia account is advisable. Somewhere in an existing page add the name of the intended page, preview and "Publish change". The new entry will be colored red. Click on it to open the new page. Initialize the new page, preview and "Publish change".

Formatting a Source Text

Various formatting conventions and preferences exist. Refer to the Oberon Mailing List, 2017-07-22 through 2017-07-26, and search for "indentation?". No particular format is essential. Any reasonable format preferred by a contributor is welcome.

Styling a Source Text

Various stylistic conventions also exist. Refer to the Oberon Mailing List, 2017-07-29 through 2017-07-30, and search for "Italicization". Editors such as PET in A2 and the "pretty printers" mentioned in the list automatically style a source Text to highlight syntax. Therefore direct syntax styling can be unnecessary. Color to distinguish a revision is optional and relatively harmless.