mirror of
https://github.com/nim-lang/Nim.git
synced 2025-12-30 18:02:05 +00:00
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
86 lines
3.8 KiB
Markdown
86 lines
3.8 KiB
Markdown
=================
|
|
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
|
|
=================== ============ ======================================
|