From 417b90a7e5b88bfc0ad1bfbbc81a3205c99e128e Mon Sep 17 00:00:00 2001 From: Andrey Makarov Date: Fri, 15 Jul 2022 20:27:54 +0300 Subject: Improve Markdown code blocks & start moving docs to Markdown style (#19954) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- doc/manual/var_t_return.md | 23 +++++++++++++++++++++++ doc/manual/var_t_return.rst | 23 ----------------------- 2 files changed, 23 insertions(+), 23 deletions(-) create mode 100644 doc/manual/var_t_return.md delete mode 100644 doc/manual/var_t_return.rst (limited to 'doc/manual') diff --git a/doc/manual/var_t_return.md b/doc/manual/var_t_return.md new file mode 100644 index 000000000..f5c5bc4c0 --- /dev/null +++ b/doc/manual/var_t_return.md @@ -0,0 +1,23 @@ +.. default-role:: code +.. include:: ../rstcommon.rst + +Memory safety for returning by `var T` is ensured by a simple borrowing +rule: If `result` does not refer to a location pointing to the heap +(that is in `result = X` the `X` involves a `ptr` or `ref` access) +then it has to be derived from the routine's first parameter: + +.. code-block:: nim + proc forward[T](x: var T): var T = + result = x # ok, derived from the first parameter. + + proc p(param: var int): var int = + var x: int + # we know 'forward' provides a view into the location derived from + # its first argument 'x'. + result = forward(x) # Error: location is derived from `x` + # which is not p's first parameter and lives + # on the stack. + +In other words, the lifetime of what `result` points to is attached to the +lifetime of the first parameter and that is enough knowledge to verify +memory safety at the call site. diff --git a/doc/manual/var_t_return.rst b/doc/manual/var_t_return.rst deleted file mode 100644 index f5c5bc4c0..000000000 --- a/doc/manual/var_t_return.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. default-role:: code -.. include:: ../rstcommon.rst - -Memory safety for returning by `var T` is ensured by a simple borrowing -rule: If `result` does not refer to a location pointing to the heap -(that is in `result = X` the `X` involves a `ptr` or `ref` access) -then it has to be derived from the routine's first parameter: - -.. code-block:: nim - proc forward[T](x: var T): var T = - result = x # ok, derived from the first parameter. - - proc p(param: var int): var int = - var x: int - # we know 'forward' provides a view into the location derived from - # its first argument 'x'. - result = forward(x) # Error: location is derived from `x` - # which is not p's first parameter and lives - # on the stack. - -In other words, the lifetime of what `result` points to is attached to the -lifetime of the first parameter and that is enough knowledge to verify -memory safety at the call site. -- cgit 1.4.1-2-gfad0