Masterview devel - Jul 2006 - Proposed File format for directives

How about something like this for the single file format for directives?

# Basic description text goes in the rdoc like normal
# more desc here
# more desc here

=begin example
 <div mv:generate="foo.bar">
    <div mv:replace="cat">
        A good example of various usage pattens would go here
    </div>
    <div mv:replace="dog(hello)">
        One could demonstrate several in one html snippet
    </div>
  </div>
=end

=begin result
  foo.bar:
     <div>
       <div><%= cat %></div>
       <div><%= dog(hello) %></div>
     </div>
=end result

class MyDirective < MasterView::DirectiveBase
  def self.category # this would actually be the category the directive gets
cataloged in (if provided)
     ''Form Helpers''
  end



  def stag
  end

  ...
end



So the thinking is that we can build our directive docs right off the source
files. We will pull the main class comments in as description text, then we
can have an example and result. The example could also automatically be made
available to the interactive test page, so it would show up as another
example link which if you click would populate it with the example text.

The self.category if exists could be used to categorize the directive so we
can put them in categories. Our directive docs have some categories now so
we could use this kind of concept to group things. The name would come from
the class name or directive name if overridden.

I haven''t quite figured out how to do multiple examples since for the
interactive link I only want one. I guess we could allow multiple but I just
will take the first one for the interactive page.

Would this be easy enough to follow if people were starting from an existing
directive or template?

I think this would work out well if we can move towards reading everything
out of our directive files that will keep things in sync everywhere with no
duplication. And it allows others to upload files or download files to their
system and if we have a simple admin page which can read the available
directives on the system it can provide a live reference of every directive
installed.
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://rubyforge.org/pipermail/masterview-devel/attachments/20060714/65b66b59/attachment.html

oops submitted before I added the version in.

Here it is with version added.

On 7/14/06, Jeff Barczewski <jeff.barczewski at gmail.com>
wrote:
>
> How about something like this for the single file format for directives?
>
> # Basic description text goes in the rdoc like normal
> # more desc here
> # more desc here
>
> =begin example
>  <div mv:generate=" foo.bar">
>     <div mv:replace="cat">
>         A good example of various usage pattens would go here
>     </div>
>     <div mv:replace="dog(hello)">
>         One could demonstrate several in one html snippet
>     </div>
>   </div>
> =end
>
> =begin result
>   foo.bar:
>      <div>
>        <div><%= cat %></div>
>        <div><%= dog(hello) %></div>
>      </div>
> =end result
>
> class MyDirective < MasterView::DirectiveBase
>   def self.category # this would actually be the category the directive
> gets cataloged in (if provided)
>      ''Form Helpers''
>   end
>

    def self.version
      1.01
     end

  def stag
>   end
>
>   ...
> end
>
>
>
> So the thinking is that we can build our directive docs right off the
> source files. We will pull the main class comments in as description text,
> then we can have an example and result. The example could also
automatically
> be made available to the interactive test page, so it would show up as
> another example link which if you click would populate it with the example
> text.
>
> The self.category if exists could be used to categorize the directive so
> we can put them in categories. Our directive docs have some categories now
> so we could use this kind of concept to group things. The name would come
> from the class name or directive name if overridden.
>
> I haven''t quite figured out how to do multiple examples since for
the
> interactive link I only want one. I guess we could allow multiple but I
just
> will take the first one for the interactive page.
>
> Would this be easy enough to follow if people were starting from an
> existing directive or template?
>
> I think this would work out well if we can move towards reading everything
> out of our directive files that will keep things in sync everywhere with no
> duplication. And it allows others to upload files or download files to
their
> system and if we have a simple admin page which can read the available
> directives on the system it can provide a live reference of every directive
> installed.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://rubyforge.org/pipermail/masterview-devel/attachments/20060714/7afdc92e/attachment-0001.html

On further consideration maybe it would be better to put all of the
description and example in class methods to make it easier to access and to
take advantage of it potentially being loaded from anywhere including gems.

If description and example are class methods then we simply iterate on the
loaded directives rather than having to read and parse files.

If the documentation for these is dynamically made available via masterview
admin pages or a new documentation controller then the need for rdoc on this
is reduced. Its all about getting good documentation and keeping it current.
And I would like to provide examples for the interactive page.

The only question is whether class methods or constants would be best
approach and whether these take up any memory footprint until needed.

So format ends up being something like

class MyDirective < MasterView::DirectiveBase
>   def self.category # this would actually be the category the directive
> gets cataloged in (if provided)
>      ''Form Helpers''
>   end
>

    def self.version
      1.01
     end



  def stag
>   end
>
>   ...
> end
>
>
On 7/14/06, Jeff Barczewski <jeff.barczewski at gmail.com>
wrote:
>
> oops submitted before I added the version in.
>
> Here it is with version added.
>
> On 7/14/06, Jeff Barczewski < jeff.barczewski at gmail.com> wrote:
> >
> > How about something like this for the single file format for
directives?
> >
> >
> > # Basic description text goes in the rdoc like normal
> > # more desc here
> > # more desc here
> >
> > =begin example
> >  <div mv:generate=" foo.bar">
> >     <div mv:replace="cat">
> >         A good example of various usage pattens would go here
> >     </div>
> >     <div mv:replace="dog(hello)">
> >         One could demonstrate several in one html snippet
> >     </div>
> >   </div>
> > =end
> >
> > =begin result
> >   foo.bar:
> >      <div>
> >        <div><%= cat %></div>
> >        <div><%= dog(hello) %></div>
> >      </div>
> > =end result
> >
> > class MyDirective < MasterView::DirectiveBase
> >   def self.category # this would actually be the category the
directive
> > gets cataloged in (if provided)
> >      ''Form Helpers''
> >   end
> >
>
>
>     def self.version
>       1.01
>      end
>
>   def stag
> >   end
> >
> >   ...
> > end
> >
> >
> >
> > So the thinking is that we can build our directive docs right off the
> > source files. We will pull the main class comments in as description
text,
> > then we can have an example and result. The example could also
automatically
> > be made available to the interactive test page, so it would show up as
> > another example link which if you click would populate it with the
example
> > text.
> >
> > The self.category if exists could be used to categorize the directive
so
> > we can put them in categories. Our directive docs have some categories
now
> > so we could use this kind of concept to group things. The name would
come
> > from the class name or directive name if overridden.
> >
> > I haven''t quite figured out how to do multiple examples since
for the
> > interactive link I only want one. I guess we could allow multiple but
I just
> > will take the first one for the interactive page.
> >
> > Would this be easy enough to follow if people were starting from an
> > existing directive or template?
> >
> > I think this would work out well if we can move towards reading
> > everything out of our directive files that will keep things in sync
> > everywhere with no duplication. And it allows others to upload files
or
> > download files to their system and if we have a simple admin page
which can
> > read the available directives on the system it can provide a live
reference
> > of every directive installed.
> >
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://rubyforge.org/pipermail/masterview-devel/attachments/20060715/35ee5d41/attachment.html

sorry gmail submitted again before I was done. The format using class
methods might be something like. Or we could use constants similarly if that
would be better for memory footprint. I kind of thing methods might be
lighterweight since constants might take up memory all the time.

class MyDirective < MasterView::DirectiveBase
>   def self.category # this would actually be the category the directive
> gets cataloged in (if provided)
>      ''Form Helpers''
>   end
>

    def self.version
      1.01
     end

    def description
       desc <<-END
         The description goes here
         more here
       END
    end

    def example
       example <<-END
    <div mv:generate=" foo.bar">
    <div mv:replace="cat">
        A good example of various usage pattens would go here
    </div>
    <div mv:replace="dog(hello)">
        One could demonstrate several in one html snippet
    </div>
  </div>
     END
   end


  def stag
>   end
>
>   ...
> end
>
>
On 7/15/06, Jeff Barczewski <jeff.barczewski at gmail.com>
wrote:
>
> On further consideration maybe it would be better to put all of the
> description and example in class methods to make it easier to access and to
> take advantage of it potentially being loaded from anywhere including gems.
>
> If description and example are class methods then we simply iterate on the
> loaded directives rather than having to read and parse files.
>
> If the documentation for these is dynamically made available via
> masterview admin pages or a new documentation controller then the need for
> rdoc on this is reduced. Its all about getting good documentation and
> keeping it current. And I would like to provide examples for the
interactive
> page.
>
> The only question is whether class methods or constants would be best
> approach and whether these take up any memory footprint until needed.
>
> So format ends up being something like
>
>
> class MyDirective < MasterView::DirectiveBase
> >   def self.category # this would actually be the category the
directive
> > gets cataloged in (if provided)
> >      ''Form Helpers''
> >   end
> >
>
>
>     def self.version
>       1.01
>      end
>
>
>
>   def stag
> >   end
> >
> >   ...
> > end
> >
> >
>
> On 7/14/06, Jeff Barczewski <jeff.barczewski at gmail.com > wrote:
> >
> > oops submitted before I added the version in.
> >
> > Here it is with version added.
> >
> > On 7/14/06, Jeff Barczewski < jeff.barczewski at gmail.com>
wrote:
> > >
> > > How about something like this for the single file format for
> > > directives?
> > >
> > > # Basic description text goes in the rdoc like normal
> > > # more desc here
> > > # more desc here
> > >
> > > =begin example
> > >  <div mv:generate=" foo.bar">
> > >     <div mv:replace="cat">
> > >         A good example of various usage pattens would go here
> > >     </div>
> > >     <div mv:replace="dog(hello)">
> > >         One could demonstrate several in one html snippet
> > >     </div>
> > >   </div>
> > > =end
> > >
> > > =begin result
> > >   foo.bar:
> > >      <div>
> > >        <div><%= cat %></div>
> > >        <div><%= dog(hello) %></div>
> > >      </div>
> > > =end result
> > >
> > > class MyDirective < MasterView::DirectiveBase
> > >   def self.category # this would actually be the category the
> > > directive gets cataloged in (if provided)
> > >      ''Form Helpers''
> > >   end
> > >
> >
> >
> >     def self.version
> >       1.01
> >      end
> >
> >   def stag
> > >   end
> > >
> > >   ...
> > > end
> > >
> > >
> > >
> > > So the thinking is that we can build our directive docs right off
the
> > > source files. We will pull the main class comments in as
description text,
> > > then we can have an example and result. The example could also
automatically
> > > be made available to the interactive test page, so it would show
up as
> > > another example link which if you click would populate it with
the example
> > > text.
> > >
> > > The self.category if exists could be used to categorize the
directive
> > > so we can put them in categories. Our directive docs have some
categories
> > > now so we could use this kind of concept to group things. The
name would
> > > come from the class name or directive name if overridden.
> > >
> > > I haven''t quite figured out how to do multiple examples
since for the
> > > interactive link I only want one. I guess we could allow multiple
but I just
> > > will take the first one for the interactive page.
> > >
> > > Would this be easy enough to follow if people were starting from
an
> > > existing directive or template?
> > >
> > > I think this would work out well if we can move towards reading
> > > everything out of our directive files that will keep things in
sync
> > > everywhere with no duplication. And it allows others to upload
files or
> > > download files to their system and if we have a simple admin page
which can
> > > read the available directives on the system it can provide a live
reference
> > > of every directive installed.
> > >
> >
> >
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://rubyforge.org/pipermail/masterview-devel/attachments/20060715/ce8f2375/attachment.html

received; digesting..., will have some reactions tomorrow
 
~ Deb
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://rubyforge.org/pipermail/masterview-devel/attachments/20060715/0d8ad3c0/attachment.html