diff --git a/content/docs/code-styles.org b/content/docs/code-styles.org index 3c1986f..99985de 100644 --- a/content/docs/code-styles.org +++ b/content/docs/code-styles.org @@ -1,5 +1,5 @@ #+title: Code styles -#+weight: 4 +#+weight: 2 #+bibliography: bibliography.bib All of the above affirmations are taken from the [[https://ziglang.org/documentation/master/#Style-Guide][Zig Style Guide]] itself. diff --git a/content/docs/concurrency/_index.org b/content/docs/concurrency/_index.org index e1210cf..0eb812b 100644 --- a/content/docs/concurrency/_index.org +++ b/content/docs/concurrency/_index.org @@ -1,5 +1,5 @@ #+title: Concurrency -#+weight: 15 +#+weight: 80 #+hugo_cascade_type: docs #+math: true diff --git a/content/docs/external-files.org b/content/docs/external-files.org index 08a08c9..278737d 100644 --- a/content/docs/external-files.org +++ b/content/docs/external-files.org @@ -1,5 +1,5 @@ #+title: External files -#+weight: 2 +#+weight: 8 ** Reading external files Reading external files is a common task in programming. In this section we are going to look at a few different ways to achieve it. diff --git a/content/docs/introduction.org b/content/docs/introduction/_index.org similarity index 53% rename from content/docs/introduction.org rename to content/docs/introduction/_index.org index e31bc52..32f24d3 100644 --- a/content/docs/introduction.org +++ b/content/docs/introduction/_index.org @@ -66,120 +66,7 @@ To read this documentation interactively, you can use Emacs. For that, you need to have the Emacs version =29.2= or =29.3= installed to use some plugins that will be installed later. You can find the installation instructions [[https://www.gnu.org/software/emacs/download.html][here]], the instructions will depend on your system. -For example, if you are using Fedora, you can install Emacs trought it package manager: -#+begin_src shell - sudo dnf install emacs -#+end_src - -*** Clone this documentation -You need to clone this repository. -You can use this command to clone: - -#+begin_src sh - git clone https://github.com/Pismice/HEIG_ZIG.git -#+end_src - -*** Using Emacs -To use Emacs with this documentation, you need to follow these instructions. - -Launch Emacs and you will have a welcome window. -To navigate to this documentation, you need to use the following shortcut: ~C-x C-f~ (~ctrl-x ctrl-f~). -This will open a command in the bottom left corner. -With this command, you can select the path of the file you want to open. - -If you want to open the introduction file, you need in the first place enter the directory path where you have cloned this documentation. -When you are in the root directory of the documentation, you can find all the documentation files in the directory: -#+begin_example sh -./content/docs/* -#+end_example - -And this introduction file can be found in : -#+begin_example sh -./content/docs/introduction.org -#+end_example - -More Emacs documentation can be found [[https://www.gnu.org/software/emacs/tour/][here]] if you want to further tweak your configuration or do other specific things. - -Now that we have opened the file, we can then start installing the necessary plugins to use the documentation with Literate programming. - -1. _Install Zig emacs org babel plugin_ -To install the plugins that will be used to interact with the example codes, you need to follow the different steps. - -Open this =introduction.org= file with Emacs. -Below, you will find instructions to create your Emacs configuration. -This configuration will be built interactively. - -1.1. _First step_ -Place your cursor in the code block below and use ~C-c C-c~ (~ctrl-c ctrl-c~) to evaluate the code below. -It will add a shell interpreter inside org-babel configuration, it will be used when shell commands are evaluated. -#+begin_src emacs-lisp - (add-to-list 'org-babel-load-languages '(shell . t)) - (org-babel-do-load-languages 'org-babel-load-languages org-babel-load-languages) -#+end_src - -1.2. _Second step_ -The shell command will clone an org babel [[https://github.com/samuel-schlaeppy/ob-zig.el.git][zig plugin]] necessary to execute some Zig examples directly in Emacs with Org babel. - -The ~HEADER~ parameter below (in the code block) configures the directory path by default. -You can change the directory where the plugin will be installed (change the argument after the ~:dir~ -> ~/CHANGE-ME~). - -Once you have changed the ~HEADER~ parameter, you can place your cursor in the code block below and use ~C-c C-c~ (~ctrl-c ctrl-c~) to evaluate the code below. -#+HEADER: :dir ~/CHANGE-ME -#+begin_src shell - git clone https://github.com/samuel-schlaeppy/ob-zig.el.git -#+end_src - -2. _Create an emacs configuration file_ -In the last section, the plugin =Ob-Zig= has been installed, this plugin will help to evaluate Zig example codes. -To use correctly this plugin, in the code block below, you need to change the string ~./PATH-WHERE-THE-OB-ZIG-PLUGIN-IS-INSTALLED/ob-zig.el~ where you have cloned the plugin =ob-zig.el=. -In addition, you need to change in the code block the string =PATH-TO-THE-ZIG-EXECUTABLE= to insert the path of the Zig executable. - -After that, the following command ~C-c C-v t~ (~ctrl-c ctrl-v t~) will produce a ~zigIterativeProgramming.el~ file. -This file can be loaded from your emacs configuration (see section below). -#+begin_src emacs-lisp :tangle zigIterativeProgramming.el - (setq base_dir "~/PATH-WHERE-THE-ZIG-PLUGIN-IS-INSTALLED/ob-zig.el") - (setq org-babel-zig-compiler "PATH-TO-THE-ZIG-EXECUTABLE") -#+end_src - -#+begin_src emacs-lisp :tangle zigIterativeProgramming.el - (require 'package) - (add-to-list 'package-archives - '("melpa" . "https://melpa.org/packages/")) - (package-initialize) - (package-refresh-contents) - - (defun install-custom-pkg (pck) - (if (featurep pck) - (message "The package %s is already installed !" pck) - (package-install pck) - )) - - (install-custom-pkg 'zig-mode) - (install-custom-pkg 'lsp-mode) - (require 'lsp-mode) - (add-hook 'zig-mode-hook #'lsp) - - (let ((local-file-path (expand-file-name "ob-zig.el" base_dir))) - (setq org-babel-zig-compiler local-file-path) - (load-file local-file-path) - ) - - (custom-set-variables - ;; custom-set-variables was added by Custom. - ;; If you edit it by hand, you could mess it up, so be careful. - ;; Your init file should contain only one such instance. - ;; If there is more than one, they won't work right. - '(org-babel-load-languages '((C . t) (emacs-lisp . t) (shell . t)))) -#+end_src - -3. _Execute the configuration file from the configuration_ -You can put the code below in your ~init.el~ it will load the file produced before and load the necessary package to learn Zig with literate programming. -But you need the specify the directory path of the ~zigIterativeProgramming.el~ file (first line below). -(the ~init.el~ can be found in ~~/.emacs.d/~ or can be created in ~~/.config/emacs/~ -#+begin_src emacs-lisp - (let ((file_dir "~/PATH-TO-THE-zigIterativeProgramming-file")) - (load-file (expand-file-name "zigIterativeProgramming.el" file_dir))) -#+end_src +In order to follow a step by step installation for this usage you can go the [[file:./emacs-config][Emacs configuration]] section. ** Enjoy the documentation We wish you a good reading and hope that you will learn a lot from this documentation. diff --git a/content/docs/introduction/emacs-config.org b/content/docs/introduction/emacs-config.org new file mode 100644 index 0000000..a36aa2a --- /dev/null +++ b/content/docs/introduction/emacs-config.org @@ -0,0 +1,119 @@ +#+title: Emacs configuration + +First use your package manager or the [[https://www.gnu.org/software/emacs/download.html][official website]] to install Emacs. + +For example if you are using Fedora, you can install Emacs trough [[https://docs.fedoraproject.org/en-US/quick-docs/dnf/][dnf]] : +#+begin_src shell + sudo dnf install emacs +#+end_src + +*** Clone this documentation +You need to clone this repository. +You can use this command to clone: + +#+begin_src sh + git clone https://github.com/Pismice/HEIG_ZIG.git +#+end_src + +*** Using Emacs +To use Emacs with this documentation, you need to follow these instructions. + +Launch Emacs and you will have a welcome window. +To navigate to this documentation, you need to use the following shortcut: ~C-x C-f~ (~ctrl-x ctrl-f~). +This will open a command in the bottom left corner. +With this command, you can select the path of the file you want to open. + +If you want to open the introduction file, you need in the first place enter the directory path where you have cloned this documentation. +When you are in the root directory of the documentation, you can find all the documentation files in the directory: +#+begin_example sh +./content/docs/* +#+end_example + +And this introduction file can be found in : +#+begin_example sh +./content/docs/introduction.org +#+end_example + +More Emacs documentation can be found [[https://www.gnu.org/software/emacs/tour/][here]] if you want to further tweak your configuration or do other specific things. + +Now that we have opened the file, we can then start installing the necessary plugins to use the documentation with Literate programming. + +1. _Install Zig emacs org babel plugin_ +To install the plugins that will be used to interact with the example codes, you need to follow the different steps. + +Open this =introduction.org= file with Emacs. +Below, you will find instructions to create your Emacs configuration. +This configuration will be built interactively. + +1.1. _First step_ +Place your cursor in the code block below and use ~C-c C-c~ (~ctrl-c ctrl-c~) to evaluate the code below. +It will add a shell interpreter inside org-babel configuration, it will be used when shell commands are evaluated. +#+begin_src emacs-lisp + (add-to-list 'org-babel-load-languages '(shell . t)) + (org-babel-do-load-languages 'org-babel-load-languages org-babel-load-languages) +#+end_src + +1.2. _Second step_ +The shell command will clone an org babel [[https://github.com/samuel-schlaeppy/ob-zig.el.git][zig plugin]] necessary to execute some Zig examples directly in Emacs with Org babel. + +The ~HEADER~ parameter below (in the code block) configures the directory path by default. +You can change the directory where the plugin will be installed (change the argument after the ~:dir~ -> ~/CHANGE-ME~). + +Once you have changed the ~HEADER~ parameter, you can place your cursor in the code block below and use ~C-c C-c~ (~ctrl-c ctrl-c~) to evaluate the code below. +#+HEADER: :dir ~/CHANGE-ME +#+begin_src shell + git clone https://github.com/samuel-schlaeppy/ob-zig.el.git +#+end_src + +2. _Create an emacs configuration file_ +In the last section, the plugin =Ob-Zig= has been installed, this plugin will help to evaluate Zig example codes. +To use correctly this plugin, in the code block below, you need to change the string ~./PATH-WHERE-THE-OB-ZIG-PLUGIN-IS-INSTALLED/ob-zig.el~ where you have cloned the plugin =ob-zig.el=. +In addition, you need to change in the code block the string =PATH-TO-THE-ZIG-EXECUTABLE= to insert the path of the Zig executable. + +After that, the following command ~C-c C-v t~ (~ctrl-c ctrl-v t~) will produce a ~zigIterativeProgramming.el~ file. +This file can be loaded from your emacs configuration (see section below). +#+begin_src emacs-lisp :tangle zigIterativeProgramming.el + (setq base_dir "~/PATH-WHERE-THE-ZIG-PLUGIN-IS-INSTALLED/ob-zig.el") + (setq org-babel-zig-compiler "PATH-TO-THE-ZIG-EXECUTABLE") +#+end_src + +#+begin_src emacs-lisp :tangle zigIterativeProgramming.el + (require 'package) + (add-to-list 'package-archives + '("melpa" . "https://melpa.org/packages/")) + (package-initialize) + (package-refresh-contents) + + (defun install-custom-pkg (pck) + (if (featurep pck) + (message "The package %s is already installed !" pck) + (package-install pck) + )) + + (install-custom-pkg 'zig-mode) + (install-custom-pkg 'lsp-mode) + (require 'lsp-mode) + (add-hook 'zig-mode-hook #'lsp) + + (let ((local-file-path (expand-file-name "ob-zig.el" base_dir))) + (setq org-babel-zig-compiler local-file-path) + (load-file local-file-path) + ) + + (custom-set-variables + ;; custom-set-variables was added by Custom. + ;; If you edit it by hand, you could mess it up, so be careful. + ;; Your init file should contain only one such instance. + ;; If there is more than one, they won't work right. + '(org-babel-load-languages '((C . t) (emacs-lisp . t) (shell . t)))) +#+end_src + +3. _Execute the configuration file from the configuration_ +You can put the code below in your ~init.el~ it will load the file produced before and load the necessary package to learn Zig with literate programming. +But you need the specify the directory path of the ~zigIterativeProgramming.el~ file (first line below). +(the ~init.el~ can be found in ~~/.emacs.d/~ or can be created in ~~/.config/emacs/~ +#+begin_src emacs-lisp + (let ((file_dir "~/PATH-TO-THE-zigIterativeProgramming-file")) + (load-file (expand-file-name "zigIterativeProgramming.el" file_dir))) +#+end_src + diff --git a/content/docs/package-manager.org b/content/docs/package-manager.org index ec610d3..a1906a4 100644 --- a/content/docs/package-manager.org +++ b/content/docs/package-manager.org @@ -2,7 +2,7 @@ #+weight: 6 ** Zig package manager -Since 0.11, Zig has now an official built-in package manager named. +Since 0.11, Zig has now an official built-in package manager that uses files with the =.zig.zon= extension. There is no global repository like [[https://crates.io][crates.io]](Rust) or [[https://npm.js.com][npmjs]](Node.js) for Zig packages. Instead, Zig packages are distributed as git repositories. diff --git a/content/docs/version-manager.org b/content/docs/version-manager.org index 0bb5231..c6f9dfc 100644 --- a/content/docs/version-manager.org +++ b/content/docs/version-manager.org @@ -2,7 +2,7 @@ #+weight: 5 ** Zig version manager -Using ZIG before 1.0 might require you to often switch between master and the last official release. +Using ZIG before 1.0 might require you to often switch between master and the last official release. Almost approximately every 3 months a new version is released. One solution would be to install both (or more) versions of ZIG and switch the PATH environment variable to the version you want to use. diff --git a/content/docs/web/_index.org b/content/docs/web/_index.org index 409992f..6735953 100644 --- a/content/docs/web/_index.org +++ b/content/docs/web/_index.org @@ -1,5 +1,5 @@ #+title: Web -#+weight: 16 +#+weight: 90 #+hugo_cascade_type: docs #+math: true