> On Apr 20, 2015, at 2:38 PM, Ron Wheeler <rwhee...@artifact-software.com> > wrote: > > On 20/04/2015 4:55 PM, Jim Klo wrote: >> Comments inline below.. >> >>> On Apr 20, 2015, at 10:44 AM, Ron Wheeler <rwhee...@artifact-software.com >>> <mailto:rwhee...@artifact-software.com> >>> <mailto:rwhee...@artifact-software.com >>> <mailto:rwhee...@artifact-software.com>>> wrote: >>> >>> RDF sounds like overkill. There is no reason why a comment could not be a >>> URI but I am not sure that you want to mandate that. >>> Use Case 1 link to web resource >>> <dependency comment="http://blog.artifact-software.com/tech/?p=191”> >> >> Having dealt with this sort of thing on other projects, linked comments >> sound good at first but ultimately become a very bad idea IMO. This creates >> a non-idempotent and brittle link scenario where the comment url is out of >> synch with the content in the POM. >> >> >>> Use Case 2 lots of in-line deatils >>> <dependency comment="added to support PDF output"> >>> <groupId>org.apache.xmlgraphics</groupId> >>> <artifactId>fop</artifactId> >>> <version comment="Can't use version 2.x see >>> FOP-3423">1.0</version> >>> <optional comment="set to true to get text in black on >>> white">true</optional> >>> </dependency> >>> >>> Use case 3 reference to a full explanation in the description >>> There is also the description tag which could be used to hold more details >>> <dependency comment="See note 2 in description tag.”> >> >> I’m not sure I’m seeing a difference between UC 2 & 3. Unless you mean >> something more like this for UC 3: >> <dependency comment_ref=“note2”> <!— or some XPath expression —> >> ... >> <description comment_refid=“note2” comment=“This version doesn’t work for >> the following reasons:….”> >> > I was thinking that the description might be <description>Note 1: Please put > all dependency versions in Parent, Note 2:FOP required for PDF > output</description> >> >>> IDE's could show comment attributes on tags in the POM editor or in XML >>> outline views. >>> >>> It seems to be a lot more flexible than adding comment tags and probably >>> less intrusive to existing plug-ins. >>> >> >> I think comment tags should still be included. Inline is great for short >> descriptions, but nothing really beats having a tag element that doesn’t >> require a lot of XML escaping like an attribute would need. >> >> - Jim >> > You are looking for a lot more machine processing that I was thinking. > I was just considering comments as a way to tell people about the choices > made. >
Actually I wasn’t looking for that - just some clarity, as I didn’t fully understand the deltas within one of your use cases. So was just posing a confirming solution. :-) I actually dis-like using references as I proposed - they are a pain to follow without tooling IMO. I would rather opt to have “embedded” javadoc annotations (@see, @link, @todo, etc) within the comment text for folks who choose to go that route. One should never discount the need to machine process these. Consider and IDE or document generation at the very least. IMO, anytime you have an opportunity to structure a vocabulary to make it machine usable - one should choose to make it machine usable to support any future automation. > Your XML escaping note is a good point. > The IDE will pick up invalid text so it should not be hard to avoid but for > people without a good IDE, they will get an error. It should only happen once > to each person editing a pom and POMs are not edited a lot in most projects. > I work with varying degrees of IDE’s daily ranging from full blown IntelliJ Ultimate down to a text editor. I tend to lean more on the expectation that the IDE is feature limited; considering about 85% of the time - I’m using a web browser to review POM’s - and I wouldn’t think I’m alone in that categorization. Less reliance on an IDE is important. > > Can you give a comment tag solution for each of the use cases. I think what you provided is sufficient for examples, however for a more globally portable solution, I would seriously consider using a namespace. From there you could have a more targeted solution: <project xmlns:cmt=“http://maven.apache.org/comments/1.0.0 <http://maven.apache.org/comments/1.0.0>”> … <version cmt:note=“Can’t use version XZY @see(http://example.com/foo-123 <http://example.com/foo-123>)”> <dependency> <cmt:note> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec et vestibulum odio, at porttitor nunc. Donec pulvinar erat quis accumsan interdum. Nunc at viverra nunc. Mauris purus ipsum, aliquam vitae nisi eget, faucibus auctor leo. Duis ipsum leo, viverra eleifend viverra in, tristique vitae tortor. Interdum et malesuada fames ac ante ipsum primis in faucibus. Suspendisse tempus nisl dui, at rutrum massa porta id. Suspendisse ultricies est vel pretium egestas. In orci ipsum, vehicula non accumsan quis, pellentesque ac ipsum. Maecenas maximus ornare tempus. Fusce libero ligula, tempor mattis pretium et, consectetur ut sapien. Aliquam rhoncus lorem erat. Nullam et. </cmt:note> </dependency> > Are you proposing that comment tags be allowed inside all tags or just some. > I would suggest comment attributes on all elements. I would vote for a comment element to be a child of any tag and a comment attribute be available on all elements. However when considering a more global solution, I would think adding a specific namespace for comments makes a whole lot more sense and would be a more portable solution and avoid collisions with existing plug-ins. IMO it’s easier to update base parsers to disregard elements from foreign namespaces than to hope to avoid collisions with existing plug-ins. However that’s a gut feeling without doing any investigation as to what the scope of impact a change like that would really mean. If it really isn't a huge problem to just add comments to the POM namespace, that would be my #1 choice.
smime.p7s
Description: S/MIME cryptographic signature
