User:Johan G/Template:Informative template with preloaded text/doc: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
(Copying parts of http://wiki.flightgear.org/index.php?title=Template:Informative_template&oldid=119156)
 
m (+- Minor cleanup)
 
(7 intermediate revisions by the same user not shown)
Line 1: Line 1:
This template can be used to document a wiki template and to distinguish the documentation from the actual template.
<noinclude>{{userpage draft}}</noinclude>__NOTOC__
This template is used when documenting templates.
 
Optionally the documentation can be put on a separate page, typically a subpage to the template, named <code>/doc</code>.
 
If the template is put on a page without a <code>/doc</code> subpage, or no link is given to a subpage with documentation, clicking a link labeled "Click here to create documentation for this template" will open a skeleton page for template documentation.  


== Usage ==
== Usage ==
The template is used with one variable and must be put between <tt><nowiki>&lt;noinclude&gt;&lt;/noinclude&gt;</nowiki></tt> tags.
The template is used with one variable and must be put between <code><nowiki>&lt;noinclude&gt;&lt;/noinclude&gt;</nowiki></code> tags.


{{inote|Please put the <tt><nowiki>&lt;noinclude&gt;</nowiki></tt> tag right behind the intended contents of the template, as an empty line or extra spaces will alter the way the template is rendered.}}
{{inote|Please put the <code><nowiki>&lt;noinclude&gt;</nowiki></code> tag right behind the intended contents of the template, as an empty line or extra spaces will alter the way the template is rendered.}}


Consider the following copyable example to be a recommended practice.
{{obr}}'''User:Johan G/Template:Informative template with preloaded text'''
<pre style="white-space: pre-wrap;">
{{!}} ''1''=
<nowiki>&lt;noinclude&gt;</nowiki>
{{!}} ''doc=''
{{Informative template|1=
{{!}} ''link box=''
__NOTOC__
{{cbr}}
== Goal ==
<!-- Short description of the purpose of the template, any automatic categorization and if there is things to consider when using or maintaining the template -->
This template can be used to...


Adding this template to a page will automatically add <nowiki>[[:Category:...]]</nowiki> to that page.
If documentation is the same page as the template '''1''' is mandatory. Otherwise all parameters are optional.


{{icaution|Caution that might help prevent lost work, very complicated debugging etc...}}
: For some content the text in '''1''' and '''link box''' must start on a new line (see examples below). Some formatting will otherwise fail.


{{inote|Note that might be helpful or lead the reader in the right direction.}}
; 1
: Will allow wiki markup to be used above or instead of a separate documentation page.


== Usage ==
; doc
<!-- Description of how to use the template -->
: Name of page with documentation
{{obr}}'''template'''{{!}}mandatory{{!}}''optional'' {{!}}mandatory= {{!}}''optional=''{{cbr}}
: If '''content''' is empty '''doc''' will default to <code><nowiki>{{FULLPAGENAME}}/doc</nowiki></code>


; parameter: What it does and how to use it.  This parameter is mandatory... ! optional and defaults to...
; link box
 
: Will add content to the link box at the bottom
; parameter:  ...


== Examples ==
== Examples ==
<!-- Examples using different options. -->
{{obr}}User:Johan G/Template:Informative template with preloaded text{{cbr}}
{{User:Johan G/Template:Informative template with preloaded text}}


== Known issues ==
{{obr}}User:Johan G/Template:Informative template with preloaded text
<!-- Known issues and workarounds if such are known. -->
  {{!}} 1=
 
  Test
== Technical details ==
{{cbr}}
<!-- Details that may help a template user or template maintainer later. This could for example be if the template uses PHP dates or is depending on other templates. -->
{{User:Johan G/Template:Informative template with preloaded text
 
| 1=
== Related templates ==
Test
<!-- Other templates in a series of templates and/or templates with similar functionality. -->
}}
* {{tl|example}}


{{obr}}User:Johan G/Template:Informative template with preloaded text
{{!}} 1=
Test
{{!}} link box=Test text{{cbr}}
{{User:Johan G/Template:Informative template with preloaded text
| 1=
Test
| link box=
Test text
}}
}}


[[Category:Templates]]
{{obr}}User:Johan G/Template:Informative template with preloaded text {{!}}doc=User:Johan G/Template:Informative template with preloaded text/doc{{cbr}}
<nowiki>&lt;/noinclude&gt;</nowiki>
{{User:Johan G/Template:Informative template with preloaded text |doc= User:Johan G/Template:Informative template with preloaded text/doc}}
</pre>


== Documenting the parameters ==
== Technical details ==
Try to list the parameters primarily beginning with mandatory then optional unnamed parameters then mandatory and optional named parameters and secondarily in the order they appear in the transcluded template when used.
When creating a template with the "Create documentation" link, the new page is preloaded from [[User:Johan G/Template:Informative template with preloaded text/preload text]].


=== Pre-filled values ===
== Known issues ==
Parameters with values that can easily be added automatically, like for example <tt>date={{CURRENTMONTHNAME}} {{CURRENTYEAR}}</tt>, could be added to the parameter in the list of parameters, like:
This template is still under development.


<nowiki> {{obr}}'''merge'''{{!}}the other page{{!}}''discussion page section'' {{!}}''date={{CURRENTMONTHNAME}} {{CURRENTYEAR}}''{{cbr}}</nowiki>
== Related templates ==
 
* {{tl|informative template}}
This will show as the easy copyable
{{obr}}'''merge'''{{!}}the other page{{!}}''discussion page section'' {{!}}''date={{CURRENTMONTHNAME}} {{CURRENTYEAR}}''{{cbr}}
 
=== Listing the parameters vertically ===
If there are many parameters, it might be a good idea to not only show them horizontally, but also vertically.  Sometimes when there is a lot of parameters, for example in infobox templates, showing only a vertical listing of parameters like below is preferred.
 
When listing parameters vertically it often is preferable to have the values aligned with each other, as that makes it easier to read and edit the source for the page it is used on.  Note the space character after the equal signs when marking the text for copying.  Those might help when reading the template wiki text and template documentation.
 
{{obr}}'''template'''
{{!}} mandatory
{{!}} ''optional''
{{!}} mandatory =  
{{!}} mandatory =  
{{!}} ''optional''  =
{{!}} ''optional''  =
{{cbr}}
 
To simplify making a list like the above one, copy the below wiki text and start from there.
 
<nowiki> {{obr}}'''template'''
{{!}} mandatory
{{!}} ''optional''
{{!}} mandatory =
{{!}} mandatory =
{{!}} ''optional''  =
{{!}} ''optional''  =
{{cbr}}</nowiki>
 
== Recommended sections ==
Please use at least the following sections:
* Goal
* Usage
 
And when applicable also use:
* Parameters subsection in the Usage section (Often not needed if there are only one or two parameters.)
* Examples
* Known issues
* Technical details
* Related templates
}}

Latest revision as of 13:39, 25 June 2019

This is a draft on a userpage.

Please suggest changes to this draft on the discussion page.

This template is used when documenting templates.

Optionally the documentation can be put on a separate page, typically a subpage to the template, named /doc.

If the template is put on a page without a /doc subpage, or no link is given to a subpage with documentation, clicking a link labeled "Click here to create documentation for this template" will open a skeleton page for template documentation.

Usage

The template is used with one variable and must be put between <noinclude></noinclude> tags.

Note Please put the <noinclude> tag right behind the intended contents of the template, as an empty line or extra spaces will alter the way the template is rendered. 

{{User:Johan G/Template:Informative template with preloaded text
| 1=
| doc=
| link box=
}}

If documentation is the same page as the template 1 is mandatory. Otherwise all parameters are optional.

For some content the text in 1 and link box must start on a new line (see examples below). Some formatting will otherwise fail.
1
Will allow wiki markup to be used above or instead of a separate documentation page.
doc
Name of page with documentation
If content is empty doc will default to {{FULLPAGENAME}}/doc
link box
Will add content to the link box at the bottom

Examples

{{User:Johan G/Template:Informative template with preloaded text}}


The following template description is not displayed when the template is inserted in an article.

1

Click here to create documentation for this template.

2 

{{User:Johan G/Template:Informative template with preloaded text
  | 1=
Test
}}


The following template description is not displayed when the template is inserted in an article.

1

Template documentation34

Test User:Johan G/Template:Informative template with preloaded text/doc/doc

The above documentation is transcluded from User:Johan G/Template:Informative template with preloaded text/doc/doc. (Edit | History)562 

{{User:Johan G/Template:Informative template with preloaded text
| 1=
Test
| link box=Test text}}


The following template description is not displayed when the template is inserted in an article.
1

Template documentation34

Test User:Johan G/Template:Informative template with preloaded text/doc/doc

The above documentation is transcluded from User:Johan G/Template:Informative template with preloaded text/doc/doc. (Edit | History)5
Test text62 

{{User:Johan G/Template:Informative template with preloaded text |doc=User:Johan G/Template:Informative template with preloaded text/doc}}


The following template description is not displayed when the template is inserted in an article.
1

Template documentation3 [ [User:Johan G/Template:Informative template with preloaded text/doc View] ] [ [User:Johan G/Template:Informative template with preloaded text/doc Edit] ] [ [User:Johan G/Template:Informative template with preloaded text/doc History] ] [ [User:Johan G/Template:Informative template with preloaded text/doc Purge] ] 4


This template is used when documenting templates.

Optionally the documentation can be put on a separate page, typically a subpage to the template, named /doc.

If the template is put on a page without a /doc subpage, or no link is given to a subpage with documentation, clicking a link labeled "Click here to create documentation for this template" will open a skeleton page for template documentation.

Usage

The template is used with one variable and must be put between <noinclude></noinclude> tags.

Note Please put the <noinclude> tag right behind the intended contents of the template, as an empty line or extra spaces will alter the way the template is rendered. 

{{User:Johan G/Template:Informative template with preloaded text
| 1=
| doc=
| link box=
}}

If documentation is the same page as the template 1 is mandatory. Otherwise all parameters are optional.

For some content the text in 1 and link box must start on a new line (see examples below). Some formatting will otherwise fail.
1
Will allow wiki markup to be used above or instead of a separate documentation page.
doc
Name of page with documentation
If content is empty doc will default to {{FULLPAGENAME}}/doc
link box
Will add content to the link box at the bottom

Examples

{{User:Johan G/Template:Informative template with preloaded text}}

Template loop detected: User:Johan G/Template:Informative template with preloaded text 

{{User:Johan G/Template:Informative template with preloaded text
  | 1=
Test
}}

Template loop detected: User:Johan G/Template:Informative template with preloaded text 

{{User:Johan G/Template:Informative template with preloaded text
| 1=
Test
| link box=Test text}}

Template loop detected: User:Johan G/Template:Informative template with preloaded text 

{{User:Johan G/Template:Informative template with preloaded text |doc=User:Johan G/Template:Informative template with preloaded text/doc}}

Template loop detected: User:Johan G/Template:Informative template with preloaded text

Technical details

When creating a template with the "Create documentation" link, the new page is preloaded from User:Johan G/Template:Informative template with preloaded text/preload text.

Known issues

This template is still under development.

Related templates

The above documentation is transcluded from User:Johan G/Template:Informative template with preloaded text/doc. ([User:Johan G/Template:Informative template with preloaded text/doc Edit] | [User:Johan G/Template:Informative template with preloaded text/doc History])562

Technical details

When creating a template with the "Create documentation" link, the new page is preloaded from User:Johan G/Template:Informative template with preloaded text/preload text.

Known issues

This template is still under development.

Related templates

Retrieved from "https://wiki.flightgear.org/w/index.php?title=User:Johan_G/Template:Informative_template_with_preloaded_text/doc&oldid=119193"