internal code names exposed - need flat file structure
-
- Propellus Maximus
- Posts: 574
- Joined: Tue Oct 03, 2006 7:56 am
- Location: Seattle, WA
- Contact:
internal code names exposed - need flat file structure
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.
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.
Pamela Denchfield
http://www.pameladenchfield.com
http://www.pameladenchfield.com
Re: internal code names exposed - need flat file structure
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.
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.
-
- 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
Hi Dave,
Thank you for your reply!
In response to this quote:
In response to this quote:
* 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.
Thank you for your reply!
In response to this quote:
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.the option in Flare is working in the way it is says it does
In response to this quote:
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: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?
* 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.
Pamela Denchfield
http://www.pameladenchfield.com
http://www.pameladenchfield.com
Re: internal code names exposed - need flat file structure
The folder structure in your output just reflects the folder structure you've set up inside the Content folder.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 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.
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".* 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.
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".
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!)* 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.
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.
-
- 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
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!
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!
Pamela Denchfield
http://www.pameladenchfield.com
http://www.pameladenchfield.com
Re: internal code names exposed - need flat file structure
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 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.
-
- 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
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.
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.
Pamela Denchfield
http://www.pameladenchfield.com
http://www.pameladenchfield.com
-
- 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
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....)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!
http://www.madcapsoftware.com/bugs/submit.aspx
Until next time....
Kevin Amery
Certified MAD for Flare
Kevin Amery
Certified MAD for Flare
-
- 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
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."
Pamela Denchfield
http://www.pameladenchfield.com
http://www.pameladenchfield.com
-
- 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
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.
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....
Kevin Amery
Certified MAD for Flare
Kevin Amery
Certified MAD for Flare
Re: internal code names exposed - need flat file structure
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).
-
- 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
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.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.
New Book: Creating user-friendly Online Help
Paperback http://www.amazon.com/dp/1449952038/ or https://www.createspace.com/3416509
eBook http://www.amazon.com/dp/B005XB9E3U
Paperback http://www.amazon.com/dp/1449952038/ or https://www.createspace.com/3416509
eBook http://www.amazon.com/dp/B005XB9E3U
-
- 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
Thanks again, Dave! Good to know that the whole-project search/replace function works!
Pamela Denchfield
http://www.pameladenchfield.com
http://www.pameladenchfield.com