This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.
The online help for the XML Catalog module appears when you click Help in the Add New Catalog dialog. It explains some things fine. But it is missing a fuller description of what kinds of catalogs are supported and what to choose. For example, I wanted to add www/www/dtds/catalog (see NB sources) which it turns out is a standard but older catalog format. I did not know what the official name of this format was. The online help was not helpful here. It mentioned OASIS #XXXX (don't remember what) and also gave one link. Is my format supported? Should I choose Sun Resolver 1.1 (whatever that means)? Or XML Catalog? (I have a catalog of XML entities, does that count, or does this mean a catalog written in XML?) In fact choosing Sun Resolver 1.1 worked fine. (I chose XML Catalog first, typing in a file:/// URL, and it gave no errors but showed no subnodes of the catalog, i.e. no entities - hmm, assume this means it did not work.) Suggest: write out a complete list of catalog formats supported by the module. For each one, give (1) its official name, (2) a URL giving more information on the format (e.g. official spec), (3) a *brief* example of it, i.e. just a tiny sample catalog in that format that you can compare your own to, (4) instructions for which kind of catalog to select in the dialog (assume the user has no idea what was supported by Sun's Resolver 1.1). If there are any popular formats *not* supported it would be good to mention that as well.
I did a little more work on the XML docs yesterday but the catalogs page definitely needs more work. Petr, could you send me a short description and sample for each of the catalog formats. Also, would it be possible for the user to just enter the location of the file and have the IDE automatically detect what catalog format it is, rather than having to explicitly choose a format? The IDE should at least recognize when a mounted file isn't a valid catalog and alert the user.
Autodetection would be nice but might not be reliable. Here's one option: make the XML Catalogs root node provide NewTemplateAction.Cookie, and have a Templates/XMLCatalogs/ folder in the system file system. Then the real New wizard would be opened, complete with possible custom wizard sequences if desired, and an HTML description for each kind of catalog. More work than a docs fix of course, just a UI idea.
We'll definitely do the docs fix but I think having a New Catalog function on the XML Catalog root node is a good idea too. I think the reason we don't provide templates for other catalog formats is because we want to encourage people to use OASIS format when creating new catalog files. Is that right, Petr?
So there is the list: Catalog formats: - XCatalog 0.2 format can be identified by <XCatalog> root element, no specs except a DTD exits. - XMLCatalog 0.4 format can be identified by <XMLCatalog> root element, no specs except a DTD exits. - OASIS XML Catalog 1.0 format can be identified by <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> root element. It deprecates all above formats. Its specs is available at http://www.oasis-open.org/committees/entity/spec.html - OASIS TR9401 format also known as SOCAT is a plain text file. Specs is at http://www.oasis-open.org/cover/sotr9401-a2.html Catalog readers support: XML Catalog: XMLCatalog 0.4 and XCatalog 0.2 Sun's Resolver: OASIS XML Catalog, TR9401 and XCatalog 0.2 Netbeans Catalog: in memory catalog of entities needed by modules And of cource other readers may by plugged in. Web module for example plugges-in a catalog similar to NetBeans one providing entities defined by DD specification.
The <XCatalog> root element is recommended but not required for XCatalog 0.2. The XMLCatalog 0.4 proposal recommends a root <Catalog> entry (not <XMLCatalog>), but again it's not required. What if I just make include the DTD for each of these in the help set, it seems like the most straightforward way to see how they work. It'd be nice to put them in popups but the OASIS DTD is pretty long for a popup so I'll probably have to put them all in separate pages. Jessie, popups don't have scroll bars, do they? For TR9401 I'll just put a link to the spec.
I wouldn't recommend putting DTDs in a popup; they are pretty long and popups are hard to scroll or copy information from. I would recommend the NB help just summarize the root element or general format and give a very small example to jog a user's memory. Users who really don't know how to use the format are better off going to the spec page, i.e. following a link, I think.
John, I would for simplicity stick with root elements. The implementations also requires particular root elements (it is probably the proposal bug to let it just optional - in final specs it is mandatory). I also prefer to mention just links to external standards for users that look for more details.
Ok, we'll do root elements and links to the specs, but I'd also like to give a short example of each format as well. Petr, could you put together some short examples for me for each of the formats? The proposal web pages for the XMLCatalog v0.4 and XCatalog v0.2 both have examples that could be quickly changed so we can use them.
Examples inlined: XCatalog 0.2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ <!DOCTYPE XMLCatalog PUBLIC "-//DTD XCatalog//EN" ""> <XCatalog> <Map PublicID="-//OASIS//DTD XML DocBook V4.1.2//EN" HRef="docbook/xml/docbookx.dtd"/> </XCatalog> XMLCatalog 0.4 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ <!DOCTYPE XMLCatalog PUBLIC "-//DTD XMLCatalog//EN" ""> <XMLCatalog> <Map PublicId="-//OASIS//DTD XML DocBook V4.1.2//EN" HRef="docbook/xml/docbookx.dtd"/> </XMLCatalog> Oasis XML Catalog 1.0 ~~~~~~~~~~~~~~~~~~~~~~ <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> <public publicId="-//OASIS//DTD XML DocBook V4.1.2//EN" uri="docbook/xml/docbookx.dtd"/> <system systemId="urn:x-oasis:docbook-xml-v4.1.2" uri="docbook/xml/docbookx.dtd"/> </catalog> TR9401 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PUBLIC "-//OASIS//DTD XML DocBook V4.1.2//EN" "docbookx.dtd" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
checked in revised XML catalog docs to release33, please validate that they're all right.
I validated it and: - Sample of XCatalog 0.2 have invalid doctype - <DOCTYPE XMLCatalog PUBLIC ... + <!DOCTYPE XCatalog PUBLIC ... - When the online help for the XML Catalog is called from Add New Catalog dialog I cannot copy the samples into clipboard because the sample dialog is blocked by modal Add dialog.
fixed the invalid doctype in the example. unfortunately the copying problem is a result of the helpsystem's known problems with modal dialogs. then only suggestion is to copy the example before you open the dialog, unfortunately. on the bright side, there's been more talk of a window system redesign for 4.0, so we may get some of the modal problems worked out as part of that.
Window system redesign will have no effect on modality of help windows - this is blocked by a missing JRE enhancement (multiple application contexts). In this case you use <param name="viewerStyle" value="javax.help.SecondaryWindow"> which will never work when help is being invoked from a modal dialog. Try <param name="viewerStyle" value="javax.help.Popup"> and see if that's better.
VERIFIED
Resolved for 3.4.x or earlier, no new info since then -> closing.