wallet/docs/writing_and_editing_documentation.md

---
# katex
title: >-
	Writing and Editing Documentation
sidebar: true
...

# Organization

My stuff is currently an enormous pile of disorganized, and thus
inaccessible, documents.


# pandoc

Much documentation is in Pandoc markdown, because easier to write. But html
is easier to read, and allows superior control of appearance

To convert Pandoc markdown to its final html form, invoke `Pandoc` by the bash
shell file `./mkdoc.sh`, which generates html.

Directories with markdown files contain a shell script mkdocs.sh which compiles
them into html, and also executes the mkdocs.sh of each of its 
subdirectories, if they have a mkdocs.sh

The directories also contain a file called navbar, which
is the horizontal navigation menu.

Each markdown files should start with some yaml data that sets
the title.

Thus the markdown for this web page starts with

```yaml
---
# katex
title: >-
	Writing and Editing Documentation
sidebar: true
...
```

- `# katex` tells the bash script and pandoc to support katex
- `sidebar: true` causes the table of contents to appear at the side
- `notmine: true` suppresses the copyright license.

In the windows 10 environment, shell scripts used  in this project need to be
associated with [Git Bash](libraries/git_bash_undocumented.html) or run from within Git Bash.

This vast pile of notes is out of control, and writing code and maths in
html leads to intolerable overheads.

Hence markdown, the popular markdown conversion program
being the open source Pandoc.

Markdown converters are apt to throw a flood of incomprehensible html code
into your final document, taking low level html control away from the writer.

Pandoc, however, will allow you to take control.  To integrate html and css
with markdown using Pandoc is a bit like rolling marbles with your
elbows through a cage. One has to work through and around the entry
points that Pandoc gives you, while if you were writing in html you could
just write what you wanted directly, but having done the work,
Pandoc can then ensure it is done for every document in the same style in
the same way, and you can change the final form of every document in the
same way all at once.

Sphinx is very popular and widely used, and written in the far more
accessible language python, but to access the power of html, css, and
JavaScript one must write a Sphinx theme, and the creation of a Sphinx theme
is less than well documented and appears to be subject to change.

Visual Studio Code theoretically does automatic generation of the html
equivalents of markdown files, but I never was able to get it working
satisfactorily.

Pandoc has a number of powerful extensions that allow integration of html and
markdown, among them markdown native mode divs `:::`

```markdown
::: {style="…"}
	…
:::
```

And native mode spans `[…]{style="…"}`

Which extensions do not work correctly in Visual Studio Code.

These can be used to put an anchor in text, but the easiest and most
intelligible way to insert an anchor is as a header.

Since markdown has no concept of a title, Pandoc expects to find the
title in a yaml inline, which is most conveniently put at the top, which
renders it somewhat legible as a title.


## Math expressions and katex

Pandoc can render most maths markdown without needing katex, for example:
$${e}^{i\pi}+1=0$$
$$a=b+c$$
$$f(x) = x^2$$
$$\sin(\pi/6) = 0.5$$
$$\int_a^b f(x) dx$$
$$\int_a^b \tan(x) dx$$
$$\int \sin(x) dx = \cos(x)$$
$$\sum a_i$$
$$\lfloor{(x+5)÷6}\rfloor = \lceil{(x÷6}\rceil$$
$$\lfloor{(x+5)/6}\rfloor = \lceil{(x/6}\rceil$$
Use `\bigcirc`, not capital O for Omicron $\bigcirc$.  `\Omicron` will not always
compile correctly, but `\ln` and `\log` is more likely to compile correctly than
`ln` and `log`, which it tends to render as symbols multiplied, rather than one
symbol.
$$\ln(1+x)=x-\bigcirc(x^2)$$
$$H(a|b|v)$$
Some maths expressions will break Pandoc unless one tells it to use katex.  Stick the
`# katex` header in when something breaks.  Pandoc avoids using katex unless it has
to.

But for these expressions, it has to:

$$\sin(\frac{\pi}{6}) = \frac12$$
$$\displaystyle\frac{u(x)}{v(x)}$$
Inline equation $\displaystyle\sum\limits_{i=1}^n i^2 = \frac{n(n+1)(2n+1)}{6}$ text after inline equation

$$\displaystyle\sum\limits_{i} i^2 = \frac{i(i+1)(2i+1)}6$$
The square root of 100 is $\sqrt{100}=10$.\
The cubic root of 64 is $\sqrt[3]{64}=4$
$$\bigg\lfloor\frac{x+5)}{6}\bigg\rfloor = \bigg\lceil{\frac{x}{6}}\bigg\rceil$$

A file that does not need katex has the header:

```markdown
---
title: >-
	Document title
...
```

But if it does need katex, it has the header

```markdown
---
title: >-
 # katex
	Document title
...
```

So that the bash script file `./mkdoc.sh` will tell `Pandoc` to find the katex scripts.

For it offends me to put unnecessary fat in html files.

### overly clever katex tricks

$$k \approx \frac{m\,l\!n(2)}{n}%uses\, to increase spacing, uses \! to merge letters, uses % for comments $$

$$k \approx\frac{m\>\ln(2)}{n}%uses\> for a marginally larger increase in spacing and uses \ln, the escape for the well known function ln $$

$$ \exp\bigg(\frac{a+bt}{x}\bigg)=\huge e^{\bigg(\frac{a+bt}{x}\bigg)}%use the escape for well known functions, use text size sets$$

$$k\text{, the number of hashes} \approx \frac{m\ln(2)}{n}% \text{} for render as text$$

$$\def\mydef#1{\frac{#1}{1+#1}} \mydef{\mydef{\mydef{\mydef{y}}}}%katex macro $$

## Tables

### Pipe table with header and alignment control

Without counting spaces, but without multiline

Pipe table:

| Right | Left | Default | Centre |
|------:|:-----|---------|:----------------------:|
|   12  |  12 |    12   |    12  |
|  123  |  123 |   123   |   the quick brown fox jumped over the lazy dog  |
|    1  |  1 |     Carrian Corporation |     1  |

### And, with less mucking about, alignments

with alignment, without counting spaces, but without multiline

fruit| price
:-----|-----:
apple|2.05
pear|1.37
orange|3.09

### multiline without bothering with pipes

Counting spaces to align.  Only editable in fixed font

This allows multiline, but visual studio code does not like it.  Visual Studio Code only supports tables that can be intelligibly laid out in visual studio code.

-------------------------------------------------------------
 Centered   Default           Right Left
  Header    Aligned         Aligned Aligned
----------- ------- --------------- -------------------------
   First    row                12.0 Example of a row that
                                    spans multiple lines.

  Second    row            5.0      Here's another one. Note
                                    the blank line between
                                    rows.
-------------------------------------------------------------

### The header may be omitted in multiline tables as well as simple tables

Notice the alignment is controlled by the first item in a column

In this table, edited in a fixed font, you are using whitespace and blank lines to lay out  the table.  It is unintellible in a variable width font.

----------- ------- --------------- -------------------------
   First    row            12.0     Example of a row that
                                    spans multiple lines.

  Second    row                 5.0 Here's another one. Note
                                    the blank line between
                                    rows.
----------- ------- --------------- -------------------------

### Grid tables

Allows multiline, and alignment, but visual studio does not like it, and you still have to count those spaces.
Works fine if you are editing in a monospaced font, otherwise unusable

+---------------+---------------+--------------------+
| Fruit         | Price         | Advantages         |
+===============+==============:+====================+
| Bananas       | $1.34         | Mary had a little  |
|               |               | lamb and every     |
|               |               | where that mary    |
|               |               | bright color       |
+---------------+---------------+--------------------+
| Oranges       | $2.10         | - cures scurvy     |
|               |               | - tasty            |
+---------------+---------------+--------------------+
| Durian        | $22.10        | - king of fruits   |
+---------------+---------------+--------------------+

Alignments can be specified as with pipe tables, by putting colons at the boundaries of the separator line after the header.

+------------+---------+---------------------+
| Left       |   Right | Centered            |
+:===========+========:+:===================:+
| Bananas    |  $1.34  | - built-in wrapper  |
|            |         | - bright color      |
+------------+---------+---------------------+
| Durian     | $22.10  | - king of fruits    |
+------------+---------+---------------------+

### For headerless tables, the colons go on the top line instead:

+--------------:+:--------------+:------------------:+
| Right         | Left          | Centered           |
+---------------+---------------+--------------------+

## footnotes

Markdown permits footnotes.

This is a useless feature present because people are moving legacy documents to the web.

[^long] They can be inline ^[this is an inline footnote]
but an inline footnote appears at the bottom of the document, which is confusing in html
unless the document is short.

Footnotes were designed to be used with paginated^[footnotes are an ancient hangover from paginated documents in order to do hypertext on paper] documents.  
Html is designed for hypertext.

[^long]: This is an out of line footnote, that can be inserted anywhere, which is confusing in an html document, and hard to edit, because they always wind up sequentially numbered at the bottom of the document.

	Reflect on how unusable wikipedia foot notes are.

# Images

Images are preferably `*.webp`, and are expressed as the markdown code

`![](./image_name.webp){style="width: 479px; height: 386px;"}`

assuming the actual image size is 479 pixels wide and 386 pixels high, 479 pixels being the typical width of an image rendered at 100% of the text width with my default formats, and indeed a whole lot of other people's default formats on a typical screen.  But obviously pixel size is getting smaller, so for device independence and simplicity, might well give a larger image, and leave out the style command.


# Diagrams

The best way to do diagrams is svg and the Visual Studio Code
scalable vector graphics extensions.

If you place the data directly in markdown, rather than in an svg file,
the markdown is a lot more tolerant of errors than the browser when it
includes an svg file, so it is very easy to create svg that displays fine,
until you separate it into an svg file to be included as an ordinary
image file, whereupon it fails to display in the browser.

Error checking in the markdown and in visual studio code svg editors
fails to pick up all errors that will prevent an svg file from displaying.

Inkscape files are unreadable, and once they are cleaned up,
Inkscape cannot read them.  To (irreversibly) clean up an Inkscape
file, minify it in Visual Studio Code to get rid of all confusing
mystery cruft inserted by Inkscape, edit it back into markdown
compatible form, and reinsert it in the markdown file.

A sequence of straight lines is M point, L point, L point.

Z and z draw a straight line back to the beginning, use in conjunction with
`fill="#red"`, for example `fill="#FF0000"`.  If the line is open, `fill="none"`

H and h draw horizontal lines, V and v vertical lines.  To see which line you are working on, convenient to temporarily begin and end it with a cross, h 3 h-6 h3 v3 v-6 v3

Drawing smooth curves by typing in text is painful and slow, but so
is drawing them in Inkscape.  Inkscape is apt to do a series of C
beziers with sharp corners between them, and when I try to fix the
sharp corners, the bezier goes weird.

If you can get your desired curve with a single `M point c point point point`
that causes the least grief, and gives you a nice smooth curve.

The first point is the starting position, the last point is the end
position.  The direction of the first control point sets the starting
direction, the direction of the second control point sets the end
direction, and how far the control points are out controls how and
where the curve changes direction.  If the curve is weird and pathological, there is something funny with your control points.

Some control point positions lead to singularities in the derivative
of the curv but for reasonable control point positions, you get a
nice smooth curve.

Capital letters indicate absolute points, lower case relative points.

Before deciding you need to add additonal points to get the curve
you want, see if you are doing something dumb with your control
points.  You usually are.

If you want a sharp turn coming out, and a smooth curve, then a
sharp curve coming in to the destination, you do not put in a bunch
of intermediate points, you just put your control points close to the
beginning and end.

The further the control point is away from the end of the previous S
curve, the further its influence propagates into the next S curve.
Which can have surprising results if the next S curve is very short, so
that influence of the previous control point propagates far beyond its end.

If you want a smooth and gentle curve, you want the the reflection of the previous C or S control around the middle of the next S curve

You only need additional points when you want the curve to go
through a narrow pass, in which case you are going to have a C
curve going to the narrow pass, the last control point before the narrow pass, its reflection in the next S curve after the narrow pass.

When you want to join two points, and don't care about the path, use an L straight line

When you want to join two points, and you care about the direction
in which it starts, or the direction in which it finishes, but not both,
use a Q, which gives you one degree of control freedom.

When you want to join two points, and care about the direction it
starts, and the direction it ends, use a C, which gives you two
degrees of control freedom.

When you want to join two points, and care about the direction it
starts, the direction it ends, and you want it to go through a
gateway in the middle, use a C S, which gives you three degrees
of control freedom.  But watch out for the reflection of the last control
point in the C landing somewhere difficult inside the S curve.  If the last control point in the C is further from the end point of the C
than the end point of the S, things can get strange. Sometimes you
want to adjust the behavior of the S curve by moving the last
control point of the previous C or S to the right position.  A distant
previous control point is apt to have a big effect on the following S,
a near control point little effect, but likely to give you an
unpleasantly sharp turn at the join.

``` default
M point c point point point s point point
s point point ... s point
```

Is guaranteed to give you a smooth curve, for reasonably sane
control points, with the curve passing through the second point of
the s, and its direction set by the first point of the s.

You change a control point, the effect is entirely local, does not
propagate up and down the line.

If, however, you have a long move and a short move, your implied control
point is likely to be in a pathological location, in which case you have to
follow an S curve by a C curve, and manually calculate the first point of
the C to be in line with the last two points of the prior curve.

``` default
M point q point point t point t point ... t point
```

<div style="width: 100%; height: auto; overflow: auto;">
<svg
	xmlns="http://www.w3.org/2000/svg"
	width="width: 100%"  height="100%"
	viewBox="0 0 120 80"
	style="background-color:ivory">
	<g stroke-width="2">
		<path fill="none" stroke="#00f000"
			d="
				M14,45,  c40,-20, 30,-56 54,-18,  s55,15 40,15
					 s-15,10 -30,15
				M 5,45,  q 10,20 30,1, t 10,10, t 10,12
			" />
	</g>
</svg>
</div>

```html
<div style="width: 100%; height: auto; overflow: auto;">
<svg
	xmlns="http://www.w3.org/2000/svg"
	width="width: 100%"  height="100%"
	viewBox="0 0 120 80"
	style="background-color:ivory">
	<g stroke-width="2">
		<path fill="none" stroke="#00f000"
			d="
				M14,45,  c40,-20, 30,-56 54,-18,  s55,15 40,15
					 s-15,10 -30,15
				M 5,45,  q 10,20 30,1, t 10,10, t 10,12
			" />
	</g>
</svg>
</div>
```

Is also guaranteed to give you a nice smooth curve for any reasonably sane
choice of the initial control point and the position of the t points, but you cannot easily control the direction the curve takes through the points.  Changing the control point of the first q will result in things snaking all
down the line, and changing any of the intermediate t points will change
the the direction the curve takes through all subsequent t points,
sometimes pushing the curve into pathological territory where bezier
curves give unexpected and nasty results.

Scalable vector graphics are dimensionless, and the `<svg>` tag's
height, width, and ViewBox properties translate the dimensionless
quantities into pixels.  The graphics default to fixed aspect ratio, and
anything outside the viewbox is not drawn.  To adjust your image's
position within the viewbox, you put everything into a single big
group, and apply a translate to that group.

The enormous advantage of scalable vector graphics is that it handles
repetitious items in diagrams beautifully, because you can define an item
by reference to another item, thus very large hierarchical structure can be
defined by very small source code.

<div style="width: 100%; height: 22em; overflow: auto;">
<svg
	xmlns="http://www.w3.org/2000/svg"
	width="58em"  height="24em"
	viewBox="40 60 60 50"
	style="background-color:ivory">
	<g  id="startblocks"
		font-family="'Times New Roman'" font-size="5"
		font-weight="400"
		stroke-width="2"
		style="text-decoration:underline; cursor:pointer;" >
		<path fill="none" stroke="#800000"
			d="M45 100,  c100 -50, -40 -50, 60 0" />
		<line x1="22" y1="70" x2="28" y2="100" stroke="grey"/>
	<rect x="60" y="64" width="20" height="20">
		<animate attributeType="XML" attributeName="y"
			from="64" to="120"
			dur="3s" repeatCount="5" restart="whenNotActive"/>
		<animate attributeType="XML" attributeName="x"
			from="60" to="0"
			dur="3s" repeatCount="5" restart="whenNotActive"/></rect>
		<rect style="fill:#FFFF00;"
			x="12" y="64" width="36" height="20">
			<animate attributeType="XML" attributeName="y"
				from="64" to="110"
				dur="5s" repeatCount="2" restart="always" />
		</rect>
		<text style="fill:blue;"  x="14" y="74">
			<animate attributeType="XML" attributeName="y"
				from="74" to="120"
				dur="5s" repeatCount="2" restart="always" />
			start animation
		</text>
	</g>
	<g
		font-family="'Times New Roman'" font-size="5"
		font-weight="400"
		stroke-width="2">
		<path fill="none" stroke="#00f000"
			d="M14 101,  c40 -20, 30 -56, 54 -18 s60 15, 40 15  c -20,0  -10,-20  0,-20 s 9,7 8,12" />
		<ellipse cx="60" cy="85" rx="12" ry="5" style="fill:red" />
		<text  x="60" y="82" text-anchor="middle"  style="fill:#A050C0;" >
			A simple scalable vector graphic
			<tspan x="60" dy="8">
				directly embedded in markdown.
			</tspan>
		</text>
	</g>
</svg>
</div>

<script>
	document.getElementById("startblocks").addEventListener
	(
		"click", evt =>
		{
			document.querySelectorAll("animate").forEach
			(
				element =>
				{
					element.beginElement();
				}
			);
		}
	);
</script>

```svg
<div style="width: 100%; height: 22em; overflow: auto;">
<svg
	xmlns="http://www.w3.org/2000/svg"
	width="29em"  height="12em"
	viewBox="40 60 60 50"
	style="background-color:ivory">
	<g  id="startblocks"
		font-family="'Times New Roman'" font-size="5"
		font-weight="400"
		stroke-width="2"
		style="text-decoration:underline; cursor:pointer;" >
		<line x1="22" y1="70" x2="28" y2="100" stroke="lightgrey"/>
		<rect style="fill:#FFFF00;"
			x="12" y="64" width="36" height="20">
			<animate attributeType="XML" attributeName="y"
				from="64" to="120"
				dur="5s" repeatCount="2" restart="always" />
		</rect>
		<text style="fill:blue;"  x="14" y="74">
			<animate attributeType="XML" attributeName="y"
				from="74" to="130"
				dur="5s" repeatCount="2" restart="always" />
			start animation
		</text>
	</g>
	<rect x="60" y="64" width="20" height="20">
		<animate attributeType="XML" attributeName="y"
			from="64" to="120"
			dur="5s" repeatCount="3" restart="whenNotActive"/>
	</rect>
	<g
		font-family="'Times New Roman'" font-size="5"
		font-weight="400"
		stroke-width="2">
		<path fill="none" stroke="#00f000"
			d="M14 101,  c40 -20, 30 -56, 54 -18 s60 15, 40 15  c -20,0  -10,-20  0,-20 s 9,7 8,12" />
		<ellipse cx="60" cy="85" rx="12" ry="5" style="fill:red" />
		<text  x="60" y="82" text-anchor="middle"  style="fill:#A050C0;" >
			A simple scalable vector graphic
			<tspan x="60" dy="8">
				directly embedded in markdown.
			</tspan>
		</text>
	</g>
</svg>
</div>
```

```script
<script>
	document.getElementById("startblocks").addEventListener
	(
		"click", evt =>
		{
			document.querySelectorAll("animate").forEach
			(
				element =>
				{
					element.beginElement();
				}
			);
		}
	);
</script>
</div>
```