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