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&acti…
[4]
http://en.wikipedia.org/w/index.php?title=Talk:Main_Page&action=edit&am…