DocsProject common entities -- problem with translations?

[Karsten Wade]

On Fri, 2007-04-06 at 08:22 +0200, Nicolas Mailhot wrote:
> Le Ven 6 avril 2007 03:58, Dimitris Glezos a écrit :
> 
> > If we choose 1, we can make sure that we notify those language teams that
> > substitute the entities that the entities have changed. They can then
> > search-and-replace all their files and substitute everything at the same
> > time
> 
> If your problem is only updating release versions, why don't you just make
> an entity with the number ? The number alone won't have the grammar
> problems of the full release string

You are right, that we could solve the numeric problems easily.

And I see from the posts on f-trans-l that it is impossible for us to
use entities for many/most words.

It might help if it was understood what types of the problems that
entities traditionally solve for technical writing.  

Example uses are:

        * A technical writer is working on content that involves using
        multiple GUI tools, such as system-config-securitylevel and
        setroubleshoot.  The tool system-config-securitylevel also has a
        name in the GUI, Security Level Configuration.  To write the
        documentation, the writer is going to refer to these
        applications multiple times.  In each situation, the writer is
        going to need to write:
        
        <command>system-config-securitylevel</command>
        <command>setroubleshoot</command>
        <application>Security Level Configuration</application>
        
        At each typing, errors might be introduced.  Macros could be
        used, which are not a very DocBook XML way of doing things, but
        that could be sufficient.  However, it doesn't take care of the
        other example ...
        
        * Dan Walsh decides that "setroubleshoot" should really be an
        action name, so he changes it to "setroubleshooter".  Without an
        entity, changing that is a mildly complex search and replace
        operation.  In some cases, changing a name can require a grammar
        check.  In English, for example, the articles "a" and "an" are
        used differently.  If Dan changed the name to
        "troubleshootselinux", the writer would need to check every
        article that appeared before the searched-and-replaced text.
        
FWIW, both of those things have happened to me (although Dan Walsh had
nothing to do with it :).  I had a product name change, but fortunately
it was the removal of the word "Enterprise" in the middle of the product
title.  I updated the entity, rebuilt six books, and went on to
something else for the afternoon.  In other situations that happened to
me, I has to to carefully edit grammar after an entity change.

As I look through this, three things are apparent:

1. It's more work on writers without ff entities.
2. It's impossible in some languages for entities to work.
3. Numbers are safe to use for entities, some trademarks may be safe to
use, e.g.
   <!ENTITY FEDVER  "7" >
   <!ENTITY IBM "<trademark class="registered">IBM</trademark>" > 
   <!ENTITY S390 "S/390" >
   ... oh, no way, that has to change to ...
   <!ENTITY S390 "System Z" >

It seems that the writers have to accept the "more work", which could
include coming up with a clever solution to the whole situation.  More
likely, we'll just muddle through somehow.

- Karsten
-- 
Karsten Wade, RHCE, 108 Editor    ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
   quaid.108.redhat.com           |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20070406/e718cb9a/attachment.sig>