Gerard has asked for the wisdom of the Perl Monks concerning the following question:

I have not yet started to implement this solution, but rather am just starting to think about my different options. What better place to ask for advice than the monastery.
I will be maintaing "online help" files for two different software products. One is the windows desktop version, and the other is the online version of the same product. Effectively the documentation will be very similar in parts. Both will be produced in html, which can be done offline, and the dekstop version will have the help files converted to "compiled html help files". I already have adequate tools for performing this operation.

What I think I want to have (at this point) is some sort of master file that holds the topics that are the same, and include some sort of extra tags in each of the seperate collections of help files so that I can generate html files and quickly populate it with the topics that are the same. I won't have to do this very often, but it will save me from maintaining the same data in two places.

Now for my questions: I have never done anything like this before, can anyone recommend any modules etc. that would be worth looking into. At this stage I am very open to suggestions, as I have not even begun to code yet.
Any help much appreciated and Merry Christmas, or whatever you are celebrating this season
Regards,
Gerard

Replies are listed 'Best First'.
Re: offline html help generation
by TVSET (Chaplain) on Dec 18, 2003 at 23:47 UTC
    I would suggest to use DocBook instead of HTML for documentation. DocBook is XML based format that was specifically designed for technical documentation writing. It is easy to convert to any other format that you might need, such as HTML, PDF, PostScript, text, etc.

    If you would have been using DocBook, then your problem could have been easily solved. Look, for example, here (Chapter 1 of "DocBook: The Definitive Guide" by Norman Walsh and Leonard Muellner). Scroll down to "Marked sections" to see an example (specifying Draft parts of the document). You can also use the rest of the book to find a number of good reasons to use DocBook instead of HTML. :)

    My 2 cents.

    Leonid Mamtchenkov aka TVSET

[reply]
Re: offline html help generation
by Tuppence (Pilgrim) on Dec 18, 2003 at 23:53 UTC

    This may be overkill, but for this I would use HTML::Mason to mark up your pages. It is designed for dynamic HTML generation ala PHP, with perl code being able to be inlined in your HTML.

    It can be called from the command line, and a script to render out your documentation shouldn't be too tough.

    Mason calls each HTML file a 'component', and components can have attributes. I would envisage your problem being solved by using the attribute tags to define what the file has in it, then have a list that goes through components looking for matching attributes to what you want.

[reply]
      ++ to you both for excellent advice. Looks like html::mason may be what I am after, I have just started wading through the documentation now...

      Thanks heaps,
      Gerard
[reply]
Re: offline html help generation
by PodMaster (Abbot) on Dec 19, 2003 at 05:25 UTC
[reply]

Back to Seekers of Perl Wisdom