Frame 7 to Frame 8 problem
December 12th, 2008 by jwilesWe have discovered a kind of a nasty problem which occurs when you bring FrameMaker 7 documents created in some non-English locale, into FrameMaker 8. This problem affects any text that is inserted into the FrameMaker 7 dialogs, such as the Paragraph Designer or the Marker dialog, under the non-English locale. When the docs are pulled into FrameMaker 8 on an English system all of the content is converted to Unicode. However, all of the text from the dialogs is not converted. This means that things like the Index and the Paragarph style names are rendered as garbage characters (or probably more correctly, the raw bytes rendered as FrameRoman encoding).
Page Template Preview Utility
October 15th, 2008 by jwilesAs promised at RoundUp, I have posted a wiki article on the Page Template Preview utility. It lacks a number of things, such as good design, a clearly defined objective, among others. However, it was fun to write and I hope that it might be useful to anyone who may be trying to unravel Page templates.
ePublisher 2008.2 Eclipse Help Article
July 7th, 2008 by jwilesThe 2008.2 Release of the ePublisher Platform went live today. This release includes the Eclipse Help Format. I have just posted a wiki page which documents the items which are peculiar to the Eclipse Help format.
ePublisher 2008.1 and wiki articles
March 31st, 2008 by jwilesI posted two new wiki articles. The first is a general outline of ePublisher URI Resolvers. The second is documentation for wwtransform:super, a cool new URI available in the 2008.1 runtime.
ePublisher 2008.1 is here. Happy Q2.
Publishing Content From the WebWorks Wiki
January 11th, 2008 by jwilesOne of the more interesting aspects of the ePublisher 9.3 Release is the introduction of the Xml Adapter. By default, this Adapter allows users to generate output from DITA source documents. However, perhaps more significantly, it carries with it the ability to configure ePublisher to accept ANY input source.
To demonstrate this functionality, during RoundUp 2007, we showed the Xml Adapter publishing content from the WebWorks Wiki to WebWorks Help 5.0. It was our intention at that time to make this project available online. With this objective in mind, I’ve added a page in the RoundUp section of the WebWorks Wiki. This page includes the project I used to publish content during the Day 2 Keynote. It also includes instructions for modifying which WebWorks Wiki content is included in the project. This effectively gives you the ability to create your own WebWorks Help 5.0 help system, or any other ePublisher supported output Format, including ones you have developed, using content from the WebWorks Wiki.
In the coming weeks, I plan to publish a tutorial on developing a custom Xml Adapter from scratch. Stay tuned.
FrameMaker 8 Conditional Expressions
December 19th, 2007 by jwiles
Figure: FrameMaker 8’s Show Conditional Text as per Expression
Currently, we are working on updating ePublisher to run on Windows
Vista. Also I am working on updating ePublisher’s FrameMaker Tool
Adapter to support FrameMaker 8. One of the more challenging
aspects of this latter task is adding support for FrameMaker 8’s new
“conditional expression” feature. This feature allows the end user
to define a logical expression which should be used when applying
visibility settings to conditional segments of a FrameMaker document.
On the FrameMaker side, it seems that retrieving the information
from the new FDK is relatively trivial. The more interesting
challenge may be how to present this new paradigm to ePublisher
users. At first we decided to wrap the old mechanism in a radio
button region, and add the new option to a new radio button section.
Figure: HTML Mock-up of Radio Button Approach
Initial efforts to design this approach have fleshed out an
important shortcoming in the current “unified” interface that
ePublisher presents for defining condition visibility. Specifically,
different source formats have different ideas of what “conditions”
are and how they are implemented. DITA provides a “tag-like”
approach which allows filtering for purposes other than visibility.
If your input is Word or a version of FrameMaker below 7.x, you have
no use for an expression option.
Figure: ePublisher’s Cross Reference Rules Dialog
This revelation is causing us to pursue an alternative approach. The
idea is to move Conditions out of the hybrid Conditions/Variables
dialog, altogether, and model a new Conditions dialog, after the
existing Cross Reference Rules dialog. As with Cross Reference Rules,
this approach would allow us to display a Conditions dialog
appropriate for each input format. No mock-up yet, but stay tuned.
process soup
December 10th, 2007 by jwilesIngredients
- I have a tendency to want to write a program first and design it later. Given that my academic background is not computer science, I often feel that I'm missing something about spec writing, design, etc. And I am. I believe that the penultimate of hubris, a path I traverse more often than I would care to admit, is to make any emphatic statement about a thing for which one has little or no first-hand knowledge.
- Recently, one of my fellow developers gave a presentation on UML and highlighted the differences between forward and reverse modeling. Reverse modeling builds an abstract representation from an existing implementation. Forward modeling is the opposite. Build the model first, write the code second. Both are valid approaches to modeling.
- Last Tuesday I attended the Agile Austin meeting with Ben. One thing which really resonated was the speaker's assertion that you need to shape a work flow to suit your process. As with any evolutionary system, there must be room to specialize.
- In film, there is a certain time of day, around the sun's rising and setting, when the natural lighting is ideal, which is referred to as the “magic hour”. On a shoot, entire days and weeks of preparation may be all centered on getting a few seconds in the can during this small window.
- Last week I read this blog entry by Joel Sposky. In this entry he writes (and I'm pulling this quote out of context, so I highly recommend that you read the entry, though for the sake of brevity, I will summarize the context as: a statement on the relationship between a software spec and the resulting program):
…the bottom line is that if there really were a mechanical way to prove things about the correctness of a program, all you’d be able to prove is whether that program is identical to some other program that must contain the same amount of entropy as the first program, otherwise some of the behaviors are going to be undefined, and thus unproven. So now the spec writing is just as hard as writing a program, and all you’ve done is moved one problem from over here to over there, and accomplished nothing whatsoever.
Soup:
So my tendency to want to build first, design later, may not be entirely misguided. It seems to me that the real trap here, is the “which is better” conundrum. Both may be valid. This soup is about the way I prefer to program, which may be summarized in the following order:
- Spend a little bit of time thinking about what I want to write. If someone else is coming up with the idea, spend a little bit of time brainstorming with them. DON'T WRITE ANYTHING DOWN YET.
- Implement the brainstorm immediately. Within a few days, or a week.
- Analyze the result (document and model; often this ends up in a readme) and recurse.
Some things to note about this process. First, the post-brainstorm implementation implies a managable chunk. It's not to say that you can't build large apps. But build incomplete representations of the large app first.
For instance, if you're going to write a classic MVC app and each aspect will probably require several weeks to implement, then the first offering might be a simple glue code program which interacts with stubs that print statements about the “real” code that should ultimately exist there. That is, if a controller needs to do a series of complex database operations, then in the initial version, the controller will print a message like, “doing complex database operations…”.
The point is, nothing should derail the programming “magic hour” which follows a good brainstorming session. Things can be refactored and analyzed later. In the beginning, generate velocity. Ultimately the resulting intertia can be much more easily molded into the desired result. But as with bicycles and sailboats, it is very hard to steer a thing which has no motion, or in programming, doesn't do anything.
Cleanup:
This, by the way, IMO is the primary reason for the ubiquity of Hello World.
Obviously, this article is mostly outloud thinking about my own process. It's unoriginal, plagiarist and derivative. It's specialization.
HTML Help: Custom TOC
November 15th, 2007 by jwilesI’ve added a Tip to the WebWorks Wiki. This is an example project
which demonstrates using a custom FTI setting to use a custom *.hhc
file for HTML Help, rather than the one ePublisher generates by
default.
FTI Article
November 12th, 2007 by jwilesI’ve published a draft of the article on FTI. I’d like to formally request
comment from anyone who has a cycle or two to go through it; what’s
good about it, what’s bad about it, etc. You can email me directly
and I will try to update it as needed. Alternatively, if you’ve got
a login to the wiki, please feel free to post any feedback
directly in the draft.
Currently the Draft does not include the wiki format as I am still
debating the best way to make this available. Can I assume that our
users have access to a directory diff program like AraxisMerge or
WinMerge? If not, I might try to deliver the format with an HTML
diff report, with the idea that this might be the easiest way to keep
track of the changes I made to Ben’s base wiki format.
Update: I’ve added the wiki format to the article, along with
a brief description of the contents of the format. Missing is a
detailed description of how the Wiki format was created, as this
probably belongs in another topic.
Post RoundUp
November 7th, 2007 by jwilesWe finished RoundUp yesterday. This was such a valuable event for
the WebWorks community and I’m so grateful for everyone who attended
and participated. I was very happy with the way the entire event
went, except for the problems with the demo at the end of my FTI
presentation.
I have the impression that I promised a few more things than I
tracked. Here in brief is what I plan to make available. Please
ping me if you feel I’ve
forgotten anything, or if you have any questions on the materials as
they are made available.
Items To Post From RoundUp 2007
- Resources Adapter (rAdapter)
- wiki-prefix, wiki-suffix example
- FTI Documentation (wiki.webworks.com)