Re: Docbook versus Home-Grown

[Steve Rickaby]

At 11:22 -0700 7/10/06, Joe Malin wrote:

Well, I *finally* finished the new book for our next software release, so I 
can justifiably turn my attention to getting myself into structured docs.

I am not going to go with DITA just yet. My plan is to convert my existing 
unstructured docs to structure first, and then start the next round of docs in 
DITA. So, my first decision is what EDD to use. Should I develop an EDD myself 
from scratch, or start with the DocBook EDD? My only hesitation in using the 
DocBook EDD is that it will have a lot of elements that I don't want to use.

Any advice, particularly from those who have gone the same route, would be 
much appreciated.

Hi Joe

I was in exactly the same position about a year and a half ago, and was 
involved in a most helpful discussion with several structured experts on this 
list, so first off you should fine some relevant stuff in the archives. One 
thread was titled 'Structured Frame novice falls in at the deep end' (that was 
me), another 'Structure/Schema - Custom or off the shelf?'. If that fails for 
you, mail me off-list and I'll forward something.

The issue you raise is a big one and one that can have ramifications down the 
line. In the end, the right route for me was a 'roll your own' EDD, but that 
doesn't mean that it's the right one for you. I think of it as the 'BigSmall' 
decision, but that will have no resonances for anyone who doesn't watch UK 
commercial television (it features on a Toyota ad for the Yaris).

There are many pros and cons in both approaches. If you are new to structure, 
as I was, you will be floundering in trying to cut down a big EDD, whereas with 
familiarity it would not be too bad a job. Conversely, again if you are new to 
structure, writing your own simple EDD from the ground up is a great way to 
learn.

There is also Scriptorium's 'DocFrame' product, which as I understand it is 
DocBook tamed: http://www.scriptorium.com/docframe/index.html. I believe that 
there are people on the list who have used it, although I haven't. Clearly, you 
have to pay for it.

Orthogonal to the decision you are battling with, and applying only if you 
'roll your own', is the decision over how much authority you will give the EDD 
over formatting. Again, molto argumentos. Some things, such as indented lists, 
are easier if the EDD is given some formatting authority (ie. 'if level 2, set 
indent to X'), although my current preference is to keep structure and 
presentation completely separate, the first in the EDD  (i.e. 'if list level 2, 
set para tag X') and the second in the template. This is in line with what I 
beleive software folks refer to as 'the principle of the separation of 
concerns'.

HTH

-- 
Steve
___


You are currently subscribed to Framers as [EMAIL PROTECTED]

Send list messages to [EMAIL PROTECTED]

To unsubscribe send a blank email to 
[EMAIL PROTECTED]
or visit 
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com

Send administrative questions to [EMAIL PROTECTED] Visit
http://www.frameusers.com/ for more resources and info.

Camtasia

[James Barrow]

Hmmm...is there a Camtasia list that I can join?  Let's see if I can get
away with posting a question here and on WWP :^)

Now that I've finished my documentation, my boss wants me to create
tutorials, so he purchased Camtasia.  Very nice application.

I listened to/looked at some of the tutorials that the previous tech writer
created and found them to be fairly good.  Although her voice sounded like a
transmission between StarFleet and the Enterprise, she was able to run
through an entire procedure without stopping.  How?  I'll never know.

I created two tutorials last week and basically had to split the various
step procedures into quarters.  More accurately, I had to split the software
screens I was talking about in quarters, talk about each quarter, while
taking breaks between each.

Is this how most of you create tutorials?

- Jim

___


You are currently subscribed to Framers as [EMAIL PROTECTED]

Send list messages to [EMAIL PROTECTED]

To unsubscribe send a blank email to
[EMAIL PROTECTED]
or visit 
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com

Send administrative questions to [EMAIL PROTECTED] Visit
http://www.frameusers.com/ for more resources and info.

Re: Copy-and-paste from FrameMaker PDF to text editor, preserving leading spaces?

[Shlomo Perets]

Guy,

You wrote:


If I create a document in FrameMaker, and it contains some blocks of
sample code...

and the code indents blocks for readability...

and I want the reader to be able to copy from the code material and
paste into a Plain Old Text Editor...

is there any way you know of to do this in a manner that will retain the
indentions? ...


The only way that I know of is to embed the original code blocks (with the 
required tabs/spaces) as text file annotations in the PDF; these can be 
opened in Acrobat/Reader 6 or higher in the original form.


For more info/examples, see Code Fragments: What You See vs. What You Get
http://www.microtype.com/homeHmmm.html


Shlomo Perets

MicroType, http://www.microtype.com
Training, consulting  add-ons: FrameMaker, Structured FM and Acrobat



___


You are currently subscribed to Framers as [EMAIL PROTECTED]

Send list messages to [EMAIL PROTECTED]

To unsubscribe send a blank email to 
[EMAIL PROTECTED]

or visit 
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com

Send administrative questions to [EMAIL PROTECTED] Visit
http://www.frameusers.com/ for more resources and info.

RE: Docbook versus Home-Grown

[Joe Malin]

Thanks for the quick reply. I have worked in structured FM before, using
someone else's EDD. I think I understand structure pretty well. I have
worked with XML and HTML quite extensively both as a software developer
and as a writer. 

I don't mind writing an EDD from the ground up. What I want to avoid is
producing an EDD that is off-track from easy conversion to DocBook XML.
My overall goal is to convert my unstructured FM to structured FM and
then to XML on the way to HTML. Obviously this will be a long project. 

One of the important constraints is that I have to do it for 0 dollars.
Though I want to have single-source and people here like the idea, I
don't think anyone here needs it urgently enough to spend money on it,
yet.

Joe

 Joe Malin
Technical Writer
(408)625-1623
[EMAIL PROTECTED] 
www.tuvox.com
The views expressed in this document are those of the sender, and do not
necessarily reflect those of TuVox, Inc.
-Original Message-
From: Steve Rickaby [mailto:[EMAIL PROTECTED] 
Sent: Sunday, October 08, 2006 4:36 AM
To: Joe Malin
Cc: framers@FrameUsers.com
Subject: Re: Docbook versus Home-Grown

At 11:22 -0700 7/10/06, Joe Malin wrote:

Well, I *finally* finished the new book for our next software release,
so I can justifiably turn my attention to getting myself into structured
docs.

I am not going to go with DITA just yet. My plan is to convert my
existing unstructured docs to structure first, and then start the next
round of docs in DITA. So, my first decision is what EDD to use. Should
I develop an EDD myself from scratch, or start with the DocBook EDD? My
only hesitation in using the DocBook EDD is that it will have a lot of
elements that I don't want to use.

Any advice, particularly from those who have gone the same route, would
be much appreciated.

Hi Joe

I was in exactly the same position about a year and a half ago, and was
involved in a most helpful discussion with several structured experts on
this list, so first off you should fine some relevant stuff in the
archives. One thread was titled 'Structured Frame novice falls in at the
deep end' (that was me), another 'Structure/Schema - Custom or off the
shelf?'. If that fails for you, mail me off-list and I'll forward
something.

The issue you raise is a big one and one that can have ramifications
down the line. In the end, the right route for me was a 'roll your own'
EDD, but that doesn't mean that it's the right one for you. I think of
it as the 'BigSmall' decision, but that will have no resonances for
anyone who doesn't watch UK commercial television (it features on a
Toyota ad for the Yaris).

There are many pros and cons in both approaches. If you are new to
structure, as I was, you will be floundering in trying to cut down a big
EDD, whereas with familiarity it would not be too bad a job. Conversely,
again if you are new to structure, writing your own simple EDD from the
ground up is a great way to learn.

There is also Scriptorium's 'DocFrame' product, which as I understand it
is DocBook tamed: http://www.scriptorium.com/docframe/index.html. I
believe that there are people on the list who have used it, although I
haven't. Clearly, you have to pay for it.


Orthogonal to the decision you are battling with, and applying only if
you 'roll your own', is the decision over how much authority you will
give the EDD over formatting. Again, molto argumentos. Some things, such
as indented lists, are easier if the EDD is given some formatting
authority (ie. 'if level 2, set indent to X'), although my current
preference is to keep structure and presentation completely separate,
the first in the EDD  (i.e. 'if list level 2, set para tag X') and the
second in the template. This is in line with what I beleive software
folks refer to as 'the principle of the separation of concerns'.

HTH

-- 
Steve
___


You are currently subscribed to Framers as [EMAIL PROTECTED]

Send list messages to [EMAIL PROTECTED]

To unsubscribe send a blank email to
[EMAIL PROTECTED]
or visit 
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com

Send administrative questions to [EMAIL PROTECTED] Visit
http://www.frameusers.com/ for more resources and info.

Docbook versus Home-Grown

[Steve Rickaby]

At 11:22 -0700 7/10/06, Joe Malin wrote:

>Well, I *finally* finished the new book for our next software release, so I 
>can justifiably turn my attention to getting myself into structured docs.
>
>I am not going to go with DITA just yet. My plan is to convert my existing 
>unstructured docs to structure first, and then start the next round of docs in 
>DITA. So, my first decision is what EDD to use. Should I develop an EDD myself 
>from scratch, or start with the DocBook EDD? My only hesitation in using the 
>DocBook EDD is that it will have a lot of elements that I don't want to use.
>
>Any advice, particularly from those who have gone the same route, would be 
>much appreciated.

Hi Joe

I was in exactly the same position about a year and a half ago, and was 
involved in a most helpful discussion with several structured experts on this 
list, so first off you should fine some relevant stuff in the archives. One 
thread was titled 'Structured Frame novice falls in at the deep end' (that was 
me), another 'Structure/Schema - Custom or off the shelf?'. If that fails for 
you, mail me off-list and I'll forward something.

The issue you raise is a big one and one that can have ramifications down the 
line. In the end, the right route for me was a 'roll your own' EDD, but that 
doesn't mean that it's the right one for you. I think of it as the 'BigSmall' 
decision, but that will have no resonances for anyone who doesn't watch UK 
commercial television (it features on a Toyota ad for the Yaris).

There are many pros and cons in both approaches. If you are new to structure, 
as I was, you will be floundering in trying to cut down a big EDD, whereas with 
familiarity it would not be too bad a job. Conversely, again if you are new to 
structure, writing your own simple EDD from the ground up is a great way to 
learn.

There is also Scriptorium's 'DocFrame' product, which as I understand it is 
DocBook tamed: . I believe that 
there are people on the list who have used it, although I haven't. Clearly, you 
have to pay for it.

Orthogonal to the decision you are battling with, and applying only if you 
'roll your own', is the decision over how much authority you will give the EDD 
over formatting. Again, molto argumentos. Some things, such as indented lists, 
are easier if the EDD is given some formatting authority (ie. 'if level 2, set 
indent to X'), although my current preference is to keep structure and 
presentation completely separate, the first in the EDD  (i.e. 'if list level 2, 
set para tag X') and the second in the template. This is in line with what I 
beleive software folks refer to as 'the principle of the separation of 
concerns'.

HTH

-- 
Steve

Camtasia

[James Barrow]

Hmmm...is there a Camtasia list that I can join?  Let's see if I can get
away with posting a question here and on WWP :^)

Now that I've finished my documentation, my boss wants me to create
tutorials, so he purchased Camtasia.  Very nice application.

I listened to/looked at some of the tutorials that the previous tech writer
created and found them to be fairly good.  Although her voice sounded like a
transmission between StarFleet and the Enterprise, she was able to run
through an entire procedure without stopping.  How?  I'll never know.

I created two tutorials last week and basically had to split the various
step procedures into quarters.  More accurately, I had to split the software
screens I was talking about in quarters, talk about each "quarter", while
taking breaks between each.

Is this how most of you create tutorials?

- Jim

Copy-and-paste from FrameMaker PDF to text editor, preserving leading spaces?

[Shlomo Perets]

Guy,

You wrote:

>If I create a document in FrameMaker, and it contains some blocks of
>sample code...
>
>and the code indents blocks for readability...
>
>and I want the reader to be able to copy from the code material and
>paste into a Plain Old Text Editor...
>
>is there any way you know of to do this in a manner that will retain the
>indentions? ...

The only way that I know of is to embed the original code blocks (with the 
required tabs/spaces) as text file annotations in the PDF; these can be 
opened in Acrobat/Reader 6 or higher in the original form.

For more info/examples, see "Code Fragments: What You See vs. What You Get"
http://www.microtype.com/homeHmmm.html


Shlomo Perets

MicroType, http://www.microtype.com
Training, consulting & add-ons: FrameMaker, Structured FM and Acrobat

Docbook versus Home-Grown

[Joe Malin]

Thanks for the quick reply. I have worked in structured FM before, using
someone else's EDD. I think I understand structure pretty well. I have
worked with XML and HTML quite extensively both as a software developer
and as a writer. 

I don't mind writing an EDD from the ground up. What I want to avoid is
producing an EDD that is off-track from easy conversion to DocBook XML.
My overall goal is to convert my unstructured FM to structured FM and
then to XML on the way to HTML. Obviously this will be a long project. 

One of the important constraints is that I have to do it for 0 dollars.
Though I want to have single-source and people here like the idea, I
don't think anyone here needs it urgently enough to spend money on it,
yet.

Joe

 Joe Malin
Technical Writer
(408)625-1623
jmalin at tuvox.com 
www.tuvox.com
The views expressed in this document are those of the sender, and do not
necessarily reflect those of TuVox, Inc.
-Original Message-
From: Steve Rickaby [mailto:srick...@wordmongers.demon.co.uk] 
Sent: Sunday, October 08, 2006 4:36 AM
To: Joe Malin
Cc: framers at FrameUsers.com
Subject: Re: Docbook versus Home-Grown

At 11:22 -0700 7/10/06, Joe Malin wrote:

>Well, I *finally* finished the new book for our next software release,
so I can justifiably turn my attention to getting myself into structured
docs.
>
>I am not going to go with DITA just yet. My plan is to convert my
existing unstructured docs to structure first, and then start the next
round of docs in DITA. So, my first decision is what EDD to use. Should
I develop an EDD myself from scratch, or start with the DocBook EDD? My
only hesitation in using the DocBook EDD is that it will have a lot of
elements that I don't want to use.
>
>Any advice, particularly from those who have gone the same route, would
be much appreciated.

Hi Joe

I was in exactly the same position about a year and a half ago, and was
involved in a most helpful discussion with several structured experts on
this list, so first off you should fine some relevant stuff in the
archives. One thread was titled 'Structured Frame novice falls in at the
deep end' (that was me), another 'Structure/Schema - Custom or off the
shelf?'. If that fails for you, mail me off-list and I'll forward
something.

The issue you raise is a big one and one that can have ramifications
down the line. In the end, the right route for me was a 'roll your own'
EDD, but that doesn't mean that it's the right one for you. I think of
it as the 'BigSmall' decision, but that will have no resonances for
anyone who doesn't watch UK commercial television (it features on a
Toyota ad for the Yaris).

There are many pros and cons in both approaches. If you are new to
structure, as I was, you will be floundering in trying to cut down a big
EDD, whereas with familiarity it would not be too bad a job. Conversely,
again if you are new to structure, writing your own simple EDD from the
ground up is a great way to learn.

There is also Scriptorium's 'DocFrame' product, which as I understand it
is DocBook tamed: . I
believe that there are people on the list who have used it, although I
haven't. Clearly, you have to pay for it.


Orthogonal to the decision you are battling with, and applying only if
you 'roll your own', is the decision over how much authority you will
give the EDD over formatting. Again, molto argumentos. Some things, such
as indented lists, are easier if the EDD is given some formatting
authority (ie. 'if level 2, set indent to X'), although my current
preference is to keep structure and presentation completely separate,
the first in the EDD  (i.e. 'if list level 2, set para tag X') and the
second in the template. This is in line with what I beleive software
folks refer to as 'the principle of the separation of concerns'.

HTH

-- 
Steve

OS 9 Applications on Tiger

[Ann Zdunczyk]

Hi All,

I have a G5 running Panther that I purchased several years ago. A purchased
an upgrade for one of my applications and it requires OS 10.4 (Tiger) to
run. I was told by the Apple rep that Tiger would run my OS 9 applications
on this machine just fine. Since I do not have the New Mac technology, which
I understand will not run OS 9 appications, I should be OK.

So I am asking the people on this list that work on Macs if there are any
problems that they have running into running OS 9 applications with Tiger. I
know you all will tell me the UNVARNISHED truth rather than a rep trying to
sell me the software.

So please let me know of any problems that you have run into with Tiger.

Thanks All
Z

**
Ann Zdunczyk
President
a2z Publishing, Inc.
Language Layout & Translation Consulting
Phone: (336)922-1271
Fax:   (336)922-4980
Cell:  (336)456-4493
http://www.a2z-pub.com
**

Docbook versus Home-Grown

[Lynne A. Price]

At 03:21 PM 10/8/2006, Joe Malin wrote:
>I don't mind writing an EDD from the ground up. What I want to avoid is
>producing an EDD that is off-track from easy conversion to DocBook XML.
>My overall goal is to convert my unstructured FM to structured FM and
>then to XML on the way to HTML. Obviously this will be a long project.

Joe,
   Sounds like you want to create an EDD that is compatible with DocBook 
without being overwhelmed with the number of elements and attributes in 
DocBook. What I do in this situation is:

1) Make a list of all the DocBook elements. One way to do so is to create 
an EDD from DocBook with no r/w rules and from this EDD generate a list of 
all Tag elements.

2) Turn each entry in the list into a drop rule (or generate the list in 
this form to begin with):

element "x" drop;
element "y" drop;
element "z" drop;

3) Review the list and decide which DocBook elements you want to keep. 
Comment out the corresponding rules:

element "x" drop;
/* element "y" drop; */
element "z" drop;

4) Do something similar with attributes.

5) Create a new EDD using the drop rules. FM will not create element 
definitions for the elements you have dropped. Furthermore, it will remove 
mention of them from the general rules of the elements you are retaining. 
The result should be a manageable EDD. You can still use the DocBook DTD.

 --Lynne





Lynne A. Price
Text Structure Consulting, Inc.
Specializing in structured FrameMaker consulting, application development, 
and training
lprice at txstruct.com   http://www.txstruct.com
voice/fax: (510) 583-1505 cell phone: (510) 421-2284