In r31865 [1], the section parameter was added to the action=edit API module. Since its usage is not what you might expect in some cases and the documentation is grossly out of date (I intend to work on bringing all of that up to date later), I'll post some usage notes here.
Existing sections can be edited by setting e.g. section=3 . This will edit the third section from the top (subsections, sub-subsections, etc. also count). The top section (the part before the first section header) can be accessed through section=0 . The content of a section cannot be retrieved from the API right now (I intend to implement rvcontentsection later), so you have to be careful here: a section consists of: * the header (don't forget that one, or you'll merge the section with the one right above it) * the section content (duh) ** which includes ALL SUBSECTIONS To clarify the latter: section number 3 in [2] is just the February section, whereas section number 1 includes sections 2 through 14 (!). The regular user interface also displays this behavior [3].
New sections can be added by setting section=new . In this case, you should NOT add a section header, it will be added for you. The section header text (without the = symbols) should go in the summary parameter. For example:
api.php?action=edit&title=Talk:Foo§ion=new&summary=Hello&text=Hello%20world
will create a new section called "Hello" with "Hello world" in it. Compare this interface to the regular section edit form [4] in which you also have to enter the section title in a separate textbox.
If you set the section parameter when creating a page (editing a nonexistent page), it'll be ignored unless it's 'new', in which case it'll behave as if you're adding a section to an empty page (the UI does that as well). If you set the section parameter to a string other than 'new', you'll get an error message. If you set the section parameter to a negative integer (e.g. -3), it'll be ignored and you'll end up EDITING THE ENTIRE PAGE. If you set the section parameter to a number larger than the number of section on the page, you'll get a successful result with the 'nochange' attribute set, e.g.:
<edit result="Success" pageid="77" title="Talk:Foo" nochange="" />
which essentially means your edit was ignored because it would change anything. Of course, this doesn't have to mean you tried to edit a nonexistent section: someone else could've changed exactly the same thing, or you could've forgotten to actually change anything.
I hope this clarifies some things that may be unintuitive at first.
Roan Kattouw (Catrope)
[1] http://svn.wikimedia.org/viewvc/mediawiki?view=rev&revision=31865 [2] http://en.wikipedia.org/w/index.php?title=1984&oldid=197705621 [3] http://en.wikipedia.org/w/index.php?title=1984&oldid=197705621&actio... [4] http://en.wikipedia.org/w/index.php?title=Talk:Main_Page&action=edit%C2%...
Roan Kattouw wrote:
New sections can be added by setting section=new . In this case, you should NOT add a section header, it will be added for you. The section header text (without the = symbols) should go in the summary parameter. For example:
api.php?action=edit&title=Talk:Foo§ion=new&summary=Hello&text=Hello%20world
will create a new section called "Hello" with "Hello world" in it. Compare this interface to the regular section edit form [4] in which you also have to enter the section title in a separate textbox.
What about providing another parameter to split that double function of the summary? I have seen the convenience to add a new section with section=new but didn't like having to set the same summary as the header.
So i propose addign a new parameter, newsectionname which if present overrides the summary for the header.
E.g. api.php?action=edit&title=Wikipedia:Wikipedia_Stats§ion=new&summary=February+statistics&newsectiinname=Automatically+adding+February+statistics+from+somesource&text=Hello%20world
2008/3/12, Platonides platonides@gmail.com:
What about providing another parameter to split that double function of the summary? I have seen the convenience to add a new section with section=new but didn't like having to set the same summary as the header.
I think that it is defined internally in MediaWiki (you don't see a "summary" field when adding a new section to some talkpage, do you?), so I think it would be counterintuitive to provide a new parameter when "summary" will be just ignored.
— Kalan
Kalan schreef:
I think that it is defined internally in MediaWiki (you don't see a "summary" field when adding a new section to some talkpage, do you?), so I think it would be counterintuitive to provide a new parameter when "summary" will be just ignored.
Well I could go ahead and change that internally, but MediaWiki 1.11 and later auto-generate a summary like "New section: [[Foo#Bar|Bar]]". In 1.11 this broke terribly if the section title contained special characters, but it works fine in 1.12 and later. For this reason I think overriding the auto-generated summary wouldn't be of much use and could be counterintuitive and/or confusing.
Roan Kattouw (Catrope)
Roan Kattouw escribió:
Kalan schreef:
I think that it is defined internally in MediaWiki (you don't see a "summary" field when adding a new section to some talkpage, do you?), so I think it would be counterintuitive to provide a new parameter when "summary" will be just ignored.
Well I could go ahead and change that internally, but MediaWiki 1.11 and later auto-generate a summary like "New section: [[Foo#Bar|Bar]]". In 1.11 this broke terribly if the section title contained special characters, but it works fine in 1.12 and later. For this reason I think overriding the auto-generated summary wouldn't be of much use and could be counterintuitive and/or confusing.
Roan Kattouw (Catrope)
Why?
Uhhh... just to interject... But that may not always remain the case. There is a possibility of the title rewrite adding a new input for titles to the edit page. And with the similarities to the section title, it may just end up splitting the setup into two inputs. One for the title/section title and the other for a summary whatever the case. Likely that the auto generated link to the section in the comment will be coded to stay there instead of the current way which allows the user to remove that.
So, ya, that's the current behavior, but remember there is always room for improvement. In fact, adding a proper summary box to the Edit form for sections might be an even better course of action than just saying "The API won't allow custom summaries for sections because you can't do that with the current edit page".
~Daniel Friesen(Dantman) of: -The Gaiapedia (http://gaia.wikia.com) -Wikia ACG on Wikia.com (http://wikia.com/wiki/Wikia_ACG) -and Wiki-Tools.com (http://wiki-tools.com)
Roan Kattouw wrote:
Platonides schreef:
Why?
Because it's not possible through the UI and uses an auto-generated edit summary. That's what section=new is pretty much about.
Roan Kattouw (Catrope)
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
DanTMan schreef:
So, ya, that's the current behavior, but remember there is always room for improvement. In fact, adding a proper summary box to the Edit form for sections might be an even better course of action than just saying "The API won't allow custom summaries for sections because you can't do that with the current edit page".
True. However, the edit form and the edit API depend on each other very much. This means I can't separate the two until someone does that in the edit form first.
Roan Kattouw (Catrope)
Kalan wrote:
2008/3/12, Platonides platonides@gmail.com:
What about providing another parameter to split that double function of the summary? I have seen the convenience to add a new section with section=new but didn't like having to set the same summary as the header.
I think that it is defined internally in MediaWiki (you don't see a "summary" field when adding a new section to some talkpage, do you?), so I think it would be counterintuitive to provide a new parameter when "summary" will be just ignored.
— Kalan
The summary is the same as the new header. It's called "Subject/headline:". Summary won't be ignored. It will be only containing the summary. It's just splitting the two actions the same field is currently doing.
Note to self:
To get a list of all section headings, even on short pages, use http://en.wikipedia.org/w/api.php?action=parse&prop=sections&text=%7...
Magnus
Roan Kattouw schreef:
The content of a section cannot be retrieved from the API right now
That's just become possible. I introduced the rvsection parameter in r31969 [1], so you can now retrieve section content with:
api.php?action=query&prop=revisions&rvprop=content&rvsection=3&titles=Foo|Bar
This will retrieve the content of the 3rd section of Foo and Bar. Note that if either Foo or Bar has less than three sections, you'll get an error message.
Also note that section numbers can differ between revisions of the same page. For that reason, the following request might not do what you expect:
api.php?action=query&prop=revisions&rvprop=content|user|timestamp|comment&rvsection=15&rvlimit=10&titles=Foo
This will return the 15th section of each of the 10 most recent revisions of Foo. This could give you 10 slightly different versions of the same section, but it could also give you 3 versions of one section and 7 versions of another if a section was added or removed at some point. Therefore, diff'ing sections in this way does not always produce meaningful output.
Roan Kattouw (Catrope)
[1] http://svn.wikimedia.org/viewvc/mediawiki?view=rev&revision=31969
mediawiki-api@lists.wikimedia.org