virtlink
7th March 2003 12:55 UTC

New NSIS Documentation
From the reactions I got here to my example XML documentation files with XSL markup, I had the idea that most people liked it.
Sunjammer responsed that he liked the idea, but KiCHiK wants to see if it's easy updateable first. What do you think?

Please download this file (click here), extract it and view 'file.xml' in an XML capable browser (IE 6, maybe IE 5) and state your opinion here.

Please vote too (poll above).

I would like to know what people think about it and if I should continue with writing the XSLT and XML files (together with dark_boy and flizebogen).

kichik
7th March 2003 13:01 UTC

I do recall a certain IRC chat... As I have said back then, if you make it usable we will use it. The layout is good, but halibut still is a lot easier to use.

virtlink
7th March 2003 13:11 UTC

Thanks for your support. I will see what I can do.

Joost Verburg
7th March 2003 14:32 UTC

I agree with kichik. It's good to have a better and more compatible layout for the documentation.

The thing we need is a documentation that is easy to update.

We should have one format for the docs that will be used by all NSIS developers. If you can make it easy, we will use it.

Joel
7th March 2003 20:46 UTC

does the xml "had to be" opened with IE6?

Sunjammer
7th March 2003 20:47 UTC

not if pre transformed by an xslt command line tool into html

RDaneel
7th March 2003 22:25 UTC

Or, there is always IE5... :)

Actually, I mostly live with Mozilla 1.2.1, but keep IE5.5 around for MS tools that *insist* on IE, or for the rare things Mozilla doesn't seem to handle properly... like virtlink's sample. :(

Anyone have the hot clue on how to tell Mozilla to handle this stuff correctly (I mean, heck, Mozilla is all about XML, right)?

Mozilla just goes into a "Loading..." loop when I hand it the "file" or "readme" XML files. Sigh.

Joel
7th March 2003 22:39 UTC

yeah, because not everyone have IE 5.5+.
Why not include html tags, CSS and JS that are supported by IE 4+?

Afrow UK
8th March 2003 00:00 UTC

Why not download IE6? Does you no harm than good to get it!

-Stuart

virtlink
8th March 2003 10:08 UTC

dark_boy: The idea is that you can use tags (like HTML, but different) to write the manual and that the XSLT does the layout. My idea was that a XML page layouted by XSLT is processed by an XML processor to an HTML, which can be read/viewed by every browser (including Mozilla, Opera, Netscape, IE 5.5- etc...). I will post a processed version here soon, for those who can't view the XML.

Sunjammer
8th March 2003 11:14 UTC

Here is a transformed version I made using xsltproc (part of libXML). It includes the css files etc. because those are still needed by the HTML. Just extract and run readme.html.

Virtlink, I hope you don't mind me posting this before you posted your transformed copy.

xsltproc hasn't done exactly the same transformation as IE6 does, Virtlink will post a perfect copy soon I guess, this is just to give those of you waiting a taster.

Sunjammer
8th March 2003 11:18 UTC

Doh I forgot to transform one of the files, please find attached the file.html I missed from the zip. (Rename the file from .zip to .html and place it with the readme.html from the zip above).

virtlink
8th March 2003 12:13 UTC

I really appreciate it that you've already processed them, Sunjammer. I use Saxon to do it, it does even a better job than IE 6 (IE6 misses some spaces in the syntax line (i.e. '/rfile' instead of '/r file'). Saxon doesn't.

But I will try to improve the XML, CSS and XSL-files, (I downloaded 10 megabytes of tutorials today, about CSS, DTD, XML, XSL, XPath, XInclude etc..) and then I will post a better version (with a non scrolling top-bar, for example).

People, please say if you's like the documentation in XML format and if you like the documentation's layout. Thanks!

Joel
8th March 2003 15:19 UTC

Originally posted by Afrow UK
Why not download IE6? Does you no harm than good to get it!

-Stuart

virtlink
8th March 2003 16:49 UTC

I agree with dark_boy. And, those people without IE6 might mave a slow internet connection (as I have) and don't want to download it.

mikem4600
8th March 2003 19:08 UTC

I think that xml-based documentation might be a good idea, as long as it works with most browsers (inlc. Mozilla, Opera...) and not just IE...

virtlink
8th March 2003 19:14 UTC

I will work with all browsers: the XML documentation will be processed to HTML first.

virtlink
18th March 2003 16:53 UTC

New XML format documentation sample
I have been working on the XML documentation, and I have got a new, cooler sample:
A sample of the Page instruction. WARNING! Links will not work. I have included page.html, a parsed html file: for those who haven't got an XML capable browser.

Good luck, and please tell me how you think about it.

kichik
18th March 2003 17:02 UTC

Looks great. The only thing that disturbs me is the that the icon and the gradient on the top right corner have the same color.

Besides that, on the maintenance side, as abstract as you can get it to be will be better. For example, instead of:

<tbl>
  <!-- <tr><th width="25">Option</th><th width="75">Description</th></tr> -->
  <tr><td>license</td><td>Displays a license page.</td></tr>
  <tr><td>components</td><td>Displays a component selection page.</td></tr>
  <tr><td>directory</td><td>Displays an installation directory selection page.</td></tr>
  <tr><td>instfiles</td><td>Displays an installation progress page.</td></tr>
</tbl>

<possibleParmOptionsList>
  <parmOption name="license" desc="Displays a license page.">
  <!-- etc... -->
</possibleParmOptionsList>

virtlink
18th March 2003 18:28 UTC

I agree with that, but the problem is that it is not possible to use tags within values, for example, if I want the word 'license' to be bold:

<possibleParmOptionsList>
  <parmOption name="<b>license</b>" desc="Displays a license page.">
  <!-- etc... -->
</possibleParmOptionsList>

<tbl>
  <!-- <tr><th width="25">Option</th><th width="75">Description</th></tr> -->
  <tr><td><b>license</b></td><td>Displays a license page.</td></tr>
  <!-- etc... --></tr>
</tbl>

kichik
18th March 2003 18:34 UTC

OK, so let it be <parmOpList><op><name>name</name><desc>desc with tags <b>bold</b></desc></parmOpList>.

I have no idea about the colors, maybe a bit darker blue...

Joost Verburg
18th March 2003 18:48 UTC

The style for a certain field will always be te same, style and content should be separated. CSS will be used for the styles.

It really should be easy to update, using HTML formatitting is no option. We won't move to another system when the maintenance will become more difficult.

About the lay-out: I don't like the light blue background image and the small margins. The page is also not really compatible with Mozilla. The XML version has quite some problems, but also the images in the HTML version do now show up right.

Because of the large number of files (one for each command), it should also be possible to create a HTML Help file.

If these problems can be solved it would be a nice system for the documentation. The only problem is the move from Halibut: everything has to be converted.

eccles
20th March 2003 00:11 UTC

Looks good; I think it has legs... I agree that it still should/could be easier/simpler to maintain though.

I think a nice addition would be to make it simpler to link to other documents. Maybe something like

some text that mentions the <inst>File</inst> instruction in passing.

<xsl:template match="//inst">
  <xsl:variable name="name"><xsl:apply-templates /></xsl:variable>
  <a href="../instructions/{$name}.html"><xsl:value-of select="$name" /></a>
</xsl:template>

virtlink
20th March 2003 17:54 UTC

eccles, you seem to know how to deal with XSLT files. Well, to be honest, I only know very little about it. I took all my knowledge from a simple tutorial.
I am sure that there are many things in my .xsl-file that could be done better, but I wouldn't know how. Maybe you can help me.
Thanks for your suggestion, tough.

eccles
20th March 2003 21:25 UTC

Actually, I don't :( I'd just seen xsl:variable used in an example somewhere (while doing some searching). But if I have any more ideas I'll let you know!

virtlink
30th March 2003 14:04 UTC

New XML documentation samples
I have been typing and typing and upgrading the XSLT-file. Attached are some new samples of NSIS documentation pages. Most links don't work since the files aren't written yet.

To make this system go a bit easier, Halibut should be adapted. I don't have any C(++) experience, nor do I have a compiler. Anybody who has experience with parsers and is willing to voluntairly put some time in making a Halibut 2 parser, can PM me.

Joost Verburg
30th March 2003 14:26 UTC

There is still way to much HTML/XML code in the file. It looks nice, but updating it will be very difficult.

A new system should be just as easy as Halibut.

virtlink
30th March 2003 15:45 UTC

I know that. But Halibut just isn't complex enough. Halibut can format code, paragraphs and bullet-lists. But this actually needs something that also can have an instruction in an instruction, like this:

S{This is syntax with a W{http://www.winamp.com}{b{bold link}}.}

kichik
30th March 2003 15:55 UTC

It can do that. It just doesn't have bold that's all. I have added an option to add HTML tags but it won't be very hard to add \b too...

virtlink
30th March 2003 17:34 UTC

So, with a bit work, it would be possible to let it generate XML and push it trough the Saxon XML parser.
And that bold thing, it was just an example.

I have been thinking about Halibut for a week now, and I came up with the following idea:

- When a line doesn't start with a function (i.e. /A), then that line is treated as being a paragraph (like now), and results is: <t>(contents)</t>.

- When a line does start with a function, but no '{' sign follows, the rest of the line (untill the CrLf) is treated as being the parameter of that function (currently, that happens).

- When a line does start with a function, and a '{' sign follows, the rest of the text, untill the right '}' is found, is treated as being the parameter of that function. This way, you can create a code block like this:

/c{
This is code
This is code
This is also code
}

/c This is code
/c This is code
/c This is also code

kichik
30th March 2003 17:46 UTC

Not that useful when considering to the amount of time required. If I am going to invest time in working on halibut it will be dedicated to making it output CHM files.