This guest blog post was written by Jack DeLand. Jack has provided Help projects and/or Help authoring training to Fortune 50 companies around the world for over 30 years. He specializes in MadCap Flare project development, architecture, and design, and resides in Ypsilanti, a small city next to Ann Arbor, Michigan.
This is the third post in a 3-part series on revamping a 2000 A.D. HTML 4 website for The James Fenimore Cooper Society using MadCap Flare, focusing here on some tools and techniques used in the transformation.
Missed Part 1 and 2? Start here.
With a truly historic (HTML 4) website from 2000 on his hands, Jack DeLand set out to give The James Fenimore Cooper Society's digital home a much-needed facelift using MadCap Flare™. This post highlights the specific tools and techniques used to address common challenges and enhance the website’s functionality and appearance.
Sample problems are discussed below; yours will differ but you can abstract the concepts.
Incorrect Stylesheet Links
/image44.png)
Upper left of text: Flare is showing that something is wrong but doesn’t have the words to express it.
This error is a little more obscure, partly because Flare isn’t sure how to describe it.
/image45.png)
Text edits are your friend.
Text mode in the Flare editor shows that a stylesheet link has been placed in the <body> section, not the <head>. Solution: cut and paste inside the <head> tag. The text on line 5 should not even be in the file.
Correcting Images
/image46.jpeg)
Original shown in preview on left; preview of changes shown right
Like many often-used historical images on the web, this one is both murky and faded. Fortunately, IrfanView offers much of the same capability as high-end graphic tools.
/image47.jpg)
Enriched
In this case, I used IrfanView to enrich the image with gamma, saturation, and contrast enhancements. Clouds are better defined, as are colors (note the green of the foreground foliage), and we can more clearly discern horseback riders on the riverbank.
About one half of this project’s images benefited from manual manipulation, but the easy way is to use Image > Auto-select Colors. This should give you a very good start, and in some cases that’s all you need.
There are some striking color images on the site.
/image48.jpeg)
Charles Bird King, “Sharitarish” (White House Collection). Courtesy White House Historical Association.
The black and white illustrations were improved significantly with subtle changes in IrfanView. Study the menus and play with expendable source files.
Crooked Images
IrfanView has a very convenient custom Rotate capability for repositioning images that are ajar: 360° in increments of one-hundredth of a degree.
/image49.png)
Custom rotation, with options
/image50.png)
Original
This image slants downward and to the left. We open it in IrfanView from Flare.
/image51.png)
Custom rotation will work here.
Rotate and trim the image.
/image52.jpeg){kind=small}
/image53.png)
Final
The final has been cropped, rotated, and given a white background. Yes, it takes a lot of time.
Gamma Correction
/image54.jpeg)
Gamma correction settings
It’s the gamma value, not the contrast, that makes for rich blacks.
/image55.jpeg)
Even black and white illustrations can reveal much more detail with a little cleanup.
This study of a dead flicker raised a bit of fuss; labeled too morbid, it was devoid of the usual nature study cheeriness.
/image56.jpeg)
Who says black and white isn’t effective?
It’s like restoring an old car: take your time to make every component the best it can be, polish, and then reassemble the perfected pieces. Awesome. Hey, you missed a spot.
Checking Your Work and Other Project-wide Operations
In Search of the Perfect Footnote
Footnotes are a special case with this website, since they’re homegrown, not made with MadCap Flare styles. There are 13,224 footnotes in the project. Each footnote numeral reference was apparently built by hand. But they were blue, ugly, and just had to be fixed.
/image57.png)
Old site
Extended Characters
I first tried using the HTML extended ASCII character set for the footnote numerals (see graphic below). Unfortunately, these met with alignment problems (tops not aligning) that I could not fix.
/image58.png)
HTML extended characters in a Flare snippet―good try, no cigar
I decided to do some investigating. My pet peeve was the disruption to the line spacing because the character, being “super,” bumped up the line above it. I discovered vertical alignment settings for footnote superscripts, and … it works.
This is the code I tested for creating a supertext footnote number 1:
<a href="#note1" style="color: #ff0000;font-weight: 900;text-decoration: none; font-size: 16px;vertical-align: top;">1</a>
This will eventually be finalized as a sup tag, but I’m still playing.
Here are the differences between the two settings:
/image59.jpg)
Align super
/image60.png)
Align top
I experimented with fonts and spacing for a very long time, trying for an imitation “typeset” look.
/image61.jpeg)
Word spacing experiment
I went through many iterations selecting fonts, and many tweakages of line- and word-spacing values while trying to simulate “real typeset.” But I came across a proper font that actually looked like what I wanted: Adobe Garamond Premier Pro. (font-family: 'garamond-premier-pro', 'adobe-garamond-pro', georgia, serif). This font works especially well on smartphones, a rarity.
p
{
-webkit-hyphens: auto;
/* for Safari */
font-size: 21px;
font-weight: 500;
hyphens: auto;
line-height: 1.33;
margin: 12px 0 2px 0;
mc-hyphenate: always;
overflow-wrap: break-word;
word-wrap: break-word;
} Unfortunately, using this font will cost about $60/month, but you do get the entire Adobe Creative Suite and thousands of other fonts along with it, so there is that.
Tools Survey (Supplemental Reference)
Not just for websites, you’ll find these tools and utilities handy for any Flare project. It’s all about saving time, time better spent designing rather than typing
Kaizen Toolbar
/image31.png)
Mattias Sander’s Kaizen Toolbar (https://www.improvementsoft.com) is absolutely indispensable for large-scale projects, and a proven time saver all around. For example, I used the Topic Splitter component to break up some very large files. The splitter drives Flare functionality to begin new topics at the heading level you specify. If the file has 100 level 1 headings, and you split on that setting, you will generate 100 files and a linked TOC. Incredibly, this tool is still offered free.
MindManager
An essential prototyping tool for any large project (i.e., anything too big to keep in your head). Use the bubble diagrammer to create topic hierarchies as decomposition diagrams, then export to Word. Massage the docs in Word, reorder sections, etc., then import the docx file back into MindManager and repeat. This tool is a Corel product, and quite robust. The web version has a real-time sharable edit mode.
I try to hold off creating new material until I have a solid project skeleton built, but conditions vary, and projects tend to go in spurts. MindManager lets me create placeholders that will be reworked. Note that this tool has many other project management features. (https://www.mindmanager.com/en)
SnagIt Editor
Use the “Grab text” option for OCR. The success rate is much better than exporting from a PDF through Acrobat. (https://www.techsmith.com/)
Notepad++
Keep this window open and edit one HTML file in Flare plus this utility simultaneously to do real-time update checks (great for debugging). Free. (https://notepad-plus-plus.org/)
Notepad++ can save files in many different programming formats and has extremely powerful search/replace capabilities but be careful: this is a programming tool with no “undo” capability. None. You changed 1,000 files by mistake? Oh, boy―you did create a backup first, yes?
Bulk Rename Utility
/image62.jpeg)
Much easier than DOS or PowerShell commands. Note the Preview and Revert buttons (actions not possible in DOS).
Much easier than DOS or PowerShell commands. Note the Preview and Revert buttons (actions not possible in DOS).
See https://www.bulkrenameutility.co.uk/ for documentation. This utility also comes in a command line version for old skoolers, and you can easily deduce that the Windows version is linked to DOS commands.
WARNING: Flare’s database is updated when file names are changed only within Flare. Try to make all your file name and folder changes before bringing the files into the project.
ColorHexa.com
To thoroughly investigate digital color values and variants, visit https://www.colorhexa.com/:
/image63.png)
Enter numbers with a hashtag, or common names such as dark blue (partial image).
This is an extraordinary resource for those who need technical advice on graphic conversions or just want to fine tune color values. And it too is free.
/image64.png)
Previews of alternatives, shades, tones, and tints for the current color.
The site even has a Color Blindness Simulator section for each color―very important nowadays.
In Sum
This post series, lengthy as it is, provides only a sampler of tools and techniques used on a one-off project. You’ll need to set up some rules on your own for your conversion project.
When remaking a website or any existing Flare project:
- Separate form from function in your existing material to determine the essentials. For example, navigation is implemented in the old Cooper site as manually created links in a table block copied and pasted over and over across topic files. This abstraction in turn drives changes to the topic files since a Flare TOC is independent of the text: find and eliminate all the (hundreds of) tables.
- Look for patterns and repetitions in text and structure. If it repeats, changes can be automated. What change gets you the biggest bang for your buck?
- Use rapid prototyping. For a large project testing new functionality, cut down a TOC to as few topics as possible and make a “minimal” running draft to see changes in operation. I do many, many builds per project.
