User:MinorProphet/Draft subpages/man convert

1. To arrive at a consensus for a standard, meaningful, and consistent nomenclature for the {{tl|Convert}} template and its documentation.
2. To apply the nomenclature in a uniform style to a proposed manual, perhaps similar in style to:

::* [http://man7.org/linux/man-pages/man1/ls.1.html man ls] or

::* the DIR command from [http://www.icpamerica.com/mcsi1/support/rdosman62.pdf RDOS manual], p. 100 [pdf. 110]

or other similar approach suitable for adapting to {{tl|convert}}.

Having leaped in at the deep end by attempting to order the tables at Template:Convert/list of units, I have come to realise that the {{tl|convert }} template is an unusually complex 1337 undertaking. I feel it could benefit greatly from a complete and inclusive manual along the lines of nixen man pages or the old MS-DOS 6.22 printed manual. I haven't really come across this idea in practice on WP or other MW operations. I have no axe to grind, as they say: absolutely no criticism is implied of anything or anyone. I may be trying to re-invent the wheel, or missing something vital on the road to Epic Fail. The talk page is open for comments.

I have a foolish(?) vision of a first-time user being able to use the template and the get the correct desired result first time, by working through a decent manual in which every unnamed and named parameter is comprehensively treated in full, with all the defaults and exceptions and mutually exclusive options/parameters/values/ and work-arounds and kludges explained and/or mouse-overed etc.

For example, every option could be arranged (in the order they occur as you fill/construct the template) in its own collapsed section, something like this empty demo:

:Input options

::Conversion-value {{convert|2|

:::Multiple conversion-values

:::Range-separators - by/x/to - formatted like List of Units {{convert|2|x|3|

::Input unit-code, {{convert|2|x|3|kg involving:

:::List of units

::::unit-names

::::unit-symbols, etc.

:::Explanation of meaning of each column in List of Units

::Output unit-codes {{convert|2|x|3|kg|lb

:::Multiple combination outputs etc. {{convert|2|x|3|kg|lb

::Rounding-value {{convert|2|x|3|kg|lb|3

::: |sigfig=, |round= {{convert|2|x|3|kg|lb|sigfig=3

:Output options

::Explanation of left and right-hand sides of output, etc and all their wild combos.

::abbr=

:::|abbr=out|in/on/off {{convert|2|x|3|kg|lb|sigfig=3|abbr=off

:::|abbr=out (default)

:::|abbr=in

:::|abbr=on

:::|abbr=off

::adj=

:::|adj=in/out/shake_it_all_about

::disp=

::etc.

Mock-up of General outline of manual, based on the above list, cobbled together in under 2 minutes

I can't be alone in feeling that much of the template documentation on WP is frustratingly incomplete, having been perhaps written by and for the pizza-and-jolt-cola types who coded it in the first place. Pwnd. I have some experience in writing instructions user manuals, which is a different skill to coding.

In creating this page, I was partly prompted by the somewhat incomplete examples at Template:Convert. Although certainly helpful, I think that the page often only hints at the relatively complex task that awaits the unsuspecting standard user/WP editor (like me), with sub-standard logic or mathematical abilities. Sometimes section headings are hardly addressed in the examples, eg Rounding. On the other hand, I find the Help:Convert messages much more at useful explaining the specific problems involved.

There are four stages to using the {{convert}} template:

1. Decide on the value for conversion, and the units you want to convert from and to (given in column 2), and start filling in the template (input) with the relevant 'unit-codes' from column 3. These are the 'unnamed parameters', with the last unnamed parameter being the number for rounding/precision (if required).
2. Decide how you want the results to be presented (output). The default output uses a mixture of full 'unit names' and 'unit-symbols' by adding various 'named parameters' such as |abbr= (also called 'display options', or simply 'options'). Click 'Show preview'.
3. Convert then calculates the measurements from one unit to the other.
4. Last, the template dynamically presents the results (output), depending on parameters (or 'display options') such as |abbr=

NB: This is just ASCII art in a table, my technical ability stops not far from here. The terms like 'unnamed parameter' need changing, but this gives a general at-a-glance outline of what is needed.

Every unit-code has a default unit to convert to: see column 6. Litres convert by default to → imperial gallons, kilometres → miles, grams → ounces, etc. You can leave out the third unnamed parameter if you only want the default conversion.

::::NB! Column 6 shows the two units as standard written abbreviations, thus: {{convert|1.0|kg|lb|abbr=on|lk=on}}.

::::However, only the unit-codes in column 3 can/must be used as unnamed parameters.

The {{convert}} template deals with and converts between units of measurement. However, it's best not to think too much about the word 'unit' by itself, since the term is used in three very specific ways within the documentation: 'unit-code', 'unit name', and 'unit-symbol', described below. The term 'parameter' is also frequently used, in terms such as 'unnamed parameter' and 'named parameter' (sometimes called 'option').

At least two 'unnamed parameters' are essential: 'named parameters' are optional, and alter the displayed result.

Convert normally uses British spelling for the 'unit names' (metre, kilometre). The notes in column 5 show the alternative U.S. spelling (meter, kilometer), which is enabled by using the |sp=us parameter/option.

Maybe there is no advantage to this whole idea, it could be unworkable for various reason I have failed to grasp.

You got this far. This section hopes to arrive at a naming scheme. It's far from complete.

Divided into two main sections, unnamed and named parameters, with each parameter/option/etc. fully documented for each.

==='Unnamed parameters' (or 'initial arguments' or 'input options' or something)===

• 'Input-value' (or 'number to be converted') (required). (e.g. {{convert|2.71)
• 'Input unit-code' (required). The whole template (I think) is structured around the use of unit-codes. These are the basis of the master tables which are processed by a script to make the conversions. The unit-codes are shown in column 3.
  There must be at least one unit-code (the input, or l-h side unit-code).
• (optional) 'value separators' like +, -, by,
• 'Output unit-code' (optional). A typical conversion uses two unit-codes (input & output). If more than two output unit-codes are specified, do not use a separator between them.
• 'Rounding-value'. (optional). This is a whole number which

• Every unit-code can be expressed in the displayed result (the output) either in words (the 'unit-name') or by an abbreviation ('unit-symbol').

This should have comprehensive subsections dealing with each column and what it means, and how the info in each column can be used to customise the output. I found that understanding the meaning of each column in the List of units was very helpful for a beginner, and how the unit-codes in each section in the Master doc are the basis (I think) of the whole template.

• System
• 'unit-code', listed in column 3.
• 'unit-name'. The units to convert from and to are listed in column 2 of the following tables.
• 'unit-symbol'. (column 4) Abbreviations for output instead of full unit names
• Notes - Different types of alternative unit-codes:
• micro-things with μ, degrees ° CKF, and Ångstrom.
• US-specific things, requiring |sp=us
• Default conversion units for each unit-code
• Multiple output combos

;Input - unnamed params

• 'unit-code' (column 3)

The {{tl|convert}} template uses unit-codes, which are similar to (but not necessarily exactly the same as) the usual written abbreviation for a given unit. These 'unit-codes' are given in column 3 of the following tables, and are accepted as input by the {{tl|convert}} template as the second and third unnamed parameters.

;Output - named params

The units in the displayed result can be shown either in full (the 'unit name' given in column 2)

or abbreviated (the 'unit-symbol' given in column 4)

NB Some duplication here...

;Unnamed parameters

• unit-code for the unit to be converted from{{spaces|3}} = left-hand side = input parameter = 2nd unnamed parameter
• unit-code(s) for the unit(s) to be converted to = right-hand side = output parameter(s) = 3rd, 4th etc. unnamed parameter
• 'unit name' (column 2)
• 'unit-symbol' (column 4)
• rounding-value = last named parameter

The number to be converted. Can be expressed in:

• Scientific notation
• Engineering notation
• Fractions, with //

And how they relate to the unit names and unit-symbols

Discusses the table and possible improvements

; + and - ("range separators"?)

I may be wrong, but I don't think that the list of Value range separators works in the same way as the Units list (possibly because it's not generated from a machine-readable source like Module:Convert/documentation/conversion data/doc?) I feel it could do with some re-jigging, to have similar/same columns as the Unit tables.

;Rounding factor

If the number is:

• negative, rounds to the nearest 10/100/1000
• 0, rounds to the nearest 1 ???
• positive, rounds to that number of significant digits (here be dragons!)

;For non-mathematicians:

If the result has unwanted trailing zeroes, eg 12.34500, reduce the "rounding value" by that number of trailing zeroes:

• {{#invoke:DemoTemplate|convert|1.02875|ft|in|5}}
• {{#invoke:DemoTemplate|convert|1.02875|ft|in|3}}

Default: Uses the same precision as the conversion value (param 1). If no rounding value (or last unnamed parameter) is given, {{tl|convert}} uses

• No value: outputs some random value, vaguely related to the actual number.
• If the value is a whole number, xxx?
• If the value has decimal places, then xxx? (The output uses the number of decimal places, including all trailing zeroes if the number of sig figs is greater than the exact number of decimal places with no trailing zeros - or something???)
• To display a specific number of significant figures, use |sigfig=

The table below is an adaptation of the table at Significant figures#Rounding and decimal places, which I found very useful in trying to understand the difference. It uses a random value of 12.345, which is exactly 12 x 1.02875 inches: thus the trivial use of ft-in in convert.

I used {{tl|convert}} to make the conversions to output the values in the table. But there's a difference (in one cell) between the original table and the ouput result of {{tl|convert}}. Why? Is it a mistake, or does it highlight the differences between the two level of precision that convert uses?

• Default:

: {{#invoke:DemoTemplate|convert|1.02875|ft|in}}

• display 5 decimal places, including all trailing zeroes:

: {{#invoke:DemoTemplate|convert|1.02875|ft|in|5}}

• display 5 significant figures:

: {{#invoke:DemoTemplate|convert|1.02875|ft|in|sigfig=5}}

• Proposed re-arrangement of the Range table to make it look and work just like the Unit tables - I don't think it does at the moment.
• + - as unnamed parameters
• ±Arguments/options/values/parameters
• Confirm exactly how rounding works...
• Last unnamed parameter = Rounding: "round number" should be "rounding number" or "number to round by" etc.
• etc.
• etc.

NB The rest of this page is just rough stuff with DemoTemplate examples.

This has been transcluded (I hope) from Template:Convert/list of units.

{{Template:Convert/list of units}}

The hat letter, or Why some ideas fail to make it into the out tray. I remember reading something like this a very long time ago, in a book by someone like James Thurber or Stephen Leacock or Leo Rosten. Re-constructed from memory, with a few extra invented phrases. Anyone recognise it, or something like?

:Messrs. Sue, Grabbitt & Runne,

:127 Lincoln's Inn,

:London WC2

:Date as postmark

:Dear Sirs,

:re: {{color|red|Final Demand for Payment}}, your ref. 192/1828/4B-673

:Thank you for your letter of the 2nd inst.

:You are evidently unaware of the method we use for paying our bills.

:At the end of every month we receive a statement from our bank, telling us how much money we have. We then write the names of each of our creditors and the amount due them on a slip of paper, and place all the slips in a hat. Next - averting our gaze in order to encourage an expectant sense of the random - we pull one slip at a time out of the hat, write out a cheque for the full amount to the creditor, seal it in a stamped addressed envelope and put in the letter tray. We continue to repeat this simple exercise until there is no more money left. At the end of the following month, we write the names of our remaining creditors on slips of paper … and so it goes.

:We therefore beg to inform you that if you persist in sending us any further letters, your name will not even go in the damn hat.

:Faithfully yours,

:pp Acme Manual Co., Inc.