Specification of Footnote Number in <fn> Tag

Hi emfabric

This was a nice surprise! It's been really long since someone contributed this much new code. Always welcome.

Based on reading but not trying it out, looks like you've done a good job, what you added integrate well with existing code. If you could re-roll the patch against the 6.x-2.x-dev (or HEAD in CVS) I would definitively want to include it.

But before we get that far... we need to talk "API" more. To have a feature like this, I'd like to have it right from the beginning:

1) You say that you'll never mix labels (as in <fn label="*">text</fn> text <fn>text</fn>) In that case it seems to me, the label type should be an attribute of the footnote tag, not the specific footnotes items: <footnotes type="*" />

2) Numbering should by default continue from the previous one. So if you have ... <fn label="8">...</fn> ... <fn>...</fn> the second footnote should be 9, not 2.

3) For completeness, you should be able to specify the start number also in the footnotes tag, as <footnotes start="8" />. (This would produce the identical result as having the first fn contain nr 8, as in the previous point.)

4) As a general rule, and I've done so in above points, I think it makes sense to copy the attribute names and functionality from the HTML 4 standard (even if they are now deprecated). See these links for hints:
http://w3schools.com/tags/tag_ol.asp
http://w3schools.com/tags/tag_ul.asp
http://w3schools.com/tags/tag_li.asp

So instead of "label" you could use "value" as the attribute name: <fn value="8">...</fn> or <fn value="*">...</fn>

5) For the footnotes label type as specified in (1), I again to propose to have the ones from HTML 4 and some of my own:
A = A, B, C...
a = a, b, c...
I = I, II, III, IV, V, VI...
i = i, ii, iii, iv...
1 = 1, 2, 3
* = *, **, ***, ****
+ = +, ++, +++

But of course you don't need to implement all of these, I'm just listing it here as something I've already thought of, kind of like a specification that we could do a subset of now. (And as a climax to all this, we could have user defined lists defined as <footnotes type="smiley" sequence=",:-), ;-),:-(,:-D,..." /> where the user could define his own sequence for the footnotes list, list separator being the first character in the string.)

n) Btw, do you have a strong requirement to support also single quotes and no quotes? I'd very much like not to allow that, just keep it to well-formed xml. It makes the code simpler too.

I've adjusted for 6.x-2.x-dev, although I didn't test that the [fn label='2'] syntax actually works.

1, 3 & 5) I think used some ambiguous terms in defining our site's requirements. When I say "never intermix specified and automatic numbers", I mean that in our application, we are going to label every footnote, so the case of what to do with mixed labeled and unlabeled fn doesn't have practical effect to us -- they will all be labelled.

Our footnotes parallel a print publication, so we need to include in the tag the fn number/label, rather than rely on automatic counting. This prevents a user editing error that corrupts or deletes one fn from affecting the numbering of the rest of the footnotes in the document. We also occasionally need to be able to do non-contiguous numbers, eg 1, 5, 6, 8, if excerpting a larger work.

2) I agree that would probably be more useful for more people. What I'll try to come up with is a modification that uses php's is_numeric($value) function to test the supplied label, and if so, kick the $n up to value of the supplied label.

4) It probably makes sense to parallel the form of <li></li>

n) We don't required unquoted label support, although I see it as helpful when footnotes are being used more informally, such as in a blog post with sparse html or via the [fn label=9][/fn] style.

Ok, I understand now. I'm trying to think what would make sense in your use case then... Maybe:

1) Instead of label="" use value="" for the attribute name.

2) If value is an integer (is_numeric() is probably fine) it will define that footnote as having the number specified and subsequent footnotes continuing to count from that. (So yes, need to set $n = $value.)

3) If value is not an integer, use the string as a label and increment $n with one. (As you have originally done.)

4) You can disregard anything else I said in the previous comment. The above three points can later be expanded to the bigger scheme I laid out - ie. this is a "forward compatible" approach, but no need to implement more than is needed for now. (You may of course, if you have time, do more of it too.)

NOTE: I refactored the approach to handling both [fn] and <fn> brackets just now. #282205: Refoactor: transform angle brackets into square brackets in process phase So make sure to download the 6.x-2.x-dev snapshot that appears whatever time after this post.
Sorry for any extra work that may cause you, but actually the new approach should make your work easier as you don't need to do some regexps twice. I don't have anything else in the pipeline just now, so if you are actively working on the patch now, I'll not mess it up again.

On (3), the more I think about, it might make more sense to not increment $n when using a string label. That would facilitate lists like

1,2,*,3

or,

*,1,2,3 (which is a pattern I've sometimes seen in scholarly articles)

with only a single value string on the * fn. I would wager that's a more common pattern than *,2,3,4.

I fully agree. Let's do it that way.

So if the value attribute is not an integer, it's kind of in a different space altogether. Except that it listed within the same footnotes list of course.

Ok, I've made the modifications as discussed. I also modified the open tag counter, $open_tags = preg_match_all("|<fn>|", $text, $foo); to match tags with parameters.

Hi emfabric

Nice and well done patch. I changed the variable name $label to $value, so it is the same as the attribute name. In comments I changed it to say "value label". I also replaced 3 occurences of tabs with 2 spaces instead.

At the last minute, I realised it is now not ok to use the value directly in the footnote id anymore, since it may contain characters other than [_a-zA-Z0-9-] so I added a check that removes any illegal characters.

I also wrote something in README and Changelog about this.

This is now committed.

Automatically closed -- issue fixed for two weeks with no activity.