Old 12th November 2003, 14:29   #1
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
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.
camillo is offline   Reply With Quote
Old 12th November 2003, 14:36   #2
Joost Verburg
NSIS MUI Dev
 
Join Date: Nov 2001
Posts: 3,717
NSIS used a customized Halibut version to output XHTML and HTML Help documentation. You would have to modify Halibut to output XML files.
Joost Verburg is offline   Reply With Quote
Old 12th November 2003, 14:48   #3
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
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
camillo is offline   Reply With Quote
Old 12th November 2003, 16:02   #4
Joost Verburg
NSIS MUI Dev
 
Join Date: Nov 2001
Posts: 3,717
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.
Joost Verburg is offline   Reply With Quote
Old 12th November 2003, 17:00   #5
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
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
camillo is offline   Reply With Quote
Old 12th November 2003, 17:04   #6
kichik
M.I.A.
[NSIS Dev, Mod]
 
kichik's Avatar
 
Join Date: Oct 2001
Location: Israel
Posts: 11,343
Halibut's sources and executable are in NSIS's CVS. It's a modified version of Halibut.

NSIS FAQ | NSIS Home Page | Donate $
"I hear and I forget. I see and I remember. I do and I understand." -- Confucius
kichik is offline   Reply With Quote
Old 14th November 2003, 12:45   #7
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
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
camillo is offline   Reply With Quote
Old 14th November 2003, 13:03   #8
kichik
M.I.A.
[NSIS Dev, Mod]
 
kichik's Avatar
 
Join Date: Oct 2001
Location: Israel
Posts: 11,343
  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.

NSIS FAQ | NSIS Home Page | Donate $
"I hear and I forget. I see and I remember. I do and I understand." -- Confucius
kichik is offline   Reply With Quote
Old 14th November 2003, 13:27   #9
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
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
camillo is offline   Reply With Quote
Old 14th November 2003, 13:44   #10
kichik
M.I.A.
[NSIS Dev, Mod]
 
kichik's Avatar
 
Join Date: Oct 2001
Location: Israel
Posts: 11,343
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.

NSIS FAQ | NSIS Home Page | Donate $
"I hear and I forget. I see and I remember. I do and I understand." -- Confucius
kichik is offline   Reply With Quote
Old 14th November 2003, 14:02   #11
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
1) You were right; this worked for me:

cvs -dserver: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
camillo is offline   Reply With Quote
Old 14th November 2003, 14:12   #12
kichik
M.I.A.
[NSIS Dev, Mod]
 
kichik's Avatar
 
Join Date: Oct 2001
Location: Israel
Posts: 11,343
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).

NSIS FAQ | NSIS Home Page | Donate $
"I hear and I forget. I see and I remember. I do and I understand." -- Confucius
kichik is offline   Reply With Quote
Old 18th November 2003, 10:05   #13
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
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.
camillo is offline   Reply With Quote
Old 18th November 2003, 12:59   #14
kichik
M.I.A.
[NSIS Dev, Mod]
 
kichik's Avatar
 
Join Date: Oct 2001
Location: Israel
Posts: 11,343
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.

NSIS FAQ | NSIS Home Page | Donate $
"I hear and I forget. I see and I remember. I do and I understand." -- Confucius
kichik is offline   Reply With Quote
Old 19th November 2003, 17:40   #15
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
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
Attached Files
File Type: zip hal2xml.zip (28.1 KB, 183 views)

Last edited by camillo; 19th November 2003 at 18:01.
camillo is offline   Reply With Quote
Old 19th November 2003, 22:36   #16
kichik
M.I.A.
[NSIS Dev, Mod]
 
kichik's Avatar
 
Join Date: Oct 2001
Location: Israel
Posts: 11,343
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.

NSIS FAQ | NSIS Home Page | Donate $
"I hear and I forget. I see and I remember. I do and I understand." -- Confucius
kichik is offline   Reply With Quote
Old 25th November 2003, 18:48   #17
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
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
Attached Files
File Type: zip docs.zip (76.8 KB, 171 views)
camillo is offline   Reply With Quote
Old 26th November 2003, 13:38   #18
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
[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
Attached Files
File Type: zip docs.zip (78.2 KB, 182 views)

Last edited by camillo; 26th November 2003 at 14:14.
camillo is offline   Reply With Quote
Old 26th November 2003, 14:56   #19
virtlink
Major Dude
 
virtlink's Avatar
 
Join Date: Sep 2002
Location: At [4C69:6E6B]
Posts: 561
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!

"I'll quote you when you say something memorable."
- Claudia Pelsmaeker
virtlink is offline   Reply With Quote
Old 26th November 2003, 21:06   #20
kichik
M.I.A.
[NSIS Dev, Mod]
 
kichik's Avatar
 
Join Date: Oct 2001
Location: Israel
Posts: 11,343
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.

NSIS FAQ | NSIS Home Page | Donate $
"I hear and I forget. I see and I remember. I do and I understand." -- Confucius
kichik is offline   Reply With Quote
Old 27th November 2003, 09:17   #21
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
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
camillo is offline   Reply With Quote
Old 27th November 2003, 11:25   #22
virtlink
Major Dude
 
virtlink's Avatar
 
Join Date: Sep 2002
Location: At [4C69:6E6B]
Posts: 561
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.

"I'll quote you when you say something memorable."
- Claudia Pelsmaeker
virtlink is offline   Reply With Quote
Old 27th November 2003, 12:58   #23
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
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
camillo is offline   Reply With Quote
Old 27th November 2003, 14:33   #24
kichik
M.I.A.
[NSIS Dev, Mod]
 
kichik's Avatar
 
Join Date: Oct 2001
Location: Israel
Posts: 11,343
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.

NSIS FAQ | NSIS Home Page | Donate $
"I hear and I forget. I see and I remember. I do and I understand." -- Confucius
kichik is offline   Reply With Quote
Old 28th November 2003, 11:03   #25
virtlink
Major Dude
 
virtlink's Avatar
 
Join Date: Sep 2002
Location: At [4C69:6E6B]
Posts: 561
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:
code:

<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.

"I'll quote you when you say something memorable."
- Claudia Pelsmaeker
virtlink is offline   Reply With Quote
Old 28th November 2003, 12:33   #26
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
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?
camillo is offline   Reply With Quote
Old 28th November 2003, 12:52   #27
virtlink
Major Dude
 
virtlink's Avatar
 
Join Date: Sep 2002
Location: At [4C69:6E6B]
Posts: 561
Quote:
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.

Quote:
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.

Quote:
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.

"I'll quote you when you say something memorable."
- Claudia Pelsmaeker
virtlink is offline   Reply With Quote
Old 28th November 2003, 13:14   #28
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
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.
camillo is offline   Reply With Quote
Old 28th November 2003, 14:22   #29
kichik
M.I.A.
[NSIS Dev, Mod]
 
kichik's Avatar
 
Join Date: Oct 2001
Location: Israel
Posts: 11,343
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?

NSIS FAQ | NSIS Home Page | Donate $
"I hear and I forget. I see and I remember. I do and I understand." -- Confucius
kichik is offline   Reply With Quote
Old 28th November 2003, 15:00   #30
virtlink
Major Dude
 
virtlink's Avatar
 
Join Date: Sep 2002
Location: At [4C69:6E6B]
Posts: 561
Quote:
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.

Quote:
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.

Quote:
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 !

Quote:
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.

Quote:
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.

Quote:
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.

"I'll quote you when you say something memorable."
- Claudia Pelsmaeker
virtlink is offline   Reply With Quote
Old 28th November 2003, 17:09   #31
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
Quote:
Any suggestions?...
I dont have any suggestions for now.
Let's start with this schema and try to apply it to the whole stuff!

Quote:
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.
Let's see if it parses xls and formats xml to html.

Quote:
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!
camillo is offline   Reply With Quote
Old 18th December 2003, 10:56   #32
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
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
camillo is offline   Reply With Quote
Old 18th December 2003, 15:43   #33
virtlink
Major Dude
 
virtlink's Avatar
 
Join Date: Sep 2002
Location: At [4C69:6E6B]
Posts: 561
Re: Help needed for XML & XSLT docs

Quote:
Originally posted by camillo
(...)Virtlink, are you always here?
Not always, but I monitor the forums from time to time.

"I'll quote you when you say something memorable."
- Claudia Pelsmaeker
virtlink is offline   Reply With Quote
Old 19th December 2003, 10:30   #34
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
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
camillo is offline   Reply With Quote
Old 19th December 2003, 12:56   #35
virtlink
Major Dude
 
virtlink's Avatar
 
Join Date: Sep 2002
Location: At [4C69:6E6B]
Posts: 561
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?

"I'll quote you when you say something memorable."
- Claudia Pelsmaeker
virtlink is offline   Reply With Quote
Old 22nd December 2003, 09:44   #36
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
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
camillo is offline   Reply With Quote
Old 22nd December 2003, 11:42   #37
virtlink
Major Dude
 
virtlink's Avatar
 
Join Date: Sep 2002
Location: At [4C69:6E6B]
Posts: 561
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

"I'll quote you when you say something memorable."
- Claudia Pelsmaeker
virtlink is offline   Reply With Quote
Old 22nd December 2003, 11:54   #38
virtlink
Major Dude
 
virtlink's Avatar
 
Join Date: Sep 2002
Location: At [4C69:6E6B]
Posts: 561
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)?

"I'll quote you when you say something memorable."
- Claudia Pelsmaeker
virtlink is offline   Reply With Quote
Old 22nd December 2003, 12:56   #39
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
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
camillo is offline   Reply With Quote
Old 23rd December 2003, 18:39   #40
camillo
Member
 
Join Date: Sep 2002
Location: Milan (Italy)
Posts: 64
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
camillo is offline   Reply With Quote
Reply
Go Back   Winamp & Shoutcast Forums > Developer Center > NSIS Discussion

Thread Tools Search this Thread
Search this Thread:

Advanced Search
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off

Forum Jump