internal code names exposed - need flat file structure

This forum is for all Flare issues related to the HTML5, WebHelp, WebHelp Plus, and Adobe Air Targets
Post Reply
pdenchfield
Propellus Maximus
Posts: 574
Joined: Tue Oct 03, 2006 7:56 am
Location: Seattle, WA
Contact:

internal code names exposed - need flat file structure

Post by pdenchfield »

Hi all, I am in a team of many writers working from one Flare project. We organize our content files by folders, and often those folders use internal code names (especially for new features that don't yet have official names). Here is a bug I logged lamenting the lack of ability to flatten the file structure in the output so these internal code names do not get exposed when the output is integrated with the software product.

Issue: No ability to flatten folder structure for .htm files in webhelp deliverable when files are organized by folder in the Flare project. I imagine this is a common setup by many Flare users - folders of content by feature name. Lacking ability to flatten folder structure for output means that our organizational project-code-name scheme is exposed in the folder structure of the product seen by IT folks at customer sites. Exposing our project code names does not meet requirements for webhelp deliverables integrated into the product.

Repro:
1. Point a webhelp target to a TOC with topics located "one folder deep" in the project: Content/[project-code-name].
2. Check the box "Do not use "Content" folder in output."
3. Build the target.

Actual results:
The output places the .htm topics "one folder deep" in the set of files we need to install with the product.

Expected results:
The output should place all .htm topics at the root level of the set of files we need to install with the product - see the Flare Help: "The Content subfolder in a project is normally used to hold all of your content files. If you do not want this subfolder to be created when you generate online output, you can omit it. When you use this option and build output, the content files will be placed at the root of the output folder instead, rather than within the Content subfolder." OR - the target should allow us to change folder names at build time.
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: internal code names exposed - need flat file structure

Post by NorthEast »

I'm not sure that is a bug really, the option in Flare is working in the way it is says it does. All it does is not include the Content folder in the output, and your topics will be organised in the the folder structure that you designed.

If you don't want internal code names appearing in the output, then wouldn't a simple solution be to not use these code names for your folders? Just use a naming convention that is ok to be exposed in your output.
pdenchfield
Propellus Maximus
Posts: 574
Joined: Tue Oct 03, 2006 7:56 am
Location: Seattle, WA
Contact:

Re: internal code names exposed - need flat file structure

Post by pdenchfield »

Hi Dave,

Thank you for your reply!

In response to this quote:
the option in Flare is working in the way it is says it does
I would like to say that it is not immediately obvious from the Flare Help that the exclusion of the Content folder structure stops short of removing the deeper file structure. My output pointed to a TOC with only one topic, so the one-folder-deep architecture seems unnecessary, and there should be a way to turn that off for topics that all sit inside one folder, no matter how deep.

In response to this quote:
If you don't want internal code names appearing in the output, then wouldn't a simple solution be to not use these code names for your folders?
Although I agree that this solution technically works if you do it at the initial set up of the Flare project, I have these reservations:
* How do you come up with meaningful names for a team of writers who work in these separate folders? I suppose initials are one answer ("SW" for an internal code name "Star Wars"), but that approach might not work for all Flare users and permutations of Flare projects.
* How do you go back and rename folders in a Flare project with a team of writers on it? Flare's issues with Visual Studio Team Foundation Server (TFS) make renaming more difficult because folder renaming has to be done in the source control application - while everyone has stopped work temporarily - and then (if I'm not mistaken) links become broken in Flare and you have to manually resolve them within Flare.

Another thought I have is that there are probably multiple customers who set up their Flare projects the way we did - with folders using and thus exposing their internal code names. If I'm right, then MadCap has an interest in "turning off" exposure of folder names in the output file structure.
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: internal code names exposed - need flat file structure

Post by NorthEast »

pdenchfield wrote:My output pointed to a TOC with only one topic, so the one-folder-deep architecture seems unnecessary, and there should be a way to turn that off for topics that all sit inside one folder, no matter how deep.
The folder structure in your output just reflects the folder structure you've set up inside the Content folder.
The only time you can't control the folder structure is when you're importing content (Flare places the imported topics in a folder named after the import file).

If you did have an option to flatten the folder structure in the output, I can forsee some issues, like how it would handle duplicate file names in separate folders.
* How do you come up with meaningful names for a team of writers who work in these separate folders? I suppose initials are one answer ("SW" for an internal code name "Star Wars"), but that approach might not work for all Flare users and permutations of Flare projects.
Just use whatever you want, perhaps document it somewhere that people can refer to, so they know what goes where. It's not any different to choosing meaningful topic filenames really, naming a topic "Creating an account.htm" is obviously better than calling it "Topic1.htm".
And if your project code names are anything like ones I've been involved with, then whatever you come up with is going to be better than having a folder called "Congo".
* How do you go back and rename folders in a Flare project with a team of writers on it? Flare's issues with Visual Studio Team Foundation Server (TFS) make renaming more difficult because folder renaming has to be done in the source control application - while everyone has stopped work temporarily - and then (if I'm not mistaken) links become broken in Flare and you have to manually resolve them within Flare.
I know you can change folder names in Flare with VSS, but I can't vouch for TFS - why not create a test project and try it? (You don't want to mess up your live project!)

If you change the folder names/paths in TFS (outside of Flare), then you will get broken links. You would need to change the folder names in Flare's Content Explorer, so that it updates all your links.
pdenchfield
Propellus Maximus
Posts: 574
Joined: Tue Oct 03, 2006 7:56 am
Location: Seattle, WA
Contact:

Re: internal code names exposed - need flat file structure

Post by pdenchfield »

Hi Dave,

Regarding folder renaming, my coworker confirmed last week that renaming folders in Flare breaks the (TFS) source control history of the folders. Whether folder contents are also affected I'm not sure, but our team was given the order to rename folders in TFS only.

Regarding concerns over duplicate file names across folders, digits could be appended to the file names for differentiation where necessary. Maybe MadCap could come up with smarter ways to handle this dilemma. :-)

Having the option to flatten the file structure of the final deliverable - especially single-topic deliverables such as the start page document I created - would probably help a lot of Flare customers. MadCap, I'm counting on you to find an intelligent solution for this issue! :-)
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: internal code names exposed - need flat file structure

Post by NorthEast »

pdenchfield wrote:Regarding folder renaming, my coworker confirmed last week that renaming folders in Flare breaks the (TFS) source control history of the folders. Whether folder contents are also affected I'm not sure, but our team was given the order to rename folders in TFS only.
Ok, it works with VSS, so it's a limitation of Flare with TFS. If you do need to rename folders in TFS, you could fix the links in Flare by using a find and replace - e.g. if your old folder was Stuff, search for Stuff/ in your topics and TOC (fltoc) files.
pdenchfield
Propellus Maximus
Posts: 574
Joined: Tue Oct 03, 2006 7:56 am
Location: Seattle, WA
Contact:

Re: internal code names exposed - need flat file structure

Post by pdenchfield »

Thanks, Dave.

FYI. Search/replace is another Flare 4.1 issue making it difficult to globally change folder structure references and fix broken links created by renaming folders in TFS (which is done to avoid losing source control history). I have been using freeware tools to do any search/replace tasks that go beyond the current topic. Although the Edit > Find and Replace > Find in Files option helps me locate files containing the offending string, the Edit > Find and Replace > Find and Replace option does not replace said string beyond the active topic, even when I select "whole project" for "Find in." I logged a bug some time back.
KevinDAmery
Propellus Maximus
Posts: 1985
Joined: Tue Jan 23, 2007 8:18 am
Location: Darn, I knew I was around here somewhere...

Re: internal code names exposed - need flat file structure

Post by KevinDAmery »

pdenchfield wrote:Having the option to flatten the file structure of the final deliverable - especially single-topic deliverables such as the start page document I created - would probably help a lot of Flare customers. MadCap, I'm counting on you to find an intelligent solution for this issue! :-)
If you haven't already, submit a feature request. Asking for it in the forums may or may not be seen, but if you submit a feature request they'll definitely get it in their system. (Whether it gets implemented or not is a whole other story....)

http://www.madcapsoftware.com/bugs/submit.aspx
Until next time....
Image
Kevin Amery
Certified MAD for Flare
pdenchfield
Propellus Maximus
Posts: 574
Joined: Tue Oct 03, 2006 7:56 am
Location: Seattle, WA
Contact:

Re: internal code names exposed - need flat file structure

Post by pdenchfield »

Thanks, Kevin! I did log a bug. The reply I received from MadCap indicated that my name was added to a feature request to "force flare into a flat file structure even if you have folders in your content explorer."
KevinDAmery
Propellus Maximus
Posts: 1985
Joined: Tue Jan 23, 2007 8:18 am
Location: Darn, I knew I was around here somewhere...

Re: internal code names exposed - need flat file structure

Post by KevinDAmery »

That's a good sign: Madcap have always told us that the more people ask for a feature, the more priority it gets, so this increases your chances of seeing it.

FWIW, I think that an option to flatten the folder structure would be useful for some workflows. I probably wouldn't want it to be the default behaviour, but having the option would be good.
Until next time....
Image
Kevin Amery
Certified MAD for Flare
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: internal code names exposed - need flat file structure

Post by NorthEast »

pdenchfield wrote:the Edit > Find and Replace > Find and Replace option does not replace said string beyond the active topic, even when I select "whole project" for "Find in." I logged a bug some time back.

The find and replace does work, although it isn't very intuitive. You start the search by clicking the Start button, not by clicking Find Next (which will only search the current topic). Then use Find Next, or >> (to skip to next topic).
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: internal code names exposed - need flat file structure

Post by RamonS »

KevinDAmery wrote:FWIW, I think that an option to flatten the folder structure would be useful for some workflows. I probably wouldn't want it to be the default behaviour, but having the option would be good.
That is especially useful when using IIS, since it runs on top of Windows no calls can be longer than 256 characters, including a URL to be served up by IIS. Sadly, Microsoft still clings to this boopid rule from the DOS ages. So having the help buried somewhere in a help folder of a web app may require a really flat structure.
pdenchfield
Propellus Maximus
Posts: 574
Joined: Tue Oct 03, 2006 7:56 am
Location: Seattle, WA
Contact:

Re: internal code names exposed - need flat file structure

Post by pdenchfield »

Thanks again, Dave! Good to know that the whole-project search/replace function works!
Post Reply