RISC OS User Guide PDF

ROL may have commisioned an update for the RO4.02 release (I could have a dig, as any accompanying CD content will be in the same cupboard (of doom as Vince says)

Don’t go digging on my account; personally I don’t want to see any ROL documentation if I’m potentially going to update some of the manuals – if I haven’t seen them then there is no (real or imagined) chance of me putting ROL text into non-ROL docs.

I’ve moved the first chapter and a half into a more maintainable format but I suspect that actually updating the content will be the tricky bit :)

User Guide History:
Acorn wrote the RISC OS User guide in a Mac? format Then for RISC OS 3.7 they converted it to HTML. The screen shots were almost unreadably low res.
ROL managed to get from E14/Pace a copy of the original Mac? document and generated an HTML version using a different? (Certainly better quality) HTML generator. So ROL have the copyright for ‘their’ HTML version.
Unfortunately neither ROOL or Castle have been able to find a copy of the original Mac? version.

Unfortunately neither ROOL or Castle have been able to find a copy of the original Mac? version.

Probably not worth going back to the source file as the format wasn’t brilliant and the updates would change various aspects.

Chris M. If you want to hammer a rough draft my way I can run it through my technical critical facilities and might persude the proof reader other half to take read through for the human side.
One thing that occurs to me is that I could probably usefully pull the text of the RO3.7 version and the RO4.02 version (if I can find both) and then do a “diff”

Some work has been done on updating it (See earlier in the thread) Bernard Boase is co-ordinating it. So to avoid duplication I suggest contacting him. If you don’t have/can’t find his email address send me an email and I will forward it. chris@cjemicros.co.uk

Hm, might be worth to have a look at RISC OS 6 User doc for inspiration and to crosscheck for changes that may have occured since RO4.02 that we may not think about directly.

Some work has been done on updating it (See earlier in the thread) Bernard Boase is co-ordinating it.

Things had gone rather quiet. That being either an indication of someone deep in the job or someone with too much other stuff to do.

It does indeed sound like one of those!

I suppose a key difference between my “version” (if I ever go through with it) and Bernard’s is that I intended to make a paged (probably PDF) document instead of HTML. Having said that, the content is probably the tricky bit so making an HTML version should be fairly simple.

It’d be interesting to see a “diff” of the same document updated by two different people; we could potentially each catch different new features. But I’m not committing to anything at this stage :)

I’m sure there isn’t enough man power available to do two updated versions. Why not get involved in the existing effort? New blood might be just what it needs to move it forward.

Re-reading my post, I didn’t word it well at all. I didn’t mean to suggest that I’d actually do it, but just that the results would be interesting (to clarify, the small amount that I have done was before finding this thread).

At this stage I’m just going to wait for a little while and see whether Bernard notices this thread (nothing wrong with a little patience) before reaching out.

Chris Evans has now alerted me to this thread (where on earth was I?). Yes, despite many distractions, it is still my intention to press on with the User Guide as described here above.

Any offers of help are gratefully received, in particular offers to take a chapter, any chapter, and recast it in HTML (to some standards I’ve listed) and bring its content up to date if need be. Drop me a line at bernardboase at gmail dot com and we can discuss topics and assign tasks.

and recast it in HTML

Would it not be better to recast it into some more generic format like XML, using subject-specific semantic markup and not just what HTML offers, then convert that into HTML or whatever other formats might be required (DDF, DDL or similar for printed copies, plain text, etc) each time a new version is required?

Bernard, don’t worry about not seeing this earlier; as is typical I suddenly became very busy after my earlier posts! I’m not sure when things will quieten down so it may be a week or two before I email you.

Regarding the format, HTML may not be the best choice, although it’s certainly better than nothing. Before finding this thread I envisaged a PDF following similar conventions to the manuals included with the DDE. Here is a sample of what I had in mind (it’s lacking images and I haven’t actually updated much of the content). It would certainly be a good idea to have a “master” file that can output in multiple formats.

Would it not be better to recast it into some more generic format like XML

Yes, very likely (though some of our efforts have already gone into HTML pages).

My practical knowledge of XML is limited. Who here is experienced in designing a suitable DTD, for example? And then also in using XSLT (say) to create HTML: and paginated? Or to output in PDF?

All worth discussing, though whenever I get back to the project I expect to continue with HTML for the moment.

One popular format to create documentation in a output-format-independant way is DocBook. It is XML-based and is very flexible. We use it here at work to produce online help in JavaHelp format (which is basically HTML) as well as nicely-printable PDF. Not easy to use out-of-the-box though.

I envisaged a PDF following similar conventions to the manuals included with the DDE.

Nice example of a look-alike but, of course, the Acorn original had lots of images of icons and tabular layouts to make it accessible. Also, I wouldn’t myself start with Word under MacOS!

For images, I have standardised on PNG for screenshots, meunus, icons, etc. and had a go at using SVG for vector images (with <100% success in either creating them in Inkscape or having them mangled by Netsurf). I do think an online version of this work should be reliably displayed by Netsurf.

The chapter on Edit, for example, looks like this. The most observant will see that it attempts to simulate the original Acorn version, while now being slightly out of date describing 1.65 when 1.73 implements the standard ctrl-C and ctrl-V conventions.

Thus far, I have used Google Drive to put working drafts in a place which can be updated by others. Named volunteers have access to a separate Admin section for standards and the like.

I would add to my previous post about XML that, with everything in HTML on Google Drive, I can update locally on RISC OS or AnotherOS, have Google Drive automatically update itself, and immediately proofread what I’ve done in several browsers including, of course, Netsurf. This is proving a rather practical way of developing pages.

the Acorn original had lots of images of icons and tabular layouts to make it accessible.

I haven’t seen Acorn’s one. I’ve found scans of Welcome Guides and other documentation, but haven’t seen a User Guide yet. All I’ve seen is the HTML one that comes with 3.7.

Also, I wouldn’t myself start with Word under MacOS!

I don’t know what you’re talking about ;)

Seriously, Word wasn’t my first choice but I ended up giving it a go. It does make it semi-easy to make a “structured” document where I say “this is a heading” and it formats it appropriately, but it’s still a bit clunkier than I’d like.

The chapter on Edit, for example, looks like this.

That looks pretty good :)

I haven’t seen Acorn’s one. I’ve found scans of Welcome Guides and other documentation, but haven’t seen a User Guide yet. All I’ve seen is the HTML one that comes with 3.7.

The printed version looks almost identical to the HTML but the images are much better and fairly readable.
The Welcome and User Guides all have the same style.

I do wonder whether it might be easier to replicate some things (such as buttons) in CSS. Admittedly I haven’t tested this in NetSurf, but you should be able to do something like Click Me without having to take screenshots of everything.

It’s probably more compatible than SVG… but I may be overthinking things as usual :)

Can I just point out that we have the master FrameMaker copy right here. If anyone wants to get involved with updating this document, please get in touch with us and we can ensure the master version is updated – PDFs/HTML or whatever can then be generated from that.

we have the master FrameMaker copy right here. If anyone wants to get involved with updating this document, please get in touch with us and we can ensure the master version is updated

I could hardly object if anyone wanted to take that route. However, my original discussions with CJE suggested it was actually easier to start from available documents (printed and web based) and craft new HTML which could then become part of ROOL’s open source offerings, available for any enthusiast to update. The objective to keep things simple might not be so well served if the prime version were based on legacy formats, and usable versions on generalised conversion software.

It does mean, though, that printed output (such as the excellent Style Guide) will be harder to achieve, and couldn’t realistically be free. Alternatively, if someone can point us to software that can reliably convert HTML (which sticks to some standards largely set in CSS) with images, and paginate it, and keep hot links, into say PDF, that might add a useful download option.

The objective to keep things simple might not be so well served if the prime version were based on legacy formats, and usable versions on generalised conversion software.

I’d struggle to call FrameMaker a legacy format, it’s what many sensible companies use for writing large structured documents or manuals – for example the ARM ARM and any flight manuals from Boeing. With the Welcome guides that used to come with Acorn computers big chunks of text were common to several models, and you just slot in the machine specific sections, and the whole thing updates with correct page cross references, index, contents etc.

It can output HTML, PDF, book artworks with crop marks for the printing press. I see it does XML type stuff too, though I’ve not used the more recent versions myself.

Individuals can “adopt a chapter” and submit the text without markup, leaving it a simple job for an editor to apply the house style and capture any screen shots.

One thing to bear in mind with a User Guide, like all the other woefully out of date manuals, is that a certain amount of archaeology is involved figuring out what changed that might not be obvious at a glance and thus get missed out. For example !WhizzyApp might now load version 6 Whizz files which now supports 3D ray tracing, but look identical to the 1997 version from RISC OS 3.70.

FrameMaker isn’t a legacy format, but it isn’t an accessible one. The main problem with HTML is getting it into a printable format—printing to a PDF from a browser just won’t do (it’s quite common for text to be split in half vertically at a page break!)

To get text and images from HTML into printable form I would usually open the individual files in a word processor and copy from there into a master document open in the same WP. In my experience MS Word (on Windows) and LibreOffice (on any platform) will do this and will also import (and wrap) images correctly, Neither MS Word (Mac) nor TechWriter wraps images correctly; Pages ‘09 can’t open HTML files at all.

OK, FrameMaker is not legacy! My mistake. But I can’t help feeling that in our sphere that approach might be a bit like the proverbial sledgehammer. It’s only a little green nut that we’re trying to crack, and I still think an online resource is the best aim for now.

@Sprow’s comment about archaeology is, I admit, a principal reason why the endeavour takes time and makes it less attractive even to those who have volunteered effort. While drafting the chapter on SciCalc, for instance, Chris(121) was busy improving the shared source so the current version differs substantially from the original. As a side effect of my documenting this I was able to feed back some bug information!

If one really wants to print from an HTML original, I have found that Netsurf→Drawfile→DrawPrint→[Printer|PDF] works well since DrawPrint gives control of not splitting either text or images, plus you can add simple page numbers.

Adopting a chapter can still be done informally, as has already happened with drafts for chapters on The Command Line and Alarm. Anyone here like to offer their time and expertise?

Alternatively, if someone can point us to software that can reliably convert HTML (which sticks to some standards largely set in CSS) with images, and paginate it, and keep hot links, into say PDF, that might add a useful download option.

Just my tuppence here – I have never had satisfactory results going from HTML to anything that is page based. HTML has no concept of “pages”, so “printed” output generated from HTML usually looks it.

For my current needs, I am using Google Docs. There may be better options, certainly, but Docs has the advantage of being free, compatible with numerous devices, and can output in a variety of formats – including HTML and PDF. It is fairly simplistic (I don’t think it can do fancy stuff like master pages, different left/right page options, and multi-column text) but it is a heck of a lot better than HTML that has no concept whatsoever of any of these sorts of things… If I wanted complex layout, I’d use OvationPro (RISC OS / Windows) and output PDF. ;-)

Whatever the base format is chosen to be (I have no experience of FrameMaker), it should contain adequate data to be able to suitably and directly output all of the desired formats.

That said, you pretty much make this point yourself:

It does mean, though, that printed output (such as the excellent Style Guide) will be harder to achieve, and couldn’t realistically be free.

Why? Okay, printed output on dead trees wouldn’t be able to be free, but if a PDF was generated from the same master that generates the HTML, then you automatically have three options:
1, Provide HTML
2, Provide PDF
3, Provide a print-on-demand service (from the PDF original, or maybe some other filetype if it is more appropriate and is supported (PostScript, perhaps))
4, As a side effect, the data may be available in a form suitable for Kindle and/or other ebook readers; some can read PDFs directly, but often it is better to use a less structured format like mobi and let the device flow the text appropriately for the user’s chosen text size/spacing

Of course, I am mostly talking from my posterior quarters at this time as I have not yet made enough of a story to think about the joys of purchasing ISBNs and the like. One day…
(note to self – when I have these plot ideas at four in the morning, writing them down then would probably be better than mostly fuzzy memories hours later :-( )
What I do know is that as much as I might have liked the idea of writing in OvationPro and using PDFs, to do so would instantly cut out all of my potential market that would prefer to use an e-reader. They don’t tend to do PDF nicely. There are better options for such devices, once you abstract yourself away from “layout” in publishing terms and view e-readers as a sort of monochrome version of HTML. The ideal master format should be able to cater for all of these options without undue strife. I think Word, PDF, Text, and HTML output ought to have most bases covered… https://support.google.com/drive/answer/2423534?hl=en FrameMaker does this sort of stuff too: https://helpx.adobe.com/framemaker/kb/supported-file-formats-framemaker-10.html

Individuals can “adopt a chapter” and submit the text without markup, leaving it a simple job for an editor to apply the house style and capture any screen shots.

That’s where I was coming from with the comments about comparing versions with diff. As you point out there is more than one reason for any split effort being purely at a text content level.

Just as a pure text comparison I suspect that the ROL derived version has little if any difference from the Acorn derived version that accompanied RO3.6 and RO3.7¹ upon which a new version can be built.

¹ Which is quite important in the yah-boo-sucks discussions. Anything Acorn derived is “clean”