[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-i18n-doc
Subject:    usage of &kappname; in documentation
From:       Frederik Schwarzer <schwarzerf () gmail ! com>
Date:       2009-02-24 22:41:33
Message-ID: 200902242341.34291.schwarzerf () gmail ! com
[Download RAW message or body]

Hi,

for documentation writing there are some entities there to ease the writing 
and maintaining process. One of them is &kappname;.
Until a few weeks ago, the documentation sanitizer on ebn[1] suggested to 
prefer the application's own entity (e.g. &dolphin;) over &kappname;.
This bothered me for quite a long time now so I contacted Frerich Raabe, who 
runs the sanitizer. He told me, that ... oh whatever... stuff happened.
In the end, Frerich, Philip, Burkhard and I decided to drop that rule.
1. http://l10n.kde.org/docs/markup/prologue.html suggests using &kappname;
2. We could not see any apparent downside

Yesterday I changed some application entiries to &kappname; in kdegames and 
received feedback from Marek Laane, the Estonian translator. He said that 
using &kappname; makes translation for some languages more difficult. So I 
reverted the change for that moment. Since I have some difficulties following 
his argument, I want to ask a more broader audience (yes, you) about possible 
pitfalls.

As far as the discussion between Frerich, Philip, Burkhard and me concerned, 
pros and cons are the following:
pros:
- reusability
  this comes in several flavours:
  - documentation snipplets that are used in multiple documents (e.g.
    describing the 'file save' action)
  - copying a doc and changing it for a new application (no, copy&paste is no
    crime in most parts of the world :)
  - translation memory in Lokalize
- scriptability
  some translation teams work with scripts to reduce the workload

cons:
- readability
  If you read &dolphin;, you can tell easily what it will be substituted by
  (if not, it's "Dolphin" :)). &kappname; does not give a hint there.

I think this con is what Marek meant, since there are different word endings 
for different application names/types/something.
What I do not understand is, that kappname is used another 299 times in 
several applications[2]. Are those problematic as well? And the application 
entity is (as far as I can see) the same as the po file name. So, does the po 
file name not carry the same amount of information as the application entity?

Ok, still awake? Good. :)
If you can think of any drawbacks of replacing e.g. &dolphin; with &kappname; 
(still mentioned or not), please list them here so they can be discussed 
properly. Marek, this also goes to you if you think that I didn't get your 
point.


Regards

Disclaimer: Most of the information in this email are boldly taken from other 
people's emails. :)


1 http://www.englishbreakfastnetwork.org/sanitizer/?component=kde-4.x
2 ark, okteta, korn, konsolekalendar, kabcclient, ksirk, kollision, kpat,
  katomic, lskat, kspaceduel, kmahjongg, bovo, ksudoku, ksquares, kreversi,
  kbreakout, kolf, kshisen, ktron, kmousetool, kmouth, kmplayer, kwrite,
  knetworkconf, gwenview, visualdict, kuickshow, kate, kcachegrind
[prev in list] [next in list] [prev in thread] [next in thread]