xodio / xod-docs Goto Github PK

In the Fritzing diagram in 110-ldr the leg of the photosensor's voltage divider with the resistor is tied to the +5 volt rail. I think that should actually be tied to ground.

Reference

The https://xod.io/docs/reference/globals/ article is required by xodio/xod#1889

Let’s document all existing globals there.

These topics are important to make new C++ nodes but are not covered anyhow:

• Reading XOD strings: iterating, dumping to a buffer
• Producing XOD strings: views, lifetime, double buffering
• Using custom type lists, implementing new view types

The Data Types Reference should describe the Errcode data type and list all its possible values.

As mentioned in #63 (comment):

We have a few conventions that are scattered through the docs or even unwritten.
For example:

We have a few conventions that are scattered through the docs or even unwritten.
For example:

• any nodes that create a new type to work with hardware should be named as xxx-device
• node that initialises hardware module should be named init
• names of any nodes which do instructions "what to do" in imperative style must begin with a verb (init, read-byte, pair-tag, write-line, etc)
• nodes that "unfold" complex types into more primitive ones are named unpack-xxx
• example patches are named example-xxx
  (and probably a few others that I forgot to mention)

It will be cool to summarize these in a single guide article.

The only way to learn about in is through Medium announce of 0.25.0.

Rationale

XOD docs in this repository is a code that should be formatted properly. We have Prettier, but formatting with it is not enforced. We can’t actually make pretty-printing check a part of PR validation because it is too strict, thus it will confuse people who just want to fix a typo involving a slight paragraph reflow. Such PRs should not trigger a CI error.

So, a linter should be more relaxed than the prettier check. Here is a possible solution: https://github.com/markdownlint/markdownlint

Acceptance criteria

• I can yarn lint to check everything with the linter
• Max line length is set to 100
• All existing content is tweaked to pass the linter check
• After doing yarn prettier:all the yart lint produces no errors
• CircleCI is set up and invokes the linter on PRs

Currently, the shortcuts reference list items through plain HTML tables.

The items are a highly structured data that might be defined in a YAML file. This way is preferable because if we want to make a slight change in the HTML markup, we are in trouble: changes in every line of the table across all translations will be required.

To support translations the YAML source can have a separate description field for every language:

- shortcut:
    mac: ⌘ N
    pc: Ctrl+N
    action:
      EN: "New patch"
      DE: "Neu patch"
      RU: "Новый патч"

May reuse parts of the xodio/xod#1769 description

In the tutorial. The Diagram shows the button set to D0
In the Pictorial, the Button is wired to D13

This created confusion when I went to try the tutorial. What saved me is that it specifically states to set the port value of the button node. this created some confusion to set to 0 per picture or 13 per the wire diagram.

The Shortcuts reference page always shows shortcuts for both Mac and PC producing clutter. A reader either uses a Mac or PC, let’s show only shortcuts relevant to him. A small embedded JS script can determine the reader’s OS and hide uninteresting shortcuts/items.

In PR xodio/xod#1512 was added port literals for STM32, like "PA13", "PB8" and etc.
We have to update port literals in the docs.