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
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list mailing list fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
