jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve Markdown code blocks & start moving docs to Markdown style (#19954)

Browse source 
- 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
This commit is contained in:
Andrey Makarov 2022-07-15 20:27:54 +03:00 • committed by GitHub
commit 417b90a7e5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
47 changed files with 341 additions and 126 deletions
Download patch file Download diff file Expand all files Collapse all files

197
doc/niminst.md Normal file
View file

@ -0,0 +1,197 @@
=========================
niminst User's manual
=========================
:Author: Andreas Rumpf
:Version: |nimversion|
.. default-role:: code
.. include:: rstcommon.rst
.. contents::
Introduction
============
niminst is a tool to generate an installer for a Nim program. Currently
it can create an installer for Windows
via `Inno Setup <http://www.jrsoftware.org/isinfo.php>`_ as well as
installation/deinstallation scripts for UNIX. Later versions will support
Linux' package management systems.
niminst works by reading a configuration file that contains all the
information that it needs to generate an installer for the different operating
systems.
Configuration file
==================
niminst uses the Nim `parsecfg <parsecfg.html>`_ module to parse the
configuration file. Here's an example of how the syntax looks like:
.. include:: mytest.cfg
:literal:
The value of a key-value pair can reference user-defined variables via
the `$variable` notation: They can be defined in the command line with the
`--var:name=value`:option: switch. This is useful to not hard-coding the
program's version number into the configuration file, for instance.
It follows a description of each possible section and how it affects the
generated installers.
Project section
---------------
The project section gathers general information about your project. It must
contain the following key-value pairs:
==================== =======================================================
Key description
==================== =======================================================
`Name` the project's name; this needs to be a single word
`DisplayName` the project's long name; this can contain spaces. If
not specified, this is the same as `Name`.
`Version` the project's version
`OS` the OSes to generate C code for; for example:
`"windows;linux;macosx"`
`CPU` the CPUs to generate C code for; for example:
`"i386;amd64;powerpc"`
`Authors` the project's authors
`Description` the project's description
`App` the application's type: "Console" or "GUI". If
"Console", niminst generates a special batch file
for Windows to open up the command-line shell.
`License` the filename of the application's license
==================== =======================================================
`files` key
-------------
Many sections support the `files` key. Listed filenames
can be separated by semicolon or the `files` key can be repeated. Wildcards
in filenames are supported. If it is a directory name, all files in the
directory are used::
[Config]
Files: "configDir"
Files: "otherconfig/*.conf;otherconfig/*.cfg"
Config section
--------------
The `config` section currently only supports the `files` key. Listed files
will be installed into the OS's configuration directory.
Documentation section
---------------------
The `documentation` section supports the `files` key.
Listed files will be installed into the OS's native documentation directory
(which might be ``$appdir/doc``).
There is a `start` key which determines whether the Windows installer
generates a link to e.g. the ``index.html`` of your documentation.
Other section
-------------
The `other` section currently only supports the `files` key.
Listed files will be installed into the application installation directory
(`$appdir`).
Lib section
-----------
The `lib` section currently only supports the `files` key.
Listed files will be installed into the OS's native library directory
(which might be `$appdir/lib`).
Windows section
---------------
The `windows` section supports the `files` key for Windows-specific files.
Listed files will be installed into the application installation directory
(`$appdir`).
Other possible options are:
==================== =======================================================
Key description
==================== =======================================================
`BinPath` paths to add to the Windows `%PATH%` environment
variable. Example: ``BinPath: r"bin;dist\mingw\bin"``
`InnoSetup` boolean flag whether an Inno Setup installer should be
generated for Windows. Example: `InnoSetup: "Yes"`
==================== =======================================================
UnixBin section
---------------
The `UnixBin` section currently only supports the `files` key.
Listed files will be installed into the OS's native bin directory
(e.g. ``/usr/local/bin``). The exact location depends on the
installation path the user specifies when running the `install.sh` script.
Unix section
------------
Possible options are:
==================== =======================================================
Key description
==================== =======================================================
`InstallScript` boolean flag whether an installation shell script
should be generated. Example: `InstallScript: "Yes"`
`UninstallScript` boolean flag whether a de-installation shell script
should be generated.
Example: `UninstallScript: "Yes"`
==================== =======================================================
InnoSetup section
-----------------
Possible options are:
==================== =======================================================
Key description
==================== =======================================================
`path` Path to Inno Setup.
Example: ``path = r"c:\inno setup 5\iscc.exe"``
`flags` Flags to pass to Inno Setup.
Example: `flags = "/Q"`
==================== =======================================================
C_Compiler section
------------------
Possible options are:
==================== =======================================================
Key description
==================== =======================================================
`path` Path to the C compiler.
`flags` Flags to pass to the C Compiler.
Example: `flags = "-w"`
==================== =======================================================
Real-world example
==================
The installers for the Nim compiler itself are generated by niminst. Have a
look at its configuration file:
.. include:: ../compiler/installer.ini
:literal: