Closed Bug 247595 Opened 20 years ago Closed 16 years ago

Use entities to describe menus and dialogs in help documentation

Categories

(Firefox Graveyard :: Help Documentation, defect)

defect
Not set
normal

Tracking

(Not tracked)

RESOLVED WONTFIX
Future

People

(Reporter: benoit.leseul, Assigned: jwalden+fxhelp)

Details

Attachments

(3 files)

User-Agent:       Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:1.7) Gecko/20040614 Firefox/0.9
Build Identifier: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:1.7) Gecko/20040614 Firefox/0.9

This is an idea of Marie Léger-St-Jean, one of the contributors to the
Frenchmozilla l10n team.

Since we are now using XML to format help documents, we could include other
chrome DTDs when required like we already do with brand.dtd to display the
product name. For example if we include chrome://help/locale/help.dtd in
welcome.xhtml, we can write 

 <li><strong>&toctab.label;</strong> shows the list of main topics.<br/>

instead of

 <li><strong>Contents</strong> shows the list of main topics.<br/>

This would help to maintain consistency within help content and the interface.
For example, when a typo is fixed in a menu or a command is clarified, help
content would reflete immediatly this change.


Reproducible: Always
Steps to Reproduce:
This is a proof of concept patch made on our local CVS, we have the same for
the 14 actual firefox help files.
--> me

OK, I can see this. But what happens when the menu item has been removed? I'm
not sure if this will help people a whole lot, but keeping it open until I think
about it more.
Assignee: bugs → rlk
Status: UNCONFIRMED → NEW
Ever confirmed: true
(In reply to comment #2)
> --> me
> 
> OK, I can see this. But what happens when the menu item has been removed? I'm
> not sure if this will help people a whole lot, but keeping it open until I think
> about it more.

Then it'll be easy to spot: if the entity has been removed from the .dtd file
defining it, we'll get an XML parsing error (before the actual release), so it
will be quite obvious that Help is not uptodate.
If it has only been deactivated in the .xul file, the help file will not reflect
that any more than the current system.

If this comes to pass, we'll need something similar for entities defined in
.properties files for use in Javascript rather than C++/XUL.

Vincent
Target Milestone: --- → After Firefox 1.0
Assignee: rlk → jwalden+fxhelp
FYI, this is used in the French Help system in Firefox for several months (since
June) and works flawlessly. 

See
http://lxr.mozilla.org/l10n-aviarybranch/source/browser/locales/fr-FR/chrome/help/
for examples of how it is used. menu_reference.xhtml is probably the most
obvious one.
I think this is a fairly positive move, especially if helps people locate the
correct part of the documentation to fix when they need to. I'm sure it will
also make the process of creating localisations easier especially when taken
alongside swapping, where possible, images for xul elements (some work being
done in bug 249744 on it). The downsides I see are:
a) When entites are removed having broken looking help - is that better than
having out of date help?
b) Less readable help files when looking at the source - still fairly readable
though.
(In reply to comment #5)
> a) When entites are removed having broken looking help - is that better than
> having out of date help?

It may be, that reminds you that your help content is out of date and has to be
fixed. Furthermore, it can only happen in nightlies, since there is a l10n
freeze a few weeks before a release, so it won't affect end-users.
Having slept on it here are some more points:
1) There may need to be some work carried out to make sure that entities within
each help page are unique.
2) I think that reviewers/super-reviewers will have to key one eye on the help
pages and if it is a simple fix to make the help uptodate encourage the patch
writer to include those changes within their patch.
Agree with (1), some entities are overlapping, but very few actually. The only
ones I've seen so far are the Options panels titles (lHeader), which is why they
are not used in h2's in prefs.xhtml. But we wouldn't have used them there anyway
because of other grammar issues.

(2) is a good thing IMHO, but is somewhat orthogonal to this bug. Taking care of
up-to-date help content along other changes could be enforced or not either way.
But using entities in help content can sometimes help to spot places where it
has *not* been done (being that it causes XML parsing errors or that a
description doesn't fit whith its title anymore).
There's no worries about breakage because that simply means we'll notice more
often when things change on it.  If breakage were a concern, we wouldn't be
using XHTML to store the documents.  If it breaks, we'll notice it sooner and
get it fixed sooner.  If we don't use entities, things may appear in better
shape, but we'll have no notice of when things change unless we scan Bonsai, so
we'll in the end be worse off.

Anyways, I'll get to this eventually.  There's plenty of time until 1.1, and the
bugs Help has are on average easily fixed.  In the meantime, tho, I'd appreciate
it if you could have the discussion elsewhere.  I'm aware of the benefits and
downsides to this, and I don't need to hear them again.  ;-)
Status: NEW → ASSIGNED
Hardware: PC → All
After going through the fun of bug 279506, I'm thinking this is looking more and
more useful, even for before 1.1.  Nominally targeting for 1.1, although we may
not actually complete this for then...
Target Milestone: Future → Firefox1.1
I'll take a look at this, but it's unlikely that I'll get it to work.
Attached patch first basic trySplinter Review
I've been very busy lately and this is all I have done so far. This can be the
new proof of concept since the old one used old chrome urls. I've only used two
DTD's so far. Please comment on this.
Attached patch updateSplinter Review
update of my preveous patch. I've added two more dtd's to pref.xhtml. Please
check it out and comment.
I'm very busy and won't work on this until next week, so feel free to work on
it.
sorry for bugspamming but, but editing all the pages by hand and replacing the
phrases with dtd's is a real pain. Is there a tool that can help me?
Target Milestone: Firefox1.1 → Future
This doesn't work with a web-based service as we have now with sumo.
Status: ASSIGNED → RESOLVED
Closed: 16 years ago
Resolution: --- → WONTFIX
Product: Firefox → Firefox Graveyard
You need to log in before you can comment on or make changes to this bug.