[kde-doc-english]Doc for konqueror

[Lauri Watts]

-----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-----