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)
Firefox Graveyard
Help Documentation
Tracking
(Not tracked)
RESOLVED
WONTFIX
Future
People
(Reporter: benoit.leseul, Assigned: jwalden+fxhelp)
Details
Attachments
(3 files)
31.36 KB,
text/plain
|
Details | |
7.54 KB,
patch
|
Details | Diff | Splinter Review | |
18.31 KB,
patch
|
Details | Diff | Splinter Review |
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.
Comment 2•20 years ago
|
||
--> 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
Comment 3•20 years ago
|
||
(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
Updated•20 years ago
|
Target Milestone: --- → After Firefox 1.0
Updated•20 years ago
|
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).
Assignee | ||
Comment 9•20 years ago
|
||
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
Assignee | ||
Comment 10•19 years ago
|
||
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
Comment 11•19 years ago
|
||
I'll take a look at this, but it's unlikely that I'll get it to work.
Comment 12•19 years ago
|
||
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.
Comment 13•19 years ago
|
||
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.
Comment 14•19 years ago
|
||
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?
Assignee | ||
Updated•19 years ago
|
Target Milestone: Firefox1.1 → Future
Comment 15•16 years ago
|
||
This doesn't work with a web-based service as we have now with sumo.
Status: ASSIGNED → RESOLVED
Closed: 16 years ago
Resolution: --- → WONTFIX
Updated•8 years ago
|
Product: Firefox → Firefox Graveyard
You need to log in
before you can comment on or make changes to this bug.
Description
•