Posts by Peter Bradley

1) Message boards : Documentation : Another Help documentation format (Message 14768)
Posted 8 Jan 2008 by Peter Bradley
Post:
If chmlib allows viewing of .chm files (on any platform) then it would allow the BOINC Manager to pop open the viewing window, rather than requiring some standalone program. Easy. (Or at least I'm hoping it would be.)


Can't speak for OS/X. I don't have a Mac handy, unfortunately.

Then there is the work of getting a set of content pages in shape to be these F1 Help pages.

And then there is the question of whether David thinks these kinds of help pages would be valuable.


Well, let me know if I can be of any help. You have my email address if I miss anything on the message boards.

Cheers


Peter

2) Message boards : Documentation : Another Help documentation format (Message 14765)
Posted 8 Jan 2008 by Peter Bradley
Post:
All I meant with mentioning DocBook is that it wouldn't be hard at all to write a converter that reads sections and titles from a DocBook file


Yes. I think we got at cross-purposes. My fault. Apologies.


Peter

3) Message boards : Documentation : Another Help documentation format (Message 14763)
Posted 8 Jan 2008 by Peter Bradley
Post:
I use the NoScript plugin, which blocks Javascript for all pages except those I explicitly add to the whitelist.


Which is good, because it leaves you in control of deciding whether or not you want to access the help in this format. As I've said above, I'm sure we can cater for users who turn JavaScript off. They just wouldn't get the indexing etc.

If there's a way of providing them with the lot, then that would be great. But I haven't found a way yet. Did you check whether DocBook can do it?

Cheers


Peter
4) Message boards : Documentation : Another Help documentation format (Message 14762)
Posted 8 Jan 2008 by Peter Bradley
Post:
XCHM works a treat. Here's a screen dump:

xchm at work

If the quality looks grainy, that's the fault of the image. On my screen the interface is of a very good quality indeed.


Peter
5) Message boards : Documentation : Another Help documentation format (Message 14760)
Posted 8 Jan 2008 by Peter Bradley
Post:
1. A subset of help pages from the wiki (Trac or UBW or both or others) are elected to become a part of the "F1 Help" package.


Yes. There seems to be a fair bit of agreement on that.

2. These are assembled into a .chm file, which in turn is also prepared for web viewing. (Peter, is that how it works?)


Yes. FlyHelp first creates the chm file and then uses that to create the searching and indexing facilities of the Web Help. It uses the HTML files created for the chm file as the content pages for Web Help. I'm not sure I've explained that very well, so just shout up if you need to know more.

Volunteers preview the result via the web, and correct the originals <em>in the wikis</em>, and the process repeats as needed.


Sounds OK to me.

3. The much improved .chm file(s?) are bundled with the BOINC client so that they can be viewed without a web connection when the user presses F1. Windows has a built-in tool for this.


Yep. Just one file, I think, although there are bits of the tool that I've not really explored yet (like providing context-sensitive help, for example).

xCHM may provide the same facility for Mac and Linux.


It might. I've just installed it on my Linux box. There are pre-requisites (wxWidgets and chmlib). The former comes as part of my SUSE distribution so the installation was no problem at all. CHMLIB can be downloaded from this site. There are no packages. It's a ./configure && make && make install job. I'm none too keen on doing this on a package-based system, but everything seems to have gone off OK.

Once the pre-requisites are done, xchm is another ./configure && make && make install. The only thing I had to do was copy the /usr/bin/wx-config-2.8 executable to /usr/bin/wx-config so that the configure script could find it. I suppose I could have edited the script, but the copy seemed easier.

Seems to be working OK now, but I haven't had chance to play yet.

The web versions might also prove to be more generally useful (I think that was Peter's original aim)


Yes. That's right.

Hope those comments are useful. And I meant what I said when I talked about buying some licenses for FlyHelp, if they would be useful. It might be helpful to have some backup, for example, ...

On a point made elsewhere about the noscript tag, yes, I'm sure we could use that to create some pages that would work. It's just a matter of redirecting to another place: perhaps another frameset. This would have to be done after producing the HTML Help, because the conversion process would, I think, over-write that file (but I'll have to check on that).

Cheers



Peter
6) Message boards : Documentation : Another Help documentation format (Message 14750)
Posted 8 Jan 2008 by Peter Bradley
Post:
It's GPL, and works on both X11 and Mac. Both good. If it's small, it might just get bundled in with the document content. Then we could have substantially the same F1 help pages - locally available - on all three platforms. Not bad.


Would you like me to play around with it on Linux (SUSE 10.0)?


Peter

7) Message boards : Documentation : Another Help documentation format (Message 14740)
Posted 8 Jan 2008 by Peter Bradley
Post:
The other might be if there are tools for displaying the .chm version. That seems more likely on Mac than Linux. And of course whatever is displayed would have to be the Mac or Linux version of the F1 help pages.


This might be of interest:

xchm

I know nothing about it other than what it says at the url above. And, of course, its presence on a user's machine would be unlikely.

So this is just to note that such a thing exists.

Cheers


Peter
8) Message boards : Documentation : Another Help documentation format (Message 14735)
Posted 8 Jan 2008 by Peter Bradley
Post:
Well, that's one strike against it. I don't like the idea of requiring JS just to get help.


I think there's a couple of points to be made here.

First, I don't think there's any suggestion that this should be the only, or even the main help system. So there would be no question of requiring JS just to get help - only of requiring it to get help in this format.

Second, given that other help systems would remain, the noscript text could contain a link/links to to other source(s).

Finally, I'm not sure how much of a disadvantage it is to require JS, in these days of AJAX. It's a knockout punch for some users, of that there is no doubt, but provided they are catered for in other, easily accessible, ways I would be able to live with that: but YMMV.

Cheers

Peter
9) Message boards : Documentation : Another Help documentation format (Message 14734)
Posted 8 Jan 2008 by Peter Bradley
Post:
I wonder if it might have another use: to prototpye a small subset of help pages which could then be bundled with the client for Windows, and viewed with the Windows help tool.


Don't see why not. Would there be any point in also bundling the same thing in HTML format for the Linux client - if the idea is to save a dial-up (i.e. open a browser on a file location in the install tree)?


Peter
10) Message boards : Documentation : Another Help documentation format (Message 14722)
Posted 7 Jan 2008 by Peter Bradley
Post:
lately I have been looking at Docbook.


Me too. I went for this solution instead because I couldn't see an easy way of adding navigation/contents/index facility, and I was in a hurry. If that can be done easily in DocBook then it'd be a better solution (IMHO) - especially as it would be free (in both senses).

EDIT: Sorry, I meant adding contents/index/search facility. Of course you can do navigation in DocBook (D'oh)! I like the cumulative index and the search facilities - but that's just a personal POV. YMMV.


Peter
11) Message boards : Documentation : Another Help documentation format (Message 14720)
Posted 7 Jan 2008 by Peter Bradley
Post:
Finally got a login sorted!

Couple of points.

First, it's me that's suggested producing help in this format, so I'll try not to present any arguments either for or against. Rather I'll just stick to bare facts and let you decide - because you know your own needs better than me.

Second, to pick up Eric's point. No, producing help in this format wouldn't be co-operative in the way that a Wiki is. Co-operation is the strong point of a Wiki (and sometimes its weakness, as well :) ). I think if you were to go for this, you'd have to only use it for docs that were pretty static and perhaps delegate the responsibility for creation and updates to one or more volunteers. Obviously it can be done, but it would need to be managed.

There's also the question of the tool to do the work. I have a license, but there'd be a need for more if it was adopted. But I'd fork out for at least a couple more, personally, to prevent that being a problem. It's not expensive.

Finally, Nicolas, yes it does require Javascript, which is one reason why I'd never suggest that it be the only format on offer. Glad you sorted the ad business. You had me worried for a minute then. And apologies for the slow speed of the server: it's on a low-speed site that I keep for mock-ups, examples and drafts for my private projects. It's never been a problem before - probably because I've never had a customer in Argentina (where some very good friends of mine live, BTW).

HTH


Peter




Copyright © 2024 University of California.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation.