New Single-sourcing discussion

This forum is for Single-Sourcing your Flare content to multiple outputs.
Post Reply
Mike Hamilton
MadCap Executive Staff
Posts: 7
Joined: Fri Dec 02, 2005 4:25 pm
Location: MadCap
Contact:

New Single-sourcing discussion

Post by Mike Hamilton »

Due to user request we are opening a new discussion area specifically for single-sourcing. Share your successes, horror stories, favorite tips and techniques.
Mike Hamilton
V.P. Product Management
MadCap software
Lucia
Propeller Head
Posts: 58
Joined: Mon Oct 27, 2008 6:22 am
Location: Blumenau SC Brazil

Re: New Single-sourcing discussion

Post by Lucia »

Come on, users who requested this! Start the discussion! :)
Lucia
LTinker68
Master Propellus Maximus
Posts: 7247
Joined: Thu Feb 16, 2006 9:38 pm

Re: New Single-sourcing discussion

Post by LTinker68 »

They have been. The forum this post is in ("Single-Sourcing") contains all the discussions/questions/comments.
Image

Lisa
Eagles may soar, but weasels aren't sucked into jet engines.
Warning! Loose nut behind the keyboard.
Lucia
Propeller Head
Posts: 58
Joined: Mon Oct 27, 2008 6:22 am
Location: Blumenau SC Brazil

Re: New Single-sourcing discussion

Post by Lucia »

Wow! Only now I realized the post date! I had the impression for some reason I don't know now that it was a new post, specifically for "successes, horror stories, favorite tips and techniques". (Shame on me, having to be scolded by Lisa)
Lucia
LTinker68
Master Propellus Maximus
Posts: 7247
Joined: Thu Feb 16, 2006 9:38 pm

Re: New Single-sourcing discussion

Post by LTinker68 »

It's a "stuck" post, so it's always at the top of the forum. The icon for the post is slightly different because of it, but that's easy to overlook. It still catches me in some of the other forums where there are several stuck posts.
Image

Lisa
Eagles may soar, but weasels aren't sucked into jet engines.
Warning! Loose nut behind the keyboard.
Lucia
Propeller Head
Posts: 58
Joined: Mon Oct 27, 2008 6:22 am
Location: Blumenau SC Brazil

Re: New Single-sourcing discussion

Post by Lucia »

OK, now I feel a tiny little better. :)
Lucia
WhyUNoWork
Jr. Propeller Head
Posts: 8
Joined: Thu Feb 23, 2012 11:38 am

Re: New Single-sourcing discussion

Post by WhyUNoWork »

I've used Flare for multiple projects and I still love it. However, my biggest gripe is that for all the bells and whistles there is no "plain HTML output" option. No, not the HTML Help (.chm) file target, that's not what I mean. I mean there is no target that gives me plain HTML pages with all of the MadCap-centric CSS, JavaScript, and XML files excluded/removed. I just want a plain "vanilla" HTML output.

Why does this even matter? Because of 2 main reasons:

1. For advanced UIs where Development wants to create their own help infrastructure, the "canned" WebHelp look-and-feel just doesn't cut it. Actually nothing "canned" will cut it because they are in essence building their own look-and-feel. Development just wants the content not the bells and whistles. The only way I can supply this to them and still keep it single-sourced is by running scripts on the Output afterwards. So I have to run it once for the PDF output, run it again for the WebHelp output, and then run the WebHelp output through a script. I always found this to be pretty dang silly in order to remove a few lines in the head and the end of the body.

2. Command-Line Help. Again, if you want to "keep it simple" in Flare and Single-Source you really can't. For CLI help the man pages are typically in .txt format. I would kill to be able to output to just plain text. Or at least plain HTML to lessen the amount of post-processing I've had to do. It's not uncommon for me to write docs for a CLI tool where they want man pages and a PDF CLI reference as well.

I've added this as an enhancement request years ago, and it's gone unheeded.

- Allow us to modify the WebHelp target to output the html files only. No frames, no toolbar, no snazzy do-hickies. Nothing that's "canned".
- Give us the option to also output with a stylesheet (NOT the MadCap .css files, but whatever .css we modified manually)

I won't even go into the localization headaches. If I had this I could send our translation vendors the Flare project via Lingo as opposed to sending them the Flare output and crossing my fingers.
LTinker68
Master Propellus Maximus
Posts: 7247
Joined: Thu Feb 16, 2006 9:38 pm

Re: New Single-sourcing discussion

Post by LTinker68 »

WhyUNoWork wrote:- Allow us to modify the WebHelp target to output the html files only. No frames, no toolbar, no snazzy do-hickies. Nothing that's "canned".
You could try the WebHelp Mobile output instead of WebHelp or WebHelp Plus.
WhyUNoWork wrote:- Give us the option to also output with a stylesheet (NOT the MadCap .css files, but whatever .css we modified manually)
The MadCap.css stylesheet is referenced before your topic stylesheet in the output, so as a workaround you can add styles to your topic stylesheet to override the styles in the MadCap.css stylesheet.
Image

Lisa
Eagles may soar, but weasels aren't sucked into jet engines.
Warning! Loose nut behind the keyboard.
WhyUNoWork
Jr. Propeller Head
Posts: 8
Joined: Thu Feb 23, 2012 11:38 am

Re: New Single-sourcing discussion

Post by WhyUNoWork »

LTinker68 wrote:
WhyUNoWork wrote:- Allow us to modify the WebHelp target to output the html files only. No frames, no toolbar, no snazzy do-hickies. Nothing that's "canned".
You could try the WebHelp Mobile output instead of WebHelp or WebHelp Plus.
Believe me, I've tried. :) I read one of your past posts that suggested this (thanks by the way! You've been a steady source of info on these forums.) Unfortunately, the HTML output is still "dirty" (for lack of a better word). For example all of this is added to the head of every HTML page for Mobile WebHelp:

Code: Select all

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/xhtml-mobile12.dtd">
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:lastBlockDepth="3" MadCap:lastHeight="47" MadCap:lastWidth="1242" MadCap:conditions="TurnConditions.ScreenOnly" MadCap:disableMasterStylesheet="true" MadCap:tocPath="" MadCap:InPreviewMode="false" MadCap:PreloadImages="false" MadCap:RuntimeFileType="Topic" MadCap:TargetType="WebHelpMobile" lang="en-us" xml:lang="en-us" MadCap:PathToHelpSystem="../../" MadCap:HelpSystemFileName="Default.xml" MadCap:SearchType="Stem">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <link href="../../Skins/Default/Stylesheets/StackLayout.css" rel="stylesheet" type="text/css" />
        <link href="../../Skins/Default/Stylesheets/Header.css" rel="stylesheet" type="text/css" /><title>advertisers</title>
        <link href="../../Resources/Topic.css" rel="stylesheet" />
        <link href="../Resources/Stylesheets/OverlayHelpStyles.css" rel="stylesheet" />
    </head>
Welp, what I need is this (although the exta bits in the html tag is ok to leave in):

Code: Select all

<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <link href="../Resources/Stylesheets/OverlayHelpStyles.css" rel="stylesheet" />
    </head>
LTinker68 wrote:
WhyUNoWork wrote:- Give us the option to also output with a stylesheet (NOT the MadCap .css files, but whatever .css we modified manually)
The MadCap.css stylesheet is referenced before your topic stylesheet in the output, so as a workaround you can add styles to your topic stylesheet to override the styles in the MadCap.css stylesheet.
Yeah, I do this. But by default it still links the MadCap stylesheet. Regardless of whether your files use that CSS or not, it's hardcoded in because a skin must be selected for a target (even if it's default).

<link href="../SkinSupport/MadCap.css" rel="stylesheet" /> <-- MadCap's
<link href="../Resources/Stylesheets/OverlayHelpStyles.css" rel="stylesheet" /> <-- Mine

Can it really be that hard to have a "BasicHTML" target next release? It's essentially a stripped down WebHelp target anyway, no?

I should add that after much fiddling with the WebHelp target and Skin I get the HTML code "cleaner" prior to running it through a script. Only those pesky SkinSupport JavaScript files and CSS are left:

Code: Select all

<?xml version="1.0" encoding="utf-8"?>
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:lastBlockDepth="3" MadCap:lastHeight="47" MadCap:lastWidth="1242" MadCap:conditions="TurnConditions.ScreenOnly" MadCap:disableMasterStylesheet="true" MadCap:tocPath="" MadCap:InPreviewMode="false" MadCap:PreloadImages="false" MadCap:RuntimeFileType="Topic" MadCap:TargetType="WebHelp" lang="en-us" xml:lang="en-us" MadCap:PathToHelpSystem="../../" MadCap:HelpSystemFileName="Default.xml" MadCap:SearchType="Stem">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /><title>advertisers</title>
        <link href="../SkinSupport/MadCap.css" rel="stylesheet" />
        <link href="../Resources/Stylesheets/OverlayHelpStyles.css" rel="stylesheet" />
        <script src="../SkinSupport/MadCapAll.js" type="text/javascript">
        </script>
    </head>
    <body>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed adipiscing, risus ac pretium semper, arcu massa ultrices mauris, eu sodales nisl quam sit amet elit. Morbi sapien leo, venenatis consequat venenatis eget, ultricies et risus. Fusce nec quam eget tortor accumsan dictum. Vestibulum ornare, nisi imperdiet tempor bibendum, risus magna blandit augue, a condimentum magna mauris ut arcu. Morbi vitae vestibulum mi. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. In ac elit bibendum massa bibendum adipiscing et eget orci. Curabitur pharetra scelerisque viverra. Integer ac ligula in nunc ornare bibendum ut ac felis. Donec a leo eleifend lectus accumsan blandit in eget orci. Nullam rutrum, massa in gravida luctus, sapien est tempus sapien, nec rhoncus enim diam mollis ligula. </p>
        <script type="text/javascript" src="../SkinSupport/MadCapBodyEnd.js">
        </script>
    </body>
</html>
SteveS
Senior Propellus Maximus
Posts: 2087
Joined: Tue Mar 07, 2006 5:06 pm
Location: Adelaide, far side of the world ( 34°56'0.78\"S 138°46'44.28\"E).
Contact:

Re: New Single-sourcing discussion

Post by SteveS »

The source files used by Flare (ie the topic you open in Falre to edit before compliling) is in HTML.

If you don't use anything that is converted during compilation/ publishing you could use the plain HTML used during the authoring phase.

Very simplistic, and it doesn't allow for glosasaries, indexes, or any of the other great stuff, but it is plain HTML.
Image
Steve
Life's too short for bad coffee, bad chocolate, and bad red wine.
WhyUNoWork
Jr. Propeller Head
Posts: 8
Joined: Thu Feb 23, 2012 11:38 am

Re: New Single-sourcing discussion

Post by WhyUNoWork »

SteveS wrote:The source files used by Flare (ie the topic you open in Falre to edit before compliling) is in HTML.

If you don't use anything that is converted during compilation/ publishing you could use the plain HTML used during the authoring phase.

Very simplistic, and it doesn't allow for glosasaries, indexes, or any of the other great stuff, but it is plain HTML.
Yes, this is true. However, if you are single-sourcing like I am even that gets a little dirty depending on the content, mainly due to the use of conditional text. For example:

Code: Select all

<?xml version="1.0" encoding="utf-8"?>
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:lastBlockDepth="4" MadCap:lastHeight="262" MadCap:lastWidth="1229">
    <head>
    </head>
    <body>
       <h1 MadCap:conditions="TurnConditions.AuthorComments">OMG a Heading!</h1>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed adipiscing, risus ac pretium semper, arcu massa ultrices mauris, eu sodales nisl quam sit amet elit. Morbi sapien leo, venenatis consequat venenatis eget, ultricies et risus. Fusce nec quam eget tortor accumsan dictum. Vestibulum ornare, nisi imperdiet tempor bibendum, risus magna blandit augue, a condimentum magna mauris ut arcu. Morbi vitae vestibulum mi. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. In ac elit bibendum massa bibendum adipiscing et eget orci. Curabitur pharetra scelerisque viverra. Integer ac ligula in nunc ornare bibendum ut ac felis. Donec a leo eleifend lectus accumsan blandit in eget orci. Nullam rutrum, massa in gravida luctus, sapien est tempus sapien, nec rhoncus enim diam mollis ligula. </p>
        <ul>
            <li>Blah</li>
            <li>Blah</li>
            <li>Blah</li>
        </ul>
    </body>
</html> 
But yes, you're absolutely right. This is pretty much the best option.
jdw2465
Propeller Head
Posts: 15
Joined: Mon Apr 30, 2012 1:18 pm
Location: Salt Lake City, Utah
Contact:

Re: New Single-sourcing discussion

Post by jdw2465 »

Another good point for plain vanilla HTML output is generating readmes in HTML. I'm still amazed at how many companies create txt and rtf readme files, which really are a pain to format. With the power of CSS and HTML, it is so easy to generate a simply formatted readme. But you'll have to do it outside of Flare using your own flavor of editors. But it also means that your readmes/you can't benefit from living in the world of Flare and single-sourcing. I do miss generating readmes at Symantec where they use Vasont to generate a simple, single-page readme with an auto-generated mini-TOC at the top of the doc. Best readmes I've ever seen, bar none! Readmes are a critical part of software releases (as are release notes). And while some dev shops write there own (scary!), offering to own them can increase a tech pub's value to the it's company.

My two cents... :)
Derek

Image
KCinColorado
Propeller Head
Posts: 40
Joined: Tue Mar 20, 2012 11:00 am

Re: New Single-sourcing discussion

Post by KCinColorado »

Glad I saw this as I was considering moving my readme files to Flare. Was hoping for a plain HTML output as I don't currently have a basic HTML editor. I second the request for such an output in Flare!
SteveS
Senior Propellus Maximus
Posts: 2087
Joined: Tue Mar 07, 2006 5:06 pm
Location: Adelaide, far side of the world ( 34°56'0.78\"S 138°46'44.28\"E).
Contact:

Re: New Single-sourcing discussion

Post by SteveS »

KCinColorado wrote:Glad I saw this as I was considering moving my readme files to Flare. Was hoping for a plain HTML output as I don't currently have a basic HTML editor. I second the request for such an output in Flare!
feature requests can be added using this URL: https://www.madcapsoftware.com/feedback ... quest.aspx :)
Image
Steve
Life's too short for bad coffee, bad chocolate, and bad red wine.
aemily89
Jr. Propeller Head
Posts: 2
Joined: Tue May 15, 2018 10:45 am

Re: New Single-sourcing discussion

Post by aemily89 »

First post! I'd like to start by admitting that I am a TOTAL noob--this is my first tech writing job, and I'm a little overwhelmed. So. That being said, I am having a bit of a problem using Flare.

We have almost 100 target files--about three for each of our clients. Each cycle, we set-up and update the targets, the conditions, and the variables (etc.) individually--a repetitive task that takes over 900 clicks. We're looking for a way to streamline this process. Is there a function in Flare (or an extension) that allows us to change the Master TOC, the Output Folder, and the variables within multiple targets at once? We are changing the same things on each of these files. That leaves a lot of room for error.

I understand that it is *work*, but we have one source and 90+ custom output targets--I'd say 80% of those targets have the same content with just a few different variables, but they all go into their own folders for each of the customers. Our CTO thinks the process can be automated, and they're talking about putting ~60 man hours into a PowerShell script to go in and edit the files outside of Flare (that could end up costing about enough money to send our team of two to MadCamp!). A few of us are convinced that we're just not using Flare's full capacity. We're a small company that does vocational rehab software for state agencies--it's great that they're so considerate to how much work we do, but something's amiss. There should be a function within the program for this purpose... I think I'm just missing it. Help?


I've been thinking about it, and I wonder... if I were to build a template that had all of my files, but no variable definitions, could I fill in the definitions later and eliminate at least some of the margin for error? :o
aemily89
Jr. Propeller Head
Posts: 2
Joined: Tue May 15, 2018 10:45 am

Re: New Single-sourcing discussion

Post by aemily89 »

aemily89 wrote:First post! I'd like to start by admitting that I am a TOTAL noob--this is my first tech writing job, and I'm a little overwhelmed. So. That being said, I am having a bit of a problem using Flare.

We have almost 100 target files--about three for each of our clients. Each cycle, we set-up and update the targets, the conditions, and the variables (etc.) individually--a repetitive task that takes over 900 clicks. We're looking for a way to streamline this process. Is there a function in Flare (or an extension) that allows us to change the Master TOC, the Output Folder, and the variables within multiple targets at once? We are changing the same things on each of these files. That leaves a lot of room for error.

I understand that it is *work*, but we have one source and 90+ custom output targets--I'd say 80% of those targets have the same content with just a few different variables, but they all go into their own folders for each of the customers. Our CTO thinks the process can be automated, and they're talking about putting ~60 man hours into a PowerShell script to go in and edit the files outside of Flare (that could end up costing about enough money to send our team of two to MadCamp!). A few of us are convinced that we're just not using Flare's full capacity. We're a small company that does vocational rehab software for state agencies--it's great that they're so considerate to how much work we do, but something's amiss. There should be a function within the program for this purpose... I think I'm just missing it. Help?


I've been thinking about it, and I wonder... if I were to build a template that had all of my files, but no variable definitions, could I fill in the definitions later and eliminate at least some of the margin for error? :o
Ok--thanks for the help. I think I figured it out. :P I just built a template with no variable entries--that way the variables populate across all 90-or-so targets. ^_^ It was actually a pretty easy fix. Thanks for giving me this space to think about it.
Post Reply