Fix minor errors in docs and create tools to detect them

[PossiblyAShrub]

After building the docs, run build/doc.sh fmt-check which will verify the resulting HTML for:

• too long code lines (currently 70 chars)
• stray backticks "`" (any raw backtick outside of a <code> is treated as an error)

Note that some TOC blocks can be longer than 70 chars because they contain links that hides part of the line length from python's HTMLParser.

I did notice that 70 chars is really limiting for code blocks like the TOC. We could decrease the font size so the jump from 800px to 801px is not so jarring, and this would increase our limit to ~80 chars:

diff --git a/web/base.css b/web/base.css
index e21863fb7..25968ea29 100644
--- a/web/base.css
+++ b/web/base.css
@@ -17,7 +17,7 @@
   body {
     margin: 0 auto;
     line-height: 1.4;  /* http://bettermotherfuckingwebsite.com/ */
-    font-size: large;  /* 2024-01 - all pages deserve this */
+    font-size: medium;  /* 2024-01 - all pages deserve this */
   }

   .skinny { width: 30em; }  /* Most blog posts */

The fmt-check script could also be added to CI, but I am not sure what the best way to do this is. I'd appreciate some help there.

[andychu]

OK cool, thanks for finding these errors!

The CI is in soil/worker.sh, and grep it you can see we run build/doc.sh soil-run

I would put it before or after write-metrics in run-for-release

---

Do we really have zero errors now though?

I kinda like the font size bigger -- we can deal with that separately ... I think on mobile it will horizontal scroll which isn't horrible

andy@hoover:~/git/oilshell/oil$ grep doc soil/worker.sh 
micro-syntax     doctools/micro-syntax.sh soil-run     -
src-tree         doctools/src-tree.sh soil-run         _tmp/src-tree-www/index.html
docs              build/doc.sh soil-run                  _release/VERSION/index.html

[PossiblyAShrub]

Do we really have zero errors now though?

No, I wanted to hear your thoughts on changing the font-size before I tried to fix all of the "code line too long" errors.

I'll add a commit to fix those errors for the larger font size.

[andychu]

Hm why 70 and not 80?

I think 80 is a bit more standard

The two cases where it matters to the user are:

• the pre blocks, but yeah this is browser-specific. There's nothing saying that font-size: medium will work for 80 or font-size: large works for 72
• I just noticed help ysh-cmd-lang and so forth are kinda broken

andy@hoover:~/git/oilshell/oil$ bin/osh -c 'help ysh-cmd-lang'
 ysh-cmd-lang 

  Command Language <a class="group-link" href="chap-cmd-lang.html">cmd-lang</a>

  [YSH Simple]    typed-arg     json write (x)
                  lazy-expr-arg assert [42 === x]
                  block-arg     cd /tmp { echo $PWD }; cd /tmp (; ; blockexpr)
  [YSH Cond]      ysh-case      case (x) { *.py { echo 'python' } }
                  ysh-if        if (x > 0) { echo }
  [YSH Iter]      ysh-while     while (x > 0) { echo }
                  ysh-for       for i, item in (mylist) { echo }

They have literal HTML

I am not sure when that happened -- probably with the last release

---

I think we should leave off the line length check until some other things are in better shape

e.g. the content is the most important thing

[andychu]

As an observation, on my machine this page has no wrapping under Firefox, but under Chrome there is a little bit of overflow

https://www.oilshell.org/release/0.22.0/doc/ref/toc-osh.html

But there's no relation to 72 or 80 really, so I think we should just punt on that

I guess if it looks super bad on some device, post a screenshot on Zulip :)

[PossiblyAShrub]

This is ready for a review.

• I removed the code to check line lengths in <code> blocks for now
• I also added a fmt-check step to CI

[andychu]

Merged, thanks!

Hm so about Python 2 vs. 3, technically we can add it to the containers if we want

e.g. mycpp must be written in Python 3, and it runs in other containers

---

But I guess since all the other doctools/ are Python 2 now, we can keep it all the same

It is generally pretty easy to switch back and forth, which I've done a few times ... that's why I always use from __future__ import print_function, because that's generally the most obvious syntax error

---

Eventually we can do something for line length, probably with some smart algorithm, but I think it's OK for now

---

I'm working on the stdlib now, should have some good updates soon

I think we should rethink our code example/code block toolchain too ... I think there are probably a ton of typos there too