Another Help documentation format

Message boards : Documentation : Another Help documentation format
Message board moderation

To post messages, you must log in.

Previous · 1 · 2

AuthorMessage
Eric Myers
Avatar

Send message
Joined: 12 Feb 06
Posts: 232
United States
Message 14756 - Posted: 8 Jan 2008, 18:53:17 UTC - in response to Message 14751.  

In these days of AJAX, I use the NoScript plugin, which blocks Javascript for all pages except those I explicitly add to the whitelist.


Which is a good idea. I wonder if a reasonable <noscript> version could also be presented, perhaps with just frames and the document tree expanded? I don't think of <noscript>You must turn on JavaScript</noscript> as reasonable.


-- Eric Myers

"Education is not the filling of a pail, but the lighting of a fire." -- William Butler Yeats
ID: 14756 · Report as offensive
Eric Myers
Avatar

Send message
Joined: 12 Feb 06
Posts: 232
United States
Message 14759 - Posted: 8 Jan 2008, 19:08:37 UTC - in response to Message 14729.  

Eric Myers wrote:
Since this is a .chm file converted to HTML(+JS) for presentation on the web, I wonder if it might have another use: to prototpye a small subset of help pages which could then be bundled with the client ...


So now just to summarize what I'm thinking, and perhaps Peter can correct any misconceptions:

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. One reason is that then those are the primary source and we don't have yet another set of pages to maintain.

2. These are assembled into a .chm file, which in turn is also prepared for web viewing. (Peter, is that how it works?) Volunteers preview the result via the web, and correct the originals <em>in the wikis</em>, and the process repeats as needed.

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. xCHM may provide the same facility for Mac and Linux.

The web versions might also prove to be more generally useful (I think that was Peter's original aim), but this process would help fill a gap in documentation without having to actually create new content pages.

Of course the existing documentation would have to be organized for this, but that would not be bad in any case.
-- Eric Myers

"Education is not the filling of a pail, but the lighting of a fire." -- William Butler Yeats
ID: 14759 · Report as offensive
Peter Bradley

Send message
Joined: 7 Jan 08
Posts: 11
United Kingdom
Message 14760 - Posted: 8 Jan 2008, 19:56:29 UTC - in response to Message 14759.  

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
ID: 14760 · Report as offensive
Peter Bradley

Send message
Joined: 7 Jan 08
Posts: 11
United Kingdom
Message 14762 - Posted: 8 Jan 2008, 20:05:21 UTC

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
ID: 14762 · Report as offensive
Peter Bradley

Send message
Joined: 7 Jan 08
Posts: 11
United Kingdom
Message 14763 - Posted: 8 Jan 2008, 20:43:07 UTC - in response to Message 14751.  

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
ID: 14763 · Report as offensive
Nicolas

Send message
Joined: 19 Jan 07
Posts: 1179
Argentina
Message 14764 - Posted: 8 Jan 2008, 20:54:58 UTC - in response to Message 14763.  
Last modified: 8 Jan 2008, 20:55:19 UTC

Did you check whether DocBook can do it?

DocBook is no more than a file format. 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 and generates this.
ID: 14764 · Report as offensive
Peter Bradley

Send message
Joined: 7 Jan 08
Posts: 11
United Kingdom
Message 14765 - Posted: 8 Jan 2008, 21:05:52 UTC - in response to Message 14764.  

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

ID: 14765 · Report as offensive
Eric Myers
Avatar

Send message
Joined: 12 Feb 06
Posts: 232
United States
Message 14766 - Posted: 8 Jan 2008, 22:04:48 UTC - in response to Message 14760.  

...There are pre-requisites (wxWidgets and chmlib).

Well, wxWidgets is already used to build the BOINC Manager for all platforms, so that is not a problem. 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.)

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.

-- Eric Myers

"Education is not the filling of a pail, but the lighting of a fire." -- William Butler Yeats
ID: 14766 · Report as offensive
Peter Bradley

Send message
Joined: 7 Jan 08
Posts: 11
United Kingdom
Message 14768 - Posted: 8 Jan 2008, 22:43:57 UTC - in response to Message 14766.  

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

ID: 14768 · Report as offensive
Previous · 1 · 2

Message boards : Documentation : Another Help documentation format

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.