(due to sad family circumstances it took somewhat longer to reply) Hi,
Christian Leutloff <[EMAIL PROTECTED]> writes: [snip] > One important aspect is the internationalisation of our > documents. I've translated our installation manual into the german > language. The first translation is relatively easy. But it's a pain to > keep track on the changes in the original document. Therefor I suppose > a mechanism to move all important changes to each language version of > a specific document and leave the exact wording to the feeling of the > native speaker. > > My idea is to maintain a skeleton which contain all the important > informations including figures and examples. This skeleton should be > part of every document. By comparing the skeletons we can find the > parts of a document that needs an update. Excellent ideas! > <------------------ start > Synchronization > > The main problem with translations is to keep them up to date. It's a bad > solution to feed diffs to each maintainer of the entire translation, i.e., > if the central maintainer changed a paragraph to clarify a sentence there is > nothing to do for all the translations because they have explained it their > way. So I propose to use a unique skeleton that's a summary of all important > facts. Only changes to this skeleton has to be distributed to the > translators. > > The skeleton can be used to discuss the content of new sections or changed > sections to get high quality documents. After we've agreed on a skeleton the > resulting document parts can be written parallel by different authors and in > different languages. It's also possible to automatically check documents how > up to date they are, by building the diffs of the skeletons included in each > document. > > Integral part of the skeleton are figures and examples. They are easy > translated and contain the important informations of the section. I think > that our manuals are really good, when the informations can be completely > obtained from the figures and examples. > ---------------------------------------------------------------------------- > > 4.1 Skeleton > > The skeleton should be an integral part of the document. Therefore it should > be placed somewhere around the sectioning tags. The skeleton area is > introduced with the <skeleton> tag. The whole area is ignored like a comment > by all the target formats. After the <skeleton> tag follows the > corresponding sectioning command. Each aspect is then introduced by > <aspect>. It should contain the central phrase and the corresponding figures > and examples. > > <skeleton> > <sect>Skeleton tags > <aspect>start tag > <aspect>aspect tag > <example>dpm0001.expl > <figure>dpm0815.fig > <aspect done>full filled with appropriate content > </skeleton> > > The skeleton can contain additional information about the author and/or > maintainer of the skeleton, the date and the version number. > ---------------------------------------------------------------------------- > > 4.2 Examples > > Most examples will contain some shell commands with the entire results. We > should use a different shell prompt for user commands and superuser > commands. What about > > [EMAIL PROTECTED] > [EMAIL PROTECTED] > > and if the path is important > > [EMAIL PROTECTED]/act/path]$ > [EMAIL PROTECTED]/act/path]# > > Lines in examples shouldn't be longer than 75 characters, because it's not > wise to let the formatter restructure the examples. > > Where possible examples should be translated. It's therefore important to > use unique strings which can be replaced automatically. > ---------------------------------------------------------------------------- > > 4.3 Figures > > Figures can be used to visualize most information that's normally described > with text. It's more difficult to put the same information in a picture but > it's worth to take the effort. We are thinking with images and therefor it's > much easier to understand pictures that the written text. Another advantage > is that most images are easy to understand in different languages. There > isn't a speech barrier when exchanging images. That's the reasons why it's > important to have as many figures in our documentation as possible. > > Figures can be used for the following items: > > * to demonstrate how programs interact > * to show what's a program doing > * to visualize the command line syntax by using small pictographies for > each component > * to show the flow of informations > > For our figures we should use a format where the text strings can > automatically be replaced through the language specific ones. Possible > formats include xfig and LaTeX. Both can be converted to a format for the > WWW and printing. The only possible problem in using language specific terms in figures might be the different space needed, but let's see how it works out. > Which format should we use for the WWW? The non-free gif, the free but > sometimes large jpeg or the new not jet known to every web browser png? > <----------- end Christian, excellent proposal. I'm absolutely in favour of using it. Why don't we make this a goal/policy for Debian 2.1? Concerning the graphic format, I propose to use gif or jpeg (maybe depending on the resulting size, maybe) for now until png is viewable by the majority of browsers. Thanks, Ardo -- Ardo van Rangelrooij home email: [EMAIL PROTECTED], [EMAIL PROTECTED] home page: http://www.tip.nl/users/ardo.van.rangelrooij PGP fp: 3B 1F 21 72 00 5C 3A 73 7F 72 DF D9 90 78 47 F9 -- TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to [EMAIL PROTECTED] . Trouble? e-mail to [EMAIL PROTECTED] .
