PRM font bounty

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

There’s some 20 year old samples here

It doesn’t look great for manual editing, it’s really designed as an interchange format for tools that can convert from one format to another.

Maybe having some sort of tool that could convert to/from a Wiki or more textual format (Markdown?) would be a better way to allow people to contribute without needing specialist software?

As far as the PRMs are concerned, I think the work lined up for the bounty is going to need doing first though.

Both ROOL and ROD can release the documents for free and have done so.

If I understood Steve’s explanations correctly, they can only do so in very limited form. They cannot currently provide free downloads for all – at least, I cannot find the PRMs anywhere here, and there must be a reason for this.

This is why I said:

IMHO, it is absolutely essential to provide the PRMs … as a free PDF download.

It might well be that there are some strange sources available from somewhere else, which may accidentially or deliberately distribute the PRMs. This is NOT the way to handle this.

Your overview is interesting, but ePic certainly does not qualify as “free”, so misses my point entirely. And promoting a 1 GiB download like RODirect as a source of documentation, which contains an IMG file (i.e. nothing that can be easily accessed) is certainly a joke?

So it sounds like there are two separate issues:

First, making the extant PDFs releasable with suitable fonts. I suggest this is done as Druck suggests by extracting the font from the current PDFs, pulling out the ‘metrics’ (ie the width and height of each character), and modifying an open source font to match the metrics. The font can then be patched back into the PDF. The position of each character on the page stays the same, but the look of each character changes a little. This is the way that Homerton, Trinity, Corpus etc were originally designed – they have the same metrics as Helvetica, Times and Courier but slighty different glyph shapes to avoid Adobe copyrights.

Anyone with font editing skills who might be up for this? It’s probably a few hours work in a font editor – the awkward part will be pulling apart and repatching the PDF (I’m sure there are Linux tools to do this, as well as commercial programs like Acrobat.)

Secondly, a longer term maintainable PRM. For this I’d suggest embracing Gerph’s PRMinXML work
While I was searching for this I came across a Gitlab issue that suggests he’s been working on this more recently. Not wanting to tread on his toes or cause him support burden, but I’d suggest this is the most developed existing solution. (I don’t know if the XML files developed during his time at ROL would be available at this point, but if so a lot of the work is already done)

From the XML can then be generated PDF, HTML, StrongHelp and maybe epub and even header files along the lines of OSLib. It can also be configured with a commit-hook on the gitlab server, so that committing a change to the documentation regenerates all of the above automatically. This means it doesn’t depend on an ‘author’ pushing out PDFs manually and so they’re always up to date.

I’m not sure about other, less regimented, documents like the user guides. Possibly the PRMinXML structure would be sufficient, or maybe more layout input would be needed (eg with lots of images).

Secondly, a longer term maintainable PRM. For this I’d suggest embracing Gerph’s PRMinXML work

I hadn’t come across this before, but I see he’s published some tools for it at https://pyromaniac.riscos.online/technologies.html

Something like that’s potentially a good option, but someone still needs to do all the work of getting the data into the right format and working out or writing the convertors required to generate all the formats required. That’s a pretty sizeable task.

the awkward part will be pulling apart and repatching the PDF

Is this necessary?

Wouldn’t it be possible to make a copy of the Framemaker document, load it up, change the master font, then fart out a new PDF without the encumbered font within?

Ah, thanks, I hadn’t spotted that.

The PRMinXML download already contains convertors to HTML, StrongHelp and Impression. From one of those could be produced PDF. I’m not clear of its status in the ROL/ROOL/ROD saga, but Gerph worked on this for ROL and presumably (some of) the PRM already exists in XML form. Perhaps he can comment?

Extracting from Framemaker is something ROL did (they made an HTML version of the PRM) but in the worst case it could be done again and (re)converted to XML. Maybe Gerph has the scripts for this, if the original XML is still copyright ROL?

Wouldn’t it be possible to make a copy of the Framemaker document, load it up, change the master font, then fart out a new PDF without the encumbered font within?

That presupposes having a copy of a) the Framemaker document and b) a suitable version of Framemaker that can load and export it. I don’t know how easy that is, but it seems like nobody has done it as yet.

I am a little bit curious, the PRMs are not the first manuals that have been updated, we have the Style Guide and the User Manual. So how did they proceed then and why can’t we reuse the same method?

I am a little bit curious, the PRMs are not the first manuals that have been updated, we have the Style Guide and the User Manual. So how did they proceed then and why can’t we reuse the same method?

The User Guide was – IIRC – updated in the same fashion as is now proposed by the PRM update bounty.

The Style Guide was only very lightly updated – some explanations about later RISC OS versions, a word about UTF-8, updated URL for resource allocations, Alpha transparency sprites naming conventions, the Theme manager, the nested WIMP. So certainly a good update, but still using the good old !Edit screenshots. There are still interesting recommendations there like “The minimum suggested configuration to support is a 4MB machine running RISC OS 3.10 or later”. And wouldn’t it be great if we could have a diffable format to see what has actually changed.

Someone who downloads the Style Guide and reads it to the last page will probably wonder why he should send comments to ctools@riscosopen.org and how to cut out the Reader’s Comment Form with his PDF reader.

The problem I see is that to update the PRMs as planned is two orders of magnitude more complicated and extensive. And if this is done via one “Gatekeeper” who is the only one with access to Framemaker, it might be a non-starter.

I may be being naive here, but it seems to me that the most effective route would be for one person with one copy of Framemaker to export the content into a format that can either be used directly as an editable source, or which can be further converted into something that can be edited using easily available tools, and by more than one person at once.

Then there are two parts to the edits:

1: Tidy up the page breaks and fix the cross-references in the converted document

2: correct, update and add to the content.

As an Ovation Pro user, it seems to me that OPro plus some existing applets (cross refs for instance) could do the job. There must be a significant pool of people with OPro who could at least tackle step 1. There are tools to create HTML from OPro, and PrintPDF or PS3 plus ghostscript could produce the PDF versions.

Step 2 needs knowledge of the internals, but the people with that knowledge will be needed whatever route is used.

That presupposes having a copy of a) the Framemaker document and b) a suitable version of Framemaker that can load and export it.

We already know both exist, because PRM bounty…

As an Ovation Pro user

While I would love to be a cheerleader for OvationPro (another happy user), wouldn’t it be better if – assuming we’re going to change the format (and that’s a very big if) we aim for a cross platform non-proprietary format?

Is there anything up to the job? Some sort of ODT supporting DTP package that could handle a book running to four volumes of many hundreds of pages each, and not get lost?

Is there anything up to the job?

I suspect that was a rhetorical question, but in case it wasn’t: NO, not really. Not if you expect to keep all the indexing, contents table generation, and cross-referencing one expects in a document like this. LibreOffice is the nearest contentder, and much as I love it, it Ain’t FrameMaker.

I suspect there might be other commercial packages, but I very much doubt there’s anything affordable.

While I would love to be a cheerleader for OvationPro (another happy user), wouldn’t it be better if –

We had an applet that could import/export MIF ?

It doesn’t look great for manual editing, it’s really designed as an interchange format for tools that can convert from one format to another.

You’re right about that! Tag soup :(

Some oil for this fire: https://github.com/dpt/PatchedPRMs

I suspect there might be other commercial packages, but I very much doubt there’s anything affordable.

Latex can handle it. But then it’s Latex.

More seriously there are a number of documentation generation systems including Sphinx (often hosted on ReadTheDocs), DocBook, and others. Once the information is in a machine readable form then any of these are possible options.

But the main thing is to have input which is machine readable. Formats like OvPro, LibreOffice aren’t amenable to concurrent editing nor are they to generating other forms of information like HTML or StrongHelp. They’re just a word processor and don’t understand anything about what the words mean, so can’t index, crossref, or be automatically processed. Every time they’re updated it’s a manual process to regenerate things. And if we know anything, there hasn’t been anyone to update the PRMs in 25 years so it seems unlikely a manual process can be maintained.

@David Interesting the amount of manual hackery you had to do at ROL, and disappointing it might have to be done again :(

You’re right about that! Tag soup

Sounds like a.n.other markup format to me

And if we know anything, there hasn’t been anyone to update the PRMs in 25 years, so it seems unlikely a manual process can be maintained.

I don’t think that’s quite accurate. Just a couple of additions to make it true:

And if we know anything, there hasn’t been anyone with access who was willing to update the PRMs in 25 years, so it seems that some people would need access, or it remains unlikely a manual process can be maintained.

Does that sound more accurate to everyone?

Hey, let’s have an Open Source OS so that everyone can update it (with usual restrictions on altering the main branch)

Let’s hide the documentation away so only one over-worked nominee can alter/update it.

I suspect there might be other commercial packages, but I very much doubt there’s anything affordable.

I said it on page 1 of this thread, there are readily-available, completely free toolchains that are more than up to the job. At work, multiple authors produce documentation that is far bigger than the PRMs (and they do so for more than 15 years now), the largest of the many books has 1500 pages of PDF, everything is beautifully layouted and has changed its base layout for various reasons multiple times during the years.

All is based on DocBook (currently version 4), so you produce HTML (or something more restricted like JavaHelp for the online help of our software products), PDF or whatever-format-you-care-to-write-an-XSLT-for from a single source. I cannot see anything in the PRMs that requires anything more complicated than DocBook. Nowadays, you would probably use AsciiDoc instead because it is much easier to write in your favourite plain text editor. Converting from AsciiDoc to DocBook is trivial, multiple tools exist.

So it all comes down to convert from something Framemaker can export to any of those input formats. While content contributors can then start immediately to produce content, other people can optimize the layouting to match the PRMs as closely as wanted.

As David Thomas has written above, it was even possible to work with HTML produced by a cut-down version of Framemaker to do the job (and even produce something that WebsterXL could render, which is an extra layer of difficulty…). So the ROOL Framemaker version with a sensible export format chosen should be a lot easier.

I would volunteer to write a StrongHelp-producing backend.

So it all comes down to convert from something Framemaker can export to any of those input formats. While content contributors can then start immediately to produce content, other people can optimize the layouting to match the PRMs as closely as wanted.

Exactly.

Stumbling block being the will to do the export from the sainted Framemaker format.

@ David

Impressive work! Thanks for releasing it :)

It appears there’s a 30 day free trial of FrameMaker, and also older versions are available on ‘retro software’ sites. It would seem feasible to extract something out of the FM files using one of them, in the worst case Postscript which can turn into PDF, but also interchange formats like their version of structured XML.

So the next question is: can the FM files be open sourced so someone can extract the data from them? This would enable a ‘quick win’ in terms of generating new PDFs, and investigations as to what can be exported to seed a longer term refactoring.

It appears there’s a 30 day free trial of FrameMaker,

And if 6 people are willing to do a book each, that’s 180 days.

that’s 180 days

I think the idea is 180 minutes in order to extract the information into something that can be used in an alternative form.