StrongHelp OS manual

Who’s maintaining the StrongHelp OS manual these days?

I’m not sure anyone is really. I’ve occasionally received updates (mostly from Sprow I think) to put on the riscos.info SH download site, but that’s about it.

I’d be very happy to hand over this process. In particular I think it would be a good idea to build the manual from sources in version control, rather than tweaking the contents of the image file by hand each time. That would make it easier to have multiple contributors.

In particular I think it would be a good idea to build the manual from sources in version control, rather than tweaking the contents of the image file by hand each time.

That should be fairly easily doable using BindHelp, which is used to build OSLib’s manual. Although it doesn’t seem to work on the OS manual at present…

Given that I seem to have been the last person to have poked BindHelp, I can have a look to see if I can see what it’s unhappy about. If it can be made to work, a repo on riscos.info might be the best home?

Given that I seem to have been the last person to have poked BindHelp, I can have a look to see if I can see what it’s unhappy about.

It seems to have been my fault, anyway, inasmuch as I didn’t disable part of the automated indexing when adding the flag to allow arbitrary manuals to be built… Maybe I’m the only person using that option. :)

Anyway, I’ve just built a copy of the 3.39 manual from “source” on Linux, and it looks OK. It’s here if anyone fancies trying to spot any broken bits – I’ve not looked that hard.

I’m happy to help to set this up somewhere if there’s any interest. Before anyone asks, this shouldn’t affect people editing pages in the file and sending in changes for inclusion. Whoever maintains the master copy can just copy the contents out into the repo, and it should just pick up the changes.

ETA: The words “just” and “should” are doing quite a lot of work in that last sentence, aren’t they?

I can set up an SVN repo on riscos.info if you like, but it might make more sense if it was on somewhere like Github, since Github’s disaster recovery plan is likely a lot better than my own :)

I can create a repo in https://github.com/riscos-dot-info/ if you want a home a bit more centralised (and then I can give anyone who wants commit access to it).

spot any broken bits

The only differences between the OS 3.39 manual I downloaded, and your osBH manual that I can see are the two files:

!Root – Where osBH has a note about your rebuild
OS_.SerialOp.9 – Where OS has an additional note about the Entries in the Table which is not in osBH.

Otherwise identical.

I’m happy to help to set this up somewhere if there’s any interest.

And, over half a year on, there’s now a GitHub repo containing the core OS manuals. I’ve diffed the build from each commit against the original from riscos.info, and everything seems to match.

The build process needs a couple of small fixes to BindHelp, which I’ll try to commit to SourceForge this week.

Before anyone asks, this shouldn’t affect people editing pages in the file and sending in changes for inclusion. Whoever maintains the master copy can just copy the contents out into the repo, and it should just pick up the changes.

I’ve been using Strong Extract to do this on Linux, but I can’t immediately see why it couldn’t be done on RISC OS so long as filetypes are retained in line with the standard cross-platform conventions.

Which means that changes can be submitted either using Git-style methods, or by the more traditional approach of editing a StrongHelp manual on RISC OS and then emailing it to someone with access to the repo.

It’s all still a work in progress, but hopefully it will make updates and maintenance easier.

Excellent work!

The build process needs a couple of small fixes to BindHelp, which I’ll try to commit to SourceForge this week.

And this is now done, I think – the version committed isn’t the one used to build the manuals, since I’ve found what looks to be a much better way to implement the required mapping from ‘.’ to ‘/’ in filenames compared to the bodge used whilst building the manuals. However, I’ve re-checked the Toolbox manual – which is the one that contained filenames with ‘/’ in them – and it still seems to come out OK.

I’ve actually found a couple more foibles in BindHelp, but they don’t seem to affect its use for this purpose: it doesn’t like empty directories in a manual, and it generates an unnecessary zero-length data block for empty files. The latter isn’t a problem (StrongHelp seems happy with the arrangement), and the former isn’t an issue for this use-case as Git strips empty folders anyway. I’d like to fix both shortcomings at some point, but the empty folders one looks to require major surgery and I’m undecided if it’s worth it.

Maybe I could easily extend StrongHelpViewer to directly access the GitHub manual sources. Well, after implementing the server-side. And Sprite support. And Squash support. And Draw support. And fixing the known bugs and shortcomings. And actually packaging a version for general use.