Ice documentation

[catalin]

Hi!

I have noticed a few referances in the Ice ( <= 1.2.0) documentation, which are wrong. Of course the greatest majority of them are right. I wonder which system do you use for your documentation? Latex?

I also wonder if the documentation is available in other formats then the pdf file. I am aware of the manual, which comes in html format, but I miss having an searchable version of the pdf file.

Whatever tool you use for documentation, I am pretty sure it can export to, say html. Do you have reasons for publishing the documentation in the pdf format only?

Best regards,
Catalin

[michi]

Originally posted by catalin
Hi!

I have noticed a few referances in the Ice ( <= 1.2.0) documentation, which are wrong.

Hi Catalin,

could you please let me know where you found those, so I can fix them?

I wonder which system do you use for your documentation? Latex?

No, we use FrameMaker.

I also wonder if the documentation is available in other formats then the pdf file. I am aware of the manual, which comes in html format, but I miss having an searchable version of the pdf file.

Whatever tool you use for documentation, I am pretty sure it can export to, say html. Do you have reasons for publishing the documentation in the pdf format only?

It's not trivial to get things to render acceptably in HTML. Frame has a tool that allows generating HTML, by mapping paragraph tags to html tags, but the output from that would necessarily look crude compared to the Frame version. The PDF is searchable, and all the cross-references in the generated PDF get turned into live links. You can also navigate from the table of contents by following the generated hyperlinks there.

I'll have a look at the HTML generation once more and see whether the result is worth the effort.

Cheers,

Michi.

[catalin]

Hi again!

I have marked several inaccuracies in my printed copy (Ice-1.2.0), I can report them as I come across them again (I haven't found that many ). Would you prefer to receive comments on the documentation off-list?

For now I think reference to Section 5.12 on page 238 (10.4.1) should be to Section 6.12, and on page 241, in the example given it says "ExampleI:p2" and maybe it should be "ExampleI:p"?

Which application can be used to search in the "fully searchable" pdf file? I tried to download Adobe Acrobat Reader for Linux from adobe.com and the INSTALL/README file of the latest available version (5.0.1 or something like that) states explicitely that the find/search is not implemented.

As far as I am concerned, it does not matter to me if the html version does not look very well. I would like to try to make an index of it, and use the index for searching. I have looked a bit at Swish++ (and Swish-e) and it seems pretty strait forward. If you provide me with html/txt files of the documentation I can try to do it and make the index available for others too, if I come up with anything usefull.

Regards
Catalin

[raymond]

Originally posted by catalin
Which application can be used to search in the "fully searchable" pdf file? I tried to download Adobe Acrobat Reader for Linux from adobe.com and the INSTALL/README file of the latest available version (5.0.1 or something like that) states explicitely that the find/search is not implemented.

xpdf does a decent job of searching and also supports the internal document links.
It comes with most Linux distributions.

Cheers,

Raymond

[catalin]

Yeah, I must have been blind not to see that button with the binoculars icon on it.

Thanks,
Catalin

[michi]

Originally posted by catalin
Hi again!

I have marked several inaccuracies in my printed copy (Ice-1.2.0), I can report them as I come across them again (I haven't found that many ). Would you prefer to receive comments on the documentation off-list?

No, posting them here will be fine. At least, that way, other people get to see where we screwed up too

I'll check all the issues you found and fix them, if necessary. Thanks for that! Bug reports are really important to us -- they are a big part of the ongoing work of making Ice a better product, and we really appreciate the time taken by our customers to let us know about bugs!

As far as I am concerned, it does not matter to me if the html version does not look very well. I would like to try to make an index of it, and use the index for searching. I have looked a bit at Swish++ (and Swish-e) and it seems pretty strait forward. If you provide me with html/txt files of the documentation I can try to do it and make the index available for others too, if I come up with anything usefull.

As I said, I'll have a look at generating HTML once more, but it's low priority right now.

Cheers,

Michi.