5 Replies Latest reply on May 4, 2007 12:50 AM by RoboColum(n)

    RH Project Structure - Source File (*HTM) - advise pls

    Simswrite
      Hi All, (running RH X5.0.2 on Windows XP SP2)

      I transferred & inherited an 'unstructured RH HELP s/ware documentation system (*.chm output) and I'm trying to determine upfront the best way to organize, share and manage the projects for chm help, documentation & translation/localization.

      I'm a Newbie to RH X5 but not tech. authoring etc, but gaining experience fast, such as editing/updating existing (legacy) projects - building them out as .chm projects - though I intend to advance to shared outputs i.e. printed docs etc in good time. But How?

      My output (.chm's)62 chms and 54 in the other with approx. 2800 - 3500 topics - has various requirements, but the main being its shared between 2 major branded products i.e. 'Product 1' and 'Product 2' - Product 1 being the flagship and the forerunner.. this causes soo much hassle as the S/ware products are sold or INSTALLED in so many differing variations/permations.. so you have to be very aware of what’s what and goes with what variation of install - time will improve this..!!

      I've found Conditional Build tags useful at this stage to define each products content - for inclusion/exclusion!

      Where as the predecessor preferred to do it the long/hard way and recopy the Topic(*.htm) file and segregate it in another folder (unfortunately, usually leaving the same filename and then edit the Product 1 data for Product 2's requirements.. (Conditional text has helped this..). ever heard of SIngle Source authoring ..?

      However, there are a magnitude of repeated, duplicated topics through out the total help system, becos of the above and I wish to bring law & order to this non share friendly file structure - ex BroadVision user speaking - and have the following question..

      1. Do the source files, (*.htm) files, have to be stored/located in same folder as the RH project (*.xpj).

      Could you place the source files in a separate location, away from the .xpj.. i.e. on a drive labeled F:\\Source Files (HTML)\HOUSE projects... Then have on the local drive i.e. D:\, the individual projects (*.xpj's) in separate folders, such as GREEN HOUSE, RED HOUSE, WHITE HOUSE projects which are all linked to 1 copy of Source files (HTML )?

      I hope the output from each separate project will build out with the same .chm filename but contain the according Green or White house data?

      This would allow just 1 lot of source files with differing types of HOUSE text/data - but conditioned appropriately could provide multiple deliveries separately & version control?

      Please say yes - although it’s not necessary for it to work across separate drives/networks but it will be desired in the future...

      2. The second and quicker way I assume, would be to use multiple project files in the same complete RH project and design the projects files accordingly - prod1_RED HOUSE.xpj and prod2_RED HOUSE.xpj then treat the xpj’s as separate projects and include/exclude topics as you want...

      3. The first is friendlier when collecting all *.htms from 1 drive and posting for translation I think – instead of having to mine the HTM’s out of each folder? Agree

      4. Also can anyone advise on the amount of work (damage) I will have to do depending on which way I decide to structure the source files/projects - as the existing projects (64+) are all in self contained individual folders .... would prefer not to be left with more work.. than what I'm actually achieving!! (Ref. to Deleting and then re-importing all the topics in as file reference have dropped…. like F/Maker?

      I welcome all ideas or any suggestions please Help.

      Hope to hear from people soon
      Sim

      BTW - Wished my company had bought Vers. RH X6 - seen the Toc Books can now be Conditioned – v nice….
        • 1. Re: RH Project Structure - Source File (*HTM) - advise pls
          RoboColum(n) Level 5
          The HTM files that make up your RH project must all be stored in the same location. However you can (and indeed should for a project your size) organise those files into a series of folders in RH. For example your project folder can have any number of folders with relevant topics in them. Set-up these folder in RH via the File > New > Folder menu item in the Project tab and then click and drag the topics into them. It is much easier to organise topics in this way.

          As far as the build tags are concerned, the output file remains the same but only contains the topics (or indeed the topic content as the tags can be applied to elements of a topic) according to the build expression used to include/exclude. Once you have decided on the build tags and assigned them accordingly, it should make things a lot easier for you.

          As far as generating printed output, this may be further down the line. You can do this by using the Printed Documentation SSL.

          BTW always have your source files on a local drive and backed up to a network drive. RH uses an underlying Access DB which does not sit well when used on a network. Many users report problems which disappear once their source files are located on their hard drive.
          • 2. Re: RH Project Structure - Source File (*HTM) - advise pls
            RoboColum(n) Level 5
            I meant to say that I am all for avoiding any duplication. If you have general stuff (e.g. how to logon) that is the same in all your projects, try putting this in one help file that you can merge into all the others as required. Before you do anything, you'll need to do a bit of analysis. I like drawing lots of boxes on a piece of paper and seeing how they fit together.
            • 3. Re: RH Project Structure - Source File (*HTM) - advise pls
              Simswrite Level 1
              Hi Colum,

              Thanks for you reply - however I think you might have misunderstood my question(s) or general intention.

              You stated;
              > 'However you can (and indeed should for a project your size) organise those files into a series of folders. For example your project folder can have any number of folders with relevant topics in them. Set-up these folder in RH via the File > New > Folder menu item in the Project tab and then click and drag the topics into them. It is much easier to organise topics in this way.' <

              But Colum when you come to build this 1 project, based on your suggested structure above, this would build out as just 1 finished final file - VERYBIG.chm. It would not allow for variations of the install - (hence the reason I've 64 chm files).

              Each feature or most of the S/ware menu commands/options are in their own project/folder.. and that supplies 1 chm.

              What I am asking is it possible to create more than 1 project & .chm, say 10 projects/.chms from 1 lot of htm files. A more accurate example may be required... see below:

              I've 1 Folder called 'MY DREAM House' that contains all htm files, and has 10 subfolders labeled as below with supporting content:

              1. Foundations/Ground Works - contains 10 htm files listing how/why foundations are required & built.
              2. Wall & Brick work design - contains 10 htm files listing how/why
              3. Doors/Windows design types - contains 10 htm files listing how/why
              4. Ground floor design/ rooms - contains 10 htm files listing how/why....
              5. 1st Floor Design / rooms - contains ... 7 htm files listing how/why....
              6. 2nd Floor Design / rooms - contains ... 17 htm files listing how/why....
              7. Electrical Systems /Design - contains 22 htm files and so on....

              ............ Up until 10 individual Features (in separate Folders), with the supporting HTM files, for the HELP design of MY DREAM House....

              Now you have three House Developers that require the HELP formatted & specific Terminology their way.. i.e. 3 different customers, but who all need the same general text/pics & but differing Languages. So there are at least 3 deliverables involved now

              And each customer/client is not getting a complete publication of all 10 Features - jobs required.

              For Customer 1
              You want to design the project (Customer1.xpj) to include only Floor Design files - all 3 folder which totals 34 topics.. and they receive it in 1 chm.. called DREAM HOUSE.chm

              Customer 2
              You want to design the project(Customer 2.xpj) to include only Electrical Systems /Design & Foundations/Ground Works files - 2 folders containing 32 Topics - in 1 finished file called DREAM HOUSE.chm

              Customer 3
              your favorite customer - You want to design the project (Customer 3.xpj) to include all 10 Folders/Features (not RH HELP folders i.e. folders), supplying all the topics in a structured RH TOC order just as the others have been, but with topics excluded - but he gets over 80 topics in 1 file called DREAM HOUSE.chm

              Separate OUTPUT folders
              Of course you would require each .xpj to build out to a different location such as Customer 1_Tender OUTPUT, and Customer 2_Tender OUTPUT and so on.. as the file names being the same would be confusing.. (preferably I don't want to have to keep flicking the generate Build conditions each time and have to remember and adjust manually!

              I think this may break down my requirement a bit better.
              What I have just explained is my companies products (software) being installed, but in all of there variations, scaled down/lite version, major install or flagship fully paid up install (Customer 3) and the .chm filenames are the same so the menu cmd/registry entries call the file .. and the htm files remain in 1 place ready for copy to translation..

              Do you understand what I'm trying to achieve now, with this greater detail?

              Please anyone feel free to HELP or offer comments
              Thanks again
              Sim
              • 4. Re: RH Project Structure - Source File (*HTM) - advise pls
                MergeThis Level 4
                I think you're unaware that you can create as many layouts as you choose, in addition to conditionalizing topics or topic content. In the Project tab, select Single Source Layouts, right click Microsoft HTML Help, and select New Layout. In the New Layout window assign a name in the Layout Name field and click OK. Right click the new layout, select Properties, and configure your settings for that layout.

                I'm not sure if there's a limit to the amount of layouts you can have, but you might be able to break up the overall structure into several groups (projects) if you have to.


                Good luck,
                Leon
                • 5. Re: RH Project Structure - Source File (*HTM) - advise pls
                  RoboColum(n) Level 5
                  Hi Sim. Using Leon's post you can have multiple single source layouts (all CHM output if you wish) outputting to different locations. Using that technique together with your build tags you'll be able to achieve what you want. My advice would be to think very carefully about your use of build tags and what ones would be required in each version of the CHM. I've found using a spreadsheet or some sort of matrix useful for this.