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

— Cpiral Cpiral 01:22, 15 August 2015 (UTC)[reply]

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)[reply]

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 Val/sortkey/unit, 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.

— Cpiral Cpiral 00:23, 17 August 2015 (UTC)[reply]

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)[reply]

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)[reply]

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? — Cpiral Cpiral 16:17, 16 August 2015 (UTC)[reply]

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)[reply]

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".— Cpiral Cpiral 08:20, 17 August 2015 (UTC)[reply]

Request for SI units at Val/list

For making the SI units at Val/list consistent, please remove the the wikilink from the base unit in field two, and put it with the unit code, either in field one or field two.

Question.current	`ms [[Millisecond\|s]] SI` `ms s Millisecond SI`	→ ms s · SI unusual wikilink
A1.good swap fields in rendering only	`[[Millisecond\|ms]] s SI` (swap required) `ms s Millisecond SI` (usual order OK)	→ ms s · SI move wikilink over
A2.better Make the 4th field a variable SI string	`ms2 [[Millisecond\|ms<sup>2</sup>]] s__SI` `ms2 ms<sup>2 Millisecond s__SI`	→ ms2 ms² · s__SI entirely consistent
A3.best When the 4th field not a number, an SI prefix	`ms2 [[Millisecond\|ms<sup>2</sup>]] m` `ms2 ms<sup>2 Millisecond m`	→ ms2 ms² · SI entirely consistent

Currently hen the hover text is over "s" and it says "millisecond"
this is a hidden inconsistency. — Cpiral Cpiral 02:47, 17 August 2015 (UTC)[reply]