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
New Docs > what about searching ?
48 posts
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.
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.
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
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
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
Sound great to me, although we going to need the HTML Help Workshop
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(++)?
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(++)?
I have a hard-core C++, Java and .NET team here ;-) Will have a look into this tonight ;-)
Dabossuk
Dabossuk
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.
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.
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.
Where are you thinking of? Generating HTML Help with the current system?
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.
- 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.
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.
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.
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++.
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.
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.
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?
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?
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.
If we have a nice TOC the current system will be no problem. Working on Halibut is a better idea.
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
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
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
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
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.
You don't need XML and stuff like that, so we would prefer a simple C/C++ application.
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#.
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#.
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.
- 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.
Thanks! 😁
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?
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?
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 😁 comments in the source!
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 😁 comments in the source!
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.
- 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.
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 😁). 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]
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 😁). 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]
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?
Now we have to choose one of the two applications. Can you create an exe file eccles? Which dependecies will it have?
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.
Dave.
OK, compiled .exe here (around 770K)
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.
I'll be working on the changes to my program today, and I'll propably post the result in the afternoon.
Eccles' file is stand-alone, your app requires the .NET Framework (20 MB).
The index file generated by eccles' version is really nice 😁
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) 🙂
The index file generated by eccles' version is really nice 😁
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) 🙂
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... 🙂
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... 🙂