417b90a7e5
- add additional parameters parsing (other implementations will just
ignore them). E.g. if in RST we have:
.. code:: nim
:test: "nim c $1"
...
then in Markdown that will be:
```nim test="nim c $1"
...
```
- implement Markdown interpretation of additional indentation which is
less than 4 spaces (>=4 spaces is a code block but it's not
implemented yet). RST interpretes it as quoted block, for Markdown it's
just normal paragraphs.
- add separate `md2html` and `md2tex` commands. This is to separate
Markdown behavior in cases when it diverges w.r.t. RST significantly —
most conspicously like in the case of additional indentation above, and
also currently the contradicting inline rule of Markdown is also turned
on only in `md2html` and `md2tex`. **Rationale:** mixing Markdown and
RST arbitrarily is a way to nowhere, we need to provide a way to fix the
particular behavior. Note that still all commands have **both** Markdown
and RST features **enabled**. In this PR `*.nim` files can be processed
only in Markdown mode, while `md2html` is for `*.md` files and
`rst2html` for `*.rst` files.
- rename `*.rst` files to `.*md` as our current default behavior is
already Markdown-ish
- convert code blocks in `docgen.rst` to Markdown style as an example.
Other code blocks will be converted in the follow-up PRs
- fix indentation inside Markdown code blocks — additional indentation
is preserved there
- allow more than 3 backticks open/close blocks (tildas \~ are still not
allowed to avoid conflict with RST adornment headings) see also
https://github.com/nim-lang/RFCs/issues/355
- better error messages
- (other) fix a bug that admonitions cannot be used in sandbox mode; fix
annoying warning on line 2711
3.8 KiB
================= API naming design
.. default-role:: code .. include:: rstcommon.rst
The API is designed to be easy to use and consistent. Ease of use is measured by the number of calls to achieve a concrete high-level action.
Naming scheme
The library uses a simple naming scheme that makes use of common abbreviations to keep the names short but meaningful. Since version 0.8.2 many symbols have been renamed to fit this scheme. The ultimate goal is that the programmer can guess a name.
=================== ============ ======================================
English word To use Notes
=================== ============ ======================================
initialize initT init is used to create a
value type T
new newP new is used to create a
reference type P
find find should return the position where
something was found; for a bool result
use contains
contains contains often short for find() >= 0
append add use add instead of append
compare cmp should return an int with the
< 0 == 0 or > 0 semantics;
for a bool result use sameXYZ
put put, []= consider overloading []= for put
get get, [] consider overloading [] for get;
consider to not use get as a
prefix: len instead of getLen
length len also used for number of elements
size size, len size should refer to a byte size
capacity cap
memory mem implies a low-level operation
items items default iterator over a collection
pairs pairs iterator over (key, value) pairs
delete delete, del del is supposed to be faster than
delete, because it does not keep
the order; delete keeps the order
remove delete, del inconsistent right now
remove-and-return pop Table/TableRef alias to take
include incl
exclude excl
command cmd
execute exec
environment env
variable var
value value, val val is preferred, inconsistent right
now
executable exe
directory dir
path path path is the string "/usr/bin" (for
example), dir is the content of
"/usr/bin"; inconsistent right now
extension ext
separator sep
column col, column col is preferred, inconsistent right
now
application app
configuration cfg
message msg
argument arg
object obj
parameter param
operator opr
procedure proc
function func
coordinate coord
rectangle rect
point point
symbol sym
literal lit
string str
identifier ident
indentation indent
=================== ============ ======================================