http://qs321.pair.com?node_id=353876

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

I have heard that a good reason for using templates is that they can be used to automatically generate documentation. I am using HTML::Template. I use templates within templates. Some templates are used by various different scripts.

I find that it can be difficult to track down how a particular piece of HTML output was generated.

I would like to read some of that autogenerated documentation. How do I create it?

I can imagine an HTML::Template subclass creating annotated HTML which illuminates the generation process. Does such a thing exist, or is there some reason why it doesn't?

It should work perfectly the first time! - toma
  • Comment on Can I automatically generate documentation from HTML::Template?

Replies are listed 'Best First'.
Re: Can I automatically generate documentation from HTML::Template?
by hv (Prior) on May 17, 2004 at 12:55 UTC

    I'm not familiar with HTML::Template, but it should be trivial, either in code (probably with a minor subclassing) or by hand, to put a marker at the beginning and end of each template:

      <!-- path/to/template -->
  ...
  <!-- /path/to/template -->

    [download]

    Hugo

[reply]
[d/l]
      When I have templates within templates, this approach is not as useful as I hoped, for large documents at least.

      I would prefer documentation that summarizes the hierarchical HTML structure and the variables used, perhaps even automatically generating diagrams.

      It seems that most general-purpose things like this that I can easily imagine have already been written. Perhaps another templating system has such a feature? If not, I can take care of it.

      It should work perfectly the first time! - toma
[reply]

        If I understand you correctly, you want a central repository that contains the variables used in each template file. I don't know of any current tools for this. It shouldn't be too difficult, though. HTML::Template->param() in list context returns the names of all variables in the template. This may suffice for your purposes.

        ----
        : () { :|:& };:

        Note: All code is untested, unless otherwise stated

[reply]
[d/l]
[select]
Re: Can I automatically generate documentation from HTML::Template?
by tachyon (Chancellor) on May 17, 2004 at 06:21 UTC

    You can do $t = HTML::Template->new( filename => 'file.tmpl', debug => 1  ); which will write to STDERR ie your server error logs.

    cheers

    tachyon

[reply]
[d/l]
      This gives me a lot of lines that look something like: 
      ### HTML::Template Debug ### 
/home/toma/audio/dyn6/perllib/EffectBlock
/templates/Add.tmpl : line 2 : parsed VAR insig1

      [download]
      (newlines added)
      but nothing I would consider to be documentation. Am I missing something?
      It should work perfectly the first time! - toma
[reply]
[d/l]

        Probably have to hack source to take an extra options flag and print the debugging info you want I guess....

        cheers

        tachyon

[reply]

Back to Seekers of Perl Wisdom