What does parse-units=false do?

[teepeemm]

I don't understand the use of parse-units=false.

siunitx/siunitx.tex

Line 2683 in 18a8576

Normally, \pkg{siunitx} is used with the unit parse enabled, and only prints

suggests that this will "print units directly" with higher performance. It then compares \qty{300}{\MHz} with \qty[parse-units = false]{300}{\MHz}.

I understand "higher performance". I don't understand "print units directly". And I don't see a difference in the printed examples - they both look like "300\thinspace MHz". What is the visible difference in parse-units=false?

[josephwright]

You won't see the difference with a simple unit such as \MHz: it shows up when things are more complicated.

When parsing, units are read and stored internally with their prefix, power, etc., all separated out. They are then put back together for typsetting. That allows things like having \per produce /, a negative power or a fraction depending on settings, or turning prefixes into powers of ten in the number. On the other hand, if parsing is disabled then each input macro has a fixed definition: in the case of \per that is /, and \kilo is a k. That's a lot less flexible, but it will always be faster.

[teepeemm]

Would it make sense to change the documentation to the paragraph you just gave? And change the example to \unit[parse-units=false]{\meter\per\second}?

[josephwright]

The point of the example is that this is a case where the performance gain is 'OK' - there's no change in the output.