sogaiu

Draft - Summary of Recommendations for Janet Docstrings

1. Emphasis

   • Use distinct characters for emphasis and strong emphasis.
   • Don’t use doubled-character delimiters.
   • Simplify emphasis rules. May be don't allow nesting?
   • Introduce special syntax for intraword emphasis, with ~ behaving like a space as far as parsing emphasis goes, but render as nothing.

2. Reference links - Don't have any kind of links

• Don’t make parsing something as a link depend on whether a reference link definition exists elsewhere in the document.

sogaiu

  ``
  (os/compiler)

  Get the compiler used to compile the interpreter. Returns one of:

  * :gcc

  * :clang

sogaiu

Background

In order to get some idea of which "Markdown" features are being used by existing Janet docstrings, generated some data using a simple .janet script (see last file in gist). The output consists of multiple lines of text where (roughly) each line indicates the presence of the first **, *, -, _, or ` in a given docstring.

Explanation of Each Line of Data

sogaiu

How to find "Subscriptions" or "Automatic Payments" - RESOLVED

"Subscriptions" is changed to "Automatic Payments", navigation steps below:

1. (Top right menu) Click the "Gear" icon, to get to Account
2. In Account, click Payments (sub Top menu option)
3. Click button on lower menu Manage Automatic Payments
4. Select radio button Show active

---

sogaiu

Background

• Manage your Apple Account

  What is Apple Account?

  An Apple Account is the personal account you use to access Apple services like the App Store, iCloud, Messages, the Apple Online Store, FaceTime, and more. It includes the information you use to sign in, as well as all the contact, payment, and security details that you’ll use across Apple services.

  What is the difference between an Apple ID and an Apple Account? >

sogaiu

Background

This document describes features that Janet docstrings exhibit (along with a few that are not). As there was no explicit convention established early on nor any supporting automation, the docstrings vary a bit in the way the features have been applied to them.

Below are some descriptions of features along with concrete examples for existing Janet docstrings:

sogaiu

exhibit a - tight

• one item
• another item
• third item

exhibit b - pseudo-loose

• one item

sogaiu

Background

Janet's docstrings "support some subset of Markdown"...but exactly what?

janet-lang.org repository

• #99 Add documentation page - gives a pretty good description (though at present, there is no support for block quotes)

janet repository

• #511 Add formatter for Markdown-formatted docstrings - has description of constructs originally supported in pyrmont's PR. There are some differences compared to what is currently supported (e.g. ATM no support for + as a list item marker).
• #694 A trailing backslash as linebreak in function docstring. - in c911f7c4, the commit that addressed the issue, doc-format was substantially changed by bakpakin

sogaiu

note that although the term "loose list" is used below, what actually happens currently is that multiple one element lists are created giving the illusion of a loose list.

one unordered list

loose list

• debug/stack
• file/read
• file/seek
• match

sogaiu

# XXX:
#
# * spork/pm.janet's resolve-bundle has a docstring that looks like
#   it might eventually end up with a nested list.
#
# * could a nested list item end up looking like an ordinary "indented"
#   line?

# assumes source has been formatted with doc-format such that there is
# no indentation and no color (which implies list item markers have