New Docs > what about searching ?

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

When used in a subdirectory, use:

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

Else, just don't use the /p-switch.

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?

Hi Virtlink,

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

makehhc < nsiscontents.txt

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.

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.

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

Yeah PDF is indeed useful for printing 🙂 So both a PDF and a CHM file would be great 😁

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.

The ideal state would be one program, or at least one batch file, that generates HTML, PDF, and CHM.

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.

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

How can I produce this text file automatically from the latest NSIS stuff on my disc? Is there an automatic way or a method to do this? Maybe using Halibut.exe?

I am using it to build a CHM that can be called from my Editor (or anything else, for that matter) and show context sensitive help.

Thanks for your help

There is currently no way to generate this file automatically.

Automatic HTML Help generation by Halibut is almost ready (not related to the applications is this topic). However, the person who was working on it did not finish it.

If anyone with C experience wants to help us, drop a note.

I thought there was someone working on an XML documentation project that could generate HTML, CHM and whatever else.

What is missing from Halibut? Where can I get information on how it works? What do you use to edit the documentation?
I haven't programmed in C for a long long long time but I could have a try at it.

I was working on a help system in XML, but those people at NSIS (Joost, Kichik, Subjammer, etc.. 😉) don't want to type all those tags. 🙁
I even wrote a nice XSL for it. And combined with Saxon, you can output HTML-files.

Do you know how they currently edit the documentation? What kind of application they use?

In order to make the XML documentation project work, you would have to provide the editor itself and the system to generate the HTML/RTF/Whatever. It seems simple. The bigest issue is to convert the old documentation!

Halibut is used to generate the documentation. It generates it from .but files that can be found in CVS. A special version of Halibut, which is used by NSIS, is also found in CVS.

Virtlink, if I remember right, it wasn't the only reason.

Any documentation system should be easy to maintain and automatically generate index files, update links etc.

Halibut works just fine. The only disadvantage is that it cannot output files to compile HTML Help.

This feature could be added easily, if someone wants to help us.

Part of a post originally posted by kichik
Virtlink, if I remember right, it wasn't the only reason.

You are propably right, but I don't recall the other reasons (they are propably there, but I don't have the time to look them up 🙂).

Any documentation system should be easy to maintain and automatically generate index files, update links etc.

Had a time I suffered by maintaining a site, was a very small but with a gigantic difficulty to maintain. Now it is now abandoned. After that, I know now how is to suffer maintaining pages or small sites by one person... If is to maintain a documentation with several pages, several persons can be more easy than just one working.