Documentation

One of the thing that non-coders can do is help with the documentation wiki. However, IIRC there’s still some uncertainty over the legal status of the PRMs and the official Style Guide. Is this any closer to being resolved?

If not, would there be any value in wikifying some of the core StrongHelp manuals for the ROOL website? AFAIK these are reliable (sometimes more so than the PRMs), and I would imagine that their content could be converted to a suitable format relatively easy, perhaps even automatically using a BASIC script.

Comments welcome. If people think it’d be a good idea, I’d be happy to look into it (though with the caveat that my time, like most people’s, is very limited).

Further to this, I’ve added a test page to demonstrate how things might look, cut and pasted from Castle’s RISC OS 5 documentation. Look for it in the PRMs page.

I’m no expert, but formatting tab stops and indents in Textile seems to be a real pain. I gave up, and used pre tags to format the SWI calls. This means tediously replacing tab characters with padded space characters, but at least it all lines up.

Also, how do I make asterisk characters visible (as in star-commands)? Textile thinks I want to make the text bold.

I’ve had a little play with Textile and have published some stuff under the Desktop section of the PRM’s. Have a little look and let me know if whats you envisage.

Obvioulsy I still have to do a lot of more work and a lot of tidying up, but hopefully its on the right track.

As for stars, apparently (I’ve not yet tried) you just use the html code ie. *

In addition, I will be happy to convert book 3 of the PRMs to the ROOL website. Are there any others who would be interested in tackling the others. A co-ordinated approach would probably be best to ensure consistent markup being used through out. eg. h3 for Main Headers, h4 for secondary headers, <’pre’> <’/pre’> for code inserts

and all the other things such as internationalizing the words used. ie Colour > Color, Standardisation > Standardization etc..

All stuff that needs to be considered.

Might I suggest that you put related articles in the same namespace, rather than polluting the global one with things like “Polling”, or “General principles”? Perhaps something like “WIMP:Polling”, instead.

Also, one assumes Castle have the PRM sources somewhere, seeing as they updated them when the 32bit C tools were released. It may be sensible to see if some kind of automated conversion of that is possible.

Might I suggest that you put related articles in the same namespace, rather than polluting the global one with things like “Polling”, or “General principles”? Perhaps something like “WIMP:Polling”, instead.

You are absolutely right about this. I’ll sort this out soon. I’ll also need to work out how to delete unwanted wiki pages, as the ones I just created will now need removing.

Sounds like there’s some interest in this, which is great. I’m happy to help out – I have a copy of the Castle PRMs, etc., and some professional experience as an editor.

Before putting anything else up on the wiki, I think we need to resolve the following:

1. The licence status of the print copies of the PRM, Style Guide, etc. Can ROOL advise on this? If the licence for the official documentation is restrictive (or uncertain), is there any mileage in my StrongHelp suggestion?

2. It would be wise to agree a format for the documentation pages before putting them up. As John-Mark says, we should agree on a consistent format for article namespaces/locations. We also need to agree a style guide for the individual pages (heading levels, etc.). FWIW, I think the pages Alan and I have put up look roughly right, but it would be good to get agreement on this before writing any more. I’d be happy to write a draft style guide to get the ball rolling, if people were happy?

3. Depending on the answer to [1], we need to decide on how to transfer the text into Textile. I’ll have a look at the Castle CD, but I assume it would be possible to automate the process, at least partially. Other more technically-minded people might be able to suggest something here.

Sounds like there’s some interest in this, which is great. I’m happy to help out – I have a copy of the Castle PRMs, etc., and some professional experience as an editor.

The more professional help in this area the better as far as I’m concerned. I’m sure your help will be invaluable.

1. The licence status of the print copies of the PRM, Style Guide, etc. Can ROOL advise on this? If the licence for the official documentation is restrictive (or uncertain), is there any mileage in my StrongHelp suggestion?

I know people have tried to get resolution from Castle in the past with no offical response in return. In the meantime, I think we should progress assuming we have the green light. If they (castle) inform us later that they do not want this available then we pull it immediately.

2. It would be wise to agree a format for the documentation pages before putting them up. As John-Mark says, we should agree on a consistent format for article namespaces/locations. We also need to agree a style guide for the individual pages (heading levels, etc.). FWIW, I think the pages Alan and I have put up look roughly right, but it would be good to get agreement on this before writing any more. I’d be happy to write a draft style guide to get the ball rolling, if people were happy?

100% agreement from me. Go for it, and perhaps we can put a few possible Style examples up on the wiki for developers to give us feedback on which ones they prefer. After all they are our customers at the end of the day, so makes sense we get their buy-in.

3. Depending on the answer to [1], we need to decide on how to transfer the text into Textile. I’ll have a look at the Castle CD, but I assume it would be possible to automate the process, at least partially. Other more technically-minded people might be able to suggest something here.

I’ve already made a start on Book 3, copying and pasting and then using some VBA macros written in MS Word to convert some things, but I’m sure there is probably a much slicker way of doing it.

[other thread] 1) I know the Documents section isn’t fleshed out yet and people are working on it but I hope there will be emphasis in there regarding the Style Guide. I know that things have changed a little since it was written but it still forms the foundation for the way things should be IMO and I think we should only tinker with it slowly and carefully.

Ah the infamous Style Guide. I’m also very interested in this particular area – I love GUI’s, design, functionality, look, feel – everything about them.

It’s been an area that has been neglected since the early 90’s – and it shows, so there is plenty of room for improvement. However, small steps in the right direction is probably the best way forward as you say.

Chris, when you edited the wiki earlier, did you have a problem with the ‘wiki info’ text overlapping the text area window? I was using FireFox 3.0.6 and it wasn’t a pretty sight.

We are speaking with Castle about the PRMs and other tomes; will keep you posted with developments as and when they come about.

On the documentation front – go for it! Also, there are individual wiki pages associated with the various pre-built released components. It would be useful if these could be fleshed-out a bit with relevant information by the more knowledgeable amongst you. Even if we some day change the format of our pre-built releases, it’ll still be useful to have wiki pages for each major component (Draw, !Printers, etc).

Chris if you want to contact me directly about the documentation project, please feel free to email me at

nytrex2001 at yahoo co uk

Justin Fletcher wrote some XSLT code to take the (ROL) PRMs as an XML document and transform it into other formats (wordprocessor, plaintext, HTML). Perhaps you could look at that as a starting point? That would make it easy to transform into whatever format you wanted (PDF, Textile, StrongHelp…). You could even automate the wiki upload.

See http://openags.cvs.sourceforge.net/viewvc/openags/AGProtocol/ and apparently there’s more to be found on the Select/Adjust CD. (Also google ‘risc os xslt’)

Msg for Chris, Have you managed to progress things on the documentation side of things?

I think some relevant discussions can be found in another thread now:

https://www.riscosopen.org/forum/forums/5/topics/190

Since reproducing the PRMs online seems to be out of the question for the moment (and out of this thread), what about putting together some plans for the stuff that isn’t in the PRMs? E.g. all the changes and additions made between PRM 5a and now. At the moment there are three sources of documentation for these – documents stored in CVS alongside the OS source code, the documentats Castle have published on the Iyonix developer website, and StrongHelp manuals (which may or may not be based on one or both of the above). None of these are guaranteed to be up to date any more, especially considering the recent official release of RISC OS 5.14.

Do ROOL have any plans on how to handle this documentation going forward? I’d assume it’s just all going to go onto the wiki? (And preferably into some stronghelp manuals too)

Having one centralised source for documentation would certainly be useful (e.g. finding out what HAL functions are meant to do can be a bit of a pain). And for each document written, it would be a good idea to go through the docs in CVS and mark any relevant docs as superceeded, and update any comments in source code (e.g. description of function arguments) to point to the wiki docs.

Ok not sure this is entirely the right place for this but it saves starting a new thread,

As someone new to ROOL and RISC OS programming in general where would someone start to look for information on programming for RISC OS and eventually been able to program the operating system itself?

Are there PRMs available for 5.xx or are the only PRMs available for 4.xx and 6.xx?

thanks Andrew

All PRMs for RISC OS 4, 5 & 6 are based very, very closely on the RISC OS 3 PRMS, which are available from www.riscos.com for a nominal amount of money (less than £10 in VAT).

RISC OS Select, which is a sucessor to RISC OS 4 has its additional bits available for free at http://select.riscos.com/prm/index.html

These should be read in conjunction with the RISC OS 3 PRMs to fully understand what is going on.

Alternatively, you could download a RISC OS software tool called StrongHelp and some of its Manuals detailing much of the PRMs. http://sudden.recoil.org/stronghelp/index.php

www.riscos.info is a website that has got lots of information and software that will help you get started programming on RISC OS too.

Hope this helps a bit.

Yes thanks i wasn’t sure if the RISC OS 3 manuals would be relevant but seeing as they are i will get and buy a cd.

Im no where near being ready to really do any programming on RISC OS yet i’ve only just done my first year computer science in which we did java which is not alot of use for RISC OS development so i need to read a couple of books on C and C ++ but i already have the dabhand guide to C.

Welcome to the wonders of RISC OS!

All the best with your Computer course.

Forgot to mention, if you decide you do wish to develop the RISC OS sources and compile them sucessfully, you currently need the C/C++ Tools CD.

Although this is a commercial product, you do get the RISC OS 5 PRMs with them, inlcuding Style Guide – I think.

So although initially more costly, it may be a better option in the long run…

Ye i was going to ask if the ROOL tools disk came with the PRMs, are the ones ROOL supplie updated with any RO5 bits or are they just the same as the RO3 PRMs?

The price of the ROL disk looks to be £30 from the form i found on there site so £50 to have the castle tools is not a lot extra.

The PRM’s on the ROOL supplied Tools CD comes with updated RISC OS 5 PRM’s (I believe). Some of it was also updated on the Iyonix website several years ago.

To put it bluntly, there is lots of documentation about, but its spread very thinly over a lot of ground at the moment.

Ultimately, if your going to do some coding with the RISC OS sources, then I think the ROOL Tools CD is the way to go. Everything you need to get started. :)

Andrew, according to Paul Middleton the ROL PRM CD is £6.50: https://www.riscosopen.org/forum/forums/5/topics/191

Jack says on that thread that the PRMs as supplied with Castle C are just a PDF dump of Acorn’s RO3 PRMs. My Castle C dates from 2003 and has just the RO3 PRMs… perhaps one of the ROOL folks can confirm, but I didn’t think RO5 PRMs existed as such – just the RO3 PRM PDFs plus the documents on iyonix.com. Since Castle just received a dump of PDFs from the original FrameMaker, I’m not sure that these would have been easy to update with the new material – and the only HTML PRMs I’ve seen are ROL’s (think these were FrameMaker’s HTML output with a lot of postprocessing).

Alan’s right though, if you’re going to do any coding you’ll need C/C++ and so the Tools CD is the best way to go.

Well i have found the pdf PRMs online with some googling (http://foundation.riscos.com/Private/index.htm) but as the ROL cd comes with html versions i will buy that for now as pdf’s don’t work very well on my ebook reader where as html files can be converted to a more useable format.

P.S. im not sure if the public are supposed to be able to browse that site as it say’s private in the address.

Question for the chaps at ROOL.

Can you clarify the legal position of the documentation at www.iyonix.com/32bit please.

Can we safely replicate the information on ROOL’s wiki, or is it in the same pot as the PRMs documents, and cant be copy’n’pasted?

It would be great if we could add the documents at iyonix.com to the ROOL wiki without having to re-write it all.

Cheers

As for stars, apparently (I’ve not yet tried) you just use the html code ie. &#42;

Or use ==*==.

Are any of the PRMs available in Strong Help format? !PDF (3.00.1.19) doesn’t seem to render any of the PDF versions correctly for me.