-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Wednesday 04 September 2002 13.41, Pam R wrote:
> But that raises another question in my mind, which is why do we need the > <mousebutton> tag at all? As far as I can see it doesn't affect the final > HTML. HTML isn't always going to be the only output. If it was, we'd write the docs in HTML and be done with it. Marking things up semantically, with no consideration for eventual output format allows the freedom to reuse the same source with any output format, from HTML to PDF to a help screen reader to some of the neat things we're already doing with the documents. Maybe in the future, we'll be able to switch <mousebutton>Left</mousebutton> with Right on the fly, for people who use the mouse left handed, based on their kcontrol settings. XSLT can do that kind of thing, Khelpcenter can also manipulate the XML directly on the fly - if the markup isn't there though, it would be a very large job to go through and add it. Look at the glossary, it's created directly out of a perfectly ordinary docbook file. Or the new expandable contents in the navigation pane of KHelpCenter, also created directly out of the XML source, and these are just baby steps, KHelpCenter has only recently gained itself some interested and capable programmers to maintain it. There's a file in kdebase/khelpcenter/DESIGN with some discussions of future plans, it's long and involved, but here's some idea of (still distant) future plans, which will only be possible if the source is marked up well: * Searching for words in a particular function "Find me the menu entry to do X" as opposed to "What's the keybinding for X". There are words that might be used very often in a particular document (reply, in kmail, for example) but only once or twice each in a particular context. * Putting hooks back into the *applications* so that in khelpcenter, clicking on the name of a dialog or function will open that app at the right place, and perhaps with a tutorial. > I believe that we have far too many markup tags, many of which seem to be > in practice equivalent; <keysym> vs. <keycap> for example. meinproc --check > will happily accept either <keysym>Enter</keysym> or <keycap>Enter</keycap> > so there is no feedback to the author saying whether what he has entered is > the correct choice (which should it be?). So why not have just one tag > here? It should be &Enter;, to save you having to think of these. Everything Frederik wrote about the user.entities file for the translators, applies here too. > There was some discussion a few months ago about the use of the <action> > tag in the Command Reference section of a handbook. As I understand it no > one could come up with a reason for using this tag. Don't remember the discussion, but again, just because we're not using it right now, doesn't mean we can't. KHelpcenter might in future be able to parse out the <action> tag and create a printable reference card of the keybindings (like you used to get as a card in the box with photoshop or wordperfect.) You're right though, we're not using all the markup in the HTML rendering just now, but if it's there, then it's a single line addition to the .css file to render it differently. If someone brings up tomorrow that <mousebutton> should be rendered in bold like the keybindings, it'd take just a few seconds to do it, it will be consistent throughout a single doc, and consistent across all docs, in all languages. In my mind, the real problem is the lack of useful GUI editing tools. For example, it must be either exceedingly easy to flood the text with markup with arbortext or whatever Sun uses, or Sun has far more detailed and rigorous requirements than we do (or more likely both), because the amount of markup in their man page sources are simply terrifying. > I also have to say that what really confuses me as a part-time author is > the different markup that seems to be applied to different parts of a > filename / path, for no apparent good reason. Do you have some examples? Maybe they can be explained. Maybe at some point, some things have been marked up wrongly, I don't know, but if you show me examples, I'll do my best. Regards, - -- Lauri Watts KDE Documentation: http://i18n.kde.org/doc/ -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.7 (FreeBSD) iD8DBQE9dlr//gUyA7PWnacRAsyiAKCVURe5h9FbvgQ+3BstyE0UN814HwCeOdTP riycg+ZIVGMnHhCSlZJlQkc= =9TbA -----END PGP SIGNATURE-----
