From: Simon Cozens <simon@simon-cozens.org>
Date: Sat, 13 Mar 2004 14:20:12 +0000 (+0000)
Subject: This is a (slightly dodgy) way of keeping template documentation with
X-Git-Tag: 2.10~275
X-Git-Url: https://git.decadent.org.uk/gitweb/?p=maypole.git;a=commitdiff_plain;h=afc350467fbb2ecbb88d824f4b36d6440552a0c0

This is a (slightly dodgy) way of keeping template documentation with
the template, but then spitting it all out to a POD file in the end.


git-svn-id: http://svn.maypole.perl.org/Maypole/trunk@87 48953598-375a-da11-a14b-00016c27c3ee
---

diff --git a/doc/StandardTemplates.pod b/doc/StandardTemplates.pod
index dd76189..88727fd 100644
--- a/doc/StandardTemplates.pod
+++ b/doc/StandardTemplates.pod
@@ -252,29 +252,7 @@ macros as we come across them.
 
 =head3 F<view> 
 
-The C<view> template takes some objects (usually just one) from
-C<objects> and displays the object's properties in a table. It gets
-the displayable form of a column's name from the hash returned from
-the C<column_names> method:
-
-    <TR>
-        <TD class="field"> [% classmetadata.colnames.$col; %] </TD>
-
-One interesting macro used in this template is C<maybe_link_view>:
-
-        maybe_link_view(item.$col);
-
-This tests whether or not the returned value is an object, and if so,
-creates a link to a page viewing that object; if not, it just displays
-the text as normal. The object is linked using its stringified name;
-by default this calls the C<name> method, or returns the object's ID
-if there is no C<name> method or other stringification method defined.
-
-The C<view> template also displays a list of other objects related to the first
-one via C<has_many> style relationships; this is done by calling the
-C<related_accessors> method - see L<Model/related_accessors> - to return
-a list of has-many accessors. Next it calls each of those accessors, and
-displays the results in a table.
+=template view
 
 =head3 F<edit>
 
diff --git a/doc/makedoc.pl b/doc/makedoc.pl
new file mode 100644
index 0000000..b6dec2f
--- /dev/null
+++ b/doc/makedoc.pl
@@ -0,0 +1,21 @@
+my @templates = <../templates/factory/*>;
+
+my %doc;
+
+for my $template (@templates) {
+    open TEMP, $template or die $!;
+    $template =~ s/.*factory\///g;
+    while (<TEMP>) {
+        next unless /^#?=for doc/... /^#?=cut/
+                    and not /(%#?\]|\[%#?)$/
+                    and not /=cut|=for doc/; # Much magic.
+        s/^\s*#//g;
+        $doc{$template} .= $_;
+    }
+}
+
+while (<>) {
+    if (!/^=template (\w+)/) { print; next; }
+    die "Can't find doc for template $1" unless $doc{$1};
+    print $doc{$1};
+}
diff --git a/templates/factory/view b/templates/factory/view
index 64c760b..0ea412e 100644
--- a/templates/factory/view
+++ b/templates/factory/view
@@ -1,3 +1,13 @@
+[%#
+
+=for doc
+
+The C<view> template takes some objects (usually just one) from
+C<objects> and displays the object's properties in a table. 
+
+=cut
+
+%#]
 [% PROCESS macros %]
 [% INCLUDE header %]
 
@@ -14,20 +24,66 @@
     NEXT UNLESS item.$col;
 %]
 
-<TR>
+[%# 
+
+=for doc
+
+It gets the displayable form of a column's name from the hash returned
+from the C<column_names> method:
+
+%#]
+
+    <TR>
     <TD class="field"> [% classmetadata.colnames.$col; %] </TD>
     <TD> [%
 
+#=cut
+
     IF col == "url";  # Possibly too much magic.
                 "<A HREF="; item.url; "> "; item.url; "</A>";
     ELSE;
-    maybe_link_view(item.$col); END;
-    %] </TD>
+
+#=for doc
+
+#One interesting macro used in this template is C<maybe_link_view>:
+
+        maybe_link_view(item.$col); 
+%]
+
+[%#
+
+This tests whether or not the returned value is an object, and if so,
+creates a link to a page viewing that object; if not, it just displays
+the text as normal. The object is linked using its stringified name;
+by default this calls the C<name> method, or returns the object's ID
+if there is no C<name> method or other stringification method defined.
+
+=cut
+
+#%] 
+
+[% END; %]
+ </TD>
 </TR>
 [% END; %]
 </TABLE>
+
+[%#
+
+=for doc
+
+The C<view> template also displays a list of other objects related to the first
+one via C<has_many> style relationships; this is done by calling the
+C<related_accessors> method - see L<Model/related_accessors> - to return
+a list of has-many accessors. Next it calls each of those accessors, and
+displays the results in a table.
+
+#%]
 [%
     view_related(item);
+
+#=cut
+
     button(item, "edit");
     button(item, "delete");
 %]