138225 - Add private entities for branding

Status: VERIFIED WONTFIX

(Core :: DOM: HTML Parser, defect, P3)

Description

[Mike Kaply [:mkaply]]

One of the big issues we have in trying to use Netscape help within Mozilla is 
the lack of an easy way to substitute branding names within the HTML files.

What I'd like to propose is the addition of a few private entities that allow us 
to accomplish.

They would look like:

&brandShortName;
&vendorShortName;
&sidebarName;

And would substitute with the values in brand.properties.

I'm attaching a patch for this.

Comment 1

[Mike Kaply [:mkaply]]

Attachment: Patch to CNavDTD.cpp to support private entities

I have designed this patch in such a way that it should have no effect on
existing entity lookups.

The code is only executed in the case where the entity is incorrect in the
first place.

If it is incorrect, we see if it matches any of the values in brand.properties,
and if it does, we query that value and use it in the HTML.

Comment 2

[Christopher Hoess (gone)]

Why not just write the files in XHTML?  I thought we loaded external DTDs...

Comment 3

[Mike Kaply [:mkaply]]

> Why not just write the files in XHTML?  I thought we loaded external DTDs...

That's definitely the future plan, XHTML and XBL.

What we are looking for right now is something to address the short term 
problem.

Comment 4

[Heikki Toivonen (remove -bugzilla when emailing directly)]

I don't like this hack.

I would prefer if we made our own Help public id and added that to our hardcoded
XML Catalog. That DTD would only have those entities we need. That DTD could
even include the XHTML and/or MathML or any other DTDs it needs in the res/dtd
folder.

Comment 5

[Mike Kaply [:mkaply]]

If someone would like to post an actual example of using an external entity 
reference from an external DTD in XHTML, I'd love to see it - I could never get 
it working.

The issue here is that Mozilla 1.0 is about to be released and there is no time 
to rewrite the help in another format.

So if we want to get help in Mozilla that other companies can use for their 
help, we need to come up with a solution in HTML.

In HTML is the key.

If anyone has a better idea, I am open to that.

Comment 6

[Ian Oeschger (gone)]

Michael - I spoke with Heikki briefly about this. We don't chase external
entities in XHTML, XML, or anything outside of the chrome itself. 

I believe he is proposing that we make these entities part of the special
catalog (like the < entities and others) because we *don't* validate external
references. In other words, we would add a special Help subset to the
catalog--things like &brandshort; &brandlong; &toolsmenu.label; (?), and then be
able to refer to them from the help HTML. 

Comment 7

[Mike Kaply [:mkaply]]

I investigated adding them to the standard set, but it looks like the standard 
HTML entities code only returns PRInt32 values. It cannot be used to return 
streams of text. So for instance, you couldn't return (C) for copyright, only a 
single Unicode character.

Where I put my code was the first place where HTML entity support could use 
something other than just a single unicode character coming back from 
nsHTMLEntities.cpp.

I agree that adding them to the standard set would be better, however I think it 
will be a lot more work, unless I missed some other code that handles entities.

I looked at:

http://lxr.mozilla.org/seamonkey/source/htmlparser/src/nsHTMLEntities.cpp

Comment 8

[Heikki Toivonen (remove -bugzilla when emailing directly)]

Uh, sorry, I assumed this was all XHTML. Ignore my previous comments.

Regarding XML, mozilla reads external entities only in chrome, *and* (sorry I
forgot this earlier) from <bin>/res/dtd directory. When Mozilla opens an XML
file, it first looks if there is a DOCTYPE. If there is DOCTYPE, we try to map
the public id (if any) to system id, and finally try to load the system id
(=filename, if any)  from that magic directory. The special mapping happens
currently for XHTML, MathML and SVG public ids.

I will attach proof of concept testcase that uses only SYSTEM id. If we decide
to implement, we should switch to public id (which would be mapped to system id).

Comment 9

[Heikki Toivonen (remove -bugzilla when emailing directly)]

Attachment: branding.dtd

Save this file into your <bin>/res/dtd folder.

Comment 10

[Heikki Toivonen (remove -bugzilla when emailing directly)]

Attachment: Proof of concept

Now you can just click here, and we will load the XHTML entities because of the
DOCTYPE, and the branding.dtd because I include it in the internal subset (and
I use system id so it is easy to test).

Comment 11

[Mike Kaply [:mkaply]]

Very cool. I've always wondered how to make this work.

How difficult would it be to convert the help to XHTML?

It's mostly about making the HTML well formed, isn't it?

Comment 12

[Heikki Toivonen (remove -bugzilla when emailing directly)]

Yeah, non-validating parsers don't check if the element's are used in valid
context, so it is only a matter of making it well-formed (and testing to see
that all the HTML features you are using work in XHTML as well).

Comment 13

[Christopher Hoess (gone)]

HTML Tidy <URL:http://tidy.sourceforge.net/> should be able to automagically
convert for you, and clean up some of the HTML on the way.

Comment 14

[Ian Oeschger (gone)]

Hey, now that we're on this subject, I am planning on writing up an article or a
doc that addresses some of these issues, since the straight dope on how we
support XML *documents*, various doctypes, entities and related stuff doesn't
seem to be spelled out in any very organized way. Making a small doc proposal
now, which I will want to run by you, heikki, and others.

A while ago I converted some of our help documents to XHTML just for fun
(actually to see how hard this would be, because we've been thinking about it
for a while), and it's really pretty simple. I will see about posting a couple
of test cases of the actual help docs and the bin/res magic you describe.
Heikki, thanks for pitching in here.

Comment 15

[Mike Kaply [:mkaply]]

Attachment: Put brand.dtd in the res/dtd directory

The point of this patch is to put brand.dtd in the res/dtd directory so XHTML
pages can use the branding entities.

Comment 16

[Mike Kaply [:mkaply]]

Attachment: XHTML file that demos this code

If anyone would like to see a demo of this, put brand.dtd in your dtd/res
directory and then open this attachment.

Comment 17

[Mike Kaply [:mkaply]]

OK, very cool information on this front. You can use the brand.dtd from chrome
in XHTML files in the browser.

Just do this:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd" [
<!ENTITY % brandDTD SYSTEM "chrome://global/locale/brand.dtd" >
%brandDTD;
]>

So once we convert the files to XHTML, the branding will be easy.

Comment 18

[Mike Kaply [:mkaply]]

We don't need to fix this since the help is being converted to XHTML and is able
to use brand.dtd directly.

Comment 19

[Daniel Wang]

v