search

citation-style-language / documentation

Citation Style Language documentation
http://citationstyles.org/
Creative Commons Attribution Share Alike 4.0 International
44 stars 21 forks source link

Define delimiter-encapsulation #120

Closed cormacrelf closed 4 years ago

cormacrelf commented 4 years ago

Fixes #65, Supersedes #116.

There are more words but I think it's easier to understand, especially with an example. It's also easier to extend it to other sequence-type elements as they arise.

bdarcus commented 4 years ago

Copying @jgm if he wants to weigh in on this alternative text.

See also @cormacrelf's longer explanation on the initial PR.

bwiernik commented 4 years ago

This is much clearer, I agree.

denismaier commented 4 years ago

I also agree that this is concise and clear.

bdarcus commented 4 years ago

Ancestor/descendent would be the more generic XML language.

bdarcus commented 4 years ago

You want to weigh in @PaulStanley or @andras-simonyi?

bdarcus commented 4 years ago

@adam3smith - if you have a moment, any feedback on this?

bwiernik commented 4 years ago

Do we absolutely need a term? Could we say something like "the output of a macro is not subject to surrounding delimiters" and something equivalent for delimiting elements? Not wedded to this change, but as a reminder, the principal audience of this document are style developers, so legibility is important.

How about

the output of a macro does not inherit delimiters from ancestor elements

bdarcus commented 4 years ago

Shouldn't the primary audience for the spec be developers?

bwiernik commented 4 years ago

Shouldn't the primary audience for the spec be developers?

Style writers read the spec much much more than developers do considering the comparative numbers of the two groups.

bdarcus commented 4 years ago

I don't really think that's relevant. I'm not saying it shouldn't serve both audiences, but I strongly believe the primary audience should be developers.

On Thu, Sep 17, 2020 at 12:25 PM Brenton M. Wiernik < notifications@github.com> wrote:

Shouldn't the primary audience for the spec be developers?

Style writers read the spec much much more than developers do considering the comparative numbers of the two groups.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/citation-style-language/documentation/pull/120#issuecomment-694345792, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAAI3VBW2Y4JCUMLMSFZ7LSGIZ6VANCNFSM4QTAKZWA .

adam3smith commented 4 years ago

We've had this discussion a couple of months ago: There is a lot of small things that the current specs don't capture that a developer needs to do, currently captured in the test suite. If we add all of this to the main specs document, it becomes completely unusable for style authors, so one of the groups needs a separate document for it to be useful. My recollection was that we agreed on keeping the specs oriented towards authors and working towards separate developer specifications (maybe call them implementation notes or so).

cormacrelf commented 4 years ago

@adam3smith Agree on the terminology too. It made it shorter as well as a bit easier for authors. Thanks!

cormacrelf commented 4 years ago

I think that's done

bwiernik commented 4 years ago

We've had this discussion a couple of months ago: There is a lot of small things that the current specs don't capture that a developer needs to do, currently captured in the test suite. If we add all of this to the main specs document, it becomes completely unusable for style authors, so one of the groups needs a separate document for it to be useful. My recollection was that we agreed on keeping the specs oriented towards authors and working towards separate developer specifications (maybe call them implementation notes or so).

Yes, that was my understanding too.

jgm commented 4 years ago

We've had this discussion a couple of months ago: There is a lot of small things that the current specs don't capture that a developer needs to do, currently captured in the test suite. If we add all of this to the main specs document, it becomes completely unusable for style authors, so one of the groups needs a separate document for it to be useful. My recollection was that we agreed on keeping the specs oriented towards authors and working towards separate developer specifications (maybe call them implementation notes or so).

I wasn't involved in this discussion, but my 2 cents as a developer: trying to guess why the test suite requires things that aren't mentioned explicitly in the spec is no fun. It makes sense to keep the spec manageable, but why not create a separate document with all the additional information that developers might need?

bdarcus commented 4 years ago

I think the primer should be the style author facing document, and the spec should be developer facing.

adam3smith commented 4 years ago

but my 2 cents as a developer: trying to guess why the test suite requires things that aren't mentioned explicitly in the spec is no fun. It makes sense to keep the spec manageable, but why not create a separate document with all the additional information that developers might need?

Absolutely; I don't think there's any disagreement that having citeproc developers rely purely on the test suite isn't great for all sorts of reasons, so a document that exhaustively describes expected citeproc behavior in precise language is definitely needed. I think the only reason it doesn't exist yet is the labor involved.

I think the primer should be the style author facing document, and the spec should be developer facing.

I don't care about the names of the respective documents at all, so if there's a good reason to call the citeproc dev documents "specificiation," by all means let's do so. I don't think the technical document is ready, though, and I don't think there's any reason to delay the 1.0.2 release while waiting for it.

(The current primer is insufficient for style authoring. What style authors need is a document that exhaustively covers the syntax of CSL, including all variables and terms, and the general behavior of CSL, without too much implementation detail, e.g. things like handling double spaces & punctuation, a number of the other edge cases covered in the test suite currently.)