Last modified: 2012-11-03 22:40:37 UTC
Created attachment 6146 [details] diff -w -c Cite_body.php.orig Cite_body.php This enhancement, with code to implement it, enable editors to invisiblly declare Ref body text outside of the flow of the article prose. This enables editors to declutter article prose. The enhancement also enables ordering of footnotes according to editor preference. The code changes to implement this enhancement are relative to cite-body.php from Cite-MW1.14-r45577. This bug replaces and supersedes Bug# 12796.
A complete Cite_body.php file (vs. the diff attached to the bug) to implement this enhancement is available from [[Wikipedia:User:Wtmitchell]]. The file is available with or without the changes made being clearly indicated. The modification adds an optional Ref tag parameter named "hide" From the editor's perspective, if the hide attribute is present in a Ref tag, two things are done: 1. Generation of the superscripted forward-link to the expanded references is suppressed; 2. Generation of the associated backlink in the expanded References item is suppressed (and appropriate adjustments are made in the other backlinks if needed). This allows Ref tag body declarations to be done in a block outside of the article prose. This block may be located anywhere preceding the <references /> tag which would expand the references. If the block is located at the head of the article (ahead of any <ref name=whatever /> tags), the Refs declared therein will be expanded in the order of declaration. A Ref declaration block would look something like the following: <div style="display:none"> <ref hide name=c1>This is a comment which should be placed in the References section</ref> <ref hide name=c2>This is another comment which should be placed in the References section</ref> <ref hide name="Cited source">This is a citation of [http://something.somewhere.com a supporting source]</ref> </div> The "display:none" is intended to hide the newlines between the Ref declarations. Sample wikitext: <div style="display:none;"> <!-- hide newlines between ref declarations --> <!-- Refs here are sorted by desired order of appearance and placed ahead of the article prose --> <ref hide name=able1987>Able, John. ''A paper about something'' (1987), Smith Publishing.</ref> <ref hide name=snodgrass1985>Snodgrass, Peter. ''A paper about something else'' (1985), XYZ Books.</ref> <ref hide name=zorch1955>Zorch, Carl. ''A paper about nothing'' (1987), Random Pubs.</ref> </div> '''Refs here are ordered by name:''' Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.<ref name=zorch1955 /><ref name=snodgrass1985 /> Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.<ref name=zorch1955 /> Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.<ref name=snodgrass1985 /><ref name=able1987 /> '''Refs here are not ordered by name:''' Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.<ref name=h2 /><ref name=h3 /> Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.<ref name=h0 /> Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.<ref name=h0 /><ref name=h1 /> Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.<ref name=h2 group=b /> Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.<ref name=h2 group=a /> Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.<ref name=h2 group=a /><ref name=h2 group=b /> ;Default ref group <div style="display:none;"> <!-- hide newlines between ref declarations --> <ref hide name=h0>def for h0</ref> <ref hide name=h1 >def for h1</ref> <ref hide name=h2 >def for h2</ref> <ref hide name=h3 >def for h3</ref> </div><references /> ;Ref group a <ref hide name=h2 group=a>def for h2 ga</ref> <references group=a /> ;Ref group b <ref hide name=h2 group=b>def for h2 gb</ref> <references group=b />
Please attach patches as unified diffs, see http://www.mediawiki.org/wiki/Subversion#Making_a_diff Thanks.
Created attachment 6149 [details] diff -u -w Cite_body.php.orig Cite_body.php Unified diff requested in Comment #2.
I screwed up the link to the code in Comment#1.The modified Cite_body.php is currently available at [http://en.wikipedia.org/wiki/User:Wtmitchell/Work1] (unless I've screwed that up too). Contact me on my wikipedia User:Wtmitchell talk page with any questions, etc.
I have put a test wiki up at http://siteslot.com/testwiki/ with the modified Cite_body.php file installed.
The hardcoded div looks pretty hacky, and taking reference text outside of the body area in this way could interfere with previews and section editing. Doesn't seem like a win to me as current...
We already very often have sections with references whose content is in another section; that part is not a problem. (It does not interfere with previews and section editing.)
In that case this bug can be closed INVALID since the requested ability already exists.
Huh? No, the requested ability does not exist. The requested ability is the ability to declare a ref somewhere where it does not show up: --- This is a sentence.<ref name="smith"/> This is another sentence. <ref hide name="smith">Smith, John (2002). ''A Book''</ref> --- That way the paragraph can remain uncluttered.
Speaking to comment #6: 1. This comment does not directly relate to the functionality of the Cite_body.php modifications at all. It is more a matter of how to accommodate the implied changes in wikitext usage. 2. In practice, the hardcoded div could, and no doubt would, be prettified by packaging it in a pair of templates. Wikipedia already has {{refbegin}} and {{refend}} to format a block of cited sources similarly to the way {{reflist}} expands and specially formats a list of <references />. The template pair might be named something like {{starthide}} and {{endhide}}. I think a better alternative might be something like {{startblock|hide}} and {{endblock}} -- allowing the {{startblock}} template to be expanded to support other types of special-purpose blocks than this ''hide'' purpose. 3. An alternative might be to junk the approach taken by the modified Cite_body.php in Bugzilla:18890 for another approach. One such approach might be to introduce a new element to the References tag to identify a block of ref declarations; something like <references block> <ref name=1st>this is the first ref.</ref> ... <ref name=327th>this is the three hundred and twenty seventh ref</ref> </references> I thought about this alternative, and shied away from it because 3a. It struck me that its implementation starting from the Cite-MW1.14-r45577 cite would likely be messier than the approach taken by Bug#18890. 3b. It does not offer the possibility of editor control of the ordering the expanded list of references. The list would be expanded and numbered in the order of appearance in the wikitext prose (whatever ref is referenced first in the wikitext prose would be first in the expanded list and would be numbered "1." , as with current usage). The approach taken by bug#18890 offers editors an additional flexibility option to control the ordering of the expanded list of references if they desire to do so.
I agree that the div seems kludgy; rather than recommend littering the output with hidden divs, it would be better to recommend putting the newlines where the extension can control them; i.e. <ref hide name=h0> def for h0 </ref><ref hide name=h1 > def for h1 </ref><ref hide name=h2 > def for h2 </ref> I also think the "define" might be a better term than "hide", conceptually that it's defining text to be used elsewhere. For that, I think this patch is more complex than necessary. It should be sufficient to define/override the text without incrementing the usage count for the footnote, rather than generating bogus instances, and keeping track of which uses shouldn't be there, so <references> can filter them out. It would also be better if some of the nonsensical cases (i.e. multiple, anonymous, missing text, etc) produce errors, for better consistency with the rest of the extension. Finally, you should look at the parser tests (see the script in the maintaneance directory & file included with the extension) both to verify that you didn't cause any new regressions, as well as to add your own test cases as examples there, since you are changing the syntax.
Speaking to Comment#11: Good one Steve!! As I said in my Comment#8, the bit about the hidden div does not directly relate to the functionality of the Cite_body.php modifications at all. It is more a matter of how to accommodate the implied changes in wikitext usage. I agree that your suggestion is cleaner than the way I handled it in the sample wikitext in my bug report. I had no doubts that it would work, but I did confirm that it does work on the test wiki for the modified Cite_body.php at http://siteslot.com/testwiki/, and have modified the sample wikitext in the Main page there accordingly.
1. In my Comment#12 above, I should have said "my Comment#10" instead of "my Comment#8". 2. Re the suggestions in Comment#11 about how the changes in the modified Cite_body.php might better be done differently: 2a. I agree "hide" might not be the best term. How about "def"? (e.g. "<ref def name=whatever>...</ref>") 2b. I've taken a quick look back at the Cite_body.php code and it looks to me as if changing the modification implementation as suggested would result in less total code, but that it would also result in more extensive changes to the code -- particularly in function stack{}. I could take a look at doing an alternative implementation, but might not get to that right away. 3. I'm new to mediawiki development and am not formally a mediawiki developer. Now that you've pointed me in the right direction, I've found the maintenance directory on my test wiki. I'll try to take a look at that and figure out how to regression test the Cite_body.php changes. That will be on my to-do list somewhere ahead of #2b above (and probably behind a lot of other things).
Re Comment#13: OK, with ssh access I have gone to to http://siteslot.com/testwiki/maintenance and said "make test >testresults". The results in http://siteslot.com/testwiki/maintenance/testresults don't look to me as if the Cite_body.php changes introduce any problems. What now?
For regression testing, you should start with running php maintenance/parserTests.php --quick --quiet --file=extensions/Cite/citeParserTests.txt On both versions, to make sure that your changes don't affect the results, then add your tests to that .txt file. For the code changes, my impression is that my suggestion would mostly mean removing unnecessary parts of your change, possibly including the entire change to referencesFormatEntry(); although I haven't tested that. Of course, the added error checking would then require a little additional code.
Re Comment#15 (rushed) In the testwiki/maintenance directory, I said "php maintenance/parserTests.php \ --quick --quiet --file=extensions/Cite/citeParserTests.txt" Results were as follows: ---begin results X-Powered-By: PHP/5.2.9 Content-type: text/html This is MediaWiki version 1.14.0. <br /> <b>Warning</b>: fopen(extensions/CiteParserTests.txt) [<a href='function.fopen'>function.fopen</a>]: failed to open stream: No such file or directory in <b>/home/siteslot/public_html/testwiki/maintenance/parserTests.inc</b> on line <b>282</b><br /> Couldn't open extensions/citeParserTests.txt ---end of of results There was no testwiki/maintenance/extensions subdirectory. I found a citeParserTests.txt file in the testwiki/extensions/Cite subdirectory. I created the testwiki/maintenance/extensions subdirectory and copied that file there. I again said "php maintenance/parserTests.php \ --quick --quiet --file=extensions/Cite/citeParserTests.txt" Results were as follows: --begin results X-Powered-By: PHP/5.2.9 Content-type: text/html This is MediaWiki version 1.14.0. Reading tests from "./extensions/citeParserTests.txt"... This test suite requires the 'ref' hook extension. ---end results I am on a travel deadline and must begin packing. I will travel today and will be using internet cafes for perhaps the next week.
OK, I'm at a loss. Does anyone know what the "'ref' hook extension" is, where it lives, how to install it, where I can find info on it, where I can find info on regression testing for mediawiki extensions, etc? I looked at http://www.mediawiki.org/wiki/Extension_Matrix, but that didn't help me.
(In reply to comment #17) > OK, I'm at a loss. Does anyone know what the "'ref' hook extension" is, where > it lives, how to install it, where I can find info on it, where I can find info > on regression testing for mediawiki extensions, etc? I looked at > http://www.mediawiki.org/wiki/Extension_Matrix, but that didn't help me. > It's http://www.mediawiki.org/wiki/Extension:Cite
Re Comment#17 Yes, I used info from http://www.mediawiki.org/wiki/Extension:Cite to install the cite extension with the modified Cite_body.php onto the test wiki for this bug at http://siteslot.com/testwiki. After Comment#15, I tried regression testing the modified Cite extension as described in Comment#16 and ran into problems which I described in Comment#16. Specifically, the test suite complains, "This test suite requires the 'ref' hook extension." The hook for the Ref tag is working OK, though, as seen on the Main page of the test wiki which uses it to handle Ref tags. Perhaps there is a problem in the test suite at testwiki/maintenance/extensions/citeParserTests.txt which I copied there from testwiki/extensions/Cite/citeParserTests.txt as described in Comment#16, or perhaps there is a problem somewhere else in the regression testing, or perhaps the complaint I'm seeing is normal (though it does not look normal). I'm at a loss.
What's happening is that since it's testing an extension, it first checks if that extension is installed; since it's not finding it, it doesn't run the tests. The question is, why the extension is found when running from the web, but not from the tests. It wouldn't be a problem with the .txt file; the ref hook definitely needs to be installed to run the tests, so that is correct. You may check that you only have one LocalSettings.php, and that the extension is installed correctly there. If you can't find the error there, you may need to trace through parserTests.inc to see why it doesn't find it.
OK, I think I've done all I can be expected to here. 1. Re the discussion in Comment#15 - Comment#20 regarding the broken regression testing, I have run regression testing on the unmodified Cite-MW1.14-r45577 extension and have observed that to fail in the same manner as it fails with this modified version. Apparently, there is some problem predating the Cite-MW1.14-r45577 extension with the citeParserTests.txt file, or with the regression test facility, or with the Mediawiki parser. Failure of regression testing of this modification to the Cite_body.php file from Cite-MW1.14-r45577 and with the unmodified Cite_body.php file from that release would appear to be unrelated to any changes made in this modification. 2. Re the portion of Comment#15 re error checking, I have added error checking code to detect two new error possibilities -- unrecognized Ref tag elements and orphan hidden refs. 3. Re the portion of Comment#15 re removing unnecessary parts, after looking back at the code again, I didn't see unnecessary parts to be removed. This is related to and illustrated by one of the new possible errors -- an orphan hidden ref error. Such an error is detected at References expansion time, at which time the orphan hidden ref must be in the stacked refs and must be distinguishable as a hidden ref. (I hope I'm not confusing anyone by speaking of "hidden refs", I'm coining terminology here as I go along) 4. Re the portion of Comment#11 suggesting that "define" might be a better term than "hide", I've done an alternative implementation growing out of Comment#13 ("<ref def name=whatever>...</ref>" instead of "<ref hide name=whatever>...</ref>"). Personally, I like the "ref def" syntax better. I have not attached the "ref def" version of the code to this bug -- I can do that if needful, or I can enter a new bug with the "ref def" version, offering that as a replacement for this bug. Suggestions? 5a. A testwiki for the <ref hide name=whatever>...</ref> version is available at http://siteslot/testwiki/. 5b. A testwiki for the <ref def name=whatever>...</ref> version is available at http://siteslot/testwiki2/. 6. Please let me know if I can usefully do any more on this -- problems seen in testing on the testwikis, further suggestions, whatever. 7. Both testwikis will stay up for now. At some point, I will take them down.
(In reply to comment #17) > OK, I'm at a loss. Does anyone know what the "'ref' hook extension" is, where > it lives, how to install it, where I can find info on it, where I can find info > on regression testing for mediawiki extensions, etc? I looked at > http://www.mediawiki.org/wiki/Extension_Matrix, but that didn't help me. > OK, I've found that the regression testing wasn't loading the hook properly, due to changes in how these are loaded. I've fixed that in r51372, so you should be able to test now.
Created attachment 6186 [details] reformatted patch I've cleaned up and reformatted the patch a little: - removed some extraneous comments - fixed a compiler warning - regenerated with 'svn diff' from current head
Created attachment 6192 [details] diff -u -w for <ref hide ...>" syntax as of 2009-06-04 Diff using "diff -w -u ..." for latest version of the "<ref hide ...>" syntax variant the modified Cite_body.php, believed to be working, installed as of 2009-06-04 on the testwiki located at http://siteslot/testwiki
Created attachment 6193 [details] diff for the "<ref def ...>" syntax Diff using "diff -w -u ..." for latest version of the "<ref def ...>" syntax variant the modified Cite_body.php, believed to be working, installed as of 2009-06-04 on the testwiki located at http://siteslot/testwiki2 (note the trailing '2')
Created attachment 6194 [details] "diff -w -u ..." for Cite.i18n.php.2009-06-04.php.diff Add handling for two new Cite errors for the English language.
Bill, does your patch still apply? I recommend that you get a developer access account https://www.mediawiki.org/wiki/Developer_access so that you can commit your patches directly into the source control system in the future -- in fact, you could update and submit this patch, and get it reviewed faster. I'm sorry for the delay.
I haven't looked at this in several years. It has been overtaken by events (see [http://en.wikipedia.org/wiki/Help:List-defined_references], which provides some of the same functionality. As I recall, that appeared without going through bugzilla.). This patch is probably not compatible with the current cite.php code, and no longer applies.
Thanks for your response, Bill. I appreciate you checking. It sounds like only part of this bug is still unresolved; is there any portion of the desired functionality that is still unavailable? If so, what?
List-defined references now supply the main functionality of removing the clutter of lengthy references and cite templates from the main article text, which I believe was the main point of Bill's patch. The only other functionality that this patch allowed was to enable the footnotes to be placed and displayed in any order. There is no advantage in changing the display order of footnotes away from the auto-numbered sequence that is currently applied, so that part is unnecessary. In the edit box, list-defined references can now be placed in any desired order anyway while still producing the same displayed output, so LDR takes care of that part of the functionality of this patch as well. I would suggest that this patch is therefore completely superseded.
(In reply to comment #30) > I would suggest that this patch is therefore completely superseded. I've wanted this feature for a while, and the Wikipedia:Tutorial/Citing sources didn't give me any clues as to how to do it. I'm glad to see that this method of list-defined references has been added. I've done a tiny bit of testing and it works as I would expect, including auto-numbered sequencing; error when citation doesn't exist; and error when reference is named but not used. I agree that the feature seems to have been completed satisfactorily
I reported this and did the code quite some time ago. it has been a long time since I looked at it. As I recall. I lost interest in this after changes to cite.php which had not gone through bugzilla addressed some parts of what this does and produced a new cite.php version which would probably require some rework of this code to restore compatibility with the newly feepeling creatureized code. As far as I am concerned, this is a dead issue.
Bill, and Steve as well, thank you for working on this, and my apologies that you didn't get response on your patches sooner. The Wikimedia Foundation is specifically working on improving the situation so that patches don't get delayed responses as yours did; I regret how long it took for you to get replies, and I want you to know I appreciate how much effort you put into this! I'm now marking this bug as resolved since it sounds like the original desire is taken care of. If you'd ever like to suggest a patch directly into our source control system for a quicker response, you now can: https://www.mediawiki.org/wiki/Developer_access Thanks and sorry again.
