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 (Shorting and commenting out for debugging)
Line 6: Line 6:
{{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 <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.}}


Consider the following copyable example to be a recommended practice.
{{obr}}'''User:Johan G/Template:Informative template with preloaded text'''{{!}}documentation page {{!}}''content=''{{!}}''link box=''{{cbr}}
<pre style="white-space: pre-wrap;">
<nowiki>&lt;noinclude&gt;</nowiki>
{{Informative template|1=
__NOTOC__
== 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.
; documentation page
: Name of page with documentation
: Defaults to <code><nowiki>{{BASEPAGENAME}}/doc</nowiki></code>


{{icaution|Caution that might help prevent lost work, very complicated debugging etc...}}
; content
: Will allow wiki markup to be used instead of a separate documentation page.


{{inote|Note that might be helpful or lead the reader in the right direction.}}
; link box
: Will add content to the link box at the bottom


== Usage ==
<!--
<!-- Description of how to use the template -->
== Examples ==
{{obr}}'''template'''{{!}}mandatory{{!}}''optional'' {{!}}mandatory= {{!}}''optional=''{{cbr}}


; parameter:  What it does and how to use it.  This parameter is mandatory... ! optional and defaults to...
== Technical details ==
 
; parameter:  ...
 
== Examples ==
<!-- Examples using different options. -->


== Known issues ==
== Known issues ==
<!-- Known issues and workarounds if such are known. -->
== Technical details ==
<!-- 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. -->


== Related templates ==
== Related templates ==
<!-- Other templates in a series of templates and/or templates with similar functionality. -->
* {{tl|informative template}}
* {{tl|example}}
-->
 
}}
 
[[Category:Templates]]
<nowiki>&lt;/noinclude&gt;</nowiki>
</pre>
 
== Documenting the parameters ==
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.
 
=== Pre-filled values ===
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:
 
<nowiki> {{obr}}'''merge'''{{!}}the other page{{!}}''discussion page section'' {{!}}''date={{CURRENTMONTHNAME}} {{CURRENTYEAR}}''{{cbr}}</nowiki>
 
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
}}

Revision as of 16:28, 22 June 2019

This template can be used to document a wiki template and to distinguish the documentation from the actual template.

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|documentation page |content=|link box=}}
documentation page
Name of page with documentation
Defaults to {{BASEPAGENAME}}/doc
content
Will allow wiki markup to be used instead of a separate documentation page.
link box
Will add content to the link box at the bottom


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