podwiki-devel

[podwiki] Re: Unifying output of POD and other markup methods

[James H. T. <jh...@lj...>]

When thinking about changing the structure of the formatters, and if you have any plans to someday
support Transclusion -
definitions and examples:
    http://c2.com/cgi/wiki?TransClusion
    http://www.burningchrome.com:8000/~cdent/wiki.cgi?TransClusion

You might want to consider the a structure to make this easier to implement in the future.

There is a discussion of how Transclusion might be implemented in Owiki (a fork of Twiki) here:
    http://www.owiki.org/twiki/bin/view/Openwiki/NamedIncludeSections


Jim

James H. Thompson
jh...@la...

Re: [podwiki] Re: Unifying output of POD and other markup methods

[Thomas L. <to...@co...>]

Hallo,

On Wed, Jun 02, 2004 at 10:49:47PM -1000, James H. Thompson wrote:
> When thinking about changing the structure of the formatters,
> and if you have any plans to someday support Transclusion -

at the moment there are no thoughts about transclusion. In my case this
is because I just didn't know about this idea :-)

If I think about it, then I realize that implementing transclusion in
PodWiki seems to be *very* easy. Why? Because it uses POD (and this
means: I don't think it will be possible with "foreign" formatters).

Say, I have a document "BlahDoc":

=head2 INTRO

This tells about fish and chips

=head2 RECEIPT

..

=cut


Now I could include part of this document like this:

P<BlahDoc?INTRO>

which includes the content (unrendered!) between the "=head2 INTRO" and
the next "*head" command. This works, because the Pod::Tree parser used
in PodWiki already divides a POD document into sections (internally called
nodes), which makes it very easy to pick out a particular section. Of
course this section must exist otherwise it would not work.

I am unsure how this could to be implemented for external formatters. 

The problem (and that's what David mentioned earlier) is the totally
different way that external Formatters and the POD parser are working.
The POD parser generates a tree of nodes from the document and PodWiki
then walks recursive over the tree while rendering each single node.
An external formatter on the other hand does a big search/replace action
over the whole document. This way is of course somewhat simpler to
implement, but it does not allow to divide the document into sections,
at least it makes it more complicated.

However - my current idea is: What if we completely move to the
tree-parsing technique, also for external formatters? If every renderer
works the same way, it would be much easier to implement new features
for both "worlds". To be frank: ok, we could also do the reverse, we
could re-implement the POD formatter using the search/replace technique.
And to be honest, I already tried to write such a formatter some months
ago (when I started with PodWiki), but I were unsuccessful :-|
The POD format is well suited for regex-parsers. 

So, perhaps it would be a good idea to write a generic tree parser,
which is used by PodWiki for actually rendering stuff. But behind the
scenes, there are specialized parsers which are overwriting some or all
of the methods of the "Super" parser, one for POD, one for Twiki and so
on, PodWiki doesn't know what type of document it is rendering. The
Super parser could provide methods similar to XML tree parsers, in fact,
if someone of you ever worked with XML parsers - they "feel" much like
the POD::Tree parser. This would provide some more possibilities: we
could even render XML directly, or: we could create several output
renderers, one for "online html" (which we are using currently in the
Wiki), or one for "offline xml", e.g. RSS feed, or for site-backup.

Much stuff to think about :-)



regards, Tom

-- 
 Thomas Linden   (http://www.daemon.de/)  tom at co dot daemon dot de
 $_=`perl -v`;s;^.*ll;;s;$^=unpack"u", "'8V]D;')E<```";s;\W;;gs;$/=7*
 ($^=~s;.;;g);%^=map{$_=>1}split//,lc;$_=join$\, (sort keys(%^))[map{
 ord($_)-$/}split//,'1I7E13?@E:7C1A7C=1:35<7C'];s"0(.)" \U$1"g;print;

Re: [podwiki] Re: Unifying output of POD and other markup methods

[Charles G. <ch...@ve...>]

On Fri, 2004-06-04 at 22:53 +0200, Thomas Linden wrote: 
> If I think about it, then I realize that implementing transclusion in
> PodWiki seems to be *very* easy. Why? Because it uses POD (and this
> means: I don't think it will be possible with "foreign" formatters).

Please do implement it.  This would be invaluable, and make podwiki a
much more effective content management tool.

> Now I could include part of this document like this:
> 
> P<BlahDoc?INTRO>

The only issue with this is that how do you differentiate between h1,
h2, h3 and how do you use H2s with spaces inbetween?

What might be more useful would be an additional syntax for defining
sections, which could be nestable.

=section FOO

appears in FOO only

=section BAR

appears in FOO and BAR

=end BAR

appears in FOO only

=end FOO
-- 
- Charlie

Charles Goodwin <ch...@ve...>
Online @ www.charlietech.com

Re: [podwiki] Re: Unifying output of POD and other markup methods

[James H. T. <jh...@lj...>]

> What might be more useful would be an additional syntax for defining
> sections, which could be nestable.

While it might make implementation more difficult, non-nesting but overlapping sections would be
useful too:

<content>

section a start
<content> in section a
section b start
<content> in section a and b
section a end
<content> in section b
section b end

<content>

Re: [podwiki] Re: Unifying output of POD and other markup methods

[David A. B. <Br...@ac...>]

On Fri, 4 Jun 2004, Thomas Linden wrote:

> Hallo,
>
> On Wed, Jun 02, 2004 at 10:49:47PM -1000, James H. Thompson wrote:
>> When thinking about changing the structure of the formatters,
>> and if you have any plans to someday support Transclusion -
>
> However - my current idea is: What if we completely move to the
> tree-parsing technique, also for external formatters? If every renderer

Oh, oh, oh! This exactly what I have been thinking, too! I got started 
implementing, but family life and work intruded (funny how that happens, eh?). 
I was thinking that rather than a PodWiki::Formatter->format() method, there 
would be a PodWiki::Formatter->parse() method. The parse method would return a 
tree that is then merged into the existing tree in place of the former result 
of the parse of

=begin formatter

...text...

=end

> could even render XML directly, or: we could create several output
> renderers, one for "online html" (which we are using currently in the
> Wiki), or one for "offline xml", e.g. RSS feed, or for site-backup.

Oooo, I like that idea, too!


Welcome back, Tom!

-- 
David A. Bright
Br...@ac...
dab...@us...

Re: [podwiki] Re: Unifying output of POD and other markup methods

[Thomas L. <to...@co...>]

On Fri, Jun 04, 2004 at 10:11:32PM +0000, Charles Goodwin wrote:
> On Fri, 2004-06-04 at 22:53 +0200, Thomas Linden wrote: 
> 
> The only issue with this is that how do you differentiate between h1,
> h2, h3 and how do you use H2s with spaces inbetween?

h1, h2, .. are differentiated using =head1, =head2, .. POD commands.

And I don't see any problems with witespaces: P<Page?Section Foo>.
 
> What might be more useful would be an additional syntax for defining
> sections, which could be nestable.

I tend to use existing commands, whereever possible, in this case I
would write:

=head1 Section FOO

appears in FOO only

=head2 Section BAR

appears in FOO and BAR

=cut

Summary: one section starts with an =head<1-4> command and ends at the
next =head command of the same level (e.g. =head1 til the next =head1)
or at document end (=cut). I don't know if =end is also usable as
"section-end" command, because the =end command already exists and
requires an =begin command somewhere above.



- Tom

-- 
 Thomas Linden   (http://www.daemon.de/)  tom at co dot daemon dot de
 $_=`perl -v`;s;^.*ll;;s;$^=unpack"u", "'8V]D;')E<```";s;\W;;gs;$/=7*
 ($^=~s;.;;g);%^=map{$_=>1}split//,lc;$_=join$\, (sort keys(%^))[map{
 ord($_)-$/}split//,'1I7E13?@E:7C1A7C=1:35<7C'];s"0(.)" \U$1"g;print;

Re: [podwiki] Re: Unifying output of POD and other markup methods

[Charles G. <ch...@ve...>]

On Sat, 2004-06-05 at 01:19 +0200, Thomas Linden wrote:
> Summary: one section starts with an =head<1-4> command and ends at the
> next =head command of the same level (e.g. =head1 til the next =head1)
> or at document end (=cut). I don't know if =end is also usable as
> "section-end" command, because the =end command already exists and
> requires an =begin command somewhere above.

Let me rephrase.

=head1/head2 are identifiers that have a visible output; you get to see
the heading.  What if you don't want the heading, if you just want to
reuse bodies of text?
-- 
- Charlie

Charles Goodwin <ch...@ve...>
Online @ www.charlietech.com