Print "Whole Book" From HTML5 Help?

This forum is for all Flare issues related to the HTML5, WebHelp, WebHelp Plus, and Adobe Air Targets
Post Reply
Mishou6779
Propeller Head
Posts: 57
Joined: Mon Jun 01, 2009 9:19 am

Print "Whole Book" From HTML5 Help?

Post by Mishou6779 »

Hi all,

I'm pretty sure I already know the answer to this question, but I'm asking it anyway because I'm always amazed at how clever other MadCap Flare users are.

I'm a lone writer in charge of a massively large software system. My online help contains more than 1,300 .htm files. In the past, our user guides were an identical copy of the online help (single sourcing, hello), so after 2 years of discussion, my manager somehow managed to convince the folks higher up on the chain of command that it was time to sunset the user guides. (Change is hard here...we FINALLY published HTML5 help just this past December...it took me YEARS to talk them into that.) Managing 26 user guides on top of all of the help content was just way too much for one person. I was glad to be rid of them.

Sadly, however, I work for a government contractor (which is usually a microcosm of the federal government), and though we announced this change last summer, suddenly yesterday, the fit has hit the shan and everyone is running around screaming, their arms flailing in the air like the little grunts in Halo.

I promised my manager I would ask if there is any way to set up my HTML5 output so that our users could print a whole "book" from the TOC. Each module in our system has its own TOC (since they used to be for the user guides), and each of those smaller TOCs feed into the larger HTML5 online help TOC. Is there a way to select a folder in the TOC and print the whole folder?

The only way I know of is to imbed the user guide PDFs into the help, the way MadCap does on their Flare online help. Is that as much work as publishing 26 different PDF files (since they all get generated into their own folders)?

Does anyone out there know of any other way? I'm looking for minimal effort here...the less touching, clicking, manipulating I have to do the better.

Thank you!
Michelle
robdocsmith
Sr. Propeller Head
Posts: 247
Joined: Thu May 24, 2018 3:11 pm
Location: Queensland, Australia

Re: Print "Whole Book" From HTML5 Help?

Post by robdocsmith »

Ahh governments do love their paper don't they...

If you want to go really simple, you could create a PDF target based on your master TOC. With a few pages set up for front/back matter with print-only conditions on them and a few page layouts, you could output the whole shebang as a PDF quite quickly. You might have to make careful additions to the print medium styles to make sure it prints as well as possible without having to mess around with individual help pages. Then add a link to the built PDF in your master pages for the help (or in the toolbar for the help). Create a batch target that builds both PDF and Help and then publishes it all to your destination.

You ideally want the help system to be the source and the PDF to just be a nice to have extra with as little fussing with changing structure as possible. A tick the box thing for compliance. Yep, got a PDF that no sensible person will ever read.

Otherwise you could get a bit more fancy and have separate PDFs for each sub TOC. Each sub TOC would need their own print-only front/back matter pages. Then you'd need to create similar print targets for each sub book. You'd have to create several links in the help for the different PDFs. Again, you'd create a batch target that builds the PDFs, then builds the help system.

Rob
Mishou6779
Propeller Head
Posts: 57
Joined: Mon Jun 01, 2009 9:19 am

Re: Print "Whole Book" From HTML5 Help?

Post by Mishou6779 »

Rob, thank you for the information, and for the laughs! It's always so nice to discuss things here with other writers who "get it."

So, funny thing...maybe not funny, but a thing...yesterday my manager asked me to just attempt to put the online help TOC into a PDF and let 'er rip. Flare did beautifully well until it had to embed the images. It took all day. Literally. I started the PDF build at 9:51 yesterday morning, and it was still not done embedding images last night when I signed off work at 5:30. I just shut it off and walked away...couldn't take it anymore.

My poor boss had to have a meeting this AM to repeat why we're not making user guides, and he just sent out the follow-up email. He did well...I am glad he gets it. But I am afraid we're going to be fighting an uphill battle.

I'm going to show him how MadCap does their online help and how they offer the PDFs (which, you are quite correct, sir, nobody in their right mind is ever going to read), because at least that might be one way for us to skirt the whole "books" thing.

Thank you again for your response, I really appreciate it!! Have a great weekend!
robdocsmith
Sr. Propeller Head
Posts: 247
Joined: Thu May 24, 2018 3:11 pm
Location: Queensland, Australia

Re: Print "Whole Book" From HTML5 Help?

Post by robdocsmith »

I once had to do a similar exercise for a project so I feel your pain. When I visited the office of the manager who said it was vital to the project, they had printed the entire help-system-rendered-as-pdf and had it proudly on their bookshelf behind them. Folders and folders of paper that I'm certain never got opened. They wanted us to provide an update process so they could keep it up to date. Yikes. It's a slippery slope.

On the embedding side of things... There could be a few things slowing it down:
Image resolution - ideally you'd optimise it for online, but might be worth checking if images aren't unecessarily large
Network speed - I've worked in situations where the source files were on a network and builds were slow because of network access issues (though I'm guessing it would also be slow for the help build in that case). Maybe try getting a local copy of the files and building there to see if it's a factor.
Image Compression - check you're not including excessively large dpi images in the pdf target (Target -> PDF Options -> Image Compression). Might help to downsample images to 300 or 150 dpi.

I'm making print books at the moment and my 300 page efforts are built (locally) in a few minutes, so there shouldn't be anything inherently slow about PDF building as opposed to help building.

Rob
Ioana_St
Jr. Propeller Head
Posts: 5
Joined: Thu Jun 18, 2020 3:02 am

Re: Print "Whole Book" From HTML5 Help?

Post by Ioana_St »

We also have clients who really, really like their PDFs, and I have about 80 help modules. I have a setup that lends itself well to automation, so I just need to click a button and wait for everything to get built. In its current incarnation, the process described below takes about 3 hours on my laptop and about 1.5 hours on a more powerful build server. (I never tried to build a mega-PDF that contains all 80 projects.)
We have a fair amount of images, but nothing excessive. The two things that I've seen affect build times dramatically are large tables (I have one 50-page table that takes 15 minutes to build) and MathML formulas.

My setup heavily relies on global project linking and variables:
  • In my global project, I have a PDF target defined. The PDF target uses variables everywhere a difference exists between individual modules (filename, cover title). Everything else is standardized (e.g. each of my modules has exactly 1 TOC, so the PDF target is defined to use the Default TOC).
  • Each child project has its set of local variables that store the name of that project (module name).
  • The global project includes a set of global variables that apply to all projects (release version, release date, etc).
In practice, this means that the file name and meta data in the PDF target are defined like: product_[%=Global-Variables.ShortReleaseNumber%]_[%=Local-Variables.HelpModule%]. This results into a file called something like product_213_data_administration.pdf.

In the post-build event of the PDF target, I have a command that copies the PDF from the Output folder to the root of the Content folder.

Then, the TOC of each module, I added the following:
  • Front matter (one cover page, one TOC page, one copyright page). These 3 topics use a Print condition that is excluded from my online help target.
  • A book called "PDF Version" with a topic that links to the PDF document that was moved to the Content folder. (The name is typed in manually... but maybe I could have used variables! I haven't tried.)
To build them all, I set up a bat file that runs madbuild.exe for each of the modules. (This takes a while to set up, but then you never have to mess with it.)

The workflow is as follows:
1. I run the batch file, the first module starts building.
2. The import file runs and, if needed, updates the target and variables from the global project.
3. The PDF gets built and has its filename and cover page populated according to the local variables of the module.
4. The PDF gets copied to the Content folder.
...and so on, until all PDFs are ready.
5. I run the online help build. Because the PDFs are already in the Content folder, they get copied over to the online help output and the links in the TOC work.

Hope this helps somewhat!
ChoccieMuffin
Senior Propellus Maximus
Posts: 2630
Joined: Wed Apr 14, 2010 8:01 am
Location: Surrey, UK

Re: Print "Whole Book" From HTML5 Help?

Post by ChoccieMuffin »

A couple of other things I'd want to consider.

1. For your own protection, I'd think about adding something to the page layout you use for your PDF that says something along the lines of "This PDF may not contain the most up-to-date information and is not controlled. For best results see the online help." so that it shows up on every page - a footer, maybe?

2. Depending on how your organisation wants to protect its IP, you might also want to have a watermark that says something like "NOT FOR DISTRIBUTION" or "COMPANY CONFIDENTIAL" or whatever else might be required, to reduce the likelihood of the PDF getting into the wild.

3. Not sure if it's possible, but you could look at whether the date the PDF is generated can also be added somewhere in your PDF. (I haven't had to do that, so don't know (a) if it can be done, or (b) if it can, how to.)
Started as a newbie with Flare 6.1, now using Flare 2023.
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
Post Reply