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.

Bug 191452 - @HelpSetRegistration
Summary: @HelpSetRegistration
Status: RESOLVED FIXED
Alias: None
Product: platform
Classification: Unclassified
Component: Help System (show other bugs)
Version: 7.0
Hardware: All All
: P3 normal (vote)
Assignee: Jesse Glick
URL:
Keywords: API, API_REVIEW_FAST
Depends on: 195242 200138
Blocks:
  Show dependency tree
 
Reported: 2010-10-29 02:26 UTC by Jesse Glick
Modified: 2011-07-14 12:36 UTC (History)
7 users (show)

See Also:
Issue Type: ENHANCEMENT
Exception Reporter:


Attachments
API, processor, usage in dbschema module; apichanges & apisupport wiz TBD (28.06 KB, patch)
2010-10-29 02:26 UTC, Jesse Glick
Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Jesse Glick 2010-10-29 02:26:21 UTC
Created attachment 102703 [details]
API, processor, usage in dbschema module; apichanges & apisupport wiz TBD

It is possible to register JavaHelp help sets in the Platform's expected location, and also run the JH search database indexer, from an annotation processor with no special support from the build system. (Unlike the current JH indexing support in the Ant harness and nbm-maven-plugin, no particular package location is assumed.) In the future this could also run various build-time validation steps as in the current CheckHelpSets - checking that XML metadata files (besides the help set master) are well-formed, even checking for broken links in HTML.

The annotation should be placed on package-info.java, conventionally in the same package as the help set master file itself. The help set must be available in the sourcepath for inspection, so I am just moving the help files into the regular source tree (or for Maven it could be src/main/resources). The result is packed into the regular module JAR; there is no need for a separate docs/*.jar Class-Path extension.

The patch leaves the current JHIndexer task and associated harness infrastructure intact for compatibility reasons.
Comment 1 Jesse Glick 2010-11-01 16:22:46 UTC
Adding others to CC who have done changes to help sets in the past few months.
Comment 2 Irina Filippova 2010-11-02 17:33:09 UTC
Jesse,
are there any actions or implications for help writers in relation to this patch? Should we do anything differently? Sorry, as I do not understand how it relates to writers.
Comment 3 Jesse Glick 2010-11-02 19:30:19 UTC
(In reply to comment #2)
> are there any actions or implications for help writers in relation to this
> patch? Should we do anything differently?

I *think* the only implication is that help files would be in some subtree of src/, rather than javahelp/ as now, for modules making use of the annotation. I CC'd some help writers in case you can think of any particular objection to such a move - e.g. processes in use during help set authoring (beyond building the module and viewing the help set via Help > Contents) which would be broken by the new location.


One minor enhancement to the annotation (and processor) which may be needed that I forgot to include in the patch so far:

/**
 * Helpset-relative HTML filenames to exclude from indexing.
 */
String[] excludes() default {"credits.html"};

For some reason, every helpset seems to include a file by this name with legal junk in it, but it should not pop up in search results.
Comment 4 Jesse Glick 2010-11-08 20:07:03 UTC
apisupport wiz can be done separately. core-main #7b11ce519c8c
Comment 5 Jesse Glick 2010-11-08 20:46:39 UTC
(In reply to comment #4)
> apisupport wiz can be done separately.

core-main #d9ff8f1708d9
Comment 6 Quality Engineering 2010-11-10 06:10:36 UTC
Integrated into 'main-golden', will be available in build *201011100000* on http://bits.netbeans.org/dev/nightly/ (upload may still be in progress)
Changeset: http://hg.netbeans.org/main/rev/7b11ce519c8c
User: Jesse Glick <jglick@netbeans.org>
Log: #191452: @HelpSetRegistration.