Editing Template:S-start/doc (section)

==Instructions for use==
There are many types of succession boxes, as the combinations of the various templates previously mentioned are virtually endless. We shall begin by demonstrating the use of simple boxes, and proceed with the analysis of more complex boxes of many lines and multiple titles.

===Simple boxes===
The very purpose of a succession box is to show the place of the ''subject'' of the box (the person—or other entity—whose article the box is in) in a succession of people (henceforth referred to as a ''succession chain''). Because of this, most boxes include three people, namely the subject, their predecessor, and their successor.

The quintessential succession box consists of three ''cells'', which go from left to right in the same order that the three persons' terms succeeded each other: the left cell names the predecessor, the middle one names the title of the subject and the years that mark their term in an office (the person's name is already mentioned in the article's title and is thus not repeated here), and the right one names the successor.

Simply enough, the creation of a box follows the same order. First comes the predecessor (template ''s-bef''), the title and years follow (template ''s-ttl''), and then comes the successor (template ''s-aft''). It should not be forgotten, of course, that every succession box opens with the ''s-start'' template, and ends with the ''s-end'' template. Each command should be given its own line in the edit box.

Have a look at this diagram.

:Enter the start field so that the program recognizes the table:
::<nowiki>{{s-start}}</nowiki>
:Enter the name of the predecessor:
::<nowiki>{{s-bef|before=[[</nowiki>''Enter predecessor here''<nowiki>]]}}</nowiki>
:Enter the title of the person on whose page you are working:
::<nowiki>{{s-ttl|title=[[</nowiki>''Enter title here''<nowiki>]]</nowiki>
:Also, enter the years during which they held that title (not necessarily in a different line):
::<nowiki>|years=</nowiki>''Enter start date here''<nowiki>&nbsp;– </nowiki>''Enter end date here''<nowiki>}}</nowiki>
:Enter the name of the successor:
::<nowiki>{{s-aft|after=[[</nowiki>''Enter successor here''<nowiki>]]}}</nowiki>
:Once everything is done, type:
::<nowiki>{{s-end}}</nowiki>


This is an example of the technique, taken from the article of [[Aegon IV Targaryen]]. Writing...

::<nowiki>{{s-start}}</nowiki>
::<nowiki>{{s-bef|before=[[Viserys II Targaryen|Viserys II]]}}</nowiki>
::<nowiki>{{s-ttl|title=[[King of the Andals, the Rhoynar, and the First Men]]<br>[[Lord of the Seven Kingdoms]]<br>[[Protector of the Realm]]</nowiki>
::<nowiki>|years={{Date|172|184}}}}</nowiki>
::<nowiki>{{s-aft|after=[[Daeron II Targaryen|Daeron II]]}}</nowiki>
::<nowiki>{{s-end}}</nowiki>

...will produce this:

{{s-start}}
{{s-bef|before=[[Viserys II Targaryen|Viserys II]]}}
{{s-ttl|title=[[King of the Andals, the Rhoynar, and the First Men]]<br>[[Lord of the Seven Kingdoms]]<br>[[Protector of the Realm]]
|years={{Date|172|184}}}}
{{s-aft|after=[[Daeron II Targaryen|Daeron II]]}}
{{s-end}}

Note that the names of the predecessor and the successor and the name of the title are enclosed within double square brackets; this allows for the names in the box to link to their respective articles. Although it is strongly suggested that you do link the names in the boxes even if they do not have their own article at the time (resulting in a red link), there can be exceptions.

It is encouraged that you include the title-holder's dates of term or reign whenever possible; if a date is dubious or disputed, use the ''s-ref'' template to include references that will back up that date (see the [[#S-ref|relevant section]] for details).

===Advanced boxes===
Some characters have held multiple offices and/or titles in their life. As it would be unwieldy to create separate boxes for all these titles, we include all of them in a single succession box. Thus, each article has one box at the bottom, which is easier to manage and more aesthetically pleasing.

In some cases, succession boxes consist of many separate rows that are made up of the previous section's simple boxes, and thus their creation follows more or less the same rules; the only difference is that special care should be given to the placement and relative order of said simple boxes, as well as to the inclusion ''s-break'' (a template version of "|-") between the lines where necessary.

On other occasions, a person might inherit more than one title from a single individual, and/or pass multiple titles on to one person. It is also possible that someone might take over an office from two different people who had held it jointly until then, or join several different titles into one that will be inherited by a single heir.

For these, and other scenarios, it is possible to create succession boxes that can clearly show those connections by making use of the advanced features of the hereinbefore presented succession template model. The system for the advanced boxes is slightly different from the simple forms demonstrated in the previous section, and it relies heavily on the ''s-break'' template, as well as on the correct counting of the rows.

====Counting the rows====
Basically, the format is the following: if a box is taking up more than one row of the table, it can be specified how many rows exactly that will be by inserting a row parameter immediately after the template name (''s-...'' field) and before every other parameter. That can be done by typing:

::<nowiki>{{s-...|</nowiki>'''rows=''Insert number of rows here'''''<nowiki>|...}}</nowiki>

The number corresponds to the number of rows this name or title overlaps in regard to the other rows, as opposed to denoting a specific height for a cell. In other words, if, for example, all three cells of a line were given a "rows=2" parameter, the box would appear as if none of these cells was assigned a rows parameter at all, the comparative heights of these cells to one another being identical.

The titles in succession boxes are usually listed in the order of the granting of the title—beginning with the oldest titles held—but other schemes exist as well. All notable successive titles should be noted, though titles tied together permanently can be listed in the same cell and some subsidiary titles may be omitted altogether.

====''s-break'' (the "|-" character) ====
In theory, it is necessary for the box to work to place "|-" between every line of the box, even if every cell is restricted to its own line. However, "|-" is already imbedded into most of the templates, so it is no longer necessary to add it to boxes that consist of simple one-row lines, with the exceptions of templates ''s-vac'' and ''s-non'': if a line ends with one of these templates, you need to place this character or the computer will not recognize a new row. Similarly, if a line begins with ''s-vac'', the character must be placed before that row.

Still, things are different with more complex tables that incorporate multiple-row cells covering more than one lines each. Complex patterns are created and it is not always easy for the computer to display all the lines correctly. This is why ''s-break'' is so important in these cases, and although its placement is unneeded between many of the lines, it is much more preferable to use it redundantly in a table than to create a non-functional box, where it will often be difficult to locate the mistake.

That said, and even though it is a safe option to place ''s-break'' between every pair of lines in a box, it is naturally better to avoid such practices to the extent this is possible. Here follow a few simple tips that can limit its redundant usage to a minimum without leading to mistakes:

*When considering the placement of ''s-break'', it is important to note the presence or absence of succession templates in a line. That is, a template for a multiple-line cell is always placed at the line from which the cell starts, therefore that line has a template for that cell while the other lines that share the cell do not. As a result, a line from which multi-line cells begin but into which no cell continues from a higher line has templates for all three cells and there is not any need to place the character before it unless this is necessitated by the presence of a ''s-vac'' or ''s-non'' template.

:In the following example, note the lack of 's-break'' between the first and the second line and, more importantly, between the fourth and fifth lines:

::<nowiki>{{s-start}}</nowiki>
::<nowiki>{{s-bef|before}}</nowiki>
::<nowiki>{{s-ttl|title=|years=}}</nowiki>
::<nowiki>{{s-aft|after=}}</nowiki>
::<nowiki>{{s-bef|rows=2|before=}}</nowiki>
::<nowiki>{{s-ttl|title=|years=}}</nowiki>
::<nowiki>{{s-aft|rows=3|after=}}</nowiki>
::<nowiki>{{s-break}}</nowiki>
::<nowiki>{{s-ttl|title=|years=}}</nowiki>
::<nowiki>{{s-break}}</nowiki>
::<nowiki>{{s-bef|before=}}</nowiki>
::<nowiki>{{s-ttl|title=|years=}}</nowiki>
::<nowiki>{{s-bef|before=}}</nowiki>
::<nowiki>{{s-ttl|title=|years=}}</nowiki>
::<nowiki>{{s-aft|after=}}</nowiki>
::<nowiki>{{s-end}}</nowiki>

*When only the predecessor cell of a line stretches between the line in question and a previous one (it does not matter whether it continues into a lower line), ''s-break'' needs not be inserted between that line and the previous one. Similarly, if only the successor cell covers multiple lines and begins in a line above the one in question, then the ''s-break'' that could follow the concerned line's ''s-ttl'' parameter can be omitted. And the situation is even easier with a multi-row title cell (a rarer occurrence), as it is usually not directly affected by line changes. Generally, it is easier for the computer to separate the lines when only one template is missing from a row's three.

*Always use the preview button before saving. If you are not certain about the inclusion of a ''s-break'', you can try removing it and then previewing the page; if a succession box has an error, that will generally be readily visible. Keep in mind that each line in a box ought to have three cells, each line and column should align perfectly, and the two side columns should have the same width, which normally is slightly smaller than that of the middle column (a 3 to 4 ratio).

Have a look at the following example. In its first iteration (left), ''s-break'' is used to separate every line from its previous and next ones. In its second version (right), ''s-break'' is used only as many times as it is necessary for the box to work properly: none. The result is exactly the same in both cases, and can be seen below the code.

{{col-begin}}
{{col-break}}
::<nowiki>{{s-start}}</nowiki>
::<nowiki>{{s-bef|before=Mary}}</nowiki>
::<nowiki>{{s-ttl|rows=2|title=President of the Balkans|years=1982–1992}}</nowiki>
::<nowiki>{{s-aft|after=William}}</nowiki>
::<nowiki>{{s-break}}</nowiki>
::<nowiki>{{s-bef|rows=2|before=Nicholas}}</nowiki>
::<nowiki>{{s-aft|after=Edgar}}</nowiki>
::<nowiki>{{s-break}}</nowiki>
::<nowiki>{{s-ttl|title=King of New Zealand|years=1990–1997}}</nowiki>
::<nowiki>{{s-aft|after=Helen}}</nowiki>
::<nowiki>{{s-break}}</nowiki>
::<nowiki>{{s-bef|before=Richard}}</nowiki>
::<nowiki>{{s-ttl|title=King of Southeast Asia|years=1990–present}}</nowiki>
::<nowiki>{{s-inc|rows=2|heir=Lee}}</nowiki>
::<nowiki>{{s-break}}</nowiki>
::<nowiki>{{s-bef|before=George}}</nowiki>
::<nowiki>{{s-ttl|title=Governor of Borneo|years=2003–present}}</nowiki>
::<nowiki>{{s-end}}</nowiki>
{{col-break}}
::<nowiki>{{s-start}}</nowiki>
::<nowiki>{{s-bef|before=Mary}}</nowiki>
::<nowiki>{{s-ttl|rows=2|title=President of the Balkans</nowiki>
::<nowiki>|years=1982–1992}}</nowiki>
::<nowiki>{{s-aft|after=William}}</nowiki>
::<nowiki>{{s-bef|rows=2|before=Nicholas}}</nowiki>
::<nowiki>{{s-aft|after=Edgar}}</nowiki>
::<nowiki>{{s-ttl|title=King of New Zealand</nowiki>
::<nowiki>|years=1990–1997}}</nowiki>
::<nowiki>{{s-aft|after=Helen}}</nowiki>
::<nowiki>{{s-bef|before=Richard}}</nowiki>
::<nowiki>{{s-ttl|title=King of Southeast Asia</nowiki>
::<nowiki>|years=1990–present}}</nowiki>
::<nowiki>{{s-inc|rows=2|heir=Lee}}</nowiki>
::<nowiki>{{s-bef|before=George}}</nowiki>
::<nowiki>{{s-ttl|title=Governor of Borneo</nowiki>
::<nowiki>|years=2003–present}}</nowiki>
::<nowiki>{{s-end}}</nowiki>
{{col-end}}

{{s-start}}
{{s-bef|before=Mary}}
{{s-ttl|rows=2|title=President of the Balkans|years=1982–1992}}
{{s-aft|after=William}}
{{s-bef|rows=2|before=Nicholas}}
{{s-aft|after=Edgar}}
{{s-ttl|title=King of New Zealand|years=1990–1997}}
{{s-aft|after=Helen}}
{{s-bef|before=Richard}}
{{s-ttl|title=King of Southeast Asia|years=1990–present}}
{{s-inc|rows=2|heir=Lee}}
{{s-bef|before=George}}
{{s-ttl|title=Governor of Borneo|years=2003–present}}
{{s-end}}