add docs app docs

content/reference/additional/dist/_index.md

@@ -1,6 +1,6 @@
 +++
 title = "Software Distribution"
-weight = 900
+weight = 90
 sort_by = "weight"
 insert_anchor_links = "right"
 +++

content/reference/additional/docs-app/_index.md

@@ -0,0 +1,20 @@
++++
+title = "Docs App"
+weight = 100
++++
+
+### [Overview](/reference/additional/docs-app/overview)
+
+General information about the Docs apps.
+
+### [File Format](/reference/additional/docs-app/file-format)
+
+Information about marks supported by the Docs app.
+
+### [Index File](/reference/additional/docs-app/index-file)
+
+Details of the `.toc` index file format.
+
+### [Suggested Structure](/reference/additional/docs-app/structure)
+
+Suggestions about how to structure docs.

content/reference/additional/docs-app/file-format.md

@@ -0,0 +1,161 @@
++++
+title = "File Format"
+weight = 5
+template = "doc.html"
++++
+
+## `%docu` mark
+
+{% callout %}
+**Note**: this section is mostly useful if you're writing a mark conversion
+method. For marks that are already supported and you can use directly, see
+further down this page.
+{% /callout %}
+
+The `%docs` app supports any mark, as long as it has a conversion method to its
+`%docu` mark. The `%docu` mark is not expected to be used directly to write
+documentation, its purpose is to be a mark conversion target.
+
+The `%docu` mark expects a `$manx`.
+
+A `$manx` is how an XML node structure is represented in hoon. See [Section
+5e](/reference/hoon/stdlib/5e#manx) of the standard library reference for
+details. A `$manx` is what `++de-xml:html` and `++en-xml:html` decode/encode
+raw XML strings from/to.
+
+The `%docu` mark will technically accept any `$manx`, but the `%docs` agent
+itself makes some changes and imposes some additional rules:
+
+- The root element must be a `<div>`.
+- `<h1>`, `<h2>`, and `<h3>` elements that are direct children of the root
+  `<div>` will be used to make the table of contents. Other header levels
+  will not be included in the table of contents, but they can still be used.
+  `<h1>`, through `<h3>` can also be used at deeper levels, but they also
+  won't be included in the table of contents.
+- Only these tags are allowed: `<a>`, `<address>`, `<b>`, `<br>`,
+  `<blockquote>`, `<code>`, `<del>`, `<div>`, `<em>`, `<h1>`, `<h2>`, `<h3>`,
+  `<h4>`, `<h5>`, `<h6>`, `<hr>`, `<i>`, `<img>`, `<ins>`, `<li>`, `<ol>`,
+  `<p>`, `<pre>`, `<q>`, `<small>`, `<span>`, `<strong>`, `<sub>`, `<sup>`,
+  `<time>`, `<ul>`, `<var>`.
+- Inside the `<h1>`, `<h2>`, and `<h3>` headers that are direct children of the
+  root `<div>` (and will therefore be used in the table of contents), only a
+  subset of the tags listed above are allowed: `<b>`, `<code>`, `<del>`, `<em>`,
+  `<i>`, `<ins>`, `<q>`, `<small>`, `<span>`, `<strong>`, `<sub>`, `<sup>`,
+  `<time>`, `<var>`.
+- All attributes will be stripped from all elements (you can still include them
+  but they'll be removed), with the following exceptions:
+  - The `src` and `alt` attributes in an `<img>` tag.
+  - The `href` attribute in an `<a>` tag.
+  - A `class` attribute in a `<pre>` tag beginning with `language-` (e.g.
+    `class="language-hoon"`). This is not currently used for anything but will be used
+    for syntax highlighting in the future.
+
+{% callout %}
+**Note**: table elements are not currently supported but will likely be added
+in a future release.
+{% /callout %}
+
+---
+
+## Included marks
+
+The following marks are supported by the %docs app and you can use them to
+write docs right away.
+
+### `%udon`
+
+Udon is a markdown-like language native to hoon, with a parser built into the
+hoon compiler. Here is its syntax in brief:
+
+- The first line of the `.udon` document **must** be a single rune: `;>`.
+  This tells the compiler to interpret everything following as udon.
+- **Paragraphs**: Content on a single line will be made into a paragraph. Paragraphs
+  may be hard-wrapped, so consecutive lines of text will become a single
+  paragraph. The paragraph will be ended by an empty line or other block
+  element.
+- **Headers**: lines beginning with 1-6 `#`s followed by a single space and then
+  some content (e.g. `## foo`) will be made into headers. The number of `#`s
+  dictates the header level.
+- **Italics**: content wrapped in single `_`s (e.g. `_foo_`) will be made italic.
+- **Bold**: content wrapped in single `*`s (e.g. `*foo*`) will be made bold.
+- **Unordered lists**: lines beginning with `-` followed by a space will be made
+  into items in a list. List lines can be hard-wrapped, with two spaces
+  beginning each subsequent line to be included in the list. Lists can be nested
+  by indenting the `-`s a further two spaces for each level of nesting.
+- **Ordered lists**: lines beginning with `+` followed by a space will be made into
+  ordered lists, and numbered in the order they appear. These have the same
+  wrapping and nesting logic as unordered lists.
+- **Links**: this is standard markdown syntax: square bracks containing the display
+  content and then parentheses containing the URL, e.g.
+  `[foo](http://example.com)`. The URL may also be a relative link or an anchor
+  link.
+- **Images**: this is also standard markdown; a link with an exclamation mark at the
+  beginning, e.g. `![foo](http://example.com/image.png)`. The square brackets
+  contain the alt-text and the the parentheses contain the image URL.
+- **Inline code**: text wrapped in single backticks will be rendered verbatim in a
+  monospace font.
+- **Fenced codeblocks**: Triple-backticks on their own line begin and end a
+  codeblock. All lines in between will be rendered verbatim in a monospace font.
+  Note that udon does not support a language specification after the opening
+  backticks like markdown does.
+- **Horizontal rules**: Three or more hyphens (`---`) will create a horizontal rule.
+- **Block quotes**: a line beginning with `>` creates a block quote. This may be
+  hard-wrapped, as long as the next line is indented two spaces. Block quotes
+  may contain anything, including other blockquotes.
+- **Line breaks**: A line ending in a single backslash will have a line break
+  inserted at the end, so it will not flow together with the subsequent line as
+  is usually the case.
+- **Escape characters**: You may prefix Udon syntax with a backslash to have it
+  treated as the literal text.
+- **Hoon constants**: Udon will automatically render any values with atom aura
+  syntax as inline code. It'll also render arms like `++foo:bar`, `+$baz`, and
+  `+*foo:bar:baz`, as inline code.
+- **Sail**: this is hoon's native XML syntax. Udon will parse it, execute it, and
+  include the `+$manx`es produced in the resulting document. This means you
+  can embed arbitrary hoon in the document. There is little formal sail
+  documentation, but you can refer to the [`;` (mic) rune
+  reference](/reference/hoon/rune/mic) for most of its runes and some
+  rudimentary examples.
+
+{% callout %}
+**Note**: Udon is quite strict on its syntax, and may fail to parse if it's
+incorrect.
+{% /callout %}
+
+### `%txt`
+
+The `%docs` app supports plain `.txt` files. The file will be rendered as a
+preformatted codeblock with wrapping.
+
+### `%html`
+
+Ordinary HTML files may be used, but note the tag and structural restrictions
+described in the `%docu` mark description above.
+
+### `%gmi`
+
+
+Gemtext is an ultra-minimal markup format developed for the [Gemini
+project](https://gemini.circumlunar.space/), an internet protocol for serving
+light-weight hypertext, inspired by Gopher. Its file extension is `.gmi`.
+
+Gemtext interprets things on a line-by-line basis, and does not support
+different types on a single line. Every line is a separate element, with the
+exception of fenced codeblocks which may span multiple lines. In brief, here is
+the syntax:
+
+- **Paragraphs**: Plain text on a single line constitutes a paragraph. Note
+  hard-wrapping is not supported.
+- **Links**: lines beginning with `=>` followed by a space create a link. After the
+  space, the target URL is given. After the URL, there may optionally be a space
+  and then some display text for the link. If no displace text is given, the URL
+  itself will be displayed.
+- **Codeblocks**: triple-backticks at the beginning of a line begin and end a
+  codeblock. All text in between will be rendered verbatim in a monospace font.
+  The opening backticks may optionally be followed by some text, which will be
+  used as the language tag.
+- **Headings**: 1-3 `#`s followed by text create a heading. The number of `#`s
+  determine the heading level.
+- **Lists**: lines beginning with `*` followed by a space and then text will create
+  a list item.
+- **Quotes**: lines beginning with `>` followed by a space creates a blockquote.

content/reference/additional/docs-app/index-file.md

@@ -0,0 +1,45 @@
++++
+title = "Index File"
+weight = 10
+template = "doc.html"
++++
+
+Each desk with docs may include a `doc.toc` file in its root. A `doc.toc` file
+looks something like this:
+
+```
+/dev                  Developer
+  /hark-store         Hark-store
+    /overview/udon    Overview
+    /types/udon       Data Types
+    /pokes/udon       Pokes
+    /paths/udon       Subscription Paths
+    /scry/udon        Scry Endpoints
+  /settings-store     Settings-store
+    /overview/udon    Overview
+    /types/udon       Data Types
+    /pokes/udon       Pokes
+    /paths/udon       Subscription Paths
+    /scry/udon        Scry Endpoints
+```
+
+Each line contains a pair of path and title with at least one space in between.
+A path with a single element (such as `/dev` and `/hark-store`) denotes a
+directory. A path with two elements (such as `/overview/udon`) denotes a file,
+where the first element is the name and the second is the mark.
+
+Any directory structure and depth is allowed. The hierarchy is determined by
+indentation. Each double-space indent denotes a nesting level. Two spaces is one
+level, four spaces is two levels, etc.
+
+The root is the `/doc` directory of your desk, it should not be explicitly
+listed.
+
+The title specified will be displayed at the top of the document and in the
+table of contents for the desk.
+
+If no `doc.toc` file is included, but a desk does have other files under
+`/doc`, the Docs app will infer a table of contents from the directory
+structure, and _all_ files will be included. Files are ordered alphabetically,
+except that 'overview' always come first. For titles, hyphens in the filename
+are replaced with spaces and the whole is converted to Title Case.

content/reference/additional/docs-app/overview.md

@@ -0,0 +1,47 @@
++++
+title = "Overview"
+weight = 1
+template = "doc.html"
++++
+
+The `%docs` app allows you to include documentation with the desks you
+distribute, making them available for easy browsing by users and developers.
+
+The `%docs` app will automatically detect and publish any docs included with
+any installed desks. As long as they're in the correct place and of a filetype
+with appropriate `mark` conversion methods, they'll be picked up.
+
+A `doc.toc` file may be included in the root of the desk, specifying the files
+to be included, their `mark`s, and their titles. See the [Index
+File](/reference/additional/docs-app/index-file) section for details.
+
+The files will be in a `/doc` directory in the root of the desk. They may be of
+any filetype, as long as it has conversion methods to the `%docu` mark used by
+the `%docs` app. The `%docs` app includes parsers and conversion methods for
+the following marks by default:
+
+- `%txt` - Ordinary `.txt` text files.
+- `%udon` - A markdown-like format that supports embedded hoon.
+- `%gmi` - An ultra-minimalist markup format called "gemtext".
+- `%html` - An ordinary `.html` file.
+
+For more details of these file formats, as well as details of the `%docu` mark
+and other format requirements of the `%docs` app, see the [File
+Format](/reference/additional/docs-app/file-format) section.
+
+Apart from the `mark` and location requirements described above, there are no
+particular restrictions on how you organise your docs, or what docs you
+include. There are, however, some general recommendations detailed in the
+[Suggested Structure](/reference/additional/docs-app/structure) section.
+
+## Dev desk
+
+To include docs in your own desk, there are a few files you'll need (mark
+files, etc). These are included in the `docs-dev` dev desk in the [github
+repo](https://github.com/tinnus-napbus/docs-app). These files are all
+symlinked, so you'll need to clone the whole repo, then copy them across with
+something like:
+
+```
+cp -rL git/docs-app/docs-dev/* /path/to/your/development/desk
+```

content/reference/additional/docs-app/structure.md

@@ -0,0 +1,91 @@
++++
+title = "Suggested Structure"
+weight = 15
+template = "doc.html"
++++
+
+Here we'll discuss recommendations and best practices for your docs. The
+%docs app doesn't impose any restrictions on the structure of your docs, so
+you're free to do things differently if you feel it's appropriate.
+
+## User docs
+
+For the most part, user documentation depends on the nature of your app, so it's
+up to you how you document it. There are, however, a couple of things that are
+advisable to include:
+
+### General info
+
+You should include some of the following information (as appropriate) in either
+a distinct informational document or at the top of the first document:
+
+- **Publisher/developer/contributors**: Your `@p`, the `@p` you distribute the app
+  from, people who have helped build the app, etc.
+- **License**: MIT, GPL, etc.
+- **Source**: Github link (or similar) for the repo containing the source code.
+- **Issues**: Where to file issues (typically also the Github repo).
+- **Group**: If you have a group associated with your app (for support, discussion,
+  or what have you), you can include the `~host/group-name`.
+- Any other metadata, links, info, etc, you feel are appropriate to include.
+
+### Changelog
+
+Another useful document is a changelog. For each version you release, you can
+add a new section at the top with the version number, release date, and a brief
+summary of the changes.
+
+---
+
+## Developer docs
+
+Like user docs, you're free to document things as you see fit, but it's helpful
+to include particular things with a standard format. These are documented
+below.
+
+{% callout %}
+**Note**: If your desk has a dev version, it's advisable to link to it
+somewhere sensible in the developer documentation.
+{% /callout %}
+
+### API Reference
+
+If there's any chance other developers will want to interface with agents on
+your desk, you should include reference information about the scry endpoints,
+pokes, subscription paths, and (if appropriate) data types of each agent.
+
+These things can either be on a single page, or each have their own separate
+page, depending on their complexity.
+
+#### Scry endpoints
+
+Scry endpoints may either be organised by their paths or by short summaries of
+each endpoint's purpose. Scry paths should be in the format
+`/[care]/rest/of/path`, like `/x/foo/bar`. Any variable parts of the scry path
+should have square brackets like `/x/foo/[ship]`. The data type of the response
+should be specified, and it's helpful to include an example of a scry and the
+pretty-printed response in a codeblock.
+
+#### Pokes
+
+Any poke actions an agent will accept should be documented. It's helpful to
+include an example poke. You may also wish to provide a JSON example if people
+can interact with your agent through Eyre's channel system or similar.
+
+If your agent's pokes are organised around something like an "action" tagged
+union structure, the poke reference might work better as a kind of data type
+reference for that action structure rather than specifically pokes.
+
+#### Subscriptions
+
+Subscription paths should be documented in a similar manner to the scry
+reference. If the updates your agent can send out to subscribers are organised
+around something like an "update" tagged union structure, the subscription
+reference might work better as just a brief path reference, and documentation of
+the updates can be done separately.
+
+#### Data types
+
+The inclusion of a data types section depends on the complexity of an agent's
+data types. If such a reference is appropriate, it's best to structure it with a
+separate section for each type. The type definition should be included in a
+codeblock, as well as a brief description of its purpose.