freelanceprogrammers.org Forum Index » XML / XSL
Criteria for evaluating Frame/Word conversion apps?
Joined: 26 Jun 2003
Posts: 20
Criteria for evaluating Frame/Word conversion apps?
The discussion on this list about WebWorks Pro`s move to
XSLT-based processing set me to thinking a bit about what the
critiera should be for evaluating the value of applications with
"convert Frame/Word to some other format" features, including the
export capabilities built into Frame itself (both "plain" Frame 6
and "structured" Frame 7 output).
Here`s my list, in order of "fundamental importantance".
1. Quality/variety of output formats.
What output formats can it produce, and of what quality?
Nothing else matters if it can`t generated quality final output
in the formats you (and your users/customers) need. Be that
HTML, PDF, or, say, nroff/groff man pages.
(By the way, how many conversion applications/systems do you
know of that can generate man pages?)
2. XML.
Can it generate some form of XML and/or does it use XML as its
internal/transitional format?
Why should this be of fundamental importance? I can see many
people saying, If it gives me the kind of final output I need
(HTML or whatever), why should the type of transitional or
internal data format it uses be important to me?
Well, it gets important when you find yourself in the situation
of needing to make the application do something other than what
its designers arbitrarily decided to make it do by default. And
when you need to work with its customization API (if it has
one) and the internal data structures it uses.
It`s very nice at the point to find yourself working with
something that is already widely used elsewhere and that you
are hopefully already somewhat familiar with.[1]
3. XML with inferred hierarchy.
Can it infer a structure where none is explicit in the source?
In plain Frame 6 (and in Word, as far as I know), the native
file format does not capture the structure of your document.
The conversion application must be smart enough to infer that
structure and convert it to form of XML that captures that.
Even plain Frame 6 can handle this correctly. You create a
mappings table in a reference page of the source, and Frame 6
uses it to generate appropriate DIV wrappers in the XML output.
4. XML with no data loss.
Can it convert to XML without losing any data from the source?
Frame 6 "Save As XML" fails here, because it drops index
markers (and drops some other things too, I think).
I think most other apps succeed here too, but don`t know for sure.
5. XML output that has existing transformation support.
Does it just convert the names of your paragraph and character
tags to XML elements with the same names (as Frame 6 does)?
Or can it convert your documents to instances of an XML
schema/DTD for which there is existing transformation support?
Frame 6 fails completely here. And Frame 7 falls short here
too (in my opinion at least), because the DocBook output it
produces is broken in a number of ways. And I suspect that
output from any of the other off-the-shelf "structured
applications" it ships with is probably similarly broken.
The old WWP also failed here, as far as I know (correct me if
I`m wrong, please), because it neither provided off-the-shelf
support for generating XML output in an industry-standard XML
vocabulary -- such as DocBook or TEI -- for which there is
existing transformation support (e.g., the XSL stylesheets from
the DocBook project) nor shipped with transformation support of
some kind for the type of internal XML it did produce.
The new WWP succeeds because it ships with XSLT support for
converting its "WWP XML" format (or whatever its name is) into
HTML and other output formats.
I think OpenOffice may succeed here too, if it does actually
allow you to open standard Word files and then save them as
(Simplified) DocBook XML.
Do any of the other available Frame/Word conversion
applications succeed here?
6. Quality of any "setting up mappings" UI provided.
How good is the UI that it provides for specifying map-to-XML
settings for converting your in-house paragraph and character
tags to whatever XML structures it uses?
Any application that succeeds at #5 should have a well-designed
UI for enabling you to set up mappings. From what I remember of
the WWP UI, it does this a lot better than the UI in
"structured" Frame 7 does.
Other criteria?
--Mike
[1] And it can also be important when you find yourself in the
situation where the provider of the app you have invested time in
learning how to use and customize decides to redesign it in such a
way as to completely get rid of the propriety customization API it
used previously, because they decided, well, that it makes more
sense to design around a portable-and-shareable-among-other-apps
format for which there is already some level of support in just
about every programming language in the universe and that you can
choose to parse and transform using any of about a bazillion
existing, free tools.
--
Michael Smith
http://logopoeia.com/ http://www.oreillynet.com/pub/au/890
[Non-text portions of this message have been removed]
Joined: 11 Mar 2005
Posts: 7
Criteria for evaluating Frame/Word conversion apps?
At 07:42 PM 6/3/2005 +0900, you wrote:
>1. Quality/variety of output formats.
>[snip]
> (By the way, how many conversion applications/systems do you
> know of that can generate man pages?)
Well, WWP can do it. You just have to write the conversion template from
scratch.
>2. XML.
> Can it generate some form of XML and/or does it use XML as its
> internal/transitional format?
I don`t agree with this. If the application is sufficiently customizable,
then I don`t think I care what the underlying format is.
> It`s very nice at the point to find yourself working with
> something that is already widely used elsewhere and that you
> are hopefully already somewhat familiar with.[1]
It`s nice, but it`s not critical if the non-XML format lets you do what you
need to.
>3. XML with inferred hierarchy.
> Can it infer a structure where none is explicit in the source?
AFAIK, there is NO tool that does this well.
>4. XML with no data loss.
> Can it convert to XML without losing any data from the source?
>
> Frame 6 "Save As XML" fails here, because it drops index
> markers (and drops some other things too, I think).
>
> I think most other apps succeed here too, but don`t know for sure.
I don`t think the unstructured FM feature is at all useful in general, so
its specific failings are irrelevant. The fact that the building`s wiring
isn`t up to code is sort of uninteresting when there`s no roof...
>5. XML output that has existing transformation support.
> Does it just convert the names of your paragraph and character
> tags to XML elements with the same names (as Frame 6 does)?
> Or can it convert your documents to instances of an XML
> schema/DTD for which there is existing transformation support?
If you are starting with unstructured content, then I wish you luck in
getting (automatically) to a XML that`s valid against a useful schema/DTD.
(Note "useful" qualifier, which basically eliminates WordML.)
> Frame 6 fails completely here. And Frame 7 falls short here
> too (in my opinion at least), because the DocBook output it
> produces is broken in a number of ways. And I suspect that
> output from any of the other off-the-shelf "structured
> applications" it ships with is probably similarly broken.
FM7, structured, has excellent support for producing valid XML. However,
you have to do the configuration work. The off-the-shelf stuff is not
generally useful. The unstructured formatting templates that FrameMaker
ships with are simplistic and rarely used in the real world. The same is
true for the structured stuff.
If you want DocBook, you need to build your own implementation -- or fix
what`s provided.
> The new WWP succeeds because it ships with XSLT support for
> converting its "WWP XML" format (or whatever its name is) into
> HTML and other output formats.
Nobody except the beta testers has seen it in action. I suggest we wait
until it`s released before passing judgment.
> Do any of the other available Frame/Word conversion
> applications succeed here?
If you`re in structured, you don`t need a conversion application in the
sense that you`re describing here.
>6. Quality of any "setting up mappings" UI provided.
> How good is the UI that it provides for specifying map-to-XML
> settings for converting your in-house paragraph and character
> tags to whatever XML structures it uses?
>
> Any application that succeeds at #5 should have a well-designed
> UI for enabling you to set up mappings. From what I remember of
> the WWP UI, it does this a lot better than the UI in
> "structured" Frame 7 does.
In structured FM 7, you have elements and attributes, not paragraph and
character tags. There`s really not a "map-to-XML" step. You`re creating
hierarchical, structured content.
Again, we haven`t seen the product and should withhold judgment. I am
anticipating, though, that the XSL-based processing will replace the WWP
macro language. In other words, where the original conversion said this:
<b>$DATA;</b>
we`ll now have this:
<b><xsl:apply-templates/></b>
Regards,
Sarah O`Keefe
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sarah O`Keefe okeefe@...
Scriptorium Publishing Services, Inc.
Accelerating Knowledge http://www.scriptorium.com
Publishing blog: http://www.scriptorium.com/palimpsest/
Joined: 25 Feb 2005
Posts: 10
Criteria for evaluating Frame/Word conversion apps?
> FM7, structured, has excellent support for producing valid XML.
I found that FrameMaker actually produces invalid XML from valid XML upon
import. FrameMaker`s errors are multiple. Details at:
http://www.getnet.net/~swhitlat/DocBook/Frame_Project_Readme.html
If I have made mistakes, please let me know and I will correct them.
> However, you have to do the configuration work.
Very heavy configuration work, including "custom API clients" before you can
do many otherwise simple things, like relocate a title to before/after a
figure/table.
But that`s not all. There`s lots more. I never could get xrefs to work
completely correctly (mostly, but not completely). Again, if the mistakes are
mine and someone wishes to offer the solutions, I`ll make corrections.
Details of the problems are described at the link listed above and the
downloadable structured app can be used to demonstrate those same problems.
> If you want DocBook, you need to build your own implementation -- or fix
> what`s provided.
If you want DocBook XML with FrameMaker, start with the downloadable
structured DocBook XML for FrameMaker project I provide at:
http://www.getnet.net/~swhitlat/DocBook/docbook_section.html
I think this downloadable structured FrameMaker app is close to as good as it
gets without writing one`s own "custom API client". If not, again, let me
know what corrections I need to make. Or, if you have a "custom API client"
you wish to contribute that solves all the problems, I`ll be glad to test it
and maybe post it as part of the package.
Steve Whitlatch
Joined: 11 Mar 2005
Posts: 7
Criteria for evaluating Frame/Word conversion apps?
At 08:28 AM 6/4/2005 -0700, you wrote:
> > FM7, structured, has excellent support for producing valid XML.
>
>I found that FrameMaker actually produces invalid XML from valid XML upon
>import. FrameMaker`s errors are multiple. Details at:
>http://www.getnet.net/~swhitlat/DocBook/Frame_Project_Readme.html
>
>If I have made mistakes, please let me know and I will correct them.
Let me just say that DocBook and XML are not identical. If you have a
correctly configured structured application, life is good. I`m not claiming
that the provided DocBook application qualifies as such.
Sarah
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sarah O`Keefe okeefe@...
Scriptorium Publishing Services, Inc.
Accelerating Knowledge http://www.scriptorium.com
Publishing blog: http://www.scriptorium.com/palimpsest/
Joined: 25 Feb 2005
Posts: 10
Criteria for evaluating Frame/Word conversion apps?
> Let me just say that DocBook and XML are not identical. If you have a
> correctly configured structured application, life is good. I`m not claiming
> that the provided DocBook application qualifies as such.
>
> Sarah
I have made a statement about structured FrameMaker, that it produces invalid
XML from valid XML upon import. I provide XML that shows that behavior and a
complete, downloadable structured FrameMaker application in which the
behavior I describe is reproducible.
In what way is my downloadable structured FrameMaker application not a
"correctly configured structured application"?
Yes, I could be making errors that cause FrameMaker to create invalid XML from
valid XML, but I don`t think that is the case. If you or someone else can
show me those errors, and perhaps show me how to correct them, I`ll make
corrections and this downloadable structured FrameMaker application would be
that much more use, to everyone. Otherwise, it seems you don`t really have an
argument and you are just resisting admission of what is already obvious.
Here on the Internet, I have seen many similar discussions regarding software
applications, errors, source code, etc. Usually, the discussion involves
substantive technical arguments.
Here are some snippets from the project`s README that discuss the ways in
which FrameMaker produces invalid XML from valid XML.
**************
4. Importing DocBook XML into FrameMaker
----------------------------------------
The XML is valid before import according to xmllint, the EDD is valid
according to FrameMaker, the rules file is valid according to FrameMaker,
and the template is as valid as an unstructured template can be. But
still, FrameMaker 7.1 creates invalid XML out of valid XML. Specifically,
upon XML import, FrameMaker:
- adds an SGML syntax "Mark" attribute with a value of "ndash" to the
"itemizedlist" element in chapter4.fm whose first "listitem" element
value is "Installation setup". The valid XML "itemizedlist" element
properly contains a "mark" attribute with a value of "ndash".
FrameMaker adds the extra "Mark" attribute to the XML upon import.
The EDD FrameMaker creates from the DocBook XML 4.4 DTD does not
specify any "Mark" attribute; however, it does properly specify a
"mark" attribute.
- same problem as listed above, but this time FrameMaker commits this
error seven times in the itemized lists in chapter5.fm. FrameMaker
consistently creates invalid XML from valid XML in this way every
time it encounters an "itemizedlist" element embedded in an
"itemizedlist" element. This construct of a list in a list is quite
common. FrameMaker`s error here is quite egregious. It makes the XML
invalid both against the EDD and the DTD and destroys automatic
formatting of embedded lists upon import. Watch for this FrameMaker
error with DocBook XML. Expect it. It`s consistent.
- duplicates all "xref" element "linkend" attribute values as "endterm"
attribute values. FrameMaker does this upon XML import even though
the read/write rules do not include this instruction, even when
the "xref" element`s "endterm" attribute is removed from the EDD,
and even though the custom client does not manipulate "xref" element
"endterm" attributes or attribute values.
.
.
.
5.4 Adding new Cross References
-------------------------------
Given implementation of the EDD adjustments and read/writes rules
described previously, DocBook XML xrefs import correctly, work as
expected in FrameMaker using ctrl+alt+click, and work as expected
in the final PDF. All this without using FrameMaker 7.1`s new
"srcfile" attribute. However, once the XML is imported, any attempt
to include additional "xref" elements does not work as expected. An
"xref" element can be inserted easily enough. But attempting to
enter a value for the required "linkend" attribute in the series
of dialog boxes FrameMaker presents results in FrameMaker incorrectly
assigning the value entered to the "xref" element`s "endterm"
attribute. The xref element`s "endterm" attribute is optional, but
its "linkend" attribute is not. Consequently, the XML becomes invalid.
Repeated attempts to correct the problem by assigning a value to an
"xref" element`s "linkend" attribute always result in the value being
incorrectly assigned to the "xref" element`s "endterm" element. The
new cross-references work as expected, but the XML becomes invalid.
**************
Steve Whitlatch
Joined: 11 Mar 2005
Posts: 7
Criteria for evaluating Frame/Word conversion apps?
At 06:51 AM 6/5/2005 -0700, you wrote:
> > Let me just say that DocBook and XML are not identical. If you have a
> > correctly configured structured application, life is good. I`m not claiming
> > that the provided DocBook application qualifies as such.
> >
> > Sarah
>
>I have made a statement about structured FrameMaker, that it produces invalid
>XML from valid XML upon import. I provide XML that shows that behavior and a
>complete, downloadable structured FrameMaker application in which the
>behavior I describe is reproducible.
>
>In what way is my downloadable structured FrameMaker application not a
>"correctly configured structured application"?
Hi Steve,
There are large organizations out there who use structured FrameMaker to
produce XML and SGML. Some of them use DocBook structure. Based on that
knowledge, I can only assume that your application is not configured
correctly. Unfortunately, I don`t have time to troubleshoot it.
Regards,
Sarah
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sarah O`Keefe okeefe@...
Scriptorium Publishing Services, Inc.
Accelerating Knowledge http://www.scriptorium.com
Publishing blog: http://www.scriptorium.com/palimpsest/
Joined: 25 Feb 2005
Posts: 10
Criteria for evaluating Frame/Word conversion apps?
> Hi Steve,
>
> There are large organizations out there who use structured FrameMaker to
> produce XML and SGML. Some of them use DocBook structure. Based on that
> knowledge, I can only assume that your application is not configured
> correctly. Unfortunately, I don`t have time to troubleshoot it.
>
> Regards,
>
> Sarah
Yes, I was thinking the same and had a better opinion of structured FrameMaker
before I actually used it. Your argument is not a substantive or technical
one, but it is the reasoning I used to justify the time spent learning
structured FrameMaker, and I can see how many others might reason along these
same lines.
Many structured FrameMaker problems cannot be solved without special C code in
a custom api client. The documentation for writing a custom api client
amounts to many thousands of pages on how to use Adobe`s FrameMaker Developer
Kit and the FrameMaker Structure API. Sometimes FrameMaker`s default behavior
is clearly buggy, for example: FrameMaker`s default handling of DocBook XML
<indexterm> tags upon XML export, in which all opening <indexterm> tags are
written as closed (</indexterm>). But that is not an isolated case. My
impression is that FrameMaker`s default behavior is buggy much more often
than many think. Those writing the C code for the custom api clients to
override the bugs would be the ones who know.
I don`t claim to be an expert, and I am open to suggestions, but I expect that
correcting most/all the problems I found with structured FrameMaker require
special custom api client C coding using Adobe`s various interfaces. Any
large organizations using structured FrameMaker with DocBook XML are probably
using custom api clients that, among other things, override FrameMaker`s
default buggy behavior.
Adobe does provide their DocBook Starter Kit and a custom api client for
DocBook XML. It tends to inspire false hope that, out of the box, structured
FrameMaker can properly accommodate DocBook XML.
Steve Whitlatch
Joined: 25 Feb 2005
Posts: 10
Criteria for evaluating Frame/Word conversion apps?
> Are you sure you don`t have some helper application "helping" you when you
> don`t need it.
I`m using the custom api client code from the DocBook Starter Kit. In a
FrameMaker 7.1 installation, it`s source files are: import.c, export.c, and
trnslate.c.
> I haven`t worked with Structured FM in a long time
How long?
Do you have FrameMaker 7.0 or 7.1 installed? Adobe provides a Visual Studio
project and workspace files along with the source code for the Starter Kit
custom client. All I had to do to get it to compile was include
project/workspace paths to the FDK header files and struct.lib. If you have
FrameMaker 7.1, and you are up to compiling the custom api client`s code, it
gets installed at
[FrameHome]structurexmlxdocbooksrc.
A compiled version also gets installed as docbook.dll.
If you get it set up, we can talk about "helper applications" and custom api
clients.
> but it strikes me odd that these things happen in an SGML/XML import (which is
> really what it is) automagically for you.
Are you referring to the bugs I mentioned? Which bug(s)? We need to be specific
and the bugs are too many for me to keep listing. What I think are bugs I listed
at:
http://www.getnet.net/~swhitlat/DocBook/Frame_Project_Readme.html
Some might not be FrameMaker bugs. There might be a read/write rule or an EDD
adjustment that fixes what I thought was a "bug". It`s possible.
> That implies some things I would
> find alarming if true.
Yes, well, "alarming" might be a little strong, but OK, the bugs are alarming.
> Instead, I believe you have referenced a helper that
> is mucking around in there without your being aware of it.
I am willing to discuss the source code that eventually becomes docbook.dll
(DocBook Starter Kit`s api client). But I am not really an experienced,
competent C programmer. Are you? I ask, because that is what is needed. Also, if
we are to discuss docbook.dll`s source code (here or offline), it would probably
be best if you first download, install, and investigate the FrameMaker
structured application in question:
http://www.getnet.net/~swhitlat/DocBook/docbook_section.html
No offense, but I get the feeling you haven`t done that.
> As to the notion that it "invalid XML" I think you have to accept the fact
> that you are importing XML into an editing environment. The representation
> within the environment may not be "valid" wrt to an external schema or DTD
> but can nevertheless be valid against an "editing" version of the schema.
> That the internal representation does not match the external is just a
> reality. The task then is to make it valid on export so that the help you
> got from FM doesn`t make your XML invalid outside the environment.
You may have missed the previous discussion in this thread. And you may want to
read the README posted at:
http://www.getnet.net/~swhitlat/DocBook/Frame_Project_Readme.html
Here is part of what I have already stated in this thread about FrameMaker
turning valid DocBook XML into invalid XML:
**********
4. Importing DocBook XML into FrameMaker
----------------------------------------
The XML is valid before import according to xmllint, the EDD is valid
according to FrameMaker, the rules file is valid according to FrameMaker,
and the template is as valid as an unstructured template can be. But
still, FrameMaker 7.1 creates invalid XML out of valid XML. Specifically,
upon XML import, FrameMaker:
- adds an SGML syntax "Mark" attribute with a value of "ndash" to the
"itemizedlist" element in chapter4.fm whose first "listitem" element
value is "Installation setup". The valid XML "itemizedlist" element
properly contains a "mark" attribute with a value of "ndash".
FrameMaker adds the extra "Mark" attribute to the XML upon import.
The EDD FrameMaker creates from the DocBook XML 4.4 DTD does not
specify any "Mark" attribute; however, it does properly specify a
"mark" attribute.
- same problem as listed above, but this time FrameMaker commits this
error seven times in the itemized lists in chapter5.fm. FrameMaker
consistently creates invalid XML from valid XML in this way every
time it encounters an "itemizedlist" element embedded in an
"itemizedlist" element. This construct of a list in a list is quite
common. FrameMaker`s error here is quite egregious. It makes the XML
invalid both against the EDD and the DTD and destroys automatic
formatting of embedded lists upon import. Watch for this FrameMaker
error with DocBook XML. Expect it. It`s consistent.
- duplicates all "xref" element "linkend" attribute values as "endterm"
attribute values. FrameMaker does this upon XML import even though
the read/write rules do not include this instruction, even when
the "xref" element`s "endterm" attribute is removed from the EDD,
and even though the custom client does not manipulate "xref" element
"endterm" attributes or attribute values.
***********
> You chose FM because you either wanted to use it to produce paper output
> from XML or you wanted to edit XML in a WYSIWYG environment or just because
> the leap to a structured editor was just too big to make.
I mostly use Epic Editor with Arbortext Styler, but often I use GNU Emacs and
open-source command-line tools in Linux. Structured FrameMaker has all the nice
features from unstructured FrameMaker and it works nicely with Acrobat Distiller
(for me anyway).
Do you mind if I ask what you use? You say you have not used FrameMaker for a
while, but you did not say what you are using.
> Whatever the
> reason, you must accept FM`s notion of the world, which is that it imports
> and exports XML and there are implications to that.
> Having said that, read/write rules or their current equivalent are not
> adequate to the task and you do need that helper app.
OK, see previous.
> That is the great
> failing and great opportunity with FM, but it takes a skill level that is
> not always found (and perhaps should not be found) in a tech writer. Calls
> for an app developer whose job is to do that.
OK, thanks Merif. If you are an app developer with the necessary C skills, we
can discuss this further. You will need to have installed FrameMaker 7.1, Visual
Studio, the FDK, the FrameMaker structure API, version 4.4 of the DocBook XML
DTD, and my downloadable Docbook XML structured FrameMaker application. It`s a
lot, but it will be necessary. Also, I am not so sure this is the case, but you
will need some prior experience with most of these things. If not, you may still
have some suggestions with respect to the read/write rules or the EDD from my
downloadable DocBook XML structured FrameMaker project.
Please be specific. For example, you could post code you have already tested.
That`s pretty much the accepted practice.
Steve Whitlatch
All times are GMT
Page 1 of 1
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
Freelace Website Designer - Customer web design and software building.
China Wholesale - Electronics Products
Character Studio - Tutorials and Help
China Wholesale - Electronics Products
Character Studio - Tutorials and Help