I'll vote for the Python approach: Each item (class, method, etc) has an unnamed history section and includes blurbs like:

    New in version 3.3.

    Changed in version 3.1: Added the optional flags argument.


On 03-Mar-14 15:33, Robert J. van der Boon wrote:
Finally back at the fun stuff....

If we want some kind of tagging on element, attributes and (?) enumeration-values, then in XSD terms we're in the xs:annotation space. I can see the following to things working (both within an xs:annotation/xs:appinfo element):
1. Specific:
<!-- deprecated attribute is optional -->
<xse:version introduced="2.x" deprecated="3.8" />
<xse:history version="3.6">Changed default from Foo to Bar</xse:history>
<xse:history version="3.7">Added enumeration Baz</xse:history>

2. Generic tagging
<xse:tags>
  <xse:tag version="2.x">New</xse:tag>
  <xse:tag version="3.6">Changed default from Foo to Bar</xse:tag>
  <xse:tag version="3.7">Added enumeration Baz</xse:tag>
  <xse:tag version="3.8">Deprecated</xse:tag>
</xse:tags>

Note: For both methods I don't really like the fact that you need to know the version nr when you submit a PR, but I don't really see a way around it.

As part of this change I'll try to put the introduced tag on every element and attribute in the WiX schemas (the "introduced" version will be one of 2.x, 3.0, 3.5, 3.6, 3.7, 3.8 or 3.9).


The next step is generating html from those xsd files. Parsing the xsd's/outputting the html probably isn't a big problem, but how to show the tagging information (when available) to the user? For elements and types: I'm thinking of a History section right before the See Also section. For attributes: I'm not sure, as the attributes are currently shown in a table. Putting the tagging information in the table directly clutters it too much to my liking, I'm thinking more along the lines of a tooltip or popup.


Any suggestions?
 Robert



On 6 February 2014 20:59, Rob Mensching <r...@robmensching.com <mailto:r...@robmensching.com>> wrote:

    Well, I expect there will be some work required in DocCompiler to
    handle the tagging... which you are actually probably one of the
    few people that know about that code (beyond me). <smile/>

    Anyway, never had a design for the concept, just that it would be
    a good idea as we added attributes that weren't in previous
    releases of v3.x.  Just saying there is more open field here to
    design. <smile/>

    *From:*rjvdb...@gmail.com <mailto:rjvdb...@gmail.com>
    [mailto:rjvdb...@gmail.com <mailto:rjvdb...@gmail.com>]
    *Sent:* Thursday, February 6, 2014 11:32 AM


    *To:* WiX toolset developer mailing list
    *Subject:* Re: [WiX-devs] 3.x docs on wixtoolset.org
    <http://wixtoolset.org>

    I must have missed the suggestion then... Maybe due to me not
    seeing how that should have worked out back then.

    Personally I like the tagging version as well. If that will be the
    direction we're going, then I'll volunteer to put some effort
    into "back-tagging" the current xsd's. (although, not in the
    coming weeks...)

     Robert

    *From:*Rob Mensching <mailto:r...@robmensching.com>
    *Sent:* Thursday, February 6, 2014 5:40 PM
    *To:* WiX toolset developer mailing list
    <mailto:wix-devs@lists.sourceforge.net>

    I see what you did there. <smile/>

    Yeah, this was the suggestion I made a while ago when Robert was
    doing some work on the doc, that is probably the best answer but
    also the most work.  It would nice to be able to markup the XSD
    when attributes were added or defaults change. I'm less worried
    about when attributes disappear (because that shouldn't normally
    happen).

    Then there is only one set of doc per major version because I
    expect v4.0 to have enough breaking changes that it won't be
    possible to mix it with v3.x stuff.

    *From:*Blair Murri [mailto:os...@live.com]
    *Sent:* Wednesday, February 5, 2014 9:15 PM
    *To:* wix-devs@lists.sourceforge.net
    <mailto:wix-devs@lists.sourceforge.net>
    *Subject:* Re: [WiX-devs] 3.x docs on wixtoolset.org
    <http://wixtoolset.org>

    Could we go "light" by simply tagging each element/attribute with
    the version that element/attribute was introduced?

    Blair


    
------------------------------------------------------------------------------
    Managing the Performance of Cloud-Based Applications
    Take advantage of what the Cloud has to offer - Avoid Common Pitfalls.
    Read the Whitepaper.
    http://pubads.g.doubleclick.net/gampad/clk?id=121051231&iu=/4140/ostg.clktrk
    _______________________________________________
    WiX-devs mailing list
    WiX-devs@lists.sourceforge.net <mailto:WiX-devs@lists.sourceforge.net>
    https://lists.sourceforge.net/lists/listinfo/wix-devs




------------------------------------------------------------------------------
Subversion Kills Productivity. Get off Subversion & Make the Move to Perforce.
With Perforce, you get hassle-free workflows. Merge that actually works.
Faster operations. Version large binaries.  Built-in WAN optimization and the
freedom to use Git, Perforce or both. Make the move to Perforce.
http://pubads.g.doubleclick.net/gampad/clk?id=122218951&iu=/4140/ostg.clktrk


_______________________________________________
WiX-devs mailing list
WiX-devs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/wix-devs

--
sig://boB
http://joyofsetup.com/

------------------------------------------------------------------------------
Learn Graph Databases - Download FREE O'Reilly Book
"Graph Databases" is the definitive new guide to graph databases and their
applications. Written by three acclaimed leaders in the field,
this first edition is now available. Download your free book today!
http://p.sf.net/sfu/13534_NeoTech
_______________________________________________
WiX-devs mailing list
WiX-devs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/wix-devs

Reply via email to