Archive: NSIS API XML Reference
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:
http://www.chiark.greenend.org.uk/~s...m/halibut.html
Thanks,
Camillo
Halibut's sources and executable are in NSIS's CVS. It's a modified version of Halibut.
Halibut & 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:pserver:anonymous@cvs-pserver.sf.net:80/cvs/NSIS login
Logging in to :pserver: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
Halibut & cvs
1) Well, a few more tries, but nothing moved right:
I changed the server and project name:
D:\Dev\TortoiseCVS>cvs -d:pserver:anonymous@cvs.sourceforge.net:80/cvs/nsis login
Logging in to :pserver: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:pserver:anonymous@cvs-pserver.sf.net:80/cvs/nsis login
Logging in to :pserver: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:pserver: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! :up:
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>
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 camilloThe 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.
(...)Did you check that every NSIS instruction can be described by such a language?
Part of a post originally posted by camilloYes, 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.
(...)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?
Part of a post originally posted by camilloI 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.
(...)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.
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 camilloAny 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.
(...)2) What I mean is: do we need a more rich desciption language? So it can include other possibilities?(...)
Part of a post originally posted by camilloYou 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.
(...)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.(...)
Part of a post originally posted by camilloThe program Saxon does just that. And it's open source :)!
(...)Instead it would be cool that the new software will parse the xsl and generate html from the xml formatted as xsl said.(...)
Part of a post originally posted by camilloWell, 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.
(...)Rememeber also that additional text must be added to those xml documents to produce the final docs.(...)
Part of a post originally posted by camilloDo 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.
(...)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.
(...)
Last part of a post originally posted by kichikA '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.
(...)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?
Any suggestions?...I dont have any suggestions for now.
You are right about the compatibility issue...Ok I will try to use "libxml" to parse xls: saxon is in java, libxml is in C.
Do you mean that your program...I was meaning the second one... because the xml API should be written separately as a standalone reference (1 for each category: basic, instructions,preprocessor etc.) and then included in the documentation like they were database tables. Doing like this you could have 2 people working on docs at the same moment, a technician and a documenter. I think this is the cleaner solution, but maybe it is not the simplest; anyway, also the first is also a good one (we don't have much time)... maybe let's ask also to NSIS guys!
Help needed for XML & XSLT docs
Anyone want to help making the xml files for NSIS new documentation?
Help needed in rendering xml & xslt files:
Xml files are the archives:
instructions.xml
installer_attributes.xml
preprocessor_commands.xml
Xsl stylesheets:
instructions.xsl
installer_attributes.xsl
preprocessor_commands.xsl
Virtlink, are you always here?
Thanks,
Camillo
Re: Help needed for XML & XSLT docs
Originally posted by camilloNot always, but I monitor the forums from time to time. :D ;)
(...)Virtlink, are you always here?
virtlink: do you have time to make an xslt schema to transalate the xml that you posted previously and compile tha xml file of all instructions?
I'll tell you the steps which I want to use make the new docs:
1) [Human step - but I will get them from halibut files] Make docs pages in pseudo-xml (pseudo because it must not have a top level tag).
2) Divide these files into Chapters and Appendixes, creating Chapter1.xml, Chapter2.xml etc.
2) [Human step] Make standalone-xml-data files (functions, instructions etc.)
3) Apply stylesheet to transform standalone-xml-data files to xml-data (for example: apply instructions.xsl to instructions.xml).
4) Include the transformed xml-data in the previously generated xml docs (Chapter1.xml, Chapter2.xml etc.).
5) Process xml docs and replace reference and links.
6) Apply formatting stylesheet to the whole project to produce html pages.
7) Add header and footer to pages with chapter index.
We should have 1 stylesheet for each data category (instructions, attributes, commands)? Or 1 for all?
Then we need another formatting xslt to translate to html, but this is simpler.
Tell me what do you think!
If anybody is interested in this, tell me!
Camillo
I still son't understand this very well, but please tell be if I'm wrong:
There are source files (generated from the .but files), then we transform them using some stylesheet. The output is another file (still Xml), which has to be transformed to Html using another stylesheet.
Can you give some lines of example Xml/Html code for each step?
Working (i hope) Demo!
The file is to big to be attached to this message (about 1 MB). Download it from here:
http://www.webplus.it/camillo/download/doxtest.zip
This zip file must be unzipped in a dir (if it is the root of a drive is better, because you will need to change a couple of paths to make it works in a directory different from "E:".
There is a "_README" directory that contains:
- Architecture design (NSISDocsArchitecture.tif)
- Important infos (readme.txt)
The architecture is made up of 5 layers:
- Pseudo-xml layer
- Data layer
- Business layer
- Presentation layer
- HTML layer
1) Pseudo-xml is the markup language which I defined taking some rules from Halibut:
C = chapter
A = appendix
T# = paragraph
R = internal reference
L = link
W = web link
etc.
This files are clled psudo-xml because the xml top level element is missing.
2) Data layer is like a database and contains the standalone xml files which must contain instructions, attributes, commands etc.
Data layer is converted in pseudo-xml with appropriate xsl transforms.
3) Business layer is the conversion of pseudo-xml to real xml with the inclusion of files generated from data layer.
4) Presentation layer is the conversion of business layer replacing all reference and internal links.
5) HTML layer is the conversion of presentation layer into html with another xsl Transform.
Tell me if it works on your machine!
On my machine this is a working example (from halibut files to html documentation). Conversion from halibut to pseudo-xml is separated from the process because it must be done only once. Don't do it, because I added some lines to pseudo-xml converted from Halibut to test the include feature.
Camillo
I've looked at the (great) samples, and read trough your description and the 'architecture'-image twice.
I think that I understand it now, but please correct me if I'm wrong:
There are source files. These are combined with the 'pseudo-xml' files. The 'pseudo-xml' files contain how the data in the source files is layouted (one instruction per page, or all instructions per chapter, etc..). Then you have files which can be converted to Html easely.
I left out some steps (link supstitution, data rendering, etc..) but I am aware of that, and I think that my description above gives a more general point of view (yours is very detailed).
- Daniël
B.t.w., is it true that most of the text and descriptions now contained in 'pseudo'-xml .but.xml-files should be contained in the data files (in the \dl folder)?
Yes, you are right:
"most of the text and descriptions now contained in 'pseudo'-xml .but.xml-files should be contained in the data files (in the \dl folder)"
I left them only to have the current situation.
When the data files will be ready, we will strip out repetitions.
What you call "source files" I prefer to call "data files", but it's ok; they are "combined" (xsl transformed and included) in 'pseudo-xml' files; the 'pseudo-xml' files contain how the data in the 'source files' is layouted (processed and xsl transformed).
BUT the first xsl-transform to source-files (i.e. instructions.xsl) contains the description of layout of "source files" in our pseudo-xml markup language. Infact to every <i> tag is added a <T2> tag to define a new paragraph.
Camillo
Kichik: will NSIS 2 be released shortly?
I will be out from the 25th of December until the 6th of January, but I can reach my email and NSIS forum.
Did you download the zip? How do you think the job is going on?
Virtlink: can you help me editing the source-files (those in the dt) directory while I am away?
Tell me if the software I sent you is working well!
If you have time, can you think also at the html rendering?
Camillo
Archive: NSIS API XML Reference
Your program works, but I have a suggestion.
Maybe it would be a little bit easier to build a program which converts the files in the dl-folder to their rendered equalivents.
Creating a stylesheet for them seems a little bit unnescessary IMHO, since (if we do it correctly), the syntax should never change.
And in case the syntax changes (added functionality), then much more has to change anyway. A little bit digging in the C++ program would be a lot easier than learning Xslt from the beginning. And I think that there are more people on these forums who know C++ than Xslt-stylesheets.
I will try to write a small Console program for it in C#, but then should you translate it to C++.
I think that using a stylesheet is much more simple, because you don't have to change the C++ code.
Also non-programmers could do it and use it.
Just do a xsl:for...next and format the item as you like...
Next I need that rendered "dl" files should contain paragraphs (T1,T2) to be referenced from the documents.
Anyway make a little sample of what you think about it and we'll see if it works better.
More: think about this software as a generic documentation software, not only for NSIS; so the "dl" files can change quickly and doing a new C++ code for each would be a useless mess.
I was thinking that the "instructions.xsl" file should transform the "instructions.xml" file in a near-html fashion, with tables and layout, but still our markup language tag for defining paragraphs and links.
Camillo