From 079bd614611e88afe885cbf6a19b9e55f442aa77 Mon Sep 17 00:00:00 2001 From: Ryan Yin Date: Thu, 11 Jan 2024 23:13:38 +0800 Subject: [PATCH] feat: README & ORGMODE --- ORGMODE.org | 69 +++++++++++++++++++++ README.md | 121 ------------------------------------- README.org | 170 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 239 insertions(+), 121 deletions(-) create mode 100644 ORGMODE.org delete mode 100644 README.md create mode 100644 README.org diff --git a/ORGMODE.org b/ORGMODE.org new file mode 100644 index 0000000..8817914 --- /dev/null +++ b/ORGMODE.org @@ -0,0 +1,69 @@ +#+title: Org Mode +#+author: ryan4yin + +[[https://orgmode.org/features.html]] + +[[https://github.com/doomemacs/doomemacs/blob/master/modules/lang/org/config.el]] + +* Tutorials + +1. [[https://orgmode.org/quickstart.html][Getting started with Org-mode]] +2. [[https://orgmode.org/manuals.htm][Org Mode Compact Guide]] +3. [[https://github.com/Somelauw/evil-org-mode/blob/master/README.org#keybindings][Org Mode's evil keybinding]] + + +* Tips + +** Convert Markdown to Org Mode + +#+begin_src bash +# enter a shel with pandoc available +nix shell nixpkgs#pandoc +# convert markdown into orgmode +pandoc --wrap=preserve --from markdown --to org README.md -o README.org +#+end_src + +If you're familiar with markdown, learn orgmode via pandoc convert is a good idea. + + +** Special Symbols(Entities) & Escaping + +[[https://orgmode.org/manual/Special-Symbols.html]] + +When migrating from Markdown to Org Mode, I have a big headache about how to escape some special symbols. + +Here are three methods I found to make things easier: + + +1. Use the following syntax for multiline code.(use =,= at the start of lines inside the code block for escaping) + #+begin_example + ,#+begin_example + ,,#+begin_example + \alpha xxx \alpha + ,,#+end_example + ,#+end_example + #+end_example +2. for one line code, colon followed by a space is a shortcut for =#+begine_src ... #+end_src=. + : : echo hello +3. Use ~=this is good=~ or =~echo hello~= for inline code + 1. ~=~ or =~= can be used inside a inline code block too: ~=~this is good~=~ will show =~this is good~=. + 1. *NOTE:* GitHub do not support =~~xxx~~= or ~==xxx==~, so if the content contains ~=~, use =~= to quote it, and vice versa. +4. Use LaTeX-like syntax to insert special symbols: [[https://orgmode.org/worg/org-symbols.html][A table of symbols for Org-mode]] + 1. For example, use =\alpha= to insert a \alpha symbol. + 2. *NOTE:* If you do not want to add a space after the LaTex syntax, you have to add a ={}= after it,e.g. =\alpha{}xxx= will show \alpha{}xxx +5. Add =#+OPTIONS ^:nil= at the start of the org file, to disable +6. Insert a zero-width Unicode character to break the text's structure, so that the content won't be recognized as some orgmode syntax. + 1. *NOTE:* I really don't like using non-ASCII characters for escaping, it's too tricky! An invisible space character can be a real headache at some point. + + +** Mysteries + +Still don't know how to make orgmode render the following correctly: + +1. =~'a~= \Rightarrow ~'a~ +2. ~='a=~ \Rightarrow ='a= +3. Show only one comma at the start of the following lines(code). + #+begin_example + ,,#+begin_example + \quotesinglbase{}xxx + #+end_example diff --git a/README.md b/README.md deleted file mode 100644 index b230b5c..0000000 --- a/README.md +++ /dev/null @@ -1,121 +0,0 @@ -# guix-config - -My dotfiles for GNU Guix - -## Tutorials - -Tutorials for Guile Scheme Language: - -- [A Scheme Primer](https://spritely.institute/static/papers/scheme-primer.html): for a basic understanding of Scheme -- [Guile 3.0 Manual](https://www.gnu.org/software/guile/manual/): The most important part of this manual is API Reference, when in doubt, check the API Reference. - -How to practice Guile Scheme Language(on NixOS): - -```bash -nix shell nixpkgs#racket-minimal --command "racket" -``` - -Tutorials for Guix itself: - -- [GNU Guix Reference Manual](https://guix.gnu.org/en/manual/en/guix.html): read this first for installation and basic usage & setup. -- [GNU Guix Cookbook](https://guix.gnu.org/en/cookbook/en/guix-cookbook.html): read this after you have your Guix installed and have some basic knowledge about Guix. - -## Key community projects - -- -- - -## Notes - -1. `'a`: a syntax sugar of `(quote a)`, a symbol `a` is not evaluated. -1. `#t` and `#f`: true and false -1. `'()` or `null`: empty list -1. `(list arg1 arg2 …)` or `'(arg1 arg2 …)`: a linked list, -1. `cons* arg1 arg2 …`: similar to `(list arg1 arg2 …)`, but its last cons cell is a dotted list, which does not have `null` for its cdr. - 1. This function is called `list*` in some other Schemes and in Common LISP. - -```bash -scheme@(guile-user)> (cons* 1 2 3 4 5) -$4 = (1 2 3 4 . 5) -scheme@(guile-user)> (list 1 2 3 4 5) -$5 = (1 2 3 4 5) -scheme@(guile-user)> '(1 2 3 4 5) -$6 = (1 2 3 4 5) - -scheme@(guile-user)> '(1 2) -$7 = (1 2) -scheme@(guile-user)> (cons 1 (cons 2 '())) -$8 = (1 2) -;; a list which does not have `null` for its cdr is called a dotted list. -scheme@(guile-user)> (cons 1 2) -$9 = (1 . 2) -``` - -## Guix Mirror in China - - - -## FAQ - -### 1. In which scenarios should I use `cons*` instead of `list` / `cons`? - -1. `cons` create a pair with two elements, the first element is its `car` and the second element its `cdr`. -2. `(list a b ...)` create a linked list with multiple elements, and a `null` is appended to the end of the list. -3. `(cons* a b ... g h)` create a linked list with multiple elements, but the last element is not `null`, it is the last element of the list. - -`cons*` is useful when you want to **insert multiple elements at the front of a list**. For example, `(cons* 1 2 3 '(4 5 6))` will insert `1 2 3` at the front of `(4 5 6)`, and the result is `(1 2 3 4 5 6)`. - -nonguix's installation description use `cons* ... %default-channels` to insert its channel infront of guix's default channels. - -if we use `list ... %default-channels`, the result have an extra `null` at the end of the list, which is not what we want. - -```bash -scheme@(guile-user) [1]> (list 1 2 3 (list 4 5 6)) -$13 = (1 2 3 (4 5 6)) -scheme@(guile-user) [1]> '(1 2 3 (4 5 6)) -$14 = (1 2 3 (4 5 6)) -scheme@(guile-user) [1]> (cons* 1 2 3 (list 4 5 6)) -$15 = (1 2 3 4 5 6) -``` - -### 2. How to install package vai `config.scm`? - -1. `guix search ` to find the package's location. - 1. For example, `guix search kitty` will show the package's location is `gnu/packages/terminals.scm`. -1. add `(use-package-modules terminals)` to the top of `config.scm`. -1. add `kitty` to the `packages` list in `config.scm`. - -### 3. Documentation? - -1. docs for `use-modules`: it's provided by guile, see -1. docs for `use-service-modules`, `use-package-modules` & `use-system-modules`: No docs for them. But you can read their definition in source code: -1. Source code: - 1. - 1. - -### 4. Why `guix pull` so slow?(stuck in `computing guix derivation`) - -> https://guix.gnu.org/manual/en/html_node/Channels-with-Substitutes.html - -When running `guix pull`, Guix will first compile the definitions of every available package. This is an expensive operation for which substitutes (see Substitutes) may be available. - -As for nonguix, you can add its official substitutes to speed up the `guix pull` process, search 'substitutes' in for details. - -> In NixOS, `nix` has no compilation phase and is a fully interpreted language, so `nix flake update` is much faster than `guix pull`. - -The substitutes you added into `config.scm` will only be available after the first `guix system reconfigure` finished! -To speed up the first reconfigure, see nonuix's official README for details. - -#### 5. `guix system reconfigure` so slow?(stuck in `build phase`) - -Same as above, you can add nonguix's substitutes to speed up the `guix system reconfigure` process. - -## References - -Other dotfiles that inspired me: - -- -- -- -- -- diff --git a/README.org b/README.org new file mode 100644 index 0000000..8b77833 --- /dev/null +++ b/README.org @@ -0,0 +1,170 @@ +#+title: guix-config +#+author: ryan4yin + +:PROPERTIES: +:CUSTOM_ID: guix-config +:END: +My dotfiles for GNU Guix + +** Tutorials +:PROPERTIES: +:CUSTOM_ID: tutorials +:END: +Tutorials for Guile Scheme Language: + +- [[https://spritely.institute/static/papers/scheme-primer.html][A Scheme Primer]]: for a basic understanding of Scheme +- [[https://www.gnu.org/software/guile/manual/][Guile 3.0 Manual]]: The most important part of this manual is API + Reference, when in doubt, check the API Reference. + +How to practice Guile Scheme Language(on NixOS): + +#+begin_src sh +nix shell nixpkgs#racket-minimal --command "racket" +#+end_src + +Tutorials for Guix itself: + +- [[https://guix.gnu.org/en/manual/en/guix.html][GNU Guix Reference Manual]]: read this first for installation and basic + usage & setup. +- [[https://guix.gnu.org/en/cookbook/en/guix-cookbook.html][GNU Guix Cookbook]]: read this after you have your Guix + installed and have some basic knowledge about Guix. + +How to use Guix on NixOS: [[https://github.com/ryan4yin/nix-config/blob/main/modules/nixos/desktop/guix.nix]] + +** Key community projects +:PROPERTIES: +:CUSTOM_ID: key-community-projects +:END: +- [[https://github.com/abcdw/rde]] +- [[https://github.com/nonguix/nonguix]] + + +** Notes +:PROPERTIES: +:CUSTOM_ID: notes +:END: +1. 'a: a syntax sugar of =(quote a)=, a symbol =a= is not evaluated. +2. =#t= and =#f=: true and false +3. '() or =null=: empty list +4. =(list arg1 arg2 …)= or ='(arg1 arg2 …)=: a linked list, +5. =cons* arg1 arg2 …=: similar to =(list arg1 arg2 …)=, but its last cons cell is a dotted list, which does not have + =null= for its cdr. + 1. This function is called =list*= in some other Schemes and in Common LISP. + +#+begin_src sh +scheme@(guile-user)> (cons* 1 2 3 4 5) +$4 = (1 2 3 4 . 5) +scheme@(guile-user)> (list 1 2 3 4 5) +$5 = (1 2 3 4 5) +scheme@(guile-user)> '(1 2 3 4 5) +$6 = (1 2 3 4 5) + +scheme@(guile-user)> '(1 2) +$7 = (1 2) +scheme@(guile-user)> (cons 1 (cons 2 '())) +$8 = (1 2) +;; a list which does not have `null` for its cdr is called a dotted list. +scheme@(guile-user)> (cons 1 2) +$9 = (1 . 2) +#+end_src + +** Guix Mirror in China +:PROPERTIES: +:CUSTOM_ID: guix-mirror-in-china +:END: +[[https://mirror.sjtu.edu.cn/docs/guix]] + +** FAQ +:PROPERTIES: +:CUSTOM_ID: faq +:END: +*** 1. In which scenarios should I use =cons*= instead of =list= / =cons=? +:PROPERTIES: +:CUSTOM_ID: in-which-scenarios-should-i-use-cons-instead-of-list-cons +:END: +1. =cons= create a pair with two elements, the first element is its =car= and the second element its =cdr=. +2. =(list a b ...)= create a linked list with multiple elements, and a =null= is appended to the end of the list. +3. =(cons* a b ... g h)= create a linked list with multiple elements, but the last element is not =null=, it is the last + element of the list. + +=cons*= is useful when you want to *insert multiple elements at the front of a list*. For example, +=(cons* 1 2 3 '(4 5 6))= will insert =1 2 3= at the front of =(4 5 6)=, and the result is =(1 2 3 4 5 6)=. + +nonguix's installation description use =cons* ... %default-channels= to insert its channel infront of guix's default +channels. + +if we use =list ... %default-channels=, the result have an extra =null= at the end of the list, which is not what we +want. + +#+begin_src sh +scheme@(guile-user) [1]> (list 1 2 3 (list 4 5 6)) +$13 = (1 2 3 (4 5 6)) +scheme@(guile-user) [1]> '(1 2 3 (4 5 6)) +$14 = (1 2 3 (4 5 6)) +scheme@(guile-user) [1]> (cons* 1 2 3 (list 4 5 6)) +$15 = (1 2 3 4 5 6) +#+end_src + +*** 2. How to install package vai =config.scm=? +:PROPERTIES: +:CUSTOM_ID: how-to-install-package-vai-config.scm +:END: +1. =guix search = to find the package's location. + 1. For example, =guix search kitty= will show the package's location is =gnu/packages/terminals.scm=. +2. add =(use-package-modules terminals)= to the top of =config.scm=. +3. add =kitty= to the =packages= list in =config.scm=. + +*** 3. Documentation? +:PROPERTIES: +:CUSTOM_ID: documentation +:END: +1. docs for =use-modules=: it's provided by guile, see + [[https://www.gnu.org/software/guile/manual/html_node/Using-Modules.html]] +2. docs for =use-service-modules=, =use-package-modules= & =use-system-modules=: No docs for them. But you can read + their definition in source code: [[https://git.savannah.gnu.org/cgit/guix.git/tree/gnu.scm#n143]] +3. Source code: + 1. [[https://git.savannah.gnu.org/cgit/guix.git/tree/]] + 2. [[https://github.com/nonguix/nonguix/tree/master/nongnu]] + +*** 4. Why =guix pull= so slow?(stuck in =computing guix derivation=) +:PROPERTIES: +:CUSTOM_ID: why-guix-pull-so-slowstuck-in-computing-guix-derivation +:END: + +#+begin_quote +https://guix.gnu.org/manual/en/html_node/Channels-with-Substitutes.html + +#+end_quote + +When running =guix pull=, Guix will first compile the definitions of every available package. This is an expensive +operation for which substitutes (see Substitutes) may be available. + +As for nonguix, you can add its official substitutes to speed up the =guix pull= process, search 'substitutes' in +[[https://gitlab.com/nonguix/nonguix]] for details. + +#+begin_quote +In NixOS, =nix= has no compilation phase and is a fully interpreted language, so =nix flake update= is much faster than +=guix pull=. + +#+end_quote + +The substitutes you added into =config.scm= will only be available after the first =guix system reconfigure= finished! +To speed up the first reconfigure, see nonuix's official README for details. + +**** 5. =guix system reconfigure= so slow?(stuck in =build phase=) +:PROPERTIES: +:CUSTOM_ID: guix-system-reconfigure-so-slowstuck-in-build-phase +:END: +Same as above, you can add nonguix's substitutes to speed up the =guix system reconfigure= process. + +** References +:PROPERTIES: +:CUSTOM_ID: references +:END: +Other dotfiles that inspired me: + +- [[https://github.com/engstrand-config/guix-dotfiles]] +- [[https://github.com/migalmoreno/guix-config]] +- [[https://github.com/Tass0sm/dotfiles]] +- [[https://github.com/yveszoundi/guix-config]] +- [[https://github.com/hiecaq/guix-config]]