NSIS API XML Reference

Any suggestions?...

I dont have any suggestions for now.
Let's start with this schema and try to apply it to the whole stuff!

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.

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 camillo
(...)Virtlink, are you always here?

Not always, but I monitor the forums from time to time. 😁 😉

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:



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

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