Difference between revisions of "Template:A or b/Documentation"

From GodWiki
Jump to: navigation, search
m (Djonni moved page Template:M-or-f/Documentation to Template:A or b/Documentation: As per talk page discussion)
m (Update docs with new default behaviour of |daily=yes and new template names, generalise wording beyond just gender in text.)
Line 1: Line 1:
The {{tl|m-or-f}} function implements logic to decide ''randomly'' but ''consistently'' on a gender to use in text on the GodWiki. It is here for the use of any creator who wishes to allow the [[Great Random]] to decide on whether the text should be about a ''{{m-or-f|male=him|female=her}}'' or a ''{{m-or-f|male=him|female=her|invert=y}}''.
+
The {{tl|a or b}} function implements logic to decide ''randomly'' but ''consistently'' on a word or phrase to use in text on the GodWiki. It is here for the use of any creator who wishes to allow the [[Great Random]] to decide what something in their text should be. The most common use case is to switch an article daily between being about a ''{{him or her}}'' or about a ''{{him or her|invert=y}}''.
  
It can be called directly, but is most likely to be called by one of the more user-friendly wrapper functions below. You are reading this documentation on {{tlf|{{BASEPAGENAME}}}}; for just the parameters relevant to the wrapper functions, skip to the section on the [[#User-friendly wrappers|user-friendly wrapper functions]] below.
+
It can be called directly, but is most likely to be called by one of the more user-friendly wrapper templates below. You are reading this documentation on {{tlf|{{BASEPAGENAME}}}}; for just the parameters relevant to the wrapper templates, skip to the section on the [[#User-friendly wrappers|user-friendly wrapper templates]] below.
  
 
==Parameters==
 
==Parameters==
  
;{{para|male|<var>male-gendered text</var>}}
+
;{{para|a|<var>option a</var>}} or {{para|1|<var>option a</var>}}
:'''''Required'''''. This parameter contains the text to return if the template decides to male-focus the text. E.g. <code>him</code>
+
:'''''Required'''''. This parameter contains the text to return if the template decides to choose option ''a''. E.g. {{para|a|him}}
  
;{{para|female|<var>female-gendered text</var>}}
+
;{{para|b|<var>option b</var>}} or {{para|2|<var>option b</var>}}
:'''''Required'''''. This parameter contains the text to return if the template decides to female-focus the text. E.g. <code>her</code>
+
:'''''Required'''''. This parameter contains the text to return if the template decides to choose option ''b''. E.g. {{para|b|her}}
  
 
;{{para|or|<var>anything</var>}}
 
;{{para|or|<var>anything</var>}}
:''Optional''. This parameter instructs the template to return both parts conjoined by ''or''. As in, "she or he will get a surprise".
+
:''Optional''. This parameter instructs the template to return both parts conjoined by ''or''. As in, "{{he or she|or=1}} will get a surprise".
  
 
;{{para|lcase|<var>anything</var>}}
 
;{{para|lcase|<var>anything</var>}}
:''Optional''. This parameter instructs the template to lowercase the first letter of the second term in an ''or'' conjunction. Use it only if giving the template uppercase <var>He</var> and <var>She</var> text, with {{para|or|yes}}. As in, "She or he will get a surprise". Omit this if you explicitly want a capital letter in your second term, as in, "Gods or Goddesses are welcome in this guild!"
+
:''Optional''. This parameter instructs the template to lowercase the first letter of the second term in an ''or'' conjunction. Use it only if giving the template uppercase <var>Option A</var> and <var>Option B</var> text, with {{para|or|yes}}. As in, "{{He or She|or=1}} will get a surprise". Omit this if you explicitly want a capital letter in your second term, as in, "{{a or b|a=Gods|b=Goddesses|or=1}} are welcome in this guild!"
 +
 
 +
;{{para|daily|<var>yes</var> or <var>no</var>}} or {{para|d|<var>yes</var> or <var>no</var>}}
 +
:''Optional'', defaults to <code>yes</code>. This parameter instructs the template to switch the options in the text each day. Note that, depending on when the page was last cached, you may not always see the change immediately (without purging or editing the page).
 +
 
 +
;{{para|invert|<var>anything</var>}} or {{para|i|<var>anything</var>}}
 +
:''Optional''. This parameter reverses the usual order of the result. If option a is usually being selected for the page, you will get option b, and vice versa. Allows sensible construction of sentences like: <code><nowiki>{{She or He}} kissed {{him or her|i=1}}.</nowiki></code> ("{{She or He}} kissed {{him or her|i=1}}.")
 +
 
 +
Note that the text given to {{tlx|a or b}} doesn't have to be male or female gendered text. For example:
  
;{{para|daily|<var>anything</var>}}
+
{{pre|<nowiki>{{a or b|a=He|b=She}} passed {{a or b|a=her|b=him}} the {{a or b|a=salt|b=pepper}}.</nowiki>}}
:''Optional''. This parameter instructs the template to switch the gender-focus of the text each day. Note that, depending on when the page was last cached, you may not always see the change without purging or editing the page.
 
  
;{{para|invert|<var>anything</var>}}
+
will give you:
:''Optional''. This parameter reverses the usual order of the result. If the male-focussed language is being selected for the page, you will get the female-focussed language with this option, and vice versa.
 
  
Note that the text passed to {{para|male}} and {{para|female}} doesn't ''have'' to be male or female gendered text. If you switch them around, you'll get the inverted result just like using {{para|invert}}. For example:
+
{{pre|{{a or b|a=He|b=She}} passed {{a or b|a=her|b=him}} the {{a or b|a=salt|b=pepper}}.}}
  
{{pre|<nowiki>{{m-or-f|male=he|female=she}} passed {{m-or-f|male=her|female=him}} the salt</nowiki>}}
+
or
  
will give you <code>he passed her the salt</code> or <code>she passed him the salt</code>.
+
{{pre|{{a or b|a=He|b=She|i=1}} passed {{a or b|a=her|b=him|i=1}} the {{a or b|a=salt|b=pepper|i=1}}.}}
  
Furthermore, there's really no reason why the parameters need to be gendered text. The function will happily accept <code><nowiki>{{m-or-f|male=arm|female=leg|daily=yes}}</nowiki></code>, and your story can change each day whether the protagonist got {{m-or-f|male=his|female=her|daily=1|or=1}} {{m-or-f|male=arm|female=leg|daily=yes|or=1}} chopped off.
+
and switch between them daily.
  
 
==User-friendly wrappers==
 
==User-friendly wrappers==
Line 42: Line 48:
 
|-
 
|-
 
! Subject
 
! Subject
| {{tl|He-or-She}}
+
| {{tl|He or She}}
| {{tl|he-or-she}}
+
| {{tl|he or she}}
 
|-
 
|-
 
! Object
 
! Object
| {{tl|Him-or-Her}}
+
| {{tl|Him or Her}}
| {{tl|him-or-her}}
+
| {{tl|him or her}}
 
|-
 
|-
 
! Possessive
 
! Possessive
| {{tl|His-or-Hers}}
+
| {{tl|His or Hers}}
| {{tl|his-or-hers}}
+
| {{tl|his or hers}}
 
|-
 
|-
 
! Adjective
 
! Adjective
| {{tl|His-or-Her}}
+
| {{tl|His or Her}}
| {{tl|his-or-her}}
+
| {{tl|his or her}}
 
|}
 
|}
  
Line 63: Line 69:
 
! lowercase
 
! lowercase
 
|-
 
|-
| {{tl|Hero-or-Heroine}}
+
| {{tl|Hero or Heroine}}
| {{tl|hero-or-heroine}}
+
| {{tl|hero or heroine}}
 
|-
 
|-
| {{tl|Heroes-or-Heroines}}
+
| {{tl|Heroes or Heroines}}
| {{tl|heroes-or-heroines}}
+
| {{tl|heroes or heroines}}
 
|}
 
|}
 +
 +
Note that every one of the above functions exists as a hyphenated name as well (as in, {{tlx|he or she}} is exactly the same as {{tlx|he-or-she}}. Use whichever you like.
  
 
All of these wrappers take these parameters as required:
 
All of these wrappers take these parameters as required:
Line 75: Line 83:
 
:''Optional''. This parameter instructs the template to return both parts conjoined by ''or''. As in, "she or he will get a surprise".
 
:''Optional''. This parameter instructs the template to return both parts conjoined by ''or''. As in, "she or he will get a surprise".
  
;{{para|daily|<var>anything</var>}}
+
;{{para|daily|<var>yes</var> or <var>no</var>}} or {{para|d|<var>yes</var> or <var>no</var>}}
:''Optional''. This parameter instructs the template to switch the gender-focus of the text each day. Note that, depending on when the page was last cached, you may not always see the change without purging or editing the page.
+
:''Optional''. This parameter instructs the template to switch the gender-focus of the text each day. Note that, depending on when the page was last cached, you may not always see the change immediately (without purging or editing the page).
  
;{{para|invert|<var>anything</var>}}
+
;{{para|invert|<var>anything</var>}} or {{para|i|<var>anything</var>}}
 
:''Optional''. This parameter reverses the usual order of the result. If the male-focussed language is being selected for the page, you will get the female-focussed language with this option, and vice versa. Use this to build sensible sentences. For example:
 
:''Optional''. This parameter reverses the usual order of the result. If the male-focussed language is being selected for the page, you will get the female-focussed language with this option, and vice versa. Use this to build sensible sentences. For example:
  
{{pre|<nowiki>{{He-or-She}} held {{his-or-her|invert=yes}} hand in the moonlight.</nowiki>}}
+
{{pre|<nowiki>{{He or She}} held {{his or her|invert=yes}} hand in the moonlight.</nowiki>}}
  
 
will result in either:
 
will result in either:
Line 93: Line 101:
 
==Decision Logic==
 
==Decision Logic==
  
The template uses the page's {{tlf|PAGEID}} property to decide, so will always return the same result for the same page. If the {{tlf|PAGEID}} is ''odd'', the male-focussed language is chosen; if it's ''even'', the female-focused. (The page you are reading this on had a {{tlf|PAGEID}} value of {{PAGEID}}.) If the {{para|daily}} parameter is set, the current day of the month ({{CURRENTDAY}}) is added to it before testing if it's odd or even, changing the result almost every day, except for the last day of months with an odd number of days.
+
The template uses the page's {{tlc|PAGEID}} property to decide, plus {{tlc|CURRENTDAY}}. If the sum is '''odd''', the ''option a'' is chosen; if it's '''even''', ''option b''. (The page you are reading this on has a {{tlf|PAGEID}} value of {{PAGEID}}, and the {{tlf|CURRENTDAY}} is {{CURRENTDAY}}.) If the {{para|daily}} parameter is set to ''no'', the current day of the month ({{CURRENTDAY}}) is ''not'' added before testing if it's odd or even, so the result will remain the same every day.
  
When creating a new page, before the page is saved the {{tlf|PAGEID}} is not set. In these cases, the template will use the {{tlf|CURRENTTIMESTAMP}} of the preview, so that it will return consistent results within each preview, but may change each time. If you must know with certainly what the final results will be, save and create the page, and the {{tlf|PAGEID}} value will be generated.
+
When creating a new page, before the page is saved the {{tlf|PAGEID}} is not set. In these cases, the template will use the {{tlf|CURRENTTIMESTAMP}} of the preview, so that it will be consistent within each preview, but may switch with each preview. If you must know with certainly what the final result will be, save and create the page, and the {{tlf|PAGEID}} value will be generated.
 
<noinclude>[[Category:Templates/Documents|{{PAGENAME}}]]</noinclude>
 
<noinclude>[[Category:Templates/Documents|{{PAGENAME}}]]</noinclude>

Revision as of 20:13, 19 December 2018

The {{a or b}} function implements logic to decide randomly but consistently on a word or phrase to use in text on the GodWiki. It is here for the use of any creator who wishes to allow the Great Random to decide what something in their text should be. The most common use case is to switch an article daily between being about a him or about a her.

It can be called directly, but is most likely to be called by one of the more user-friendly wrapper templates below. You are reading this documentation on {{A or b}}; for just the parameters relevant to the wrapper templates, skip to the section on the user-friendly wrapper templates below.

Parameters

|a=option a or |1=option a
Required. This parameter contains the text to return if the template decides to choose option a. E.g. |a=him
|b=option b or |2=option b
Required. This parameter contains the text to return if the template decides to choose option b. E.g. |b=her
|or=anything
Optional. This parameter instructs the template to return both parts conjoined by or. As in, "he or she will get a surprise".
|lcase=anything
Optional. This parameter instructs the template to lowercase the first letter of the second term in an or conjunction. Use it only if giving the template uppercase Option A and Option B text, with |or=yes. As in, "He or she will get a surprise". Omit this if you explicitly want a capital letter in your second term, as in, "Gods or Goddesses are welcome in this guild!"
|daily=yes or no or |d=yes or no
Optional, defaults to yes. This parameter instructs the template to switch the options in the text each day. Note that, depending on when the page was last cached, you may not always see the change immediately (without purging or editing the page).
|invert=anything or |i=anything
Optional. This parameter reverses the usual order of the result. If option a is usually being selected for the page, you will get option b, and vice versa. Allows sensible construction of sentences like: {{She or He}} kissed {{him or her|i=1}}. ("Template:She or He kissed her.")

Note that the text given to {{a or b}} doesn't have to be male or female gendered text. For example:

{{a or b|a=He|b=She}} passed {{a or b|a=her|b=him}} the {{a or b|a=salt|b=pepper}}.

will give you:

He passed her the salt.

or

She passed him the pepper.

and switch between them daily.

User-friendly wrappers

These tables show the wrapper functions for various common uses.

Wrapper functions for pronouns
Pronoun Case Uppercase lowercase
Subject {{He or She}} {{he or she}}
Object {{Him or Her}} {{him or her}}
Possessive {{His or Hers}} {{his or hers}}
Adjective {{His or Her}} {{his or her}}
Wrapper functions for nouns
Uppercase lowercase
{{Hero or Heroine}} {{hero or heroine}}
{{Heroes or Heroines}} {{heroes or heroines}}

Note that every one of the above functions exists as a hyphenated name as well (as in, {{he or she}} is exactly the same as {{he-or-she}}. Use whichever you like.

All of these wrappers take these parameters as required:

|or=anything
Optional. This parameter instructs the template to return both parts conjoined by or. As in, "she or he will get a surprise".
|daily=yes or no or |d=yes or no
Optional. This parameter instructs the template to switch the gender-focus of the text each day. Note that, depending on when the page was last cached, you may not always see the change immediately (without purging or editing the page).
|invert=anything or |i=anything
Optional. This parameter reverses the usual order of the result. If the male-focussed language is being selected for the page, you will get the female-focussed language with this option, and vice versa. Use this to build sensible sentences. For example:
{{He or She}} held {{his or her|invert=yes}} hand in the moonlight.

will result in either:

He held her hand in the moonlight.

or

She held his hand in the moonlight.

Decision Logic

The template uses the page's {{PAGEID}} property to decide, plus {{CURRENTDAY}}. If the sum is odd, the option a is chosen; if it's even, option b. (The page you are reading this on has a {{PAGEID}} value of 12352, and the {{CURRENTDAY}} is 5.) If the |daily= parameter is set to no, the current day of the month (5) is not added before testing if it's odd or even, so the result will remain the same every day.

When creating a new page, before the page is saved the {{PAGEID}} is not set. In these cases, the template will use the {{CURRENTTIMESTAMP}} of the preview, so that it will be consistent within each preview, but may switch with each preview. If you must know with certainly what the final result will be, save and create the page, and the {{PAGEID}} value will be generated.