mirrors/Nim
1
0
Fork 0
mirror of https://github.com/nim-lang/Nim.git synced 2025-12-29 09:24:36 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
0641df33aabe25d0c83b00a334cc157a8ca50607
Nim/doc/nimfix.md
Andrey Makarov 417b90a7e5 Improve Markdown code blocks & start moving docs to Markdown style (#19954) 
- 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
2022-07-15 19:27:54 +02:00

1.6 KiB
Raw Blame History

.. default-role:: code

===================== Nimfix User Guide

:Author: Andreas Rumpf :Version: |nimversion|

WARNING: Nimfix is currently beta-quality.

Nimfix is a tool to help you upgrade from Nimrod (<= version 0.9.6) to Nim (=> version 0.10.0).

It performs 3 different actions:

  1. It makes your code case consistent.
  2. It renames every symbol that has a deprecation rule. So if a module has a rule {.deprecated: [TFoo: Foo].} then TFoo is replaced by Foo.
  3. It can also check that your identifiers adhere to the official style guide and optionally modify them to do so (via --styleCheck:auto).

Note that nimfix defaults to overwrite your code unless you use --overwriteFiles:off! But hey, if you do not use a version control system by this day and age, your project is already in big trouble.

Installation

Nimfix is part of the compiler distribution. Compile via::

nim c compiler/nimfix/nimfix.nim mv compiler/nimfix/nimfix bin

Or on windows::

nim c compiler\nimfix\nimfix.nim move compiler\nimfix\nimfix.exe bin

Usage

Usage: nimfix [options] projectfile.nim

Options:

--overwriteFiles:on|off overwrite the original nim files. DEFAULT is ON! --wholeProject overwrite every processed file. --checkExtern:on|off style check also extern names --styleCheck:on|off|auto performs style checking for identifiers and suggests an alternative spelling; 'auto' corrects the spelling.

In addition, all command line options of Nim are supported.