Module Naming: 'Template' Name Conflict & Author Unreachable
Ian Flanigan
Hello again,
I've created a set of modules to manipulate document templates. I've
tentatively named them 'Template', 'Template::Place', 'Template::HTML'
and 'Template::POD'. All of these are object-oriented modules.
My purpose in creating the these modules was to allow me a way to
separate a CGI script from its user interface (i.e. the HTML it spits
out). My goal was to create a system that would allow a user
unfamiliar with CGI programming to be able to change the look of a
script by editing normal HTML documents using their favorite editor.
As I thought about the project, I figured that it could be used for
more than just HTML, so I generalized everything.
I would like to upload these modules to CPAN, but I am unclear as to
whether 'Template' is a good name (though it is the only name I can
think of). Also, there is already a Text::Template module which is
significantly different. Also, because the system can be used for
almost any kind of document, I hesitate to put it under Text:: or
HTML:: or anything else. Does it make sense, then, to make a toplevel
category for it?
Any thoughts, ideas, or suggestions would be appreciated.
Thanks,
Ian Flanigan
----
Following is a short description of what the Template modules do:
Templates all have the following properties:
o Templates have a set of parameters. The only system defined
parameter is the "NAME" parameter, which names the template. All
other parameters may be interpreted by the perl script in
whatever way it likes.
o Templates have a set of variables. Each time a variable is
referenced in the document, its value is inserted.
o Templates may define sub-templates (and so on).
o Templates define 'Places'--locations in the document where text and
other templates may be inserted. Places are unlike variables in
that any number of things may be inserted at a Place and *all* of
them will be added in FILO order at that spot in the document.
Places, like templates, have parameters. Again, the only system
defined parameter is "NAME", which names the place.
Here is a small example:
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<!-- $Id: ECOReport.html,v 1.2 1997/03/18 00:27:01 flan Exp $ -->
<html>
<head>
<title>Sign Off Report on ECO: @@number@@</title>
</head>
<body>
<h1>Sign Off Report on ECO: @@number@@</h1>
<table border="1">
<tr>
<th>ECO Number</th>
<th>Revision</th>
<th>Verification #</th>
<th>Full Name</th>
<th>Title</th>
<th>Date</th>
</tr>
<!-- Place NAME=ECO -->
<!-- Template NAME=ECO -->
<tr>
<td>@@number@@</td>
<td>@@revision@@</td>
<td>@@vernum@@</td>
<td>@@name@@ (@@login@@)</td>
<td>@@title@@</td>
<td>@@date@@</td>
</tr>
<!-- /Template -->
</table>
</body>
</html>
First, the whole document is a template. In that template, words
surrounded by '@@'s are variables. They will be replaced by the
variable's value when the document is rendered. (Note that these are
*NOT* perl variable names; all variables are local to each template.)
The comment "<!-- Template NAME=ECO -->" starts the definition of a
new template named "ECO". That continues until the
"<!-- /Template -->" comment. Note that the ECO template is just
*defined* by this section of the document--it does not necessarily get
inserted there. Rather, it *may* be inserted at a Place, like the one
defined by "<!-- Place NAME=ECO -->". In fact, the template may be
inserted multiple times into the same Place. In this case, they form
rows of a table.
Anyway, that's probably enough for a "short" description. :-)
Brad Appleton
In article <pi1yba9...@famine.engwest.baynetworks.com>,
Ian Flanigan <fl...@cs.wustl.edu> writes:
> Hello again,
>
> I've created a set of modules to manipulate document templates. I've
> tentatively named them 'Template', 'Template::Place', 'Template::HTML'
> and 'Template::POD'. All of these are object-oriented modules.
If your talking about using these modules as more convenient ways of
writing out documents in the given format to a given stream, there
seems to be a pattern of calling them things like POD::Stream,
HTML::Stream, ..., XXXX::Stream (Im pretty sure that HTML::Stream
already exists on CPAN).
>I would like to upload these modules to CPAN, but I am unclear as to
>whether 'Template' is a good name (though it is the only name I can
>think of).
I dont care for the "Template" name my self. I think the XXX::Stream
name would be more accurate or more consistent with existing modules.
If you insist otherwise, then DocTemplate would be more mnemonic IMHO.
> Also, because the system can be used for almost any kind of
> document, I hesitate to put it under Text:: or HTML:: or anything
> else.
Why? If someones looking for HTML stuff they are typically going
to look for it under HTML::Xxxxx. If the *only* theing they
want to use is the HTML template, why should that namespace
be polluted with other modules that have nothing to do with HTML?
I think Text::Stream, ... would be a much better separation than
Template::Xxxxx.
> Does it make sense, then, to make a toplevel category for it?
Not in my personal opinion (but then again, my opinion plus one
dollar will give you one dollar ;-)
--
Brad Appleton <bra...@enteract.com> | http://www.enteract.com/~bradapp/
"And miles to go before I sleep." | 2600+ WWW links on CS & Sw-Eng
Eric D. Friedman
>Text:: something would be okay as well I guess.
Text::Template::HTML and so forth makes the most sense to me. A
Template is a Text, after all.
my two cents,
Eric
--
Eric D. Friedman
frie...@uci.edu
lvi...@cas.org
According to Brad Appleton <Brad_Apple...@email.mot.com>:
:In article <pi1yba9...@famine.engwest.baynetworks.com>,
:Ian Flanigan <fl...@cs.wustl.edu> writes:
:> I've created a set of modules to manipulate document templates. I've
:> tentatively named them 'Template', 'Template::Place', 'Template::HTML'
:> and 'Template::POD'. All of these are object-oriented modules.
:
:> Also, because the system can be used for almost any kind of
:> document, I hesitate to put it under Text:: or HTML:: or anything
:> else.
:
:Why? If someones looking for HTML stuff they are typically going
The reason why is as he states - his code is so general that it could
be used to generate text fiels of mailing lables, resumes, nroff documents,
programs, etc. It's a general mechanism where one defines the skeleton of
a file, and then fills in variables thru the file. The results need not
be any one 'type' of file. I certainly would never think of looking under
HTML for such a thing. I would how ever not be surprised to find such
a thing under File:: .
:I think Text::Stream, ... would be a much better separation than
:Template::Xxxxx.
Text:: something would be okay as well I guess.
--
Larry W. Virden INET: lvi...@cas.org
<URL:http://www.teraform.com/%7Elvirden/> <*> O- "We are all Kosh."
Unless explicitly stated to the contrary, nothing in this posting should
be construed as representing my employer's opinions.
Mark Mills
On 23 Apr 1997 15:59:07 -0700, Ian Flanigan <fl...@cs.wustl.edu> wrote:
>I would like to upload these modules to CPAN, but I am unclear as to
>whether 'Template' is a good name (though it is the only name I can
>think of). Also, there is already a Text::Template module which is
>significantly different. Also, because the system can be used for
>almost any kind of document, I hesitate to put it under Text:: or
>HTML:: or anything else. Does it make sense, then, to make a toplevel
>category for it?
>
>Any thoughts, ideas, or suggestions would be appreciated.
>Ian Flanigan
Why not DOC or DOCU or DOCUMENT?
If it is generalized then for goodness sake don't name it HTML :>
[Hopper, Dennis]: There's mines over there, there's mines over
there, and watch out those goddam monkeys bite, I'll tell ya.
==Apocalypse Now==
Andy Wardley
I've been working on a similar Template module for some time now and
"The Powers That Be" permitting, will be able to release it to CPAN
in the near future.
Looking at Ian's example our respective modules share a lot of
functionality: variables substitution, block/sub-template definition,
etc. Mine goes a little way further, offering external document
inclusion (great for web page headers/footers), conditional inclusion
(eg %% INCLUDE html/header if="some_condition" %%), print filters and
formatters, external functions (e.g. run some command and include the
output) and currently in development: loops, automatic document
indexing and some other neat stuff.
It's a pity that these modules replicate elements of each other's
functionality (I even wrote a derived HTML module), but that's
often the way things happen - this module, in it's most basic form,
was developed to satisfy an internal need and it's only now after
some 12 months or so of work on and off, that it's become what it
is and ready for the world.
At present, I've also used the Template:: stem although I realise that
while this is suitable for internal use, it would trample on too
many toes in CPAN, (especially if Ian gets there first :-):
Template::Base
Template::Html (ISA Template::Base)
Template::WhateverYouWant
The name I have considered for this module is "MetaText" and I had
previously assumed it would fall into CPAN as "Text::MetaText". Ian's
work (and also Text::Template and Text::Vpp which are similar) might
suggest that a top-level Template:: category is required. I could
then adopt Template::MetaText and Ian could choose his own "sub-domain":
Template::ianstemplate::Place, etc.
My preference, and I suspect that which is most in keeping with the
current CPAN structure, would be for Ian to use Text::Template::*
and for me to use Text::MetaText::*. The only problem with this
is the conflict with the existing Text::Template (which also defines
Text::Template::Lexer). The existing Text::Template, version 0.1b
is dated 25-Jan-96 and seems to offer a subset of what Ian's module
does. If the original author cannot be contacted, is there any
justification in "superceding" the original package. Failing that,
I guess Ian will have to come up with a new name (but "MetaText" is
already taken :-).
A
[ My newsfeed is very ropey at the moment. I'll continue to monitor
the group, but I'd appreciate a CC: by mail to a...@peritas.com on
any follow-ups just to be safe...ta ]
--
Andy Wardley <a...@peritas.com> **NEW** http://www.peritas.com/~abw
A responsible and professional individual who has no need for silly
comments, inane banter or bizarre "in-jokes" in his signature file.
Brad Appleton
In article <5k03du$sct$1...@cas.org>, lvi...@cas.org writes:
> The reason why is as he states - his code is so general that it could
> be used to generate text fiels of mailing lables, resumes, nroff documents,
> programs, etc. It's a general mechanism where one defines the skeleton of
> a file, and then fills in variables thru the file. The results need not
> be any one 'type' of file.
I understood that much. Certainly the main/abstract part of it wouldnt
go under something like HTML::Xxxxx, but the HTML part of it might.
>:I think Text::Stream, ... would be a much better separation than
>:Template::Xxxxx.
>
>Text:: something would be okay as well I guess.
Some have suggested Text::Template. If you end up using the word
"Template" anywhere I would urge you to precede it with "Doc" to be
something like "DocTemplate". By itself, the term "template" is so
general that while it may seem obvious to some what you mean buy it,
it will be extremely UNobvious to others. Adding those extra letters
(like DocTemplate or FormTemplate) should be more helpful.
Ian Flanigan
appl...@chiefs.northbrook.aieg.mot.com (Brad Appleton) (Brad) writes:
flan> Also, because the system can be used for almost any kind of
flan> document, I hesitate to put it under Text:: or HTML:: or
flan> anything else.
Brad> Why? If someones looking for HTML stuff they are typically going
Brad> to look for it under HTML::Xxxxx. If the *only* theing they want
Brad> to use is the HTML template, why should that namespace be
Brad> polluted with other modules that have nothing to do with HTML?
lvi...@cas.org (lvirden) writes:
lvirden> The reason why is as he states - his code is so general that
lvirden> it could be used to generate text fiels of mailing lables,
lvirden> resumes, nroff documents, programs, etc.
Exactly. So, if I call it HTML::XXXX and POD::XXXX, etc, that misses
the point. And it also makes it problematic as to where to stick the
base class.
One solution (which addresses Andy Wardley's module as well) would be
to have a top level domain called Template:: under which we could have
things like
Template::
MetaText
DocTemplate
Then, for each format supported, we could add
HTML::
MetaText
DocTemplate
POD::
MetaText
DocTemplate
and so on. What do people think of that?
Thanks,
Ian Flanigan
a...@peritas.com (Andy Wardley) (Andy) writes:
Andy> Looking at Ian's example our respective modules share a lot of
Andy> functionality: variables substitution, block/sub-template
Andy> definition, etc. Mine goes a little way further, offering
Andy> external document inclusion (great for web page
Andy> headers/footers), conditional inclusion (eg %% INCLUDE
Andy> html/header if="some_condition" %%), print filters and
Andy> formatters, external functions (e.g. run some command and
Andy> include the output) and currently in development: loops,
Andy> automatic document indexing and some other neat stuff.
I thought of adding this stuff too, but my philosophy was: "If I can
do it in Perl all ready, why shouldn't I do it there?" I tried to
keep my module an output system only; it should have no "smarts" at
all. Therefore I purposefully omitted if's, includes, etc. I figured
that those could be layered on top if they were needed. (And I made
sure that this *would* be easy.)
On the other hand, I've run into cases where it's handy to have smarts
in both places, but that's rare.
I'd be interested in seeing what you have so far. I'm planning to
make a preliminary distribution of my stuff RealSoonNow(tm) and I'd
like to have comments on it. I'll change the name to something
besides "Template" (but not "MetaText" :-) in the meantime.
Eryq
Brad Appleton wrote:
> If your talking about using these modules as more convenient ways of
> writing out documents in the given format to a given stream, there
> seems to be a pattern of calling them things like POD::Stream,
> HTML::Stream, ..., XXXX::Stream (Im pretty sure that HTML::Stream
> already exists on CPAN).
It does. :-)
--
___ _ _ _ _ ___ _ Eryq (er...@enteract.com)
/ _ \| '_| | | |/ _ ' / Hughes STX, NASA/Goddard Space Flight Cntr.
| __/| | | |_| | |_| | http://www.enteract.com/~eryq
\___||_| \__, |\__, |___/\ Visit STREETWISE, Chicago's newspaper by/
|___/ |______/ of the homeless: http://www.streetwise.org
Daniel LaLiberte
Andy Wardley wrote:
> It's a pity that these modules replicate elements of each other's
> functionality (I even wrote a derived HTML module), but that's
> often the way things happen
The nature of some problems seems to be that many alternative solutions
must be investigated. Template languages seem to be one of those
problem areas.
I worked a few weeks (last spring) on an extension to the
Text::Template module generalizing it as I thought necessary for
my purposes. I got it mostly working, but got tangled up
in name space problems. I think it is worth considering some
of the features I was working on, so others might benefit. I'll
provide my code to anyone interested since I am not doing anything
with it.
For a little background, the Text::Template module provides
a very simple and universal mechanism for embedding code in
any text. Any Perl expression to be evaluated is simply wrapped
in curly brackets. E.g. The title is: {$title}
There is support for reading templates from files or specifying
templates dynamically in a Perl program. Evaluation is in the
context of a designated package.
There were two main extensions I was interested in. First,
I wanted to be able to "compile" the template to Perl code that
could be executed more quickly, thus not requiring a run-time
interpreter of the template format.
Second, along with compiling comes the notion of compile-time
vs run-time evaluation. So to indicate compile-time evaluation,
I wrapped expressions in double curlies.
E.g. Compile-time evaluation looks like: {{$var}}
The result of the compile-time evaluation is more text that
is evaluated at run-time.
The compile-time evaluation is most useful for including other
template text or files in-line. Therefore, a large comglomerate
template composed of several separately maintained template pieces
could be compiled into a single Perl file for relatively fast
execution.
Some kind of "include" or "use" construct
would be convenient notation here, but then this is more special
syntax that I wanted to avoid, as did the original author of the
module. It seems to be far better to do everything else in
"straight" Perl.
Larry W. Virden
In article <5k1rub$e...@aoxomoxoa.peritas.com>,
Andy Wardley <a...@peritas.com> wrote:
:
:I've been working on a similar Template module for some time now and
:
:
:It's a pity that these modules replicate elements of each other's
:functionality (I even wrote a derived HTML module), but that's
:often the way things happen - this module, in it's most basic form,
Actually, somewhere in the Perl resources there is some comments about
this. I think it may be in the modules listing; there's a note that
says that if folk 'register' the ideas on which they are working with
the CPAN folk, then the naming can be worked out, groups can work
together, and parallel efforts become intentional rather than accidental.
Unfortunately, this seems to be overlooked at times.
Andy Wardley
[ in reply to messages from Ian Flanigan and Daniel LaLiberte that I've
seen via email, but not yet through news so apologies if I'm outta sync ]
Ian and Daniel both raise the point "if I can do it in Perl, why do it
in text?" This is absolutely valid for many cases and I think this
is a compelling argument for having a "Template Lite" (Text::TempLite? -
Nah, far too cryptic) that handles simple substitutions and little more.
In particular, the idea of being able to "compile" the template down to
perl code for faster executiton is nice.
However, I still see the need for the all-singing, all-dancing
Text::MetaText module, perhaps because we've been using it (or rather,
it's predecessor) here (work) for nearly a year and have grown to find it
indispensable. In particular, some of our designers who have little or
no perl experience can "embed" little bits of magic into web pages.
Leaving aside the simplest cases ("I'm sorry %%name%%, I can't do that."),
there is much to be gained from even simple INCLUDE's of external files
with a bit of run-time processing thrown in on the side.
For example, we have 900ish web pages at our site (http://www.peritas.com)
of which 100 are static and the other 800 are generated dynamically.
The static pages look somthing like this:
%% INCLUDE html.header
title = "This is a sample page"
keywords = "perl,example,MetaText"
author = "Andy Wardley"
%%
%% INCLUDE header section=2 %%
... page content...
%% INCLUDE footer %%
'html.header' generates the approriate "<HTML><HEAD><TITLE>This is a
sample page</TITLE>...etc", adding keywords and author. It also
supports cookies, expires, refresh, base, status, redirect, etc., etc.
"header" prints our standard company page header with logo, navigation
icons, etc (and a little indicator bar over the second button because
we've said we're in section 2)
'footer' prints our standard page footer, with copyright message, last
modification date of the file, and so on. All automagic.
I have a script which trawls through our source tree feeding every file
it finds (well, every modified file, a la 'make') through the MetaText
processor to generate an html output file which can then be released to
the web server.
A similar dynamic page would be created as follows:
#!/usr/bin/perl
use Template::Base; # old name - now "MetaText"
my $template = new Template::Base; # plus a bunch of options if I want
print $template->process('html.header', { title => "dynamic page" } ),
$template->process('header', { section => 2 } ),
"...page content..."
$template->process('footer');
It makes life very easy. More importantly, when we need to change an
element, say a new footer or whatever, I can change it in one element
file, feed every static page through the filter and let the dynamic
pages pick up the new version next time they need it. Easy.
Now add to that the facility for loops...
%% INCLUDE person
delimiter = ,
repeat = 3 # strictly not necessary - works it out from the data
person = "Tom,Dick,Harry"
age = "21,31,41"
%%
...or conditional constructs...
%% INCLUDE greeting
message = "Happy Christmas"
if = "day=25 and month=dec"
%%
...user definable print formatting and filters...
%% INCLUDE mail.message
filter = strip_headers # a code sub somewhere...
print = "> %s"
%%
...the ability to read external files and delimit fields...
%% READ /etc/telepone
name = telephone.list
delimiter = :
fields = "name:userid:deparment:extension"
%%
...and then use the list you created as the basis for a loop...
%% INCLUDE telephone.entry
list = "telephone.list"
if = "department = online"
%%
...and so on, and so on...
None of the tasks above are difficult to do in perl, but I hope the
examples demonstrate how easy and fast it is to build up complex
documents with a tool such as this.
At the time of writing, almost everything above (the noticable absence
being the list processing in the final example) has been completed.
Documentation currently stands at a hefty 26 lines (generously donated
by h2xs), so I have some serious effort to put into that. Following
that, I have to get permission from those people who pay me, to give
away the code that they paid me to write. But I'm working on it.
Hopefully I've clarified my position and Ian, myself, and others
can continue to work without stepping on each other's toes. As I
see it, the two different modules offer similar things but in
different ways, each having their own pros and cons (a parallel example
would be CGI.pm and CGI_Lite.pm) and I'm sure there's room enough in
CPAN for both our contributions.
A
[ still suffering with the newsfeed so cc's to a...@peritas.com would
be appreciated. Thanks ]
Tim Bunce
In article <1997Apr28.1...@schbbs.mot.com>,
Brad Appleton <Brad_Apple...@nospam.email.mot.com> wrote:
>
> In article <5k03du$sct$1...@cas.org>, lvi...@cas.org writes:
> > The reason why is as he states - his code is so general that it could
> > be used to generate text fiels of mailing lables, resumes, nroff documents,
> > programs, etc. It's a general mechanism where one defines the skeleton of
> > a file, and then fills in variables thru the file. The results need not
> > be any one 'type' of file.
>
> I understood that much. Certainly the main/abstract part of it wouldnt
> go under something like HTML::Xxxxx, but the HTML part of it might.
>
> >:I think Text::Stream, ... would be a much better separation than
> >:Template::Xxxxx.
> >
> >Text:: something would be okay as well I guess.
>
> Some have suggested Text::Template. If you end up using the word
> "Template" anywhere I would urge you to precede it with "Doc" to be
> something like "DocTemplate". By itself, the term "template" is so
> general that while it may seem obvious to some what you mean buy it,
> it will be extremely UNobvious to others. Adding those extra letters
> (like DocTemplate or FormTemplate) should be more helpful.
The template modules being discussed are very general and I can't see
how a Template category, especially in the "11) String Processing,
Language Text Processing, Parsing and Searching" section of the list
would be too unobvious.
Given the volume of work done in this area I think it needs a
category of its own. I think I favor the simple Template::* name.
The names of the modules within the category should help avoid any
possible ambiguity.
Tim.