[Moin-user] Include with version number (was Re: Wiki for document management)

[Greg Ward]

[my original post]
> We are a small-but-growing software company that needs a good way to
> manage our software documentation (requirements, specs, designs, etc.).
> 
> Let me clarify this last one.  E.g. for a single new feature, we will
> typically create four wiki pages:
> 
>   NewFeature/BusinessRequirementsSpecification
>   NewFeature/SoftwareRequirementsSpecification
>   NewFeature/SoftwareDesignSpecification
>   NewFeature/DevelopmentTestPlan
> 
> There are various operations we would like to be able to do on the whole
> group, but the critical one is the ability to link to (or print, or
> download, whatever) a specific version of the complete documentation for
> NewFeature.

[Franklin PIAT replies]
> Have you tried using [[Include()]], to include common section,  or
> Dictionaries to replace variables ?
> Also, you could have a page, that [[Include]] the four sub pages.
[...]
> If the tags where implemented, you could use a tag to mark the last
> Review/approved version.
> Meanwhile, you can have a page where you keep links to the last approved
> versions.

Great idea.  I've been playing around with <<Include>> and I like it.  I
would like it even more if I could do

  <<Include(NewFeature/SoftwareDesignSpecification, version=7)>>

to include a specified version of a particular page.  Then I could
publish "version 1" of all the docs for NewFeature as a page
NewFeature/Version1Docs containing just

  <<Include(NewFeature/BusinessRequirementsSpecification, version=5)>>
  <<Include(NewFeature/SoftwareRequirementsSpecification, version=3)>>
  <<Include(NewFeature/SoftwareDesignSpecification, version=13)>>
  <<Include(NewFeature/DevelopmentTestPlan, version=9)>>

Then I make NewFeature/Version1Docs immutable and *presto* we have met
our regulatory requirements.  (I hope.)

After coming up with this idea, I took a look at the source of the
Include macro.  It's a bit hairy, and seems to use an old macro API.
I'm not sure I like the idea of hacking in a new feature without doing
any refactoring.

Alternately, I could just write a new IncludeVersion macro that copies
the important bits from Include.py and leaves behind all the
functionality that I don't need right now.  This is gross because of the
code copying, but the current state of Include.py means the existing
code is not very reusable.

So:

  * does anyone else think that Include with a 'version' parameter would
    be generally a useful feature?

  * if not, do you think that I should be able to write my own
    IncludeVersion macro that reuses code in Include.py rather than
    copying it?

  * is anyone interested in a series of patches to refactor Include.py
    in order to make it more extensible and more reusable?

Thanks --

        Greg