In a message of Thu, 14 Jun 2007 22:24:23 BST, Joaquim Baptista writes:
>On 2007/06/14, at 05:19, Laura Creighton wrote:
>> What I have had the need for is to make a standard doc, say 'how
>> to get to Open End' whch everybody in the company shares, and is
>> kept up to date about airport regulations, how to use the tram
>> system, nice htings to see, and other stuff we think our customers
>> would like to know. We have two versions of most of the text in
>> this doc -- one in Swedish and one in English. We also have maps
>> and photographs which get included into both versions.
>> Then my father decides to come visit me in Sweden. What I would like
>> to do is send him a doc that is basically the same doc as we give
>> customers, but with certain paragraphs replaced, and some new ones
>> (such as directions to my _house_, my private home phone number
>> and the like added.)
>> Is this the sort of use you are envisioning? or what?
>In general, there are three different ways to achieve that purpose:
>1) Copy and change.
>You grab a copy of the document, change whatever you see fit, and
>While in general you have two completely different documents with a
>corresponding maintenance problem, you may be using a system that
>somehow remembers that one document is derived from the other, and
>can help update the derived document when the source changes.
>This is what you typically do with Word, typically with no support to
>track derived documents.
This is what we _really_ _really_ hate. And so does every other
word user I have talked to. Indeed this is one of the main reasons
people want to move to ReST -- so they can stick their files into
svn and manage them the way that they manage code.
>2) Conditional text.
>You have a document where some parts are marked as conditional,
>depending on the value of some external parameter.
>By planning in advance, you may be able to generate several derived
>documents using combinations of parameter values.
>FrameMaker supports this approach. It works well when you have a
>small number of variations (such as Unix/Windows/Mac plus beginner/
This works fine if you only have to generate the various documents
_once_. Or if there is an implicity 'up to date' version, and you only
want to generate that, albeit in 3 or 4 flavours at all times.
But if you have to re-generate them on a regular basis and
it is important that all readers of the 'How to get to Open End
Document, version 6.17 2007.02.12' read the same document while
the document can be generated at any time, this does not work.
>3) Text component.
>You have a set of identifiable text snippets, and a way to combine
>those snippets into several output documents.
>DITA supports this approach.
>The multi-file input proposal supports but does not require (3).
>By planning in advance, you may store your document as a set of text
>snippets (on in each file).
>For example, two files have the airport regulations (one in English,
>the other in Swedish), two other files talk about the tram system,
>and so on.
>With this setup, you can have multiple super-documents that combine
>different text snippets in different ways, such as:
>- Company English version
>- Company Swedish version
>- Company multilingual version
>- Private for Laura Creighton's father, combining some of the English
>text snippets with private directions to Laura's house and a full set
>The text component approach is very powerful: by adopting suitable
>rules of what is a text snippet, you can quickly publish variations
>of documents for specific purposes without any special advanced
This is what we are doing now, and it works out better than the
other approaches. I want to get this sort of functionality
out-of-the-box from ReST. Looks Like I can, great. The next
step will be to build an interactive 'superdocument builder'.
The marketing departments of the world are going to love this.
thank you, and
you take care,