Module talk:Val/units

Documentation

I thought I had understood the format of entries. Now I have questions:

1) In the Chemistry section, why are these entries "invalid definition" ?

 uM  [[Molarity|µM]]  SI
 uM    µM    Molarity  SI

2) For these entries in Electromagnetism:

 N.A-2   N⋅A<sup>−2</sup>   Permeability 
 YC      C       Coulomb                            SI

How is it that when the second field is markup, it is displayed,

{{val|1|ul=N.A-2}} → 1 N⋅A⁻²

but when the SI marker is used the first field is displayed, not the second field?

{{val|1|ul=YC}} → 1 YC

— CpiralCpiral 01:22, 15 August 2015 (UTC)

I added the extra "SI flag" documentation below to clarify what's going on. The "invalid definition" is because the symbol column is actually the base unit when "SI" is used. I think the following should provide the answers; please ask again if more wanted. The conclusion is that if markup is wanted for the symbol, the SI flag should not be used—instead, the definition must provide the correct symbol and scale. Johnuniq (talk) 03:31, 15 August 2015 (UTC)

Got it. Documented it. Catching up to your way of thinking, but I do have a question about sorting.

What's the easiest way to tell for sure if Convert sorts a Val unit? None. But at Module:Val/units#Testing a new unit the table functions to "fall into place" out of order. Crude but very effective. As far as I know it's the easiest way to tell about sorting: a "trial and error" technique. Takes under a minute with a slow connection.

Got a better way to tell if Convert handles a unit? Although Template:Convert#Units and Template:Val/unitsfromconvert listings are useful for many other things, they themselves say they are not complete, and this makes them useless for deciding definitively about whether or not to add sorting here. That Convert may handle the sorting for certain units does not seem to help the documentation, although it is necessary in the wikitext above those certain units, in order to keep editors from "helping" in that way.

The alternative to documenting the "cut-and-paste trial-and-error crude-but-effective" way seems to be to go backwards, to get Val/units out of to much or so much user-config-file business. It seems to me that the Val/units page either handles the addition of sorting maintenance and its documentation well, or it goes back to the way it was before, where sorting was not handled by users, but transparently, by Jimp and a few others "in the know". It goes against my grain to think we'd have to revert to , but then I haven't studied sorting or Module Val very much, and I haven't seen users step up very often and start taking on Val/units tasks for themselves. So maybe I would agree to get out of the sorting business.

— CpiralCpiral 00:23, 17 August 2015 (UTC)

When I rewrote Module:Val I did a lot of checking on a local computer, including comparing the exact output produced by the old template from Special:ExpandTemplates with the exact output produced by the module for about 3000 examples. That showed many minor problems with the old system. One example of a significant problem is that the SI prefixes f, a, z, y were not handled so the old system regarded 2 fm as larger than 1 m. In practice, that's unimportant because sorting is not frequently used, and sorting errors would be very rarely noticed, so it doesn't matter. The checks I've done show that the module is sorting correctly. I added a section below (#Sort key) to document how it works.

One way to check whether convert is doing what is wanted would be like this:

• {{val|1|debug=yes}} → 7000100000000000000♠1
• {{val|1|u=''example''|debug=yes}} → 7000100000000000000♠1 example

The fact that the sort keys are the same shows that the scale for example is 1. If the editor wants something else they should ask at Template talk:Val and you or I will fix it.

If I needed to know whether convert supports a unit, I would preview something like this (mouse over the error message for details):

• {{convert|1|''example''}} → 1 example

The old system was identical in effect. For example, if it weren't already present, an editor might add quadrillion without thinking about sorting. It would sort incorrectly until someone added it to {{Val/sortkey/unit}}. Using the module, exactly the same thing would occur. The editor would add quadrillion, and it would not sort correctly until someone added a scale to the definition. Johnuniq (talk) 01:52, 18 August 2015 (UTC)

SI flag

This is a further explanation of the original documentation (I agree, it's obscure!). The following has three unit definitions for illustration—the links shown here are not the same as those in the module.

A unit may be defined as "SI" which means that the unit code begins with an SI prefix which will be interpreted by {{convert}}. For example, the following defines an SI unit with code kV, base symbol V, and link Kilovolt. The symbol V refers to the base unit with the SI prefix removed. A unit defined in this manner will have its sort key scaled by convert according to the SI prefix: for example, {{val|1|u=kV}} would sort after {{val|999|u=V}}. This is useful for units which are not defined in convert, or which are defined but where a link different from that specified in convert is wanted.

kV   V   Kilovolt    SI

µV   V   Microvolt   SI

uV   V   Microvolt   SI

SI specifies that the unit's symbol is for a base unit after removing the SI prefix in the unit code.

The idea is that SI is merely a convenience to simplify the definitions which are identical apart from the unit code and link. The symbol column shows "V" for each, but it is not the symbol—it is the base unit after removing the SI prefix so convert can work out what is intended to be the prefix. The following would give identical results:

kV   kV   Kilovolt    1e3

µV   µV   Microvolt   1e-6

uV   µV   Microvolt   1e-6

Without "SI", it is necessary to define the symbol wanted, and the scale, and it is necessary to use the correct micro character for the symbol for unit code uV. When "SI" is used, convert does the right thing for the symbol and scale.

The following shows how to check the sort key (this uses fixed wikitext output so it will correctly show what would happen with the above definitions):

• {{val|999|u=uV|debug=yes}} → 6996998999999999999♠999 µV
• {{val|99|u=V|debug=yes}} → 7001990000000000000♠99 V
• {{val|1|u=kV|debug=yes}} → 7003100000000000000♠1 kV

Johnuniq (talk) 03:31, 15 August 2015 (UTC) Updated using fixed wikitext. Johnuniq (talk) 10:56, 16 August 2015 (UTC)

Sort key

By default, a hidden sort key is included in the output. For testing, the key can be displayed:

Val	Output
{{val|12.3|debug=yes}}	7001123000000000000♠12.3
{{val|12.3|u=bit/s|debug=yes}}	7001123000000000000♠12.3 bit/s
{{val|12.3|u=kbit/s|debug=yes}}	7004123000000000000♠12.3 kbit/s
{{val|12.3|u=V|debug=yes}}	7001123000000000000♠12.3 V
{{val|12.3|u=kV|debug=yes}}	7004123000000000000♠12.3 kV

The sort key produced by Module:Val follows these rules:

• If a scale is given for a unit, it is used as a factor to multiply the value. For example, the unit kbit/s is defined to have scale = 1e3 = 1000, and that means {{val|12.3|u=kbit/s}} has a sort key calculated from 12.3 × 1000 = 12300. The sort key is calculated by Module:Convert and is the same as that produced by {{ntsh|12300}} (except that ntsh has some quirks).
• If a unit is defined with the SI flag, its SI prefix sets the scale, which is then used as if a scale had been given.
• Otherwise, Module:Convert uses its knowledge of units to determine the scale. If the unit is unknown, the scale is 1.

Editors won't want to spend time digesting this mumbo-jumbo, but that does not matter. Anyone can add a unit and ignore sorting. If it is found that the unit sorts incorrectly they can either ask to have it fixed (if that hasn't already been done), or ponder the documentation. Adding units is pretty rare so there is not a big problem, and I'm likely to fix any issues from someone unfamiliar with val anyway. Johnuniq (talk) 01:36, 18 August 2015 (UTC)

SI still a problem

The recent changes are not working as expected, as shown by the fact that currently the output in the third column of the following table is different from that in the second.

Val	Correct output	Current output
{{val|999|u=uV|debug=yes}}	6996998999999999999♠999 µV	6996998999999999999♠999 μV
{{val|99|u=V|debug=yes}}	7001990000000000000♠99 V	7001990000000000000♠99 V
{{val|1|u=kV|debug=yes}}	7003100000000000000♠1 kV	7003100000000000000♠1 kV

The following examples from the current definitions are not correct:

kV  [[Volt|kV]]  SI
µV  [[Volt|µV]]  SI
uV  [[Volt|uV]]  SI

For example, the following has the sort key "7000100000000000000" which is the value for 1 with no scale, and it does not use a micro symbol in the output. This uses fixed wikitext so the output shows what happens with the above definitions.

• {{val|1|u=uV|debug=yes}} → 7000100000000000000♠1 uV

Please examine #SI flag above, in particular, the two equivalent sets of definitions, one with and one without SI. I would try to explain some more, but I think this is one of those cases where more text would just generate more complexity. Johnuniq (talk) 11:19, 16 August 2015 (UTC)

I just saw that it doesn't sort correctly. I'll have it sorting again ASAP, less than 10 min. OK? Thanks.

Two quick things about "invalid definition". It did not say "invalid definition" when the difference between the unit code and unit symbol was made zero (so that it presented well at Val/list), but it should have. Also, it did say "invalid definition" when there was a single space at the end of the entry, a difficult thing to find. Should it have? — CpiralCpiral 16:17, 16 August 2015 (UTC)

 Done

Documentation planning

I don't think it's worth optimizing the documentation because very few people will want to add units, and it would be far easier, more reliable, and less stressful for them to post at Template talk:Val and ask for someone to add a unit they have in mind. That would have the benefit of clearing up any disagreements about what would be desirable before starting to edit. Val is used on quite a lot of pages so the modules should not be regarded as a scratchpad where people use trial-and-error to get a unit they want, while others change the definitions because they regard them as undesirable. That's because every edit to the module tells MediaWiki to generate new html output for any page using val, rather than using a page in its cache. We're not supposed to worry about performance, but we shouldn't do obviously bad stuff either. However, I'll leave these notes here to record my thoughts on some points.

I'm aiming at a very few people, I'm thinking "new maintainers" like myself. But I will make the talk page link stand out in the lead section. I have always encouraged units being added to Val because it's natural to imagine all units to just be there.

The docs are far too long with many more words than needed. The whole point of the simple system used to define units is that it is easy to find something similar, then copy it.

You're totally right, but please think of them as babies that need to grow down. I The baby fat is then moved to anemic help files like preview. This blah blah bloat technique has worked elsewhere for me, like {{search link}} and help:search.

One issue that might be mentioned is that people do not need to define a unit—any old stuff can be entered into val and it will use what is given. A definition is only needed if the unit will be used in several places and the markup wanted is a bit cumbersome, so a short unit code would be preferable.

You keep saying that. Hmmm. It sounds too rational. Take a look at the number of zero-usage one-usage units Val now has, for example, take a look at how only List of device bit rates uses bits/s and other of our units. Wild guess? The avg use looks to be about 0.1 uses per unit.

I can make out what "The common reference for a unit on the wiki is the unit code" means, but I don't think it would help someone needing to read the docs.

I can cut that, thanks. Terminology. I pound that term so many ways, it needs no formal definition. You're spot on. Terminology definitions like that are stolid braille. I got the terminology from Convert, then used "unit code" to replace "unit" to clarify many statements.

I don't think "If the same unit code is defined twice on this page, the later one overrides the earlier one" is correct. I would expect val to use the first definition.

For the earlier switch statement, that was true. You're probably right. The draft needs to be questioned like that. Testing... You're right. Updating the doc...

Rather than encouraging people to leave comments at Template_talk:Val/list, I think all discussion should be at Template talk:Val. Even the discussion on this page probably should be at the main template talk so others can see it and at least be aware of what is going on even if they don't want to join in.

OK. Hmmm. Yes. Although that creates less-categorized conversation "clutter", It has the benefit of a newspaper and a city. Back country pages can still pacify trepidation.

The explanation with "Previewing this page with Val/list is different from previewing it with other pages" and "Val/list is a transclusion of this page" is not accurate. When editing a template or a module, the "Preview page with this template/module" feature can be used to show what any other page would look like, if the changes to the template or module were saved. The only thing that is special about Val/list is that its wikitext calls val with an option that generates the list of units.

Well said. When I renamed the transclusion and setup the two module sandboxes (Val and Val/units) with val/list/test, my hunches about the way things inter-work were pleasantly accurate, but trying to put my learning in words... it does need some attention, fixing it now thanks (shorter).

I'm not sure that it is useful to tell people to add definitions they don't intend to use. For example, "We end up with both the slash a/b and inversion ab-1 forms" tells people they should define something that might never be used, and that adds clutter making maintenance more difficult.

If you keep saying things like that, maybe things will change, but that's been the Val mantra since I first saw Val.

It's only clutter when you're having to make some kind of consideration on a unit-by-unit basis (re-categorise, re-association, reconsideration, etc), otherwise for line-oriented record processing it's easily automated, you know. In this regard Template:Val/units/test shows many units usage are shockingly low or zero. If you would see Val/units/test as a decluttering tool, a cleanup project checklist, we would see differently on that. I see it as just the reality that we do support well over two thirds of our units in potentia only, as they lay unused, or used once. Put another way, although we spend way more time on maintaining "that one use" that could have just been done by hand... and the rational thought is to avoid that inefficiency and just forget the template usage... It's not right to keep all these units, but it's not wrong.

How about we just comment out unused units, while keeping them in place for easy restoral?

The statement "Note that the base unit does not need the SI sort-marker" is not always correct. I doubt there would be a real-world usage where the inaccuracy would be visible, but the essence of the SI flag is being missed. If SI is omitted (and assuming no scale is given), convert will be asked to generate a sort key using its knowledge of the unit code. For example, the definition dam  [[Decametre|dam]] does not specify a scale. Nevertheless, a correct sort key will be generated because convert knows that 1 dam = 10 m so the sort keys following are the same:

• {{val|10|u=m|debug=yes}} → 7001100000000000000♠10 m
• {{val|1|u=dam|debug=yes}} → 7001100000000000000♠1 dam

If SI is omitted, the definition m  [[Metre|m]] will only do what is expected if m has a scale of 1 in convert. The simplest is to include SI for all the units that belong together, and to not attempt to explain it in the documentation. Johnuniq (talk) 02:27, 17 August 2015 (UTC)

I would defer to help:sorting if it had the word "scale", but neither it nor {{ntsh}} use the term, but then template ntsh isn't documented very well; help sorting is terse for the most part, although very long and they don't use "scale".— CpiralCpiral 08:20, 17 August 2015 (UTC)

The help page and ntsh that you mention do not handle units, and that is why they don't have a need to worry about a scale. The templates like ntsh generate a sort key calculated only from the value they are given. By contrast, val may have a unit, and it is useful for the sort value to be calculated from the given value and a scale factor to account for the size of the unit. That allows, for example, kilovolts, volts, and millivolts to be used in one table and still sort correctly. The sort key for 1 kV is 1000 times bigger than that for 1 V, which in turn is 1000 times bigger than that for 1 mV.

Re your comment above concerning unused units, I have a big todo list for convert which includes the fact that I would like to prune many of the unused units there (with stuff like "Cypriot dönüm"), but I may never get around to it. Johnuniq (talk) 03:25, 18 August 2015 (UTC)

Bug when displaying more than 2 units

There seems to be a bug when displaying 3 or more units. For example:

• {{val|1|u=kg.m}} looks like kg·m Y
• {{val|1|u=m/s2}} looks like m/s² Y
• {{val|1|u=kg.m/s2}} looks like kg.m/s2 N (should look like kg·m/s², with a middle dot and a superscript 2)

This also happens with e.g. {{val|1|u=kg.m.s}} or {{val|1|u=kg/m/s2}}, which leads me to think that there's a bug when displaying 3 or more units.

(Here are all the above using the template: 1 kg⋅m — 1 m/s² — 1 kg.m/s2 — 1 kg.m.s — 1 kg/m/s2 — when this is fixed, the last 3 will display different to what I wrote)

—Cousteau (talk) 10:41, 9 March 2016 (UTC)