On Mon, May 13, 2013 at 7:33 PM, Sylvester Keil <[email protected]> wrote: > > On May 13, 2013, at 11:22 AM, Charles Parnot wrote: > >> The conclusion on the original proposal was that it was hard to read (from a >> human perspective) and had the problem of moving some of the logic to the >> attribute values (which from an implementation point of view, and for >> validation purposes, is a problem). > > Isn't this problem eliminated by introducing the nand matcher? > > As I understood it the new proposal does not support the individual negation > either but uses the 'nand' matcher for this purpose – you can apply this to > the original proposal just as easily. The example becomes: > > <if match="all" type="book" variable-nand="edition"> > >> This proposal is more verbose, but also more readable. >> >>> ['all', ['type', 'all', ['book']], ['variable', 'nand', ['edition']]] >> >> >> Only programmers can parse that ;-) > > Indeed – it wasn't supposed to be a new syntax proposal, just to explain what > sort of information we as programmers need to extract from the style. : ) > >>> This is the information I need to process the conditions – I personally >>> think that using 4 XML nodes to describe this list makes testing a >>> nightmare. >> >> It's again a trade-off between being friendly/readable to style >> implementors, and being friendly to the processors. Though I am not sure >> where the nightmare comes from in this case. Did you mean it's harder to >> build test cases? In which way? > > Is it being friendly to style implementors though? Personally, I don't enjoy > writing so much XML. Nightmare is perhaps a little strong, granted, but look: > I want to have test cases for each individual element – it helps limit errors > when I am able to do that. With the new syntax the sole purpose of the if or > conditions element is to fetch the conditions from its child elements – > that's something you cannot test in isolation unless you mock all the child > elements. However, since the logic involved here is so trivial it isn't > really worth the trouble to write mocks – and your tests will, in all > likelihood not be isolated anymore.
That's true. But the problem isn't limited to this syntax. cs:label inside cs:names can't be tested without its parent and sibling elements, and children of a sibling cs:substitute node. Implicit suppression in cs:group can't be tested without its children. cs:macro can't be tested without children. > > Furthermore, I am writing a processor specifically to be able to deal with > CSL fragments, because sometimes users want to overrule a specific element on > the fly or because they don't need a full CSL style, but just want to format, > say a title, or a name – for these cases, and for testing, it is extremely > useful to just create a new node on the fly and feed it to the processor. > Having child elements always complicates matters because you need to create > those first. > > Of course, in many cases this is necessary – but is that true for a > condition? More so, as conditions are something that, conceivably, you might > want to quickly change on the fly if you're working with a CSL processor > programmatically. > > I have the feeling that CSL processors tend to become these monolithic > black-boxes that take the style, and the locale, and the citation data and > give you the output – but are extremely difficult for other developers to > work with from the outside – this is certainly what happened to citeproc-ruby > and this is why I started to re-write it from scratch. Having to handle an > XML sub-tree to hold a simple condition is precisely something that > encourages this tendency in my opinion. I agree that it is less cumbersome to have the entire logic on the cs:if or cs:else-if node, but working through some initial cleanup in one of the legal styles has taught me that second proposal is necessary to produce more compact code in a complex style. Here is what the title macro from the American Law style now looks like: https://gist.github.com/fbennett/5567599 Welcome to my nightmare: as you can see, the underlying style is quite a disaster zone, but we're stuck with it (and not just us -- pity the poor paralegals who are currently tasked with typing this stuff out by hand). The conditions seem to cope: the current set of 1760 integration tests for the style now pass. Through this consolidation I was able to remove four macros and 60 lines of code. Any mis-rendered title in the style will now originate from this macro, which should save a lot of debugging time going forward. With the initial proposal, the result would not have been this compact. Implementing the syntax wasn't too much work, since it was just a matter of nesting functions that had already been coded. But that's just one experience: I hear you when you say that spreading logic across nodes has costs. I just don't see how logic of several of the conditions in the sample could be squeezed onto a single node. > > I realize that at the end of the day it is largely a matter of taste: do you > prefer more attributes or more elements? – But to actively support both > approaches is a really bad idea in my opinion. Most processors parse the > style and convert it into some kind of internal representation – but all > tools that also want to convert the internal presentation back into a valid > style are in a really bad position now: the easy way out is of course, to > always convert to the more expressive syntax – but if, as you say, the idea > is to keep the old one for the simple cases because it is shorter and more > readable, this defeats the purpose. I confess that the idea of converting the internal representation back to XML never occurred to me, and I'm curious. What would be the use case for that? > > Sylvester > > >> >> On May 13, 2013, at 10:40 AM, Sylvester Keil <[email protected]> wrote: >> >>> >>> On May 13, 2013, at 9:50 AM, Charles Parnot wrote: >>> >>>> When you put it this way, I agree "backward-compatibility" is more of a >>>> trick than a real thing. >>>> >>>> However, it got me thinking: do we want to get rid of the "old" syntax, >>>> where the predicates are in the `<if>` element? I would think no, we want >>>> to keep them. This is still the shortest and most readble way to write >>>> conditionals in most cases. So maybe in this case, we are in fact truly >>>> backward-compatible :-) >>> >>> Charles, you're right, if we still want to encourage its use that's a >>> compelling reason to keep the old way around, of course. (I wanted to make >>> the case firmly against keeping old features around just for the sake of >>> compatibility.) >>> >>> But if this is the case, it gives me even more reason to believe that the >>> original proposal was actually the better one – if only a handful of styles >>> need the advanced syntax anyway it seems much more reasonable to me for it >>> to be an extension of the normal syntax rather than a completely different >>> one. Especially since you decided to lose the 'not:' in favour of 'nand' >>> matchers anyway. >>> >>> Do we really want to add two new elements for an alternate syntax when most >>> styles use attributes on cs:if anyway? >>> >>> Thinking about how to implement this, my best approach was to simply >>> convert the new conditions to the lists which can be used with the >>> original/extended rendering algorithm. But this just tells me that all >>> we're accomplishing here is introducing a bloated XML syntax to describe >>> simple lists. >>> >>> Looking at the example: >>> >>> <choose> >>> <if> >>> <conditions match="all"> >>> <condition type="book"/> >>> <condition variable="edition" match="nand"/> >>> </conditions> >>> <text macro="some-text-macro"/> >>> </if> >>> </choose> >>> >>> >>> What I would do here, in order to evaluate the statement is translate the >>> conditions to something that can be reduced efficiently. Something like >>> this: >>> >>> ['all', ['type', 'all', ['book']], ['variable', 'nand', ['edition']]] >>> >>> This is the information I need to process the conditions – I personally >>> think that using 4 XML nodes to describe this list makes testing a >>> nightmare. >>> >>> Also, think of the headaches you're creating for tools that create styles >>> like the style editor: if you have a condition in the 'old' way and you >>> change a little detail – does it stay in the old way or is it converted? If >>> you try to keep it in the old way then once you add a feature that can't be >>> expressed in the old way you need to convert everything etc. – or if tools >>> cannot handle this sort of thing, as a style author you're forced to >>> convert all conditions to the new syntax if you want to add something that >>> was not supported previously. With the original approach you can always add >>> new conditions without having to change the old ones. >>> >>> Sylvester >>> >>> >>> >>>> On May 13, 2013, at 9:11 AM, Sylvester Keil <[email protected]> wrote: >>>> >>>>> >>>>> On May 8, 2013, at 9:19 PM, Rintze Zelle wrote: >>>>> >>>>>> On Wed, May 8, 2013 at 3:06 PM, Bruce D'Arcus <[email protected]> wrote: >>>>>>> I'd like to ask an orthogonal question. See below ... >>>>>>> >>>>>>>> As this is backward-compatible, deployment in a CSL 1.0.2 version >>>>>>>> should be possible (but I have no strong opinion). >>>>>>> >>>>>>> Do we have a common understanding of how we define >>>>>>> "backward-compatible" for CSL? >>>>>>> >>>>>>> Do we maybe need to make that explicit if it's not now? >>>>>> >>>>>> Didn't we have this discussion already when I prepared the release of >>>>>> CSL 1.0.1? >>>>>> >>>>>>> From http://en.wikipedia.org/wiki/Backward_compatibility: "If products >>>>>> designed for the new standard can receive, read, view or play older >>>>>> standards or formats, then the product is said to be >>>>>> backward-compatible". So for us, I would define backward-compatibility >>>>>> as the ability of CSL processors written for one specific version >>>>>> (e.g. "1.0.1") to process CSL styles written in an earlier CSL version >>>>>> (e.g. "1.0"). >>>>> >>>>> I think the following are two separate things: >>>>> >>>>> - the spec is backwards compatible >>>>> - a CSL processor is backwards compatible >>>>> >>>>> Note that that no matter what you write in the spec a processor can >>>>> *always* opt to be backwards compatible (unless you outright forbid it) >>>>> by analyzing a given style and choosing between alternative algorithms. >>>>> >>>>> Note also that you can *always* make new features backwards compatible in >>>>> the spec by doing exactly what you propose below: explicitly specifying >>>>> alternatives by saying there is a 'new' way and an 'old' way. In my >>>>> opinion this should not be part of a spec – by all means, you can add a >>>>> note urging implementers to also support an 'old' way, but why force >>>>> them? I find this extremely disrespectful – sure, it's easy for an >>>>> established implementation to switch to a new feature and keep the old >>>>> one around for compatibility's sake, but think for a moment what you're >>>>> saying to developers working on a new implementation (I understand that >>>>> this is something to be encouraged) – essentially, to implement a feature >>>>> twice, or to wrap their head around how they can reconcile two approaches >>>>> into a single algorithm – precisely what the spec fails to do in the >>>>> first place. >>>>> >>>>> If a feature differs so much that the underlying syntax changes or that >>>>> new elements need to be created, I don't think it's fair to call it >>>>> backwards compatible. Such a feature should go into a major release and >>>>> the legacy feature should be dropped completely. By doing this you're >>>>> actually *helping* implementers to provide backwards compatibility, >>>>> because they can simply look at a style's version and tell whether they >>>>> need to follow the 'new' or 'old' way. >>>>> >>>>> A new feature that can be implemented in such a way that the *same* >>>>> algorithm can still render old styles – this is something I would call >>>>> backwards-compatible (as far as the spec is concerned). The original >>>>> proposal for the feature in question was just that by the way – I would >>>>> see no problem to include it in a minor release. This is not the case >>>>> with the current proposal. >>>>> >>>>> Sylvester >>>>> >>>>> >>>>>> If this proposal is accepted, there would be two ways to encode >>>>>> conditions in CSL styles: the "old" way, where all conditions and the >>>>>> "match" attribute are loaded on cs:if's and cs:else-if's, and the >>>>>> "new" way, where we use the XML structure from the current proposal. >>>>>> Styles would be able to mix & match at the level of individual cs:if's >>>>>> and cs:else-if's (e.g., using the "old" structure for one cs:if, and >>>>>> the "new" structure for the following cs:else-if). Since we keep the >>>>>> "old" structure around, CSL 1.0.1 styles will keep working. Hence the >>>>>> change would be backward-compatible, hence the change would qualify >>>>>> for a 1.0.2 release. >>>>>> >>>>>> Rintze >>>>>> >>>>>> ------------------------------------------------------------------------------ >>>>>> Learn Graph Databases - Download FREE O'Reilly Book >>>>>> "Graph Databases" is the definitive new guide to graph databases and >>>>>> their applications. This 200-page book is written by three acclaimed >>>>>> leaders in the field. The early access version is available now. >>>>>> Download your free book today! http://p.sf.net/sfu/neotech_d2d_may >>>>>> _______________________________________________ >>>>>> xbiblio-devel mailing list >>>>>> [email protected] >>>>>> https://lists.sourceforge.net/lists/listinfo/xbiblio-devel >>>>> >>>>> >>>>> ------------------------------------------------------------------------------ >>>>> Learn Graph Databases - Download FREE O'Reilly Book >>>>> "Graph Databases" is the definitive new guide to graph databases and >>>>> their applications. This 200-page book is written by three acclaimed >>>>> leaders in the field. The early access version is available now. >>>>> Download your free book today! http://p.sf.net/sfu/neotech_d2d_may >>>>> _______________________________________________ >>>>> xbiblio-devel mailing list >>>>> [email protected] >>>>> https://lists.sourceforge.net/lists/listinfo/xbiblio-devel >>>> >>>> -- >>>> Charles Parnot >>>> [email protected] >>>> twitter: @cparnot >>>> http://mekentosj.com >>>> >>>> >>>> >>>> ------------------------------------------------------------------------------ >>>> Learn Graph Databases - Download FREE O'Reilly Book >>>> "Graph Databases" is the definitive new guide to graph databases and >>>> their applications. This 200-page book is written by three acclaimed >>>> leaders in the field. The early access version is available now. >>>> Download your free book today! http://p.sf.net/sfu/neotech_d2d_may >>>> _______________________________________________ >>>> xbiblio-devel mailing list >>>> [email protected] >>>> https://lists.sourceforge.net/lists/listinfo/xbiblio-devel >>> >>> >>> ------------------------------------------------------------------------------ >>> Learn Graph Databases - Download FREE O'Reilly Book >>> "Graph Databases" is the definitive new guide to graph databases and >>> their applications. This 200-page book is written by three acclaimed >>> leaders in the field. The early access version is available now. >>> Download your free book today! http://p.sf.net/sfu/neotech_d2d_may >>> _______________________________________________ >>> xbiblio-devel mailing list >>> [email protected] >>> https://lists.sourceforge.net/lists/listinfo/xbiblio-devel >> >> -- >> Charles Parnot >> [email protected] >> twitter: @cparnot >> http://mekentosj.com >> >> >> >> ------------------------------------------------------------------------------ >> Learn Graph Databases - Download FREE O'Reilly Book >> "Graph Databases" is the definitive new guide to graph databases and >> their applications. This 200-page book is written by three acclaimed >> leaders in the field. The early access version is available now. >> Download your free book today! http://p.sf.net/sfu/neotech_d2d_may >> _______________________________________________ >> xbiblio-devel mailing list >> [email protected] >> https://lists.sourceforge.net/lists/listinfo/xbiblio-devel > > > ------------------------------------------------------------------------------ > Learn Graph Databases - Download FREE O'Reilly Book > "Graph Databases" is the definitive new guide to graph databases and > their applications. This 200-page book is written by three acclaimed > leaders in the field. The early access version is available now. > Download your free book today! http://p.sf.net/sfu/neotech_d2d_may > _______________________________________________ > xbiblio-devel mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/xbiblio-devel ------------------------------------------------------------------------------ Learn Graph Databases - Download FREE O'Reilly Book "Graph Databases" is the definitive new guide to graph databases and their applications. This 200-page book is written by three acclaimed leaders in the field. The early access version is available now. Download your free book today! http://p.sf.net/sfu/neotech_d2d_may _______________________________________________ xbiblio-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/xbiblio-devel
