RISC OS User Guide PDF

Have you considered using MySociety’s SayIt:

<http://sayit.mysociety.org/>

Have you considered using MySociety’s SayIt

Looks to me to be text only, so unsuited to this project.

Meanwhile, for those interested in FrameMaker, Adobe’s current price for the full version 12 (Windows only) is £952.80. If anyone were to offer that kind of money, I’d rather see it go towards a Bounty!

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)"

Actually the main reason was because ROOL/JB told us that the FrameMaker version couldn’t be found. Very glad to hear that it has now been found.

To be honest rather than worry about the format what is needed is people willing to edit the text.
I’m convinced that the vast majority of the necessary work could be done in !Edit. It can then be imported into FameMaker/whatever with hyperlinks/images then added.

£952.80

What an utterly peculiar price. Is it a whole amount in $?

I’m guessing from this discussion that there is no viable open source alternative?
That said – what do we need that [Libre|Open|Whatever]Office cannot do? Serious question. The PRM layout is quite pleasant, but it doesn’t look that complex. The hard part, I’d have imagined, would be keeping track of all those page references (across multiple books).

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.

I have done something similar: I started with a programme that processed some data from a spreadsheet to generate HTML with multiply nested tables to provide odd and even page margin gutters, relied upon the browser to generate consistent paginated output (using page-break-before: always style commands in the HTML) but found that a browser update could introduce new and different behaviour and there was always the chance (significant once more than 200 pages long) that one or two images would be shown as blank. My conclusion was that using HTML as a way of producing a book was doomed to failure. I therefore produced an intermediate spreadsheet which I processed to produce individual Draw files for each page that I could batch-convert to individual PDF files and combine in Acrobat 8.3. That was to produce a 300 or 400 page book and an HTML equivalent, available on line and password protected.

I started with a programme that processed some data from a spreadsheet to generate HTML with multiply nested tables to provide odd and even page margin gutters, relied upon the browser to generate consistent paginated output (using page-break-before: always style commands in the HTML) but found that a browser update could introduce new and different behaviour and there was always the chance (significant once more than 200 pages long) that one or two images would be shown as blank. My conclusion was that using HTML as a way of producing a book was doomed to failure.

I can’t say that I’m surprised to learn that…

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.

You’re still looking at this from the wrong direction.

HTML + CSS is your destination format, not the source. The source needs to be in a far more semantic format that cares nothing for layout: XML is ideal, but there are other options too. You edit the source files, and when you want a new HTML document you run a conversion tool. Ditto for plain ASCII text, or StrongHelp, or PDF, or whatever. When editing your text, you do not want to be worrying about any target layout.

I’m not suggesting for a minute that you use it (because it’s rubbish, frankly, and an XML-based system would have been far better if I’d known that 15 years ago), but all of my software manuals are generated via a set of Perl scripts that I call ManTools. The source files are some home-brew markup format which allows the purpose and meaning of text to be described, not the formatting (so when describing a * command, for example, it would highlight that some text was a description of a named parameter, not how it should be formatted). As standard it generates the text and StrongHelp manuals that come with my software. It can also generate HTML + CSS for use on my website (although I’ve not normally bothered with this); if anyone remembers the printed CashBook manual that I once sold at shows, it came via a DDL output from ManTools which was dropped into Ovation Pro and turned into PDFs for Lulu to print.

These days, I’ve got similar Perl scripts that work with XML, which I’m using on different projects. One day, they might replace ManTools for my software documentation, too – they’re far better to work with, but there’s a lot of stuff in ManTools format. That’s the other issue here: it seems as if you’re spending a lot of time at present moving the manuals into the wrong format.

Looking at FrameMaker’s website, it seems to be XML-based. Is there any mileage in looking at using an XML format that works with FrameMaker for the printed stuff and home-brew Perl scripts for everything else? How open are FrameMaker’s documentation formats?

The source needs to be in a far more semantic format that cares nothing for layout.

Absolutely right. Sources must be in a textual format. I wish the secretaries at my department who could only use MS Word, had understood this better. Once you have mixed the eggs into the mixture you cannot get your eggs back from the cake. I use Lua for brewing all my webpages. The next stage from raw sources is a bit of abstraction – this is displayed code, this is a comment, this is a bibliographic reference, and so on. Layout and display to implement the abstractions must surely come last. I suppose nobody uses it anymore, but this separation of content from style is what TeX and LaTex were all about.

In academic circles, at least where mathematical output is required, TeX/LaTeX is still widely used. It has even moved with the times—PDF output is now the norm, there are tools like TeXWorks which make it easy to work on a document and get a rapid preview, and (using XeTeX or LuaTeX) it’s even possible to specify TrueType fonts to be used…

The only thing is that this won’t work on RISC OS where TeX is older and there is no really good PDF viewer to the standard of other platforms.

Using a text-based format to generate output in various forms is nothing new—the UNIX man pages are generated this way, using nroff/troff etc.

It seems to me that for this particular issue, the most important thing is having a format that as many people as possible can contribute work in. ODT format might be suitable but would cut out people working only on RISC OS; an XML-based semantic format would first need to be agreed on and defined (you would even need to decide how to define it—DTD is no longer the preferred option, there is now XML Schema and others). And people would need to submit their input in the correct format—which really needs an XML-aware editor (not just syntax highlighting).

I do not think anyone has mentioned EasiWriter/TechWriter yet. From its native format it can produce PDF and HTML. It can also import HTML and make a reasonable job of links. Just a thought. ;-)

I have been an admirer of TechWriter for many years and under Martin’s stewardship it has got better and better. Unfortunately its document format is not textual, and so its documents are not easily scriptable. In the days when it was first designed this was not yet a consideration. The same applies to Draw – indeed all the Acorn formats that use the chunk system. I am not saying that there were not good reasons for the formats chosen then, but today’s speeds and memory costs were not a factor.

Perhaps, and in suggesting it I’m inventing work for someone, the answer is to produce a small application that produces text with markers¹ that can be imported to a layout system².

Anyone can work on the text and markers using the small app.

¹ The markup doesn’t need much beyond headline 1, 2, 3, 4,5, bold, italic, code
² A small translation script to take the markup and produce an OvationPro document (or Impression assuming people can work with that).

If the markup only needs those things, why invent a new way of describing things when existing methods can handle this? For instance, LaTeX can do this (it would be simple to create a style file if required.). The text can be checked for errors with existing tools and you can generate PDF and HTML (including hyperlinks) as required.

I don’t see why you need to generate Ovation Pro or Impression other than as a route to PDF…

When I said, above:

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

I could have enlarged on the extent to which layout is at least as important as content for understanding, and the desire to have images and tables (and images in tables) for example makes it all the harder to separate content from layout in such a way that a variety of output formats are equally useful to the reader.

Does there even exist a free editor capable of easily maintaining a data structure that would satisfy the purists in respect of maintaining layout-free content, yet reliably supporting different output formats, given the above?

This has been a fascinating discussion but I will, for the time being, continue to hand-code HTML so as to look as much like the original print as is sensible. Offers of help either in that vein or in even a slightly more ambitious one are always welcome.

I don’t see why you need to generate Ovation Pro or Impression other than as a route to PDF…

Layout and addition of graphics, unless Latex can do multiple columns with inline graphics and flow round graphics.

The simplistic editor was something the contributor could use to prepare text, Latex might fit the bill but I suspect the RO version won’t do the final layout.

Are multiple columns needed? LaTeX can certainly do them, and inline graphics if needed. As for flowing round graphics, I’m not sure as to the extent it permits this—you can certainly have a graphic which takes up all of a column or two columns and there is a lot of support for floating an illustration to a place where there is sufficient room for it if there isn’t at the current location.

Can I reinforce what sprow said earlier – it would be far better for people to send textual updates to pre-existing Acorn books where ROOL has the master copies (in FrameMaker format). Without having worked on any of these books, it is very easy to grossly underestimate just how complex and inter-dependent they are, and FrameMaker is the perfect tool for the job. Anything else will just be placing an unacceptable burden upon ROOL if/when we want to update the master copies or make proper professionally printed versions.

So, Steve, the model you’re advocating is that volunteers provide updated text, and ROOL merge the text and (at some stage) make available files in some more common format (HTML, PDF, etc.)? Which means that ROOL have a working installation of FrameMaker?

it would be far better for people to send textual updates to pre-existing Acorn books

All right, but (also to reiterate an earlier point) what about images and tabular style updates? Is there a FrameMaker input format that would assist ROOL’s updating where PNG images and table-type constructs are involved?

And should we therefore assume that ROOL has been using FrameMaker for the new editions of the Style Guide and the DDE books, and now have experience of exporting them in PDF (and perhaps other) formats?

the model you’re advocating is that volunteers provide updated text, and ROOL merge the text

Correct.

and (at some stage) make available files in some more common format (HTML, PDF, etc.)?

Correct. We can easily release updated versions in PDF format, for example. HTML would require more work so we’ve not got any immediate plans to tackle that – we’d like to do the more important work of getting the actual content updated and correct first.

Which means that ROOL have a working installation of FrameMaker?

Yes. We’ve moved all of the original documents across to a much newer version of Framemaker and got ourselves a copy. This is how we’ve been able to make the significant updates to the Style Guide (out now), the Objasm Manual, C/C++ Manual and Desktop Tools Manual (to be released soon).

So, without further ado, here is a copy of the User Guide exported as a PDF from Framemaker. There are a couple of glitches with missing images that we can sort out another time but that should be sufficient for people to start looking at what edits need to be made.

All right, but (also to reiterate an earlier point) what about images and tabular style updates? Is there a FrameMaker input format that would assist ROOL’s updating where PNG images and table-type constructs are involved?

Updating images should simply be a case of sending us the image(s) and telling us where to add/replace them. We would need to agree on things like which toolsprites and iconsprites must be used (as per our updated Style Guide manual – I’ll check what we used) in order for the whole manual to be consistent. I suspect all screenshots will need to be touched to some degree for that reason alone.

For more complex updates which include tabular content or similar, then sending us ASCII text with fixed-width fonts doing the layout would be fine for us. Or HTML if that floats your boat. Either way, we’re going to have to do a pile of copying and pasting of whatever you send to update the master document, but that’s the price you pay for having a master document in a proper publishing program’s file format, which as I’ve said earlier is of critical importance to being able to get these books professionally printed (and get indexes and cross-references across volumes/books correct).

And should we therefore assume that ROOL has been using FrameMaker for the new editions of the Style Guide and the DDE books, and now have experience of exporting them in PDF (and perhaps other) formats?

Yes, correct. It has been a vast amount of work (considering this is a spare time activity for a ROOL helper) but it’s important that we maintain these master documents and don’t degrade everything to being in some inferior format, such as HTML, which would be probably impossible to get properly printed.

I’d be happy to help out with updating the text for SciCalc and Patience, as I worked on both apps. Bernard: I believe you’ve already produced updated texts for these, so I’d be happy to collaborate in order to get something to ROOL in the right format. I think you’ve got my email – let me know if you’d like to join forces.

I’ve also submitted a test copy of Chars for evaluation with quite a few more features than the existing one. If this finds its way into the sources then I’d be happy to help update the documentation for that too.

Updating images should simply be a case of sending us the image(s) and telling us where to add/replace them. We would need to agree on things like which toolsprites and iconsprites must be used (as per our updated Style Guide manual – I’ll check what we used) in order for the whole manual to be consistent. […] For more complex updates which include tabular content or similar, then sending us ASCII text with fixed-width fonts doing the layout would be fine for us. Or HTML if that floats your boat.

It would be good to have this info. As well as requirements for screenshots, it’d be nice to have some guidance – as much for ROOL as for contributors – on the most effective way to indicate formatting. For example, it looks like there are three levels of headings in the body of the text, which will need to be indicated somehow.

I’ve also submitted a test copy of Chars for evaluation with quite a few more features than the existing one.

Upvote for this.

There are more things to do, more features to add, however even as it stands it is a big improvement over the generic !Chars. So much so that I’ve replaced the ROM version with Chris’ improved version.

So, without further ado, here is a copy of the User Guide exported as a PDF from Framemaker.

Excellent. Thanks for that; it’s great to see a “proper” reference for the first time :)