Re: [platform-ua-dev] BuildHelpIndex ant task problem in 3.2

["Curtis D'Entremont" <curtispd@xxxxxxxxxx>]

Hi Pierre,

To answer some of your follow-ups..

The XHTML 1.0 specification says nothing about .xhtml
being the only file 
extension for xhtml documents:
http://www.w3.org/TR/xhtml1/

- You're correct. This was
a restriction placed by eclipse to make the selection of content producers
and lucene search participants by the platform more efficient. We are currently
exploring supporting the XHTML features for .htm and .html file extensions.
See https://bugs.eclipse.org/bugs/show_bug.cgi?id=135107.

Shouldn't you rather detect xhtml documents that
use dynamic content 
specific markup?

- It can, but there would
be a significant performance cost. For example, if you only have one instance
of dynamic content at the very end of your long document, it has to scan
through the entire document just to find out whether it has dynamic content.

N.B.: using the eclipse specific elements and/or attribute in a valid
xhtml 
document would it make invalid.

- While it is true that it
now contains eclipse-specific content, browsers must still be able to handle
the xhtml and ignore the extra eclipse-specific content. See section 3.2
of User Agent Conformance, criteria 4 and 5:

4. If
a user agent encounters an element it does not recognize, it must process
the element's content. 
5. If
a user agent encounters an attribute it does not recognize, it must ignore
the entire attribute specification (i.e., the attribute and its value).


So it should not break any
browsers as long as they're compliant.

What about xhtml documents without a doctype declaration? How would
they be 
treated?

- It will likely treat it
as HTML. I believe the latest HTML and XHTML versions require the doctype,
but I'm not sure about the older HTML.

The "New and Noteworthy" page for Eclipse
3.2 M6 says about the XHTML 
conversion tool: "In addition to converting the HTML to valid XHTML..."

Shouldn't it rather say "In addition to converting valid HTML to valid
XHTML 
and invalid HTML to well-formed HTML..."?

- You're right, it should
have specified valid HTML.

Can xhtml files and html files coexist in the same documentation plugin?

- Yes.

If my xhtml files don't contain dynamic content, will the search-index
genrerated by Eclipse 3.1.x for my doc plugin be compatible with Eclipse
3.2?

- Yes.

Thanks,
Curtis d'Entremont
Eclipse User Assistance
IBM Toronto Lab

Phone: (905) 413-5754
E-Mail: curtispd@xxxxxxxxxx

"pierre _" <pican123@xxxxxxxxxxx>
Sent by: platform-ua-dev-bounces@xxxxxxxxxxx

06/04/2006 06:08 AM

Please respond to
"Eclipse Platform User Assistance component developers list." <platform-ua-dev@xxxxxxxxxxx>

To	platform-ua-dev@xxxxxxxxxxx
cc
Subject	Re: [platform-ua-dev] BuildHelpIndex ant task problem in 3.2

Hi Curtis,
here are some remarks...

Regards,
Pierre

>1) most of the html files in my doc plugin are already xhtml 1.0. If
I'm
>not
>interested in using search participants, do I have to change the extension
>
>of these files from .html to something else (.xhtml, I presume)?
>
>You have to use the correct extension (.xhtml) in order for searching
and
>dynamic content (filters, includes, anchors) to work properly. The
>platform uses the file extension to determine the type of file it is,
and
>to find the appropriate lucene search participant to index the document
>for searching. The HTML search participant may work in some cases for
>XHTML, but I wouldn't count on it.

The XHTML 1.0 specification says nothing about .xhtml being the only file
extension for xhtml documents:
http://www.w3.org/TR/xhtml1/

Furthermore, the rfc 3236 (eventhough it's not normative) says:
There are three known file extensions that are currently in use for XHTML
1.0; ".xht", ".xhtml", and ".html"
http://www.ietf.org/rfc/rfc3236.txt

It's really a shame that it was decided to enforce such a restrictive (and
annoying) constraint.

I prefer Dejan's idea (bug #135069, comment #1) of detecting xhtml documents
based on the doctype declaration, though it doesn't address the real 
problem.
I doubt the W3C created XHTML 1.0 only for dynamic content in Eclipse Help
System pages.
Shouldn't you rather detect xhtml documents that use dynamic content 
specific markup?
ie based on 
http://www.eclipse.org/eclipse/platform-ua/proposals/xhtml/HelpDynamicContent.html,
xhtml documents containing:
- include element(s)
- filter element(s)
- standard html element(s) with a filter attribrute

N.B.: using the eclipse specific elements and/or attribute in a valid xhtml
document would it make invalid.

That way, "normal" xhtml documents would be indexed as they were
in Eclipse 
3.1.x (and even before).

What about xhtml documents without a doctype declaration? How would they
be 
treated?

>- does it update links in the .html files?
>suppose I have 2 files, a.html and b.html, and there's a link from
a.html
>to
>b.html. In the converted files, is there gonna be a link from a.xhtml
to
>b.xhtml?
>
>Currently it doesn't. I've opened a bug for this on your behalf:
>https://bugs.eclipse.org/bugs/show_bug.cgi?id=135069

The "New and Noteworthy" page for Eclipse 3.2 M6 says about the
XHTML 
conversion tool: "In addition to converting the HTML to valid XHTML..."

Shouldn't it rather say "In addition to converting valid HTML to valid
XHTML 
and invalid HTML to well-formed HTML..."?
Because I looked at the java source code and I haven't found where invalid
html code is supposed to be converted to valid xhtml code.

>- can it be invoked with an ant task?
>
>Not at the moment. The idea is to only have to use it once, rather
than
>maintaining .html files and converting as part of a build process.
If
>you're using tooling to generate the files, I suggest you check if
it's
>possible to tell the tool to generate .xhtml extension instead.

What about files generated by javadoc or by the ConvertSchemaToHtml ant
task, for instance?
Can xhtml files and html files coexist in the same documentation plugin?

If my xhtml files don't contain dynamic content, will the search-index
genrerated by Eclipse 3.1.x for my doc plugin be compatible with Eclipse
3.2?


_______________________________________________
platform-ua-dev mailing list
platform-ua-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/platform-ua-dev