PRM font bounty

I don’t know about Acorn, but at ARM us tech authors did all have Framemaker installed on our PCs, yes. Mostly only one author would be working on any one document at any given time, but it is possible for different people to work simultaneously on different sections of the same document and merge later. I honestly don’t remember the details after all these years!

Was there no thought of using their own Arc machine?

These manuals were originally written and laid out using Adobe® FrameMaker® on UNIX™ machines.

Nobody would have believed if it said:

;-)

I’m not sure AcornDTP was up to it, Impression was but probably wouldn’t have been a contender after CC’s Impulse.

I also doubt whether the bounty will be big enough to buy many Framemaker licences.

FrameMaker 7 (the version the bounty specifies) seems to be fairly cheap on places like eBay. The latest version is likely to be expensive, but there’s probably no pressing need for a ‘modern’ version if the existing files are compatible with version 7.

FrameMaker 7 (the version the bounty specifies) seems to be fairly cheap on places like eBay.

Ah. Interesting, thanks. How cheap? Will v7 run on my MacMini? (64-bit Intel, late 2014.)

I could not find a cheap copy on e-bay – the cheapest I could find was £77.

That’s very cheap compared with full retail price.

That’s very cheap compared with full retail price.

Indeed it is, but as Chris implies, it’s too much for the likes of me for the amount of use I’d make of it, or for it to be worth a bounty getting several copies for several people who might all want to work on the docs.

I could not find a cheap copy on e-bay – the cheapest I could find was £77.

There was one for US$29 a couple of days ago but it’s gone now. I stopped looking after seeing that one, so didn’t realise that most of them were more expensive.

Will v7 run on my MacMini? (64-bit Intel, late 2014.)

No. Version 7 (which happened to be the last Mac version) needs OS 9, and newer versions are only for Windows. I actually still have an OS 9 machine (an iMac G3), but it’d probably be more ‘enjoyable’ to set up a Windows virtual machine instead of hunch over a 15" CRT. It’s OK for retro games but I can’t imagine doing actual work on it.

It seems to me that the fundamental question is whether we want to maintain the masters in Framemaker format.

I don’t have an opinion either way. I did use Framemaker almost 30 years ago (to write the specifications of the ASICs that I was commissioning), and I remember that even then it was a serious piece of software. It beat Word for Windows into a cocked hat. (WfW was still young – lots of people were still using the DOS version.)

If we were to transfer out, it could probably be done for one month’s subscription to the current version. But would that simply leave a harder maintenance job?

If we stay in, I don’t think it would be difficult to raise the £399 or whatever it is for a new copy. But who gets to use that new copy? It’s single-user. Unless it’s possible to set it up, with adequate security, on a server that someone else can use via RDP or even VNC. Not the most comfortable way of doing things.

It seems to me that the fundamental question is whether we want to maintain the masters in Framemaker format.

As evidenced by the “revised PRM” bounties, keeping the PRMs up-to-date is a big job. So if I were ROOL I’d be looking into how to make that job smaller, e.g. by putting the PRM masters in source control and allowing developers/users to submit updates via merge requests. There’ll still be some overhead for ROOL (e.g. ensuring the documentation is clearly worded), but if developers can update the PRM text at the same time as they submit the corresponding code then things should become much simpler.

I’ve got no idea of the practicalities of doing this using Framemaker (how source control-friendly are the files?) – but since enough people already complain about having to buy the DDE to work on the OS, I can’t say that there’d be too happy if they find they also need to buy Framemaker in order to keep the documentation up to date.

One option could be to identify an open format which can (relatively) easily be imported by Framemaker. The open format could be used to directly generate HTML/markdown versions of the PRMs for the online versions, and periodically (for each stable OS release?) imported into Framemaker & tidied up in order to create the print/PDF versions.

whether we want to maintain the masters in Framemaker format.

Yes, no, maybe.

Logically it would make sense to transition to an non proprietary format (and fonts), but remember the size and scope of the PRMs. The need to do the conversion doesn’t just mean pasting the text in place and adding images, all of the styles need to be applied, and then the entire text checked to ensure page references are correct (though this seems like something a macro ought to be able to cope with?).

But would that simply leave a harder maintenance job?

As opposed to “only certain people can edit it, if they have the right software”.

There was one for US$29 a couple of days ago but it’s gone now.

Just looked at eBay for v7 Windows. There are a few. Change the $ to a € and then add a zero to the price. Then it’s more like reality.

I’m not sure AcornDTP was up to it

Urine was being extracted. ;-)

I actually still have an OS 9 machine (an iMac G3)

I have one in the shed. Never really found anything useful to do with it, and the mouse was horrible.

We should separate the goals better, to make up our minds and discuss possibilities further.

The “we can’t release the docs for free” problem – I understood from Steve’s presentation at the Wakefield Show that this is a font licensing problem. IMHO, it is absolutely essential to provide the PRMs as well as the BASIC manual, the User Guide and whatever I forgot at the moment as a free PDF download. Forget about the need to update things, the first goal is to make available what is already here.

The “we want to produce a new unified up-to-date documentation” problem – there might be some merit in keeping doing that inside the current master copy in Framemaker, but then it is a one-man thing with very little collaboration possible.

The “we want it all” wish list – having an up-to-date PRM (and User Guide and BASIC manual and…), constantly evolving with the OS (and carrying clear indications when things got changed/added), versioned in Git, allowing collaboration in the same way as the RISC OS source code. I would suggest to go open-standard here – export the current state of things from Framemaker into whatever-format-can-be-easily-transformed-further (probably some XML stuff), convert it into something that is currently state-of-the-art for such documentation (AsciiDoc, DocBook, DITA), put it into Git and set up a toolchain to produce various output formats like HTML, PDF, ROOL-Wiki-Textile and StrongHelp just like the Nightly Build for the rest of the OS is done.

The last option might sound complicated, but unless you aim for e.g. a PDF visualization that exactly matches the current PRMs, you can always start with the out-of-the-box styling of AsciiDoc-DocBook-FOP, so you “just” need to translate whatever Framemaker exports into a semantically equivalent representation. Maybe someone with the right version of Framemaker could export one of the PRMs into various formats so we can have a look how feasible that plan is?

The “we can’t release the docs for free” problem

Both ROOL and ROD can release the documents for free and have done so. It is third parties that cannot.

and whatever I forgot at the moment

You mean the Style Guide – it is often forgotten.

the first goal is to make available what is already here

At present we have most of the manuals available as PDFs on free to download distros (quoting Archive issue 25:3), note that the RISC OS User Guide is now the 2018 version and is thus ‘up to date’, not the 2016 draft as shown:

plus the BBC BASIC Reference Manual from the ROOL download tab

The BBC BASIC VI Manual is available here

PRM Volume 1 here

PRM Volume 2 here

PRM Volume 3 here

PRM Volume 4 here

PRM Index here

I don’t think the bounty is quite big enough to cover converting it to be an ODT file.

I think that a MIF file translator would be useful if ROOL wish to persist in using Framemaker

Of course the alternate would be to export as HTML and allow someone(s) with spare time to work on a cleaner and more up-to-date version

Of course the alternate would be to export as HTML and allow someone(s) with spare time to work on a cleaner and more up-to-date version

Who can offer an informed opinion on the relative difficulty of editing HTML versus using Framemaker?

PRM Volume 1 here

Uh huh. I think pointing to 4corn as a source of PRMs in PDF format actually pretty much makes the point.

I think that a MIF file translator

My brain snuck an errant L into that acronym, which led to a complete parse failure.

That’s it. I’m too tired. Going to bed n……..

I haven’t looked at MIF but Wikipedia reckons that it’s human-readable.

MIF (Maker Interchange Format) is a markup language that functions as a companion to FrameMaker. The purpose of MIF is to represent FrameMaker documents in a relatively simple, ASCII-based format, which can be produced or understood by other software systems and also by humans. Any document that can be created interactively in FrameMaker can also be represented, exactly and completely, in MIF.

Theoretically this would allow contributors to edit the documentation text without needing a copy of FrameMaker. Any formatting or structure changes might be more complex, but I’d imagine that basic editing wouldn’t be too much harder than editing HTML.

Annoyingly I can’t find an example MIF file to see what the ‘real world’ syntax looks like.

Who can offer an informed opinion on the relative difficulty of editing HTML versus using Framemaker?

You can’t really compare those things. Framemaker is a professional, hence expensive, documentation tool. In many ways it’s ideal for this sort of thing because it is designed for long and complex documents and handles all the indexing and cross-referencing and other things you need for doing big books. You can also generate HTML out of it as well as PDFs.

While it’s conceivable that you could export it all into something else and somehow generate equivalent documents, that’s probably a far bigger task than the more useful job of sorting out the 20+ years of neglect that the bounty envisages.

It would be nice if the bounty work could also make the process of contributing edits easier and more visible, as Jeffrey suggested earlier – that would be a bonus if feasible.

Who can offer an informed opinion on the relative difficulty of editing HTML versus using Framemaker?

You can’t really compare those things. Framemaker is a professional, hence expensive, documentation tool.

Spot on.

There’s also the question of What HTML. HTML can be dead easy to edit – if it’s reasonably simple, human-generated HTML. Or it can be a totally impenetrable tangle, if it’s generated from a source in some other software package. Such as for example, FrameMaker.

I haven’t looked at MIF but Wikipedia reckons that it’s human-readable

HP PCL4 is human¹ readable, assembler similarly.

Annoyingly I can’t find an example MIF file to see what the ‘real world’ syntax looks like.

Even more annoyingly, there’s someone who ghosts in and out of these forums that could generate one for you/us. Plus a collection more with useful content.

I was merely pointing out what I considered a good idea – I didn’t expect anyone to actually do something and give people here a chance to do more than talk about it.

¹ Just be careful to define the human

I think pointing to 4corn as a source of PRMs in PDF format actually pretty much makes the point.

ROL withdrew the link to the PDFs that was on the wayback machine and this was the only link I could still find working. So blame ROL.