NSIS API XML Reference

Hi!

I think it should be useful to standardize the NSIS API and to describe and document them inside an XML format file which should be used by NSIS Editors too to help integration of new features.

Is there someone (also Nullsoft guys) who wants to partecipate to this project?

Anyone already thought about this?
Any comments?

This should be useful also for new Nullsoft and non-Nullsoft software.

Camillo.

NSIS used a customized Halibut version to output XHTML and HTML Help documentation. You would have to modify Halibut to output XML files.

I was looking at something to describe the API and the properties of the parameters that should go with the API.

Like:

<Function name="AddBrandingImage" description="Function to set the bla bla bla...">
<Parameter name="Align" type="enum" enumvalues="top|left" description="bla bla" />
<Option>
<Parameter name="Height" type="int" description="bla bla" />
<Parameter name="Width" type="int" description="bla bla" />
</Option>
</Function>
<Function name="AutoCloseWindow" description="Function to set the bla bla bla...">
<Parameter name="Autoclose" type="enum" enumvalues="false|true" description="bla bla" />
</Function>

And so on...

This is a simple implementation and does not cover every NSIS API.

I think it's a big effort, so we need the help of a Nullsoft dev.

Do you think Halibut can do this kinf of things?

Camillo

That should be possible, but you will have to add support to Halibut.

Finishing NSIS 2 has priority for the developers, maybe some other users want to help you.

Halibut?

Where can I find the Halibut version for NSIS?

Do I have to contact the author? (Who is he?)

I cannot find any info about this Halibut...
Only here:


Thanks,
Camillo

Halibut's sources and executable are in NSIS's CVS. It's a modified version of Halibut.

Halibut &amp; cvs

Ok I downloaded the last shapshot of NSIS cvs dir and I found the source of Halibut and the docs for NSIS documentation.

Two things, please help:
1) I cannot access the cvs repository as an anonymous; I am behind a firewall so I tried the port 80 but this is the result:


D:\Dev\TortoiseCVS>cvs -d😛server:anonymous@cvs-pserver.sf.net:80/cvs/NSIS login

Logging in to 😛server:anonymous@cvs-pserver.sf.net:80:/cvs/NSIS
CVS password:
cvs [login aborted]: authorization failed: server cvs-pserver.sf.net rejected ac
cess to /cvs/NSIS for user anonymous


Know why?

2) I am also a developer and I really would like to integrate my idea in Halibut, but:
- is it possible?
- to whom do I have to ask? is there somebody who is currently working on the project?

Thanks,
Camillo

1. Instructions on using CVS can be found here:
   
   
   http://sourceforge.net/cvs/?group_id=22049
   
   
   After a short look it seems you have just specified the wrong project name.
   
   You can also use NSIS Update which runs CVS for you or the nightly snapshot (available in the development page on the NSIS hoempage).
2. Halibut was originally developed by the same person who wrote PuTTY, I think. I think it would be easier to make a converter from the XML listing you have suggested to Halibut files because there are a lot of other information in the documentation but instructions reference. But if you can fit it all in XML so it will be easier for other programs to read it, it would be even better.

BTW, Virtlink once started a similar project, he might still be interested, so you might be able to work together on this.

Halibut &amp; cvs

1) Well, a few more tries, but nothing moved right:

I changed the server and project name:


D:\Dev\TortoiseCVS>cvs -d😛server:anonymous@cvs.sourceforge.net:80/cvs/nsis login
Logging in to 😛server:anonymous@cvs.sourceforge.net:80:/cvs/nsis
CVS password:
cvs [login aborted]: unrecognized auth response from cvs.sourceforge.net: HTTP/1
.1 400 Bad Request


I changed the project name:


D:\Dev\TortoiseCVS>cvs -d😛server:anonymous@cvs-pserver.sf.net:80/cvs/nsis login

Logging in to 😛server:anonymous@cvs-pserver.sf.net:80:/cvs/nsis
CVS password:
cvs [login aborted]: authorization failed: server cvs-pserver.sf.net rejected ac
cess to /cvs/nsis for user anonymous


Am I doing something wrong?

2) The Virtlink Project (NICE) seems to be unfortunately ended.
Look here: http://nsis.sourceforge.net/archive/....php?pageid=80

Are you saying that it should be good and useful to convert Halibut to use xml instead of its current work files?
This should be a nice project to work on, but unfortunately, I don't know anything about Halibut and can't find any docs about it. Is there something out there?
If not, maybe I should try to develop first a converter to Halibut.

[REEDITED MSG]
Ops, I found what you were talkin about and sent a mail to VirtLink.
Thanx!
[/REEDITED MSG]

Camillo

Why are you trying to access CVS on port 80? The first error you got it because of that (server sent you error 400 - bad request). The second seem to come from a server that has port 80 open especially for people with firewall restrictions. Am I correct?

Anyway, in both cases, you're missing root. It's supposed to be /cvsroot/nsis not in /cvs/nsis. Have a look at that page I linked to in the last post.

I wasn't talking about NICE, I was talking about this thread.

As for converting Halibut to use XML, I don't think that would be wise. I think it will be way easier to create a new program that will process XML only. But that's up to you. I think starting with just a converter will be a good idea, but, again, that's up to you.

We will use whatever form of XML parser you supply us as long, as long as it's maintainable, easy to use, creates both CHM and HTML, open-source, and last but not least - has a relatively small and fast first conversion step from the current method.

1) You were right; this worked for me:

cvs -d😛server:anonymous@cvs-pserver.sf.net:80/cvsroot/nsis login

Yes I am connecting to this server on port 80 because I am behind a firewall... I am at work!

2) Sorry for boring you, but this thing is getting interesting; could you please reply me with 3 lines to explain me the current Halibut method? Who writes the docs,with which software (notepad???) and in which format (BUT files?)? What does Halibut (parses the BUT files and creates both HTML and CHM)?

Thanx for your time!

Camillo

Halibut eats .but files which are simple text files containing certain one line or inline mark-ups. There are mark-ups to start chapters, sections and smaller sections, mark-ups to link to other sections or an external page and some more mark-ups that are usually not used. Using these files it creates HTML pages with contents and splits them according to a setting set in the text files (see config.but in NSIS's case). Our own Halibut version also spits out input for Microsoft's HTML Help compiler (hhc) if asked to (see config_chm.but).

Hi!

I was wondering if you have in mind some design issues for a new documentation software. Maybe more features or corrections for the current software. I think simplicity is the most important key.

Currently I started working on a little app which should convert Halibut's BUT files to a simple simple xml format.
I am stuck with recursive tags at the moment, but I see they are not so used in the current BUT files.

If already going towards XML, I'd like it to be as abstract as possible. For example, the parameter list should be as you described above and not as currently kept. Other than that, there is nothing else I can think of at the moment. I will let you know if something else comes up.

Thanks.

XML Conversion Sample

Hi!

I just completed the converter from Halibut to simple xml.

First step will be to define a simple standard xml format to describe the docs architecture (all very simple) and implement the parser and renderer. Take the current BUT files and convert them to the new xml format.

Next I will work on the parameter list.
This is a bit complicated because NSIS API have many different syntactical behaviours. If you have suggestions on this point please tell me.

I attached to this msg a sample of the BUT files converted to xml.
Just unzip and view with Internet Explorer.
Recursive tags already works.

Camillo

Cool, good work.

I don't think a convertor would really work for the parameter list. The format is pretty loose there... Manual work would be best there.

I don't currently have any suggestions to the format of the XML, but if I think of anything, I'll let you know.

Docs beta release

Hi!

This is the first release of NSIS docs created using simple xml files instead of halibut files.

The process was:
1) Converted BUT files to simple xml.
2) Parsed simple xml and rendered new docs.

The tag are quite the same as those in Halibut, except:
- H tag replaced by T1.
- S# tags replaced by T#+1.
- c tag can be multiline.
- b tag needs <ul> and </ul> for start and end of list.
Other changes could be made easily.

The conversion is completely automatic.

I managed to reproduce the structure of html pages as halibut does, but it can be personalized with the header and footer files.

Now I am going to check the html for any errors, but I think the conversion is quite perfect.

To check it, unzip in a folder and open "toc.html".

Camillo

[UPDATE] Some bugs corrected

Hi!

This is an updated version of the docs produced from xml; I found some bugs in the conversion routine from halibut to xml and corrected them:
- new lines
- pre tags next to ul tags
- preformatted html

Download this one!

PS BUT halibut files are not the latest but those of NSIS2b3. I will update them when I will have a stable version of my software.

PPS The source code of my new doc software will be open source soon.

Camillo

It all looks very great, but I have a few suggestions.

At first, would it be possible to make an Xml Styleheet which provides the markup for the 'halibut-xml'-files. I think it is possible, and it would save you a lot of trouble. You could use Saxon to parse the xml and xslt-files to html files. And it would create the possibility to change the looks of the output html-file without diving into computer code. Another thing is that people with Xml and Xslt-enabled browsers may assign a different stylesheet to the Xml-files, which results in the look-and-feel they desire, which may very well differ from the default look-and-feel.

Just a suggestion, but I think that you should take a look here: http://forums.winamp.com/showthread....000#post916000. I've been working on stylesheets and xml for the documentation of NSIS, and the results looked promising in my eyes.

Keep up the good work! 👍

camillo, cool, getting better 🙂

Any estimate on when the real XML benifit will pop in? I want to know if we'll be able to push it into NSIS 2.

I think a XSLT could save some time, but the program would still need to work out the refernces, links and contents.

kichik:
The xml parser and doc renderer is quite ok.
I'm just struggling with <PRE> formatting... the xml tends (by design xml is so...) to strip out the spaces ' '... maybe I will leave it so for now.
For the xml benefit it's not only a matter of upgrading the xml parser, but also:
1- study a suitable format to express data (e.g. function parameters)
2- make (cut & paste) the xml files

some questions:
1- have you in mind to standardize NSIS API syntax & parameters?
2- do you know every possible syntax for NSIS API parameters? like a radio, checkbox or listbox syntax?

virtlink:
Do you have any simple idea of how to use an xsl schema in this stuff... this is the moment where I need ideas... 🙂
Would you like to help me reviewing current NSIS docs to extrapolate a cool xml format for data and making the xml files?
My idea is like making queries to a db (which is the xml file) and have a few commands to get out the info by name.

Camillo

Well, I can help you. I wrote a stylesheet before, and I think that I figured out how to do it this time.

And I suppose that you mean that you actually need a way to describe the parameters better in XML, and to preserve the whitespace. I think that a stylesheet can preserve whitespace when nescessary, and I also have some toughts about Xml-elements for the parameters (e.g. describing [optional [optional2]] required).

I'll take a look into it today, but not now. 🙂

virtlink:
One thing... the xml parser I am using is a simple xml parser written in C not by me a couple of years ago; I took it, converted to C++ and I am changing it to implement the behaviour I want (like the whitespace problem...); so it is a very simple parser.
The whole project is ANSI C++, so "should" be portable...
The idea is to keep it simple; I would like, if possible, to encapsulate the xls parser into my parser and dont use an external & complicated one (also because xls is written in xml, my xml parser should be enough to parse it).
So we have to work on a simple description language... or I should look for an open source advanced parser or switch definitely to Microsoft MSXML.

Anyway, go on with it!

Camillo

As you've said, the hard part is indeed coming up with the XML schema (description language) and create the XMLs. Because of that, I think it would be best to use an existing XML parser, libxml for example as it seems the fastest one.

I think the schema should consist of three basic blocks, instructions, installer attributes and pre-processor commands. Each command of each type should first describe the number of arguments it can get and then list the different possibilties. There shold be several types of arguemnts - mandatory (function name), from a list (on|off), optional (/o or /e) and probably some type that indicates it is requried only if some other one was used.

From my perspecitive, I think that the syntax should be able to be understood by programs (e.g. be describtable) but should also be used to generate the documentation.

I've created the following example with the File instruction:

<i id="File" cat="basic" syntax="File">

  <d>Adds file(s) to be extracted to the current output path (<see cref="$OUTDIR"/>).</d>

  <p name="/nonfatal" required="0" type="switch">When used, a warning will be issued if no files found instead of an error.</p>

  <p name="/a" required="0" type="switch">When used, the attributes of the file(s) added will be preserved.</p>

  <po required="1">

    <pg>

      <p name="/r" required="0" type="switch">When used, files and directories are added recursively.</p>

      <po required="1" repeat="-1">

        <p name="file" type="filepath">The output filename. Note that the output file name is <see cref="$OUTDIR"/>\filename_portion_of_file,

          or, if no filename specified, the whole tree will go in <see cref="$OUTDIR"/>\last_folder_name.</p>

        <p name="wildcard" type="pathwc">The output path. Note that the whole tree will go in <see cref="$OUTDIR"/>.</p>

      </po>

    </pg>

    <pg>

      <p name="/oname" value="/oname=" required="1" type="text" nospace="1" />

      <p name="file.dat" type="filename" required="1">The output filename.</p>

      <p name="infile.dat" type="filepath" required="1">The input filename (and optionally a fully qualified path).</p>

    </pg>

  </po>

</i>

In this code, the following elements are used:

• I element: An instruction (or attribute).
• P element: An instruction parameter.
• PG element: A group of parameters.
• PO element: The user has to choose one parameter from the parameters contained in this element (i.e. option1 | (option2_1 option2_2) | /switch).
  
  Trough this, all parameters of all instructions, attrbutes, functions, macros, Var, etc.. can be specified.

This seems to me a good description language.
Did you check that every NSIS instruction can be described by such a language?
Should we be more generic and add some more elements that maybe NSIS Docs do not use but that another software could use in the future?

Now we should choose how to implement the parsing of that xml.
The fastest one is implement the parsing intelligence inside the source code.
The smartest is to use an xsl schema which would describe in some manner the xml and which describes the rendering of such an element.

kichik: When will NSIS 2 come out?
How much time do we have?

Part of a post originally posted by camillo
(...)Did you check that every NSIS instruction can be described by such a language?

The File instruction seemed the most complex one to me. So if the File instruction can be described, then with no doubt the others can too.

Part of a post originally posted by camillo
(...)Should we be more generic and add some more elements that maybe NSIS Docs do not use but that another software could use in the future?

Yes, we should. This format's main advantage is that programs can read it too. If that would not be nescessary, then we would just be writing HTML.

Part of a post originally posted by camillo
(...)Now we should choose how to implement the parsing of that xml.
The fastest one is implement the parsing intelligence inside the source code.
The smartest is to use an xsl schema which would describe in some manner the xml and which describes the rendering of such an element.

I agree. I think that an XSL schema would be complicated, but highly modifiable on the other hand. A source code parser would be fast, but wouldn't allow much modification.

I tought that a combined work of the two might be nice. What about a program which parses the 'xml-file for applications' to an 'xml-file which looks like a webpage', which then can be combined with an xsl-file. This would allow users to modify the look of the documentation, and save us a lot of touble getting the stylesheet right. We could use a modified version of the format and stylesheet I made before: http://forums.winamp.com/showthread....000#post916000.

1) Ok for me the xml description of functions can be that one; maybe we should also wait for kichik to see if he has suggestions.

2) What I mean is: do we need a more rich desciption language? So it can include other possibilities?

3) I dont like very much the idea that the browser should parse itself the xsl file to format the page, bacause I think we will be limited to IExplorer6 and we should check for the browser version.

Instead it would be cool that the new software will parse the xsl and generate html from the xml formatted as xsl said.

Rememeber also that additional text must be added to those xml documents to produce the final docs.

Lets take an example:
halibut2xml file: basic.but.xml
xml NSIS function reference: functions.xml
xsl formatting stylesheet: functions.xsl
output file: Chapter1.html

So the process should be:
an xml parser parse the basic.but.xml for preprocessor directives; it finds a tag that tells the parser to include file "functions.xml" and format it as "functions.xsl".
The inclusion converts the file in a complete xml file.
This xml file is then rendered to html to produce output.

Dont know if it is simple to parse xsl and generate html, or if some libraries do the job for me.

NSIS 2 will hopefully be released in less than a month. Not much more is to be done before b5, and after that it's RC1 and then final.

To know if the format will fit every command you really have to go on every command and check. I would start with those who can take an infinite number of parameters such as !if. Does that format work with them?

Part of a post originally posted by camillo
(...)2) What I mean is: do we need a more rich desciption language? So it can include other possibilities?(...)

Any suggestions? I think that while the xml should specify everything as detailed as possible, it also still should be easy to add a new instruction.

Part of a post originally posted by camillo
(...)3) I dont like very much the idea that the browser should parse itself the xsl file to format the page, bacause I think we will be limited to IExplorer6 and we should check for the browser version.(...)

You are right about the compatibility issue. I didn't mean that the ONLY way of reading the docs is by letting the bowser apply the stylesheet. I indeed meant that we also need a program to convert them to HTML, and include them both: the HTML and the XML + stylesheet.

Part of a post originally posted by camillo
(...)Instead it would be cool that the new software will parse the xsl and generate html from the xml formatted as xsl said.(...)

The program Saxon does just that. And it's open source 🙂!

Part of a post originally posted by camillo
(...)Rememeber also that additional text must be added to those xml documents to produce the final docs.(...)

Well, in my example, the extra describing text is included. For the text that can't be described, since they aren't part of an instruction (i.e. a tutorial), different elements (tags) must be invented.

Part of a post originally posted by camillo
(...)An xml parser parse the basic.but.xml for preprocessor directives; it finds a tag that tells the parser to include file "functions.xml" and format it as "functions.xsl".
The inclusion converts the file in a complete xml file.
This xml file is then rendered to html to produce output.
(...)

Do you mean that your program, or any other program, would generate functions.xml from basic.but.xml? Or are the two (functions.xml and basic.but.xml) combined to form the document. I go for the first.

Last part of a post originally posted by kichik
(...)To know if the format will fit every command you really have to go on every command and check. I would start with those who can take an infinite number of parameters such as !if. Does that format work with them?

A 'isinfinite="1"' argument could be set on the P-element (or PO or PG). Then the parser should add the [...] to the end of it.