Beefy Boxes and Bandwidth Generously Provided by pair Networks
No such thing as a small change
 
PerlMonks  

Can I automatically generate documentation from HTML::Template?

by toma (Vicar)
on May 17, 2004 at 06:03 UTC ( #353876=perlquestion: print w/replies, xml ) Need Help??

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 (Parson) 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 -->

    Hugo

      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

        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

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

      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
      (newlines added)
      but nothing I would consider to be documentation. Am I missing something?
      It should work perfectly the first time! - toma

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

        cheers

        tachyon

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://353876]
Approved by blokhead
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others chanting in the Monastery: (5)
As of 2020-09-20 17:44 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    If at first I donít succeed, I Ö










    Results (122 votes). Check out past polls.

    Notices?