From b178405c4426f7d1b2b9a729eaa3de005bbe8710 Mon Sep 17 00:00:00 2001 From: "reaction.la" Date: Mon, 9 May 2022 22:08:13 +1000 Subject: [PATCH] starting to think and prepare to organize this great pile of random thoughts --- docs/replacing_TCP.md | 18 ++ docs/writing_and_editing_documentation.md | 261 ++++++++++++++-------- 2 files changed, 184 insertions(+), 95 deletions(-) diff --git a/docs/replacing_TCP.md b/docs/replacing_TCP.md index 20e6163..22c3cc5 100644 --- a/docs/replacing_TCP.md +++ b/docs/replacing_TCP.md @@ -16,11 +16,29 @@ title: Replacing TCP, SSL, DNS, CAs, and TLS matter of copying it and embedding it where possible, and forking it if unavoidable. DDOS resistance looks like it is going to need forking. +It implements ledbat, a protocol designed for applications that download +bulk data in the background, pushing the network close to its limits, while +still playing nice with TCP. + Implementing consensus over [µTP] is going to need [QUIC] style streams, that can slow down or fail without the whole connection slowing down or failing, though it might be easier to implement consensus that just calls µTP for some tasks. +I have not investigated what implementing short fixed length streams over +[µTP] would involve. Bittorrent already necessarily does something mighty +like that. Maybe it just sequentializes everything. Which kind of makes +sense, a single concurrent process managing each connection is easier to +program and comprehend, even if it cannot give optimal performance. +Obviously it must have a request response layer, documented only in +source code. The question then is how it maps that layer onto a µTP +connection. You are going to have to copy, not just µTP, but that layer, +which should be part of µTP, but probably is not. You will have to +factorize that they probably not cleanly factorized. + +Their request response layer is probably somewhat documented in +[BEP0055] I suspect that what I need is not just µTP, but the largest common factors of [BEP0055] + [BEP0055]:https://www.bittorrent.org/beps/bep_0055.html "BEP0055" {target="_blank"} diff --git a/docs/writing_and_editing_documentation.md b/docs/writing_and_editing_documentation.md index d2c5eb4..d90ff45 100644 --- a/docs/writing_and_editing_documentation.md +++ b/docs/writing_and_editing_documentation.md @@ -1,10 +1,81 @@ --- +# katex title: >- Writing and Editing Documentation -# katex -# Pandoc Markdown ... +# Organization + +My stuff is currently an enormous pile of disorganized, and thus +inaccessible, documents. + +The clean and elegant style of open source documentation always has a +header bar at the top, through which all documents can be accessed. And a +moderately sized logo and title at the top. I am thinking a rho, surrounded +by a flaming halo of green blue radial flames, followed by "Rhocoin" + +Then a top level menu of five or six items, followed by lower level horizontal menus that depend on which higher level menus was selected. + +The best layout I have seen the [wxWidgets style](https://docs.wxwidgets.org/3.0/functions.html){target="_blank"} which has multiple bars, +and when you clicked on entry in one bar, the lower bars changed. +wxSqlite3 used to have this style. Now, has a [single bar with multilevel drop downs](https://utelle.github.io/wxsqlite3/docs/html/index.html){target="_blank"} , as does the [SQLite3 style](https://sqlite.org/docs.html){target="_blank"} , of which it is a direct copy, +but SQLite3 style lacks a way to handle the enormous number of SQLite3 +documents, which can only be handled by a multi level bar, or by a page +full of links + +Libsodium, on the other hand, has a [left hand bar with drop downs](https://doc.libsodium.org/secret-key_cryptography){target="_blank"}. Which +is probably easier to implement, but that there is no documentation locally +installed suggests that it too is in some way server generated. Apache2 and +nginx similarly, and handle the enormous number of documents by +bringing up pages full of links. Which is OK, but means you do not have +navigation at your fingertips.] + +This layout is in some way automatically generated on the server, which +sucks. Probably relies on server side include, which is the easiest way to +do it.The documentation needs to be in every install and every repository. +Thus wxWidgets documentation on the server has nice organizational +style, but on each person's individual installed copy, disorganized crap. + +Client side include works like this: + +```html + +``` + +Where the script b.js is: + +```js +document.write("…") +document.write("…") +… +``` +When encountered, the browser downloads the script “b.js”, executes +it, and prints any output that the script might generate as if it were +inline HTML. + +Each bottom level subtree should be a directory, and each html document +in that directory should call the script which generates the horizontal bars +on the path from the root to it. The bash script that uses pandoc to generate +those documents from the markdown documents in that directory should +also generate the javascript, concatenating all the javascripts of the parent +directories into it. + +Thus one final javascript file for each bottom level directory, which +generates a sequence of horizontal bars corresponding to the path to +that directory, followed by a horizontal bar for that directory. + +One tricky bit is that you want the path highlighted. In which case it is +probably easier for the bash script, which is recursing through the tree of +files and keeps track of the path by which it got there in an enormous +string variable, to insert a direct copy of the header bar into each html file, + +The directory name is what appears in the top level bars, and the final bar +is a possibly multiline bar that is the titles of all the documents in the directory +and any subdirectories. + +# pandoc + Much documentation is in Pandoc markdown, because easier to write. But html is easier to read, and allows superior control of appearance @@ -87,7 +158,7 @@ title: >- ... ``` -# Converting html source to markdown source +## Converting html source to markdown source In bash @@ -96,7 +167,7 @@ fn=foobar git mv $fn.html $fn.md && cp $fn.md $fn.html && pandoc -s --to markdown-smart --eol=lf --wrap=preserve --verbose -o $fn.md $fn.html ``` -# Math expressions and katex +## Math expressions and katex Pandoc can render most maths markdown without needing katex, for example: $${e}^{i\pi}+1=0$$ @@ -170,7 +241,7 @@ So that the bash script file `./mkdoc.sh` will tell `Pandoc` to find the katex s For it offends me to put unnecessary fat in html files. -## overly clever katex tricks +### overly clever katex tricks $$k \approx \frac{m\,l\!n(2)}{n}%uses\, to increase spacing, uses \! to merge letters, uses % for comments $$ @@ -182,6 +253,96 @@ $$k\text{, the number of hashes} \approx \frac{m\ln(2)}{n}% \text{} for render a $$\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 | Center | +|------:|:-----|---------|:----------------------:| +| 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 spacees + ++---------------+---------------+--------------------+ +| Fruit | Price | Advantages | ++===============+==============:+====================+ +| Bananas | $1.34 | - built-in wrapper | +| | | - 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 | ++---------------+---------------+--------------------+ + # diagrams The best way to do diagrams is svg and the Visual Studio Code @@ -509,93 +670,3 @@ defined by very small source code. ``` - -# Tables - -## Pipe table with header and alignment control - -Without counting spaces, but without multiline - -Pipe table: - -| Right | Left | Default | Center | -|------:|:-----|---------|:----------------------:| -| 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 spacees - -+---------------+---------------+--------------------+ -| Fruit | Price | Advantages | -+===============+==============:+====================+ -| Bananas | $1.34 | - built-in wrapper | -| | | - 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 | -+---------------+---------------+--------------------+