dabossuk
30th March 2003 20:36 UTC

New Docs > what about searching ?
Hi

I was thinking of converting the current NSIS help into a .CHM file. However just popped on here and seen the current efforts, both in XML and .CHM. My main concern about the current help and the inability to search. The .CHM project that someone else on here seems to be starting would solve this, however what thoughts have you on the XML side.

I have been a user of Wise and Installshield for over 7 years, and have only just moved to NSIS, which I think we will all agree is one amazing bit of open source! ;-)

DabossUK

kichik
30th March 2003 22:44 UTC

Well, it's planned. We are aware that a better documentation system is required, it's just that we have some more important things to do at the moment.

The problem with the current projects is that are far from easy to update, they are currently just beautiful and searchable (in the CHM's case) but to update them is currently a nightmare. If someone will come up with a good system that's easy to update and that produces a searchable format that looks good too we'll happily take it.

dabossuk
31st March 2003 00:53 UTC

Hi

The CHM format would make sense ... although it seems some people on here are against it ?

I would be happy to start something on this if it would help - giving something back to the NSIS! ;-) I am not a documentation person, so someone needs to carry on writing the docs – but happy to work on the process of getting the raw data into a CHM. Just converting what is there now will not take long. I cannot see how the XML version that is being worked on could be searchable in the future.

If a CHM version was created - we create a HTML / CSS template that everyone can edit and then someone can then compile into a chm.

My 2p anyway ;-)

Dabossuk

Joel
31st March 2003 01:43 UTC

Yeah! You can set to an "Open source" the Nsis CHM Manual.
Sound great to me, although we going to need the HTML Help Workshop

virtlink
31st March 2003 11:51 UTC

I already wondered where it was, that HTML Workshop. I've been looking all over my PC, and I couldn't find it. I think that I left it on the Visual Basic 6 CD.

Anyway, the XML documentation is/was just a system to update the docs. They would be parsed to HTML by the program Saxon, so everyone could view it. A CSS-file is included.

Please see this thread (if you haven't already), and download the latest NXDDL.zip-file, containing XML-files + XSLT-file + parsed XML files. There are still some errors in the XML-files when you view them with, for example, IE6, but those errors don't appear in the 'parsed by Saxon' versions.

Currently, a program called Halibut is used for the documentation. It parses the .but-files (you can find them + halibut source in the NSIS zip, not in the installed NSIS version, tough), and creates HTML output. I don't know how this program works from the inside, since I can't program in C(++), but I doubt that it wouldn't be adaptable.

dabossuk, maybe you have any experience with C(++)?

dabossuk
31st March 2003 17:19 UTC

I have a hard-core C++, Java and .NET team here ;-) Will have a look into this tonight ;-)

Dabossuk

Joost Verburg
31st March 2003 17:31 UTC

A CHM (HTML Help) file is just a package of HTML documents.

The current documentation system (Halibut) generates HTML documents.

The problem with documentation systems is the updating. Writing HTML code and having to update it every time the documentation format or order is being changed is no option.

Of course you can just create a CHM package from the current Halibut-generated HTML documents (you can download HTML Help Workshop at microsoft.com) but again, updating is the problem.

If you generate a nice TOC with links to all chapters and numbers and we change the chapters, add commands etc., you will have to do everything again.

I think the best solution for now would be to let Halibut generate HTML Help files that can be compiled with the HTML Help compiler. Converting everything into a new (XML) format will require really a lot of work. Unless someone wants to spend days to convert all the stuff, it will never be finished.

So if someone with good C++ exeperience can modify Halibut to generate the files for the HTML Help compiler, that would be a good solution.

virtlink
31st March 2003 19:38 UTC

dabossuk contacted me about this, and I've send a reply. No answer yet (that because Í sended it two minutes ago ;)), but I think that we (dabossuk, flizebogen, the NSIS team and I) would be able to solve this updating problem.

Joost Verburg
31st March 2003 20:35 UTC

Where are you thinking of? Generating HTML Help with the current system?

virtlink
1st April 2003 09:36 UTC

Yes, but not with the current system. The current Halibut system needs a lot of work, and since it is written in C++, and I don't know C++ (but C#), and dabossuk prefers C#, it might be a better idea to rewrite it. Changes that then would be made are:
- It can call the HTML Workshop help-compiler.
- It can generate the index table, keyword table and other tables needed for CHM-files.
- It might be possible to also generate PDF files (for those who want a printed version of the docs), but that is not certain yet.
- It still generates HTML-files, but all the used HTML data is saved in an external HTML-template.
- The syntax might slightly differ a bit.

All of the above still needs to be worked out, and dabossuk is discussing it with his team.

[EDIT]The new program doesn't have to be complex. I think that it will even be really small and fast.[/EDIT]

As always, any suggestions, comments and/or questions are welcome, especially from those with documentation experience (KiCHiK, Joost, Sunjammer, flizebogen, etc..), but others too.

Joost Verburg
1st April 2003 13:50 UTC

This is really not that easy. Writing a good generator will take months, really.

I'm afraid that a project to write a completely new system will never be finished. Modifying Halibut is a much better solution. Maybe someone with C++ experience can help.

kichik
1st April 2003 15:11 UTC

C# requires .NET and VisualStudio.NET to compile, both of which I don't have so I won't be able to help. I prefer it to be in the good old, fast C language, or even C++.

Joost Verburg
1st April 2003 15:19 UTC

Yep, we can't make the .NET Framework a requirement.

But please don't start from the beginning. Halibut is written and C and can probably be modified to generate the HTML Help index files.

virtlink
1st April 2003 17:25 UTC

I agree: we can't make the .NET Framework a requirement. But, please understand, that it is a lot easier to work with than C or C++ (at least for me, from a Visual Basic point of view), and most of the (advanced) functions are already written, like XML support.

But the .NET framework won't be a requirement. Only for those who want to compile the documentation. Any, believe it or not, you'll have it install it anyway, since Microsoft is deperately trying to get it on all Windows PC's as fast as possible.
Trough Windows Update, it can be downloaded.

And since dabossuk's team's codebase is C#, and I have C# installed on my PC, and I understand it, and it is the future, and it is not such a big deal to install it, and it won't be a requirement for normal NSIS users, etc..., etc..., etc..., I think that, now that we've found some people who might be willing to help us, that we should grab this oppertunity and create a good documentation system. Currently, all the instructions are stuffed into one chapter. And that's now how I think it should be.

We agree about this:
- The documentation needs to be better.
- The documentation should be easy to updater and maintain.
- The documentation should be easy to use/search trough the CHM file format.

Currently, the only problem is the programming language, and the program itself. I don't think that C# is such a bad idea at all. dabossuk will get back to me shortly with a plan. I'll review it and such, and then we can continue this discussion. What if the plan is an excellent idea and easy too?

Joost Verburg
1st April 2003 17:36 UTC

Writing a complete system is so much work. You can really work for months on something like that.

If we have a nice TOC the current system will be no problem. Working on Halibut is a better idea.

Joost Verburg
1st April 2003 18:13 UTC

What about this as a first start?

I generated a text file with an index of the complete documentation.

Can you write an application (in C# or whatever you like) that converts this file to a .hhc HTML Help Contents file?

The file does not contain links, but they all have the same format: (Chapter/Appendix)?.html#number

dabossuk
1st April 2003 22:46 UTC

Hi

Just wanted to say that you can compile a C# application with the .NET Framework SDK. Which is free. The studio is what costs the £££ and it just makes life easier.

The main reason for C# is that things like XML are built in ... building a XML serialize / desterilise class in C++ is big task unless we buy one – which is not very open source now …

Anyway - lets keep talking - best way to work out the issues. We are still brain storming here ... will post my thoughts on here shortly.

Also just out of interest how many people here would recompile the help ? I assume people that wish to help write it ? ;-)

Dabossuk

Joost Verburg
2nd April 2003 11:59 UTC

Dabossuk, writing a converter for the textfile won't be that difficult. I think writing one will only take a few hours.

You don't need XML and stuff like that, so we would prefer a simple C/C++ application.

virtlink
2nd April 2003 17:16 UTC

I've created a small console executable that converts Joost's text-file to a .hhc and a .hhp file.

Just place that textfile in the \Docs directory of NSIS, run the CHMgen.exe file, with as parameter, the full path to that textfile, and .hhc and .hhp files will be generated.

You need to have HTML Workshop installed to compile those files to a .CHM-file. And you need to have the .NET Framework installed, since this program was written in C#.

virtlink
2nd April 2003 17:18 UTC

I forgot to tell:
- There are some double items in Joost's text file.
- When you compile the files to a CHM-file, all the attached and referred files are also included. So, the readme.html + images + stylesheets of the Modern UI and InstallOptions dll are propably also included in the .CHM-file. The CHM-file will be aproximately 161 kB in size.

Joost Verburg
2nd April 2003 17:40 UTC

Thanks! :D

Where are double items? I had the problem before and tried to remove them. Can you add a filter for double items in your app?

Can you also include the source?

virtlink
2nd April 2003 17:46 UTC

I'll add a filter, and I'll include the source, as long as the complete size won't exceed the 100 kB, else I can't attach it.

Don't forget: The program is written with Visual Studio .NET, so a project and solution file is included too. And, I am a bad commenter. There are NO :D comments in the source!

virtlink
2nd April 2003 20:48 UTC

A new version of NSIS Help File Generator.

- I've added a filter for double items.
- Chapters and Appendixes start with their chapter number.
- The generated CHM file is v. 1.0 compatible.
- Full search capabilities.
- Some more...
- Source included.

eccles
3rd April 2003 22:32 UTC

Hi virtlink etc,

At the same time you made your program I started doing a similar thing (in Perl) which I've now just finished. The output for the .hhc is almost identical (well, it is now :D). The main difference is this also generates a .hhk for an index tab, for easy lookup of instructions by name, etc. It's not perfect, but you might want to try something similar (or just use this ;)).

A .exe version can be created if needed.

Have fun...

[edit]To create the hhc/hhk just pipe Joost's .txt file through the perl script[/edit]

Joost Verburg
4th April 2003 08:09 UTC

I already asked virtlink to add an index with the instruction names :)

Now we have to choose one of the two applications. Can you create an exe file eccles? Which dependecies will it have?

eccles
4th April 2003 13:57 UTC

It is possible to create a self-contained .exe out of it, using perl2exe, although you need to have perl installed to do it. I'll knock one together when I get home later...

Dave.

eccles
4th April 2003 22:13 UTC

OK, compiled .exe here (around 770K)

virtlink
5th April 2003 10:04 UTC

Mine is the smallest! About 100K if I'm not mistaken ;).
I'll be working on the changes to my program today, and I'll propably post the result in the afternoon.

Joost Verburg
5th April 2003 12:26 UTC

Eccles' file is stand-alone, your app requires the .NET Framework (20 MB).

The index file generated by eccles' version is really nice :D

I think developing two versions is a bit waste of time, so we have to decide which one to use.

The current HTML Help files include external files (Modern UI Readme, examples etc.), so Halibut should be modified to optionally generate JavaScript links: http://msdn.microsoft.com/library/de...ptslinkchm.asp. Do you have time to work on that Dave? Maybe Halibut can be modified to generate the textfile for conversion too (I use a modified messy Winhelp module for it now) :)

eccles
5th April 2003 12:55 UTC

Now now children, stop all this bickering ;)

New version (attached) is about 24K, requiring this DLL (about 300K), but only the .exe should change in future versions.

Joost, I made it so that the .chm file should be built from the NSIS root directory (sorry, I forgot to mention that before) so that all links referenced would be included in the .chm, but I guess your idea is better. I must drop by on IRC soon to talk about it; it's been too long... :)

virtlink
5th April 2003 15:03 UTC

I have a new version ready.
It now supports the output of an index file too.

And you can use the "/p [prefix]" switch to prefix the paths to the source HTML file with [prefix], so that you can place the textfile in a subdirectory (or parent directory) of the Docs directory.
When used in a parent directory, use:

chmgen.exe /p "Docs\" NSIScontents.txt

chmgen.exe /p "..\" NSIScontents.txt

virtlink
5th April 2003 15:11 UTC

Dave: How do I get your program working? I've downloaded the .exe and the .dll and put them both in the NSIS root directory. Then I dropped the textfile on top of the exe. The program starts, but doesn't output anything and doesn't stop. What am I doing wrong?

eccles
5th April 2003 15:26 UTC

Hi Virtlink,

You need to open a command prompt, go to the NSIS directory, then run

makehhc < nsiscontents.txt

pengyou
19th April 2003 17:43 UTC

From reading this thread it seems that CHM documentation is the preferred format for searchable documentation. I prefer PDF files to CHM files as I find the CHM format too inflexible and not at all easy to print out. I hope that whatever documentation scheme is adopted will continue to provide HTML files as an alternative, even if they are only available via CVS.

My understanding is that the new documentation scheme requirements are for a system that takes a simple text file with very little in the way of formatting commands and produces a searchable document, hopefully suitable for printing a hard copy.

As I am too lazy to even think about writing such a program, I looked around to see if there were any free programs that could help meet these requirements. I've found two free programs that seem quite promising: one (Scheme Scribe) creates HTML files and the other (HTMLDOC) converts HTML files into PDF files.

I've created a small demo using some pages from the NSIS User Manual and found that it took very little effort to get a searchable PDF file suitable for printing. I am still learning how to use these programs so my demo cannot claim to be anything other than a poor example of what these programs can do. If anyone is interested in seeing what can be achieved by someone who doesn't really know how to use these programs, the HTML and PDF versions of my demo and a few source files are in the scribedemo.zip attachment.

Joost Verburg
20th April 2003 11:35 UTC

Your PDF isn't really different from one big HTML file, you can search both in the same way.

The CHM documentation we are working on will have a TOC, an index (an easy list of all commands), etc.

A CHM (HTML Help) file is just a package of HTML files and TOC/index files, so the HTML files will still be available.

Sunjammer
20th April 2003 11:37 UTC

I quite like the final result but I can't comment on it's usability from the perspective of the doc maintainers since I'm not one :)Cheers for the input.

-- Sunjammer

Joost Verburg
20th April 2003 14:43 UTC

Yeah PDF is indeed useful for printing :) So both a PDF and a CHM file would be great :D

kichik
20th April 2003 16:40 UTC

I hope that whatever documentation scheme is adopted will continue to provide HTML files as an alternative, even if they are only available via CVS.

pengyou
21st April 2003 01:57 UTC

HTMLDOC does not make many demands upon the format of the HTML files it processes. As an experiment I converted the first four chapters of the NSIS manual to a PDF file and only had to make a few minor changes to the HTML files.

Attached is an 86KB ZIP file with the PDF and details of the changes made. Three lines were deleted from each HTML file and in two of the four files I had to move one line (the <H1> header) to the start of the body.

joelpaula
29th October 2003 17:59 UTC

Originally posted by Joost Verburg
What about this as a first start?

I generated a text file with an index of the complete documentation.
[...]
The file does not contain links, but they all have the same format: (Chapter/Appendix)?.html#number