Some typos I found while reading through the docs

[fwitte]

Hi @chmarti1 and @jranalli,

• The link to the handbook is broken

  pyrodoc/html/about.html

  Line 163 in 4d20404

  <b>Units:</b> Version 2.0.1 also saw the addition of a user-configurable system of units. Because unit conversion is dangerously more complicated than one might expect at first glance, the PYroMat unit conversion system is carefully documented in the <a href="handbook.pdf">PYroMat User and Developer Handbook</a>.

  and

  pyrodoc/html/about.html

  Line 172 in 4d20404

  The oldest codes used in PYroMat were variations on Newton-Rhapson iteration with maximum and minimum guesses set to guard against divergence. That approach is still implemented in the back-end <span class="code">_iter1</span> method. That works pretty well with ideal gas properties, but it fails miserably with multi-phase properties. Tests with bisection methods were highly stable, but disappointingly slow. The <span class="code">_hybrid1</span> back-end method was introduced in version 2.1.0, which implements a custom hybrid of Newton and bisection iteration. It is described in detail in the <a href="handbook.pdf">User and Developer Handbook</a>.

  It should be pdf/handbook.pdf
• These (1-5) could be actual bullets for better readability and (5) is the best reason I can imagine ;).

  pyrodoc/html/about.html

  Line 166 in 4d20404

  <b>Numerical methods:</b> Numerical iteration to invert functions is an essential part of evaluating these property models, and that is especially trick when phase changes. PYroMat has always implemented its own custom numerical codes written in pure Python. A number of programmers out there are screaming, "WHY!?" (1) It reduces the number of back-end dependencies that need to be installed and working correctly, (2) these algorithms have been studied and tuned specifically for the types of functions one is likely to get in thermodynamic property calculations, (3) design control over the algorithm makes studying and correcting numerical convergence issues much easier, (4) I've been able to very carefully engineer a balance between speed and reliable numerical convergence, and (5) because it's fun! OK, that last one is a bad reason.

• Some code blocks are outside of the paragraph-blocks

  pyrodoc/html/download.html

  Lines 74 to 78 in 4d20404

  	</p>
  	<div class="code">
  	python3 -m pip install pyromat
  	</div>
  	<p>

  some inside

  pyrodoc/html/download.html

  Lines 65 to 71 in 4d20404

  	<p>
  	On Windows systems, users simply need to right click the command propt icon and select "run as administrator" for the commands to have global effect. On a Linux or MacOS system, the Python Package Authority has historically recommended
  	<div class="code">
  	$ sudo -H python -m pip install pyromat
  	</div>
  	but this is discouraged these days. Personally, I still use this approach when installing PYroMat on most of my machines, and I have yet to regret it.
  	</p>

  Is that intentional?
• In English, do you actually say heated to a boil (

  pyrodoc/html/live/rankine.html

  Line 76 in 4d20404

  Sometimes referred to as the "steam" cycle, the Rankine cycle drove an industrial revolution and still drives most of our power plants today. In the rankine cycle, a liquid (usually water) is pumped into a boiler, where it is heated to a boil. Steam is pulled from the boiler and expanded to do work. In the old steam engines, the work was done by a piston. In modern power generation systems, it is all done by turbines. Finally, the low pressure vapor/liquid mix is cooled in a condenser. Pure liquid is drawn from the bottom of the condenser, so it will be on the saturated liquid line.

  )? Or is the asuperfluous?
• In the superheated Rankine cycle demo, work of turbines is calculated with inverted sign convention to heat transferred in the boiler, superheater and condenser. Is that intentional? See chmarti1/PYroMat@370f0b8#diff-9e1ae1a2737274e9fd787a625ea5510ed6be5a6bd9b0360186ef70fde3ff6a1aL890-L902 (I guess that is the correct place)
• The tp keyword does not work anymore

  pyrodoc/html/doc_howto.html

  Lines 153 to 154 in 4d20404

  	>>> H2O.hs(T=450.,tp=True)
  	(450.0, 9.3204107913593361, 749.29333968000344, 2774.4101890593283)

Because I am curious: Why do you leave double spaces after dots in sentences? Something to search-replace and figure out if it is a floating point or abbreviation?

[jranalli]

• In English, do you actually say heated to a boil

I will let Chris comment on most of these things, since it's his writing, but I did want to hit this one, because these minutiae of language are one of my favorite things, especially given the global audience for english these days.

Short answer:
This is a typical way to phrase this, at least in American English.

Longer Answer:
This appears to be a location and context specific usage. I am from the east coast of the US. I would give no pause to the phrases heated to a boil, heated to boil or heated to boiling. Whether they're "proper English" or not, I can't say, but they at least sound natural enough to me as a native American English speaker that I would not object to any of them spoken or in writing. But we should note that most of our everyday usage of these terms relates to cooking. So if I were myself telling you how to cook pasta, I would say:
Add the water to the pot, bring it to a boil, then add the noodles.
The instructions on boxes of pasta and oatmeal in my pantry agree with that to a boil usage, and I would say that's probably the most common way to phrase this in American English.

British English apparently uses a phrasing that I have never heard before today: bring to the boil.

In a technical article or something, I would say that "bring to a boil" is probably not the best term, since I think of "boil" as loosely defined. So textbooks on thermodynamics would likely to use more precise terminology like "convert to steam" or "vaporize" or "bring to the boiling point/saturation temperature" or something like that.

So in sum, if you're talking with some American friends about making some tea, you might talk about bringing the water to A boil, otherwise, it's probably better to use more scientific language to describe the process. But if there's any larger conclusion we can reach, I think it's that English is a messy, messy language!

[chmarti1]

First off, thanks so much for the detailed comments! It's rare we get detailed feedback on the documentation.

(1) I'll be correcting those broken links today. Good catch!
(2) I think you're right - an ordered list looks tidier, and it reads better. (It's great to hear someone else thinks the fun is part of the point!)
(3) I originally had a principled idea for the use of code blocks/paragraphs, but it looks like I got sloppy in this page. Now that you've drawn attention to it, I don't like the inconsistent spacing. I'll fix that.
(4) @jranalli is right, "heat to a boil" is more commonly used when cooking. I am going to elect not to update the live pages, since those are slated to be completely replaced soon.
(5) Great catch on the tp=True keyword in the saturation methods. In the original algorithm for saturation properties this used to make sense, but it was dropped quite some time ago in a major revision release. I'd trimmed it from the handbook, but looks like I missed it in the "how-to" section. Thanks!

While digging through, I found a few typos of my own. I'll push these out today. Thanks again!

[fwitte]

Thank you very much for the extensive answers. Very interesting, always nice to learn something :).