Help:Section

From FamilySearch Wiki

(Difference between revisions)
m (Changing where the TOC appears)
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Contributor Help badge}}<br><br>
+
{{Help article}}
  
 +
<br>A page can and should be divided into '''sections''', using the section heading syntax. For each page with more than three section headings, a table of contents (TOC) is automatically generated.
  
A page can and should be divided into '''sections''', using the section heading syntax. For each page with more than three section headings, a table of contents (TOC) is automatically generated.
+
== Naming  ==
  
== Creation and numbering of sections ==
+
In essence, the same guidelines apply for titles of sections as for general naming conventions of articles (see [[FamilySearch Wiki:Naming conventions]]). In short, they should be easily recognizable by English speakers, be brief without being ambiguous and should be chosen, where possible, to avoid implying a viewpoint.
 +
 
 +
== Creating sections ==
  
 
'''Sections''' are created by creating their headings, as below.  
 
'''Sections''' are created by creating their headings, as below.  
 
<pre>==Section==
 
<pre>==Section==
 
 
===Subsection===
 
===Subsection===
 
 
====Sub-subsection====
 
====Sub-subsection====
 
</pre>
 
</pre>
Please ''do not'' use only one equals sign on a side ({{xt|<NOWIKI>=Heading=</NOWIKI>}}). This would cause a section heading to be as large as the page's name (title).
 
  
For registered users who use the preference setting [[Help:Preferences#Misc_settings|Auto-number headings]], sections are numbered in the table of contents and at beginning of each section heading.  
+
 
 +
{{Note|One equals sign ({{xt|<NOWIKI>=Heading=</NOWIKI>}}) should not be used for sections as this causes the section heading to be as large as the page's name (title).}}
 +
 
  
 
Headings of sections (including subsections) should be unique on a page. Using the same heading more than once on a page causes problems:  
 
Headings of sections (including subsections) should be unique on a page. Using the same heading more than once on a page causes problems:  
  
*An [[Help:Link#Wikilinks|internal link (wikilink)]] to a section, in the form {{xt|<NOWIKI>[[Article name#Section heading]]</NOWIKI>}}, will only link to the first section on the page with that name, which may not be the intended target of the link. See also [[FamilySearch Wiki:Linking#Linking_to_sections_of_articles|Linking to sections of articles]].  
+
*An [[Help:Links|internal link]] to a section, in the form {{xt|<NOWIKI>[[Article name#Section heading]]</NOWIKI>}}, will only link to the first section on the page with that name, which may not be the intended target of the link.
 
*When a section with a duplicate name is edited, the edit history and summary will be ambiguous as to which section was edited.  
 
*When a section with a duplicate name is edited, the edit history and summary will be ambiguous as to which section was edited.  
 
*When saving the page after a section edit, the editor's browser may navigate to the wrong section.
 
*When saving the page after a section edit, the editor's browser may navigate to the wrong section.
  
A section of a page can be a [[FamilySearch Wiki:Transclusion|transclusion]] of a separate page or template. See [[Help:Template#Composite_pages]]. This in effect gives the section its own separate edit history (i.e., the page history of the transcluded page) and also allows registered users to [[Help:Watching pages|watch]] it separately.  
+
A section of a page can be a [[FamilySearch Wiki:Transclusion|transclusion]] of a separate page or template. This in effect gives the section its own separate edit history (i.e., the page history of the transcluded page) and also allows registered users to [[Help:Watching pages|watch]] it separately.
  
 
In a page calling a template with sections, the sections in the template are numbered according to their position in the rendered page, e.g. if the template tag is in the third section, then the first section of the template is numbered four. Any text in the template before its first section shows up as part of the section with the template tag, and any text after the tag before a new heading shows up as part of the last section of the template. This may be done deliberately, but can usually better be avoided (see also below).  
 
In a page calling a template with sections, the sections in the template are numbered according to their position in the rendered page, e.g. if the template tag is in the third section, then the first section of the template is numbered four. Any text in the template before its first section shows up as part of the section with the template tag, and any text after the tag before a new heading shows up as part of the last section of the template. This may be done deliberately, but can usually better be avoided (see also below).  
 
In MediaWiki software, a section heading in wikitext is [http://svn.wikimedia.org/viewvc/mediawiki/trunk/phase3/includes/Parser.php?view=markup defined by] a [[Regular expression]], <code>/(^={1,6}.*?={1,6}\s*?$)/m</code> (''m'' refers to multi-line mode).
 
  
 
== Table of contents (TOC)  ==
 
== Table of contents (TOC)  ==
  
For each page with more than three headings, a '''table of contents (TOC)''' is automatically generated from the section headings, unless:  
+
For each page with more than three headings, a "table of contents" (TOC) is automatically generated from the section headings, unless:  
  
 
*(for a user) [[Help:Preferences|preferences]] are set to turn it off  
 
*(for a user) [[Help:Preferences|preferences]] are set to turn it off  
 
*(for an article) the [[Help:Magic words|magic word]] <tt><nowiki>__NOTOC__</nowiki></tt> (with '''two underscores''' on either side of the word) is added to the article
 
*(for an article) the [[Help:Magic words|magic word]] <tt><nowiki>__NOTOC__</nowiki></tt> (with '''two underscores''' on either side of the word) is added to the article
 +
 +
=== Forcing the TOC to appear ===
  
 
When either <tt><nowiki>__FORCETOC__</nowiki></tt> or <tt><nowiki>__TOC__</nowiki></tt> (with '''two underscores''' on either side of the word) is placed in the wikitext, a TOC is added even if the page has fewer than four headings.  
 
When either <tt><nowiki>__FORCETOC__</nowiki></tt> or <tt><nowiki>__TOC__</nowiki></tt> (with '''two underscores''' on either side of the word) is placed in the wikitext, a TOC is added even if the page has fewer than four headings.  
  
With <tt><nowiki>__FORCETOC__</nowiki></tt>, the TOC is placed before the first section heading. With <tt><nowiki>__TOC__</nowiki></tt>, it is placed at the same position where this code is placed. This allows any positioning, e.g. on the right or in a table cell. In old versions of MediaWiki, it also allows multiple occurrence, e.g. in every section (However, this seems only useful if the sections are long, so that the TOCs take up only a small part of the total space.).  
+
With <tt><nowiki>__TOC__</nowiki></tt>, it is placed at the same position where this code is placed. This allows any positioning, e.g. on the right or in a table cell (see below).
 +
 
 +
<tt><nowiki>__FORCETOC__</nowiki></tt> is similar to the TOC <tt><nowiki>__TOC__</nowiki></tt> except that it can be placed anywhere on the page and the TOC will still be placed before the first section heading.
  
There may be some introductory text before the TOC, known as the "lead". Although usually a heading after the TOC is preferable, <tt><nowiki>__TOC__</nowiki></tt> can be used to avoid being forced to insert a meaningless heading just to position the TOC correctly, i.e., not too low.
+
=== Hiding the TOC ===
  
 
Using <tt><nowiki>__NOTOC__</nowiki></tt> it is possible to disable the normal table of contents. Section links, as explained below, allow creating '''compact ToCs''', e.g. alphabetical <tt><nowiki>[[#A|A]] [[#B|B]]</nowiki></tt> etc.  
 
Using <tt><nowiki>__NOTOC__</nowiki></tt> it is possible to disable the normal table of contents. Section links, as explained below, allow creating '''compact ToCs''', e.g. alphabetical <tt><nowiki>[[#A|A]] [[#B|B]]</nowiki></tt> etc.  
  
The TOC's depth can be limited by the use of [[Template:TOClimit]]. This template can reduce the number of "header levels" visible to the reader&nbsp;– thus avoiding the problem of an overwhelming TOC when an article has many headings and sub-headings.
+
=== Changing where the TOC appears ===
  
This Table of contents can be forced onto a floating table on the right hand of the screen with the code below:  
+
There may be some introductory text before the TOC, known as the "lead". <tt><nowiki>__TOC__</nowiki></tt> can be used to place the TOC at the top of the page before any text avoiding the need to insert a meaningless heading just to position the TOC correctly. Additionally, <tt><nowiki>__TOC__</nowiki></tt> can be used anywhere on the page to force the TOC to appear at a specific location.
 +
 
 +
'''Forcing the TOC to appear on the right'''
 +
 
 +
This Table of Contents can be forced to appear on the right hand side of the screen using the template {{tl|TOC right}}.
 +
 
 +
Alternatively the code below can be used::  
  
 
   <nowiki>&nbsp;{| align="right"
 
   <nowiki>&nbsp;{| align="right"
 
   | __TOC__
 
   | __TOC__
 
   |}</nowiki>
 
   |}</nowiki>
 
  
=== Globally limiting the TOC depth ===
+
=== Limiting the number of headings ===
 +
 
 +
The TOC's depth can be limited by the use of [[Template:TOClimit]]. This template can reduce the number of "header levels" visible to the reader&nbsp;– thus avoiding the problem of an overwhelming TOC when an article has many headings and sub-headings.
 +
 
 +
'''Globally limiting the TOC depth'''
  
 
It is possible to limit the depth of sub-sections to show in the TOC globally using $wgMaxTocLevel. If configuration setting $wgMaxTocLevel in LocalSettings.php is set to 3 for example, only first and second level headings show up in the TOC. Until version [http://svn.wikimedia.org/svnroot/mediawiki/tags/REL1_10_0RC1/phase3/RELEASE-NOTES 1.10.0rc1], there is a bug in the parser making a limited TOC display incorrectly. A simple solution is proposed in bug report [[Bugzilla:6204|6204]].  
 
It is possible to limit the depth of sub-sections to show in the TOC globally using $wgMaxTocLevel. If configuration setting $wgMaxTocLevel in LocalSettings.php is set to 3 for example, only first and second level headings show up in the TOC. Until version [http://svn.wikimedia.org/svnroot/mediawiki/tags/REL1_10_0RC1/phase3/RELEASE-NOTES 1.10.0rc1], there is a bug in the parser making a limited TOC display incorrectly. A simple solution is proposed in bug report [[Bugzilla:6204|6204]].  
  
== Section linking ==
+
== Section linking ==
  
In the HTML code for each section there is an anchor [[HTML element#Anchor|HTML element "a"]] with both "name" and "id" attributes holding the section title. This enables [[W:hyperlink|linking]] directly to sections. These section anchors are automatically used by MediaWiki when it generates a table of contents for the page, and therefore when a section heading in the ToC is clicked, it will jump to the section. Also, the section anchors can be manually linked directly to one section within a page.  
+
In the HTML code for each section there is an anchor [[HTML element#Anchor|HTML element "a"]] with both "name" and "id" attributes holding the section title. This enables [[Help:Links|linking]] directly to sections. These section anchors are automatically used by MediaWiki when it generates a table of contents for the page, and therefore when a section heading in the TOC is clicked, it will jump to the section. Also, the section anchors can be manually linked directly to one section within a page.  
  
 
The HTML code generated at the beginning of this section, for example, is:  
 
The HTML code generated at the beginning of this section, for example, is:  
 
<pre>&lt;p&gt;&lt;a name="Section_linking" id="Section_linking"&gt;&lt;/a&gt;&lt;/p&gt;
 
<pre>&lt;p&gt;&lt;a name="Section_linking" id="Section_linking"&gt;&lt;/a&gt;&lt;/p&gt;
 
&lt;h2&gt;Section linking&lt;/h2&gt;</pre>
 
&lt;h2&gt;Section linking&lt;/h2&gt;</pre>
 +
 +
 
A link to this section ([[Help:Section#Section_linking|Section linking]]) looks like this:  
 
A link to this section ([[Help:Section#Section_linking|Section linking]]) looks like this:  
  
Line 90: Line 105:
 
**<tt><nowiki>[[namespace:page#section|]]</nowiki></tt> -&gt; [[namespace:page#section|]]
 
**<tt><nowiki>[[namespace:page#section|]]</nowiki></tt> -&gt; [[namespace:page#section|]]
  
For linking to an arbitrary position in a page see [[Help:Link#Section_linking_.28anchors.29|Section linking (anchors)]].  
+
For linking to an arbitrary position in a page see [[Help:Advanced Linking|Advanced Linking (anchors)]].  
  
=== Section linking and redirects ===
+
== Section editing ==
 
+
A link that specifies a section of a redirect page corresponds to a link to that section of the target of the redirect.
+
 
+
A [[Help:Redirect|redirect]] to a section of a page may also work in some environments (see [[Bugzilla:218|bug 218]]), try e.g. the redirect page [[Help:Section linking and redirects|Section linking and redirects]]. (One might have to force reload CSS style sheets.)
+
 
+
A complication is that, unlike renaming a page, renaming a section does not create some kind of redirect. Also, there is no separate [[Help:What links here|backlink feature for sections]], pages linking to the section are included in the list of pages linking to the page. Possible workarounds:
+
 
+
*Instead of linking directly to a section, link to a page that redirects to the section; when the name of the section is changed, change the redirect target. This method also provides more or less a "what links here" for sections (look for redirects linking to the page, select the one linking to the section; this may be recognized from the name even if the section name has changed).
+
*Put an anchor and link to that
+
*Put a comment in the wikitext at the start of a section listing pages that link to the section
+
*Make the section a separate page/template and either transclude it into, or just link to it from, its parent page; instead of linking to the section one can then link to the separate page.
+
 
+
Redirect pages can be categorized by adding a category tag after the redirect command. In the case that the target of the redirect is a section, this has to some extent the effect of categorizing the section: through the redirect the category page links to the section; however, unless an explicit link is put, the section does not link to the category. On the category page, redirects are displayed with class redirect-in-category, so they can be shown in e.g. italics; this can be defined in [[MediaWiki:Common.css]]. See also [[FamilySearch Wiki:Categorizing redirects]].
+
 
+
== Section editing ==
+
  
 
Sections can be separately edited by clicking special edit links labeled "[edit]" by the heading, or by right clicking on the section heading, depending on the [[Help:Preferences|preferences]] set. This is called "section editing feature" (<nowiki>Preferences -> Editing -> "Enable section editing via [edit] links"</nowiki>). Section editing feature will take you to an edit page by a URL such as  
 
Sections can be separately edited by clicking special edit links labeled "[edit]" by the heading, or by right clicking on the section heading, depending on the [[Help:Preferences|preferences]] set. This is called "section editing feature" (<nowiki>Preferences -> Editing -> "Enable section editing via [edit] links"</nowiki>). Section editing feature will take you to an edit page by a URL such as  
Line 121: Line 121:
 
Inserting a section can be done by editing either the section before or after it, merging with the previous section by deleting the heading. Note that in these cases the preloaded section name in the edit summary is not correct, and has to be changed or deleted.  
 
Inserting a section can be done by editing either the section before or after it, merging with the previous section by deleting the heading. Note that in these cases the preloaded section name in the edit summary is not correct, and has to be changed or deleted.  
  
=== Adding a section at the end ===
+
=== Adding a section at the end ===
  
 
Adding a section at the end can also be done with a URL like http://meta.wikimedia.org/w/wiki.phtml?title=Meta:Sandbox&amp;action=edit&amp;section=new . On talk pages and pages with in the wikitext the code <nowiki>__NEWSECTIONLINK__</nowiki> a special link labeled with the {{msg|addsection}}, e.g. "+" or "Post a new comment", is provided for this. In this case, a text box having as title the {{msg|subject}}, e.g. "Subject/headline", will appear and the content you type in it will become the section heading. There is no inputbox for the [[Help:Edit summary|edit summary]], it is automatically created according to the pattern of {{msg|newsectionsummary}}, where "/* $1 */" represents a right arrow linking to the new section and, with CSS-class "autocomment", the name of the section followed by " - ". In the case of the default of message newsectionsummary this is followed by the text "new section". The user cannot provide more text for the edit summary than just the header itself (use the method mentioned earlier if that is desired).  
 
Adding a section at the end can also be done with a URL like http://meta.wikimedia.org/w/wiki.phtml?title=Meta:Sandbox&amp;action=edit&amp;section=new . On talk pages and pages with in the wikitext the code <nowiki>__NEWSECTIONLINK__</nowiki> a special link labeled with the {{msg|addsection}}, e.g. "+" or "Post a new comment", is provided for this. In this case, a text box having as title the {{msg|subject}}, e.g. "Subject/headline", will appear and the content you type in it will become the section heading. There is no inputbox for the [[Help:Edit summary|edit summary]], it is automatically created according to the pattern of {{msg|newsectionsummary}}, where "/* $1 */" represents a right arrow linking to the new section and, with CSS-class "autocomment", the name of the section followed by " - ". In the case of the default of message newsectionsummary this is followed by the text "new section". The user cannot provide more text for the edit summary than just the header itself (use the method mentioned earlier if that is desired).  
Line 133: Line 133:
 
See also [[Help:Edit summary#Linking_to_a_section|linking in an edit summary to a section]], and [[Help:Edit summary#.22Post_a_comment.22_feature|"Post a comment" feature]].  
 
See also [[Help:Edit summary#Linking_to_a_section|linking in an edit summary to a section]], and [[Help:Edit summary#.22Post_a_comment.22_feature|"Post a comment" feature]].  
  
=== Editing before the first section  ===
+
=== Subsections ===
 
+
In general, no particular link for editing the introductory text before the first section heading is provided.
+
 
+
=== Preview ===
+
 
+
The preview in section editing does not always show the same as the corresponding part of the full page, e.g. if on the full page an image in the previous section intrudes into the section concerned.
+
 
+
The edit page shows the list of templates used on the whole page, i.e. also the templates used in other sections.
+
 
+
=== Subsections ===
+
  
 
Subsections are included in the part of the section that is edited. Section numbering is relative to the part that is edited, so on the relative top level there is always just number 1, relative subsections all have numbers starting with 1: 1.1., 1.2, etc.; e.g., when editing subsection 3.2, sub-subsection 3.2.4 is numbered 1.4. However, the heading ''format'' is according to the absolute level.  
 
Subsections are included in the part of the section that is edited. Section numbering is relative to the part that is edited, so on the relative top level there is always just number 1, relative subsections all have numbers starting with 1: 1.1., 1.2, etc.; e.g., when editing subsection 3.2, sub-subsection 3.2.4 is numbered 1.4. However, the heading ''format'' is according to the absolute level.  
  
=== Editing a page with large sections ===
+
=== Editing a page with large sections ===
  
 
If a page has very large sections, or is very large and has no division into sections, and one's browser or connection does not allow editing of such a large section, then one can still:  
 
If a page has very large sections, or is very large and has no division into sections, and one's browser or connection does not allow editing of such a large section, then one can still:  
Line 156: Line 146:
 
If one can view the wikitext of a large section, one can divide the page into smaller sections by step by step appending one, and finally deleting the original content (this can be done one large section at a time). Thus temporarily there is partial duplication of the content, so it is useful to put an explanation in the edit summary.  
 
If one can view the wikitext of a large section, one can divide the page into smaller sections by step by step appending one, and finally deleting the original content (this can be done one large section at a time). Thus temporarily there is partial duplication of the content, so it is useful to put an explanation in the edit summary.  
  
{{Help:Editing sections of included templates}}
+
=== Sections within parser functions ===
 
+
=== Sections within parser functions ===
+
  
 
When conditionally (using a [[ParserFunctions|parser function]]) transcluding a template with sections, edit links of this and subsequent sections will edit the wrong section or give the error mesage that the section does not exist (although the page (including TOC) is correctly displayed and the TOC links correctly). This is because for the targets of the edit links the content of conditionally included templates is considered part of the page itself, and the sections are counted after expansion.  
 
When conditionally (using a [[ParserFunctions|parser function]]) transcluding a template with sections, edit links of this and subsequent sections will edit the wrong section or give the error mesage that the section does not exist (although the page (including TOC) is correctly displayed and the TOC links correctly). This is because for the targets of the edit links the content of conditionally included templates is considered part of the page itself, and the sections are counted after expansion.  
Line 168: Line 156:
 
The problem does not occur when transcluding a template with a conditional name (which has more advantages). Use {{tim|void}} for the template to transclude to produce nothing.  
 
The problem does not occur when transcluding a template with a conditional name (which has more advantages). Use {{tim|void}} for the template to transclude to produce nothing.  
  
=== Editing a footnote ===
+
=== Editing a footnote ===
  
To edit a footnote rendered in a section containing the code <nowiki><references /></nowiki>, edit the section with the footnote mark referring to it, see [[Help:Footnotes]]. However, the resulting text of the footnote is not shown in a preview of the section via "Show preview", so any mistake made by the editor will not be discovered until after the section edit is saved via "Save page". A workaround is to temporarily add a <nowiki><references/></nowiki> or <nowiki>{{reflist}}</nowiki> tag at the end of the section prior to previewing it. But after you are satisfied with the text of the reference shown in the preview, this temporary tag must be removed before the edit is saved.  
+
To edit a footnote rendered in a section containing the code <nowiki><references /></nowiki>, edit the entire page as the "References" section will not display the reference which is located in another section on the page.
  
=== Viewing a section ===
+
== Sections vs. separate pages vs. transclusion ==
 
+
The section editing feature can also be used to just ''view'' a section without loading the whole page. There is no other way.
+
 
+
== Sections vs. separate pages vs. transclusion ==
+
  
 
Advantages of separate pages:  
 
Advantages of separate pages:  
  
*[[Help:What links here|what links here]] feature  
+
*What links here feature  
 
*separate edit histories  
 
*separate edit histories  
 
*some template limits apply ''per page''  
 
*some template limits apply ''per page''  
Line 186: Line 170:
 
*loading a small page is faster than loading a large page  
 
*loading a small page is faster than loading a large page  
 
*can separately be put in categories (however, see also below)  
 
*can separately be put in categories (however, see also below)  
*with [[Semantic MediaWiki]]: have separate annotations
 
  
 
Advantages of one large page with sections:  
 
Advantages of one large page with sections:  
Line 194: Line 177:
 
*enforces the cohesion of a concept that while having several definitions needs independent editing.
 
*enforces the cohesion of a concept that while having several definitions needs independent editing.
  
An alternative is [[Help:Template#Composite_pages|composing a page of other pages using the template feature]] (creating a [[W:compound document|compound document]] by [[FamilySearch Wiki:Transclusion|Transclusion]]). This allows easy searching within the combined rendered page, but not in the combined wikitext. As a disadvantage, a title for each page has to be provided. For the pre-expand include size limit this is disadvantageous even compared with one large page: the pre-expand include size is the sum of the pre-expand include sizes of the components plus the sum of sizes of the wikitexts of the components.  
+
An alternative is [[Help:Template#Composite_pages|composing a page of other pages using the template feature]] (creating a compound document by [[FamilySearch Wiki:Transclusion|Transclusion]]). This allows easy searching within the combined rendered page, but not in the combined wikitext. As a disadvantage, a title for each page has to be provided. For the pre-expand include size limit this is disadvantageous even compared with one large page: the pre-expand include size is the sum of the pre-expand include sizes of the components plus the sum of sizes of the wikitexts of the components.  
  
== Section size guidelines ==
+
== See also ==
 
+
The size of sections may vary, depending on what kind of subject is described and other variables. "Hard" knowledge, e.g. biochemistry articles, presenting many names and mechanisms in a short interval may have shorter section size, while, on the other hand, "soft" knowledge, like articles concerning movies, may have longer ones. There is no strict rule about how long a section may be, just as with [[FamilySearch Wiki:Article size|article size]]. Nevertheless, a proper section size is probably somewhere between 80 and 500 words. More specifically, "hard" knowledge articles should contain between 80 and 250, while "soft" ones may contain more than 250. Each article's content should determine its section sizing&nbsp;— many short sections make it easier to find desired information about a subject, but may, when used in excess, also disturb the fluency of an article.
+
 
+
== Naming ==
+
 
+
In essence, the same guidelines apply for titles of sections as for general naming conventions of articles (see [[FamilySearch Wiki:Naming conventions]]). In short, they should be easily recognizable by English speakers, be brief without being ambiguous and should be chosen, where possible, to avoid implying a viewpoint.
+
  
See also [[FamilySearch Wiki:Words to avoid#Article_and_section_titles]] for advice on how to maintain [[FamilySearch Wiki:Neutral point of view|NPOV]].
+
:*[[Help:Formatting|Formatting]]  
 +
:*[[Help:Magic words|Magic words]]  
  
In addition, sections containing many references to various studies are preferably not simply titled "Research" without further specification. Unless the contents relate to principles or techniques in researching, and could fit into the main article [[Research]], the titles of such sections are better specified with what the studies and their results are aimed at. "Research" alone tend to make the section a miscellaneous and unorganized dump of random studies that have any link to the subject.
+
Templates:
 +
:*{{tl|TOClimit}}
 +
:*{{tl|TOC right}}
  
== See also ==
+
{{Translation needed|es|Ayuda:Secciones}}
  
*[[Help:Preferences]]
+
{{Contributor help-navbox}} {{Editing help}}
*[[Help:Magic words]]
+
*[[Template:Sections]]
+
*[[FamilySearch Wiki:Layout]], a style guide concerning what sections to create in wiki articles
+
  
 
[[Category:Help|{{PAGENAME}}]]
 
[[Category:Help|{{PAGENAME}}]]

Revision as of 04:28, 3 September 2012

Help-content.png This help article will guide you as you edit in the Wiki. See Contributor Help for more help articles.



A page can and should be divided into sections, using the section heading syntax. For each page with more than three section headings, a table of contents (TOC) is automatically generated.

Contents

Naming

In essence, the same guidelines apply for titles of sections as for general naming conventions of articles (see FamilySearch Wiki:Naming conventions). In short, they should be easily recognizable by English speakers, be brief without being ambiguous and should be chosen, where possible, to avoid implying a viewpoint.

Creating sections

Sections are created by creating their headings, as below.

==Section==
===Subsection===
====Sub-subsection====



Headings of sections (including subsections) should be unique on a page. Using the same heading more than once on a page causes problems:

  • An internal link to a section, in the form [[Article name#Section heading]], will only link to the first section on the page with that name, which may not be the intended target of the link.
  • When a section with a duplicate name is edited, the edit history and summary will be ambiguous as to which section was edited.
  • When saving the page after a section edit, the editor's browser may navigate to the wrong section.

A section of a page can be a transclusion of a separate page or template. This in effect gives the section its own separate edit history (i.e., the page history of the transcluded page) and also allows registered users to watch it separately.

In a page calling a template with sections, the sections in the template are numbered according to their position in the rendered page, e.g. if the template tag is in the third section, then the first section of the template is numbered four. Any text in the template before its first section shows up as part of the section with the template tag, and any text after the tag before a new heading shows up as part of the last section of the template. This may be done deliberately, but can usually better be avoided (see also below).

Table of contents (TOC)

For each page with more than three headings, a "table of contents" (TOC) is automatically generated from the section headings, unless:

  • (for a user) preferences are set to turn it off
  • (for an article) the magic word __NOTOC__ (with two underscores on either side of the word) is added to the article

Forcing the TOC to appear

When either __FORCETOC__ or __TOC__ (with two underscores on either side of the word) is placed in the wikitext, a TOC is added even if the page has fewer than four headings.

With __TOC__, it is placed at the same position where this code is placed. This allows any positioning, e.g. on the right or in a table cell (see below).

__FORCETOC__ is similar to the TOC __TOC__ except that it can be placed anywhere on the page and the TOC will still be placed before the first section heading.

Hiding the TOC

Using __NOTOC__ it is possible to disable the normal table of contents. Section links, as explained below, allow creating compact ToCs, e.g. alphabetical [[#A|A]] [[#B|B]] etc.

Changing where the TOC appears

There may be some introductory text before the TOC, known as the "lead". __TOC__ can be used to place the TOC at the top of the page before any text avoiding the need to insert a meaningless heading just to position the TOC correctly. Additionally, __TOC__ can be used anywhere on the page to force the TOC to appear at a specific location.

Forcing the TOC to appear on the right

This Table of Contents can be forced to appear on the right hand side of the screen using the template {{TOC right}}.

Alternatively the code below can be used::

  {| align="right"
  | __TOC__
  |}

Limiting the number of headings

The TOC's depth can be limited by the use of Template:TOClimit. This template can reduce the number of "header levels" visible to the reader – thus avoiding the problem of an overwhelming TOC when an article has many headings and sub-headings.

Globally limiting the TOC depth

It is possible to limit the depth of sub-sections to show in the TOC globally using $wgMaxTocLevel. If configuration setting $wgMaxTocLevel in LocalSettings.php is set to 3 for example, only first and second level headings show up in the TOC. Until version 1.10.0rc1, there is a bug in the parser making a limited TOC display incorrectly. A simple solution is proposed in bug report 6204.

Section linking

In the HTML code for each section there is an anchor HTML element "a" with both "name" and "id" attributes holding the section title. This enables linking directly to sections. These section anchors are automatically used by MediaWiki when it generates a table of contents for the page, and therefore when a section heading in the TOC is clicked, it will jump to the section. Also, the section anchors can be manually linked directly to one section within a page.

The HTML code generated at the beginning of this section, for example, is:

<p><a name="Section_linking" id="Section_linking"></a></p>
<h2>Section linking</h2>


A link to this section (Section linking) looks like this:

[[Help:Section#Section_linking|Section linking]]

To link to a section in the same page you can use [[#section name|displayed text]], and to link to a section in another page [[page name#section name|displayed text]].

The anchors disregard the depth of the section; a link to a subsection or sub-subsection etc. will be [[#subsection name]] and [[#sub-subsection name]] etc.

An underscore and number are appended to duplicate section names. E.g. for three sections named "Example", the names (for section linking) will be "Example", "Example_2" and "Example_3". However, after editing section "Example_2" or "Example_3" (see below), one, confusingly, arrives at section "Example" from the edit summary.

If a section has a blank space as heading, it results in a link in the TOC that does not work. For a similar effect see NS:0.

To create an anchor target without a section heading, you can use a span: <span id="anchor_name"></span> but this won't work with some very old browsers.

Notes:

For linking to an arbitrary position in a page see Advanced Linking (anchors).

Section editing

Sections can be separately edited by clicking special edit links labeled "[edit]" by the heading, or by right clicking on the section heading, depending on the preferences set. This is called "section editing feature" (Preferences -> Editing -> "Enable section editing via [edit] links"). Section editing feature will take you to an edit page by a URL such as

https://familysearch.org/w/wiki.phtml?title=Help:Section&action=edit&section=2

Note that here section numbers are used, not section titles; subsections have a single number, e.g. section 2.1 may be numbered 3, section 3 is then numbered 4, etc. You can also directly type in such URLs in the address bar of your browser.

This is convenient if the edit does not involve other sections and one needs not have the text of other sections at hand during the edit (or if one needs it, open the section edit link in a new window, or during section editing, open the main page in a different window). Section editing alleviates some problems of large pages.

"__NOEDITSECTION__" anywhere on the page will remove the edit links. It will not disable section editing itself; right clicking on the section heading and the url still work.

Inserting a section can be done by editing either the section before or after it, merging with the previous section by deleting the heading. Note that in these cases the preloaded section name in the edit summary is not correct, and has to be changed or deleted.

Adding a section at the end

Adding a section at the end can also be done with a URL like http://meta.wikimedia.org/w/wiki.phtml?title=Meta:Sandbox&action=edit&section=new . On talk pages and pages with in the wikitext the code __NEWSECTIONLINK__ a special link labeled with the Template:Msg, e.g. "+" or "Post a new comment", is provided for this. In this case, a text box having as title the Template:Msg, e.g. "Subject/headline", will appear and the content you type in it will become the section heading. There is no inputbox for the edit summary, it is automatically created according to the pattern of Template:Msg, where "/* $1 */" represents a right arrow linking to the new section and, with CSS-class "autocomment", the name of the section followed by " - ". In the case of the default of message newsectionsummary this is followed by the text "new section". The user cannot provide more text for the edit summary than just the header itself (use the method mentioned earlier if that is desired).

Parameter "preloadtitle" provides initial content of the "Subject/headline" box, e.g.:

http://meta.wikimedia.org/w/wiki.phtml?title=Meta:Sandbox&action=edit&section=new&preloadtitle=pqr

It can be edited before saving.

See also linking in an edit summary to a section, and "Post a comment" feature.

Subsections

Subsections are included in the part of the section that is edited. Section numbering is relative to the part that is edited, so on the relative top level there is always just number 1, relative subsections all have numbers starting with 1: 1.1., 1.2, etc.; e.g., when editing subsection 3.2, sub-subsection 3.2.4 is numbered 1.4. However, the heading format is according to the absolute level.

Editing a page with large sections

If a page has very large sections, or is very large and has no division into sections, and one's browser or connection does not allow editing of such a large section, then one can still:

  • append a section by specifying a large section number (too large does not matter); however, one has to start with a blank line before the new section heading
  • append content to the last section by not starting with a section heading; however, with the limitations of one's browser or connection, one cannot revert this, or edit one's new text.

If one can view the wikitext of a large section, one can divide the page into smaller sections by step by step appending one, and finally deleting the original content (this can be done one large section at a time). Thus temporarily there is partial duplication of the content, so it is useful to put an explanation in the edit summary.

Sections within parser functions

When conditionally (using a parser function) transcluding a template with sections, edit links of this and subsequent sections will edit the wrong section or give the error mesage that the section does not exist (although the page (including TOC) is correctly displayed and the TOC links correctly). This is because for the targets of the edit links the content of conditionally included templates is considered part of the page itself, and the sections are counted after expansion.

Thus the edit links of the sections of the included template link to the page itself instead of the template, and the edit links after the included template link to the correct page but the wrong section number.

More generally conditional sections give such a complication.

The problem does not occur when transcluding a template with a conditional name (which has more advantages). Use >Template:void (backlinks, edit) for the template to transclude to produce nothing.

Editing a footnote

To edit a footnote rendered in a section containing the code <references />, edit the entire page as the "References" section will not display the reference which is located in another section on the page.

Sections vs. separate pages vs. transclusion

Advantages of separate pages:

  • What links here feature
  • separate edit histories
  • some template limits apply per page
  • automatic redirect on renaming
  • loading a small page is faster than loading a large page
  • can separately be put in categories (however, see also below)

Advantages of one large page with sections:

  • loading one large page is faster and more convenient than loading several small ones
  • searching within one large page (the page itself or the wikitext) with a local search function is faster and in some respects better than searching several pages (for which one has to search the whole project); also the TOC provides for convenient navigation.
  • enforces the cohesion of a concept that while having several definitions needs independent editing.

An alternative is composing a page of other pages using the template feature (creating a compound document by Transclusion). This allows easy searching within the combined rendered page, but not in the combined wikitext. As a disadvantage, a title for each page has to be provided. For the pre-expand include size limit this is disadvantageous even compared with one large page: the pre-expand include size is the sum of the pre-expand include sizes of the components plus the sum of sizes of the wikitexts of the components.

See also

Templates: